Custom API Provider: Connect Any OpenAI-Compatible Endpoint

What Is the Custom API Provider?

Most modern LLM providers expose an OpenAI-compatible REST API: the same /chat/completions request and response shape that the official OpenAI SDK uses. Any such provider can be reached by changing just two things — the base URL and the API key. The Custom API Provider card is that escape hatch: if your provider isn’t one of the built-in cards, enter its base URL and key here instead of waiting for a dedicated integration.

This covers hosted gateways like Together AI, Mistral, Fireworks, DeepInfra and Novita, as well as anything you run yourself — a vLLM server, an Ollama box exposed over HTTPS, or an internal company gateway — as long as it answers the OpenAI chat completions endpoint.

What You Need

• An endpoint base URL — the part before /chat/completions. It almost always ends in /v1, for example https://api.together.xyz/v1 or https://api.mistral.ai/v1. Enter the base URL only, not the full /chat/completions path.
• An API key for that provider. Format varies — it might start with sk-, gsk_, or have no prefix at all. Use whatever the provider issues you.
• A model ID the endpoint serves (for example mistralai/Mixtral-8x7B-Instruct-v0.1 on Together). You’ll set this as your instance’s model after saving.

Common Base URLs

Base URLs change — always confirm the current one in your provider’s API documentation. The pattern to look for is the value they tell you to set as baseURL or OPENAI_BASE_URL in their OpenAI-SDK quickstart.

Add a Custom Endpoint on OpenClaw Launch

1. Sign in at openclawlaunch.com and open the API Keys page.
2. Scroll to the Custom API Provider card at the bottom of the page.
3. In API Endpoint URL, paste the base URL — ending in /v1 (or your provider’s equivalent), without the /chat/completions suffix.
4. In API Key, paste the key the provider issued you.
5. Click Save. Your key is encrypted at rest and applied to your running instances — no redeploy.
6. Open your instance settings and set the model ID to a model your endpoint serves. The bot now routes chat through your custom provider.

Prefer Hermes Agent? The same card works for Hermes Agent instances — enter the base URL and key the same way.

Requirements & Limits

• The endpoint must implement the OpenAI chat completions API (POST /chat/completions). Providers that only offer a proprietary orlegacy completions format won’t work through this card.
• For agentic use (skills, tools, web search), the model you point at should support tool / function calling. Text-only chat works regardless.
• A self-hosted endpoint must be reachable over the public internet with HTTPS — a localhost or LAN-only address won’t be reachable from your hosted container.
• Image, video and music generation are handled by the dedicated media cards, not the custom chat endpoint. Use the fal, Runway, Replicate and similar cards for those.

Troubleshooting

The key won’t save / 404 on save

• Make sure the base URL ends at /v1 (or the provider’s documented base) and does not include /chat/completions. We append the path ourselves — a doubled path returns a 404.
• Confirm the URL uses https:// and has no trailing spaces or newline.

401 Unauthorized

• Re-copy the key from the provider dashboard; check it isn’t revoked or out of credit. Some providers require you to enable billing before the key activates.
• A few providers scope keys to specific models or projects — make sure the key you used has access to the model ID you set.

Model not found

• Use the exact model ID string the provider lists (they’re case-sensitive and often namespaced, e.g. mistralai/Mixtral-8x7B-Instruct-v0.1). Guessed variants return a 404.
• Query the provider’s /v1/models endpoint if you’re unsure which IDs are served.

Frequently Asked Questions

Which providers work with the Custom API Provider card?

Any provider that exposes an OpenAI-compatible /chat/completions endpoint — Together AI, Mistral, Fireworks, DeepInfra, Novita, and self-hosted servers like vLLM or a remotely-exposed Ollama. If the provider’s docs tell you to set an OpenAI baseURL, it will work here.

Do I enter the full /chat/completions URL?

No. Enter only the base URL — the part ending in /v1 (or the provider’s documented base). OpenClaw appends the /chat/completions path automatically. Including it yourself causes a 404.

Is my custom key safe?

Yes. The key is encrypted at rest and only ever shown back to you as a masked preview. It is passed to your own container to call the endpoint on your behalf and is never displayed in plain text again.

Can I point at a model running on my own server?

Yes, as long as it serves the OpenAI chat completions format over public HTTPS. A vLLM server or an Ollama instance exposed with the OpenAI-compatible /v1 path both work. A localhost address won’t — your hosted bot can only reach a publicly-routable URL.

What's Next?

• API Keys & BYOK overview — Every provider you can add and how bring-your-own-key works
• OpenClaw BYOK overview — The BYOK basics for OpenClaw instances
• Compare AI models — Pick the right model before you bring a key
• API Keys page — Add or manage all your provider keys in one place