--- title: "OpenClaw Custom Provider Setup: Add Any OpenAI-Compatible API" description: "Add Haimaker, Ollama, OpenRouter, or any OpenAI-compatible API to OpenClaw. Includes copy-paste provider config, model allowlist setup, and fixes for the common errors." date: 2026-01-26 location: San Francisco, CA – Jan 26th, 2026 image: /images/integrating-custom-llm-providers-clawdbot-hero.jpg updatedDate: 2026-06-26 keywords: openclaw custom provider, openclaw add provider, opencode custom provider, openclaw model provider, openclaw openai compatible api, openclaw llm provider, custom llm provider, openai compatible api, haimaker, ai agent configuration faq: - question: "How do I add a custom LLM provider to OpenClaw?" answer: "For Haimaker, 'npx -y @haimaker/connect --openclaw' writes both the provider and the allowlist entry for you. To add any provider by hand: add the provider to models.providers in ~/.openclaw/openclaw.json with baseUrl, apiKey, and api type 'openai-completions', then add each model to agents.defaults.models with the fully-qualified name (provider-name/model-name), and apply with 'openclaw gateway config.apply'. Both steps are required — missing the allowlist is the most common error." - question: "Why does OpenClaw say 'model not allowed' for my custom provider?" answer: "The model isn't in the agents.defaults.models allowlist. The key must be the fully-qualified name like 'haimaker/openai/gpt-oss-120b', not just 'gpt-oss-120b'. Defining the provider isn't enough — you also need this allowlist entry." - question: "Why doesn't my custom model show up in /models?" answer: "You likely added the allowlist entry in agents.defaults.models but forgot the model definition in models.providers[].models[], or vice versa. Both are required. Check that the model id in your provider definition matches exactly what the provider's API expects." - question: "How do I test if my custom provider is working in OpenClaw?" answer: "Run /models to check the model appears, then /model your-alias to switch to it, then /status to confirm. Send a test message. If it fails, test the API directly with curl first to isolate whether the issue is with your credentials or with the OpenClaw config." - question: "What API format does OpenClaw support for custom providers?" answer: "OpenClaw supports any API that implements the OpenAI chat completions format. Set api to 'openai-completions' in your provider config. This covers Haimaker, Ollama, OpenRouter, Together, and most other LLM providers." howToSteps: - name: "Find your OpenClaw config" text: "Open ~/.openclaw/openclaw.json. This is where provider and model definitions go. Run 'cat ~/.openclaw/openclaw.json' to see the current config." - name: "Add the provider" text: "Add your provider to the models.providers section with baseUrl, apiKey, api type 'openai-completions', and a models array containing each model's id, name, reasoning flag, cost, contextWindow, and maxTokens." - name: "Allowlist the model" text: "Add the model to agents.defaults.models using the fully-qualified name (provider-name/model-name) as the key. Without this step, OpenClaw will reject the model with 'model not allowed'." - name: "Apply the config" text: "Run 'openclaw gateway config.apply --file ~/.openclaw/openclaw.json' to restart the gateway with the new config. Then run /models to verify and /model your-alias to test." --- > **Note:** Clawdbot was renamed to Moltbot, and is now called **OpenClaw** (handle: [@openclaw](https://twitter.com/openclaw), website: [openclaw.ai](https://openclaw.ai)). This guide applies to all versions — the configuration process is the same regardless of what name you know it by. For new users, install via `npm install -g openclaw`. OpenClaw supports the usual suspects (OpenAI, Anthropic), but it also lets you plug in any OpenAI-compatible API as a custom provider. That means Haimaker, Ollama, OpenRouter, Together, a private vLLM server, or whatever internal gateway your team already runs. The part people miss is the two-step setup. Defining the provider is only half of it. You also have to allowlist the exact model name OpenClaw should use. Skip that, and you end up with the classic "model not allowed" error even though the API key is fine. ## Why bother with custom providers? Depends on what you need. Maybe you want cheaper inference for bulk tasks, access to a model that isn't on the main platforms, or a provider that keeps data in a specific region for compliance reasons. Some models are just better at certain things, and being able to route between them gives you more control. ## What you'll need - OpenClaw installed and running (`npm install -g openclaw`) - API credentials for your custom provider - Access to the OpenClaw CLI - Comfort editing JSON config files ## Skip the manual editing For Haimaker specifically, you don't have to touch the config at all. Run: ```bash export HAIMAKER_API_KEY=your-haimaker-key npx -y @haimaker/connect --openclaw ``` [`@haimaker/connect`](/connect) writes both halves of the OpenClaw setup — the provider definition in `models.providers` and the allowlist entry in `agents.defaults.models` — so you never hit the "model not allowed" trap covered below. It defaults to `haimaker/auto`; pass `--model` to pin a specific model or `--pick-model` to choose interactively. Reverse it any time with `npx @haimaker/connect --uninstall --openclaw`. If you'd rather not run the CLI, you can have OpenClaw edit its own config from a chat prompt instead. With OpenClaw already running, [sign up for Haimaker](https://app.haimaker.ai/sign-up?utm_source=openclaw_blog&utm_medium=cta&utm_campaign=openclaw_integration&utm_content=easy_way), create an API key from the dashboard, then paste this prompt into your OpenClaw chat: ``` Add Haimaker as a custom provider to my OpenClaw config. Use these details: - Provider name: haimaker - Base URL: https://api.haimaker.ai/v1 - API key: [PASTE YOUR HAIMAKER API KEY HERE] - API type: openai-completions Add these two models: 1. openai/gpt-oss-120b (reasoning: true, context: 128000, max tokens: 32000, cost: $0.60/$2.40 per 1M tokens) 2. minimax/minimax-m2.5 (reasoning: true, context: 196608, max tokens: 196608, cost: $0.30/$1.20 per 1M tokens) Create aliases "gpt-oss-120b" and "minimax-m2.5" for easy switching. Apply the config when done. ``` OpenClaw will update your config, add the provider definition and model allowlist entries, and restart the gateway automatically. You can verify it worked by running `/models` and looking for your new models. If you prefer to understand what's happening under the hood (or need to troubleshoot), keep reading for the manual approach. ## Step 1: Find your OpenClaw config Your config lives at `~/.openclaw/openclaw.json` (legacy: `~/.clawdbot/clawdbot.json` — the new path is automatically symlinked). This is where provider and model definitions go. ```bash cat ~/.openclaw/openclaw.json ``` ## Step 2: Add the provider Add your provider to the `models.providers` section in your OpenClaw config. Here's the structure: ```json { "models": { "mode": "merge", "providers": { "your-provider-name": { "baseUrl": "https://api.yourprovider.com/v1", "apiKey": "your-api-key-here", "api": "openai-completions", "models": [ { "id": "model-name", "name": "model-name", "reasoning": false, "input": ["text"], "cost": { "input": 0.01, "output": 0.03, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 32000, "maxTokens": 32000 } ] } } } } ``` A few things to note: - `baseUrl` is the API endpoint for your provider - `api` must be `"openai-completions"` for OpenAI-compatible APIs - `models[].id` needs to match exactly what the provider's API expects in the request body - `reasoning` should be `true` if the model supports reasoning mode - `contextWindow` is the max tokens the model can take as input - `cost` is in USD per 1K tokens (used for tracking, not billing) ## Step 3: Allowlist the model This is the part that trips people up. Defining the provider isn't enough. You also need to add the model to the allowlist in `agents.defaults.models`, or OpenClaw will reject it. ```json { "agents": { "defaults": { "models": { "your-provider-name/model-name": { "alias": "model-shortcut" } } } } } ``` The key format is `provider-name/model-name`. This is the fully-qualified identifier OpenClaw uses internally, combining your provider name with the model ID. ## Step 4: Apply the config After editing, apply the changes: ```bash openclaw gateway config.apply --file ~/.openclaw/openclaw.json ``` The gateway restarts automatically to pick up the new config. > **Note:** Legacy `clawdbot` commands are aliased to `openclaw` for backward compatibility, but new installs should use the `openclaw` command. ## Full example: Haimaker integration Here's a working config with Haimaker and two models: ```json { "models": { "mode": "merge", "providers": { "haimaker": { "baseUrl": "https://api.haimaker.ai/v1", "apiKey": "YOUR-HAIMAKER-API-KEY", "api": "openai-completions", "models": [ { "id": "openai/gpt-oss-120b", "name": "openai/gpt-oss-120b", "reasoning": true, "input": ["text"], "cost": { "input": 0.60, "output": 2.40, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 128000, "maxTokens": 32000 }, { "id": "minimax/minimax-m2.5", "name": "minimax/minimax-m2.5", "reasoning": true, "input": ["text"], "cost": { "input": 0.30, "output": 1.20, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 196608, "maxTokens": 196608 } ] } } }, "agents": { "defaults": { "models": { "haimaker/openai/gpt-oss-120b": { "alias": "gpt-oss-120b" }, "haimaker/minimax/minimax-m2.5": { "alias": "minimax-m2.5" } } } } } ``` ## Testing it Once the config is applied, check that everything works: 1. Run `/models` to see if your new models show up in the list. 2. Switch to one of them: ``` /model gpt-oss-120b ``` 3. Run `/status` to confirm you're on the right model. 4. Send a test message and make sure you get a response back. ## Common problems ### "model not allowed: provider/model-name" This is the most common one. It means the model isn't in the `agents.defaults.models` allowlist. Go back to Step 3. The allowlist key needs to be the fully-qualified name, like `haimaker/openai/gpt-oss-120b`, not just `gpt-oss-120b`. ### Model doesn't show up in /models Check that you actually added the model to the `models.providers[].models[]` array. It's easy to add the allowlist entry but forget the model definition (or vice versa). ### Wrong model getting called The `id` field in your model definition has to match exactly what the provider's API expects. Check their docs. If they expect `gpt-oss-120b` but you have `openai/gpt-oss-120b`, the request will either fail or hit a different model. ### Connection errors Double-check `baseUrl` and `apiKey`. Test the API directly with curl first: ```bash curl https://api.yourprovider.com/v1/chat/completions \ -H "Authorization: Bearer your-api-key" \ -H "Content-Type: application/json" \ -d '{"model": "model-name", "messages": [{"role": "user", "content": "hello"}]}' ``` If that doesn't work, the problem is with your credentials or endpoint, not OpenClaw. ### JSON syntax errors If you get parsing errors or the config doesn't apply, you can simply ask OpenClaw to fix it: ``` Hey, can you fix the JSON syntax errors in my openclaw config? I keep getting parse errors. ``` OpenClaw can often identify and fix common JSON issues like missing commas, incorrect quotes, or malformed objects. ## How the request routing works It helps to understand what OpenClaw does under the hood: 1. You type `/model gpt-oss-120b` 2. OpenClaw resolves the alias: `gpt-oss-120b` → `haimaker/openai/gpt-oss-120b` 3. It looks up the provider config for `haimaker` 4. It sends the request to `https://api.haimaker.ai/v1/chat/completions` 5. The request body contains `{ "model": "openai/gpt-oss-120b", ... }` The fully-qualified name (`haimaker/openai/gpt-oss-120b`) is internal to OpenClaw. The API only sees the model `id`. That's why both the provider definition and the allowlist entry are required: they serve different purposes. ## Why Haimaker? If you're looking for a provider to try this with, Haimaker is a good fit. It's OpenAI-compatible out of the box, has competitive pricing, and with a single API key you get access to a [wide variety of models](https://haimaker.ai/models) — not just GPT-OSS-120B and MiniMax M2.5, but many others you might not find elsewhere. The latency has been solid in my testing. ### About premium subscriptions There have been reports of providers like Anthropic restricting usage of premium subscriptions (like Claude Max) through third-party automation tools. Using those subscriptions through OpenClaw or similar platforms may violate their terms of service and risk your account. ![Claude Max ToS Warning](/images/claude-max-tos-warning.jpg) If you're running OpenClaw as an always-on agent, use dedicated API access. It's cheaper in the long run, you won't get banned, and the performance is more consistent for automated workloads. ### Get started with Haimaker [Sign up for Haimaker](https://app.haimaker.ai/sign-up?utm_source=openclaw_blog&utm_medium=cta&utm_campaign=openclaw_integration&utm_content=article_cta) — no subscription lock-in, pay for what you use. ## Wrapping up The whole process comes down to two things: define the provider and its models in `models.providers`, then add the fully-qualified model names to `agents.defaults.models`. Miss either step and it won't work. The allowlist requirement might feel like an extra hoop, but it's there for access control. In multi-agent setups, you probably don't want every agent hitting every model. If you run into something not covered here, check the [OpenClaw documentation](https://docs.openclaw.ai) or ask in the [OpenClaw community Discord](https://discord.openclaw.ai). --- *Written for OpenClaw version 2026.1.30-1. Config structure is backward-compatible with Clawdbot/Moltbot. For the latest updates, visit [openclaw.ai](https://openclaw.ai).* **Related articles:** - [Best Models to Run for OpenClaw in 2026](/blog/best-models-for-openclaw) - [Setting Up Your First OpenClaw Agent](/blog/getting-started-with-openclaw)