OpenClaw LLM Provider Setup: Add & Configure Any Provider

Do not index

OpenClaw does not ship with a brain. You connect one: an LLM provider such as OpenAI, Anthropic, Google, or a local model server, authenticated once and set as your default model. To add a provider in OpenClaw, run openclaw onboard on a fresh install (or openclaw configure on an existing one), add an API key, then point agents.defaults.model.primary at a provider/model ref like anthropic/claude-opus-4-6. The flow is identical whether OpenClaw runs on your laptop, a VPS, or an always-on Agent37 instance.

This guide covers the whole surface of OpenClaw LLM provider setup: the current supported-provider list, where your API keys actually go, and how to add a custom provider for any OpenAI-compatible endpoint. It also covers the config that controls model selection and fallbacks, plus fixes for the exact errors that stall most setups.

What an OpenClaw LLM Provider Does

OpenClaw is the agent framework. It owns your channels (WhatsApp, Telegram, Discord, Slack), your skills, your memory, and your schedule. The intelligence is rented: every reply your agent sends comes from a model served by a provider you configure.

Configure one and everything downstream lights up.

Before touching anything, three terms:

Provider: the company or server hosting the model, identified by a short id like openai, anthropic, or ollama.

Model ref: written as provider/model, parsed on the first slash and normalized to lowercase. openai/gpt-5.6 and anthropic/claude-opus-4-6 are refs.

Auth profile: the stored credential (API key or OAuth token) OpenClaw uses when calling that provider.

Wire those three together and your agent works. That is the entire job.

OpenClaw LLM Provider List: What Is Supported in 2026

The official provider directory now links out to more than 60 providers. Here are the ones that matter, grouped by what they are good at.

Frontier providers

OpenAI (openai): add a key via OPENAI_API_KEY, or sign in with a ChatGPT/Codex subscription. Both auth paths share the same provider id (older builds used openai-codex/ refs; openclaw doctor --fix migrates them to openai/). Example ref: openai/gpt-5.6. New key? Follow our OpenAI API key walkthrough.

Anthropic (anthropic): ANTHROPIC_API_KEY, or paste a subscription token generated by claude setup-token. Example ref: anthropic/claude-opus-4-6. Key creation steps are in our Claude API key guide.

Google (google): GEMINI_API_KEY, with refs like google/gemini-3.1-pro-preview. Vertex AI is a separate provider (google-vertex) that authenticates through gcloud.

xAI (xai): SuperGrok/X Premium OAuth or XAI_API_KEY. Example ref: xai/grok-4.3.

Budget and value providers

DeepSeek (deepseek): deepseek/deepseek-v4-flash is one of the cheapest capable agent models right now.

Moonshot AI / Kimi (moonshot, and kimi for the coding endpoint): the docs tell you to install the Moonshot provider plugin before onboarding. Refs like moonshot/kimi-k2.6.

Z.AI (zai): the GLM family. Current example ref: zai/glm-5.2.

MiniMax (minimax): global and CN endpoints, text default minimax/MiniMax-M3.

Qwen (qwen): an official external plugin. Run openclaw plugins install @openclaw/qwen-provider, restart the gateway, then use refs like qwen/qwen3.5-plus.

Groq (groq): very fast serving of open models, for example groq/llama-3.3-70b-versatile.

Gateways and aggregators

OpenRouter (openrouter): one key, hundreds of models. openrouter/auto lets it route for you. Model ids that already contain slashes keep the provider prefix in front: openrouter/moonshotai/kimi-k2.

Vercel AI Gateway (vercel-ai-gateway): refs like vercel-ai-gateway/moonshotai/kimi-k2.6, following the gateway's own catalog naming.

Anything OpenAI-compatible or Anthropic-compatible: LiteLLM, a company proxy, a regional reseller. These are added as custom entries under models.providers in your config. The custom provider section below walks through it end to end.

Subscriptions you already pay for

GitHub Copilot (github-copilot): openclaw models auth login-github-copilot reuses your existing Copilot plan.

ChatGPT, Codex, and Claude subscriptions work through the OAuth and setup-token flows named above. If you already pay for one, you may not need a separate API bill at all.

Local models

Ollama (ollama): set OLLAMA_API_KEY to any value for a local host (export OLLAMA_API_KEY="ollama-local" works; local hosts need no real token, but the variable is what switches discovery on), and OpenClaw discovers your models from 127.0.0.1:11434. Pull the model first (ollama pull llama3.3), then use ollama/llama3.3.

LM Studio (lmstudio): default endpoint http://localhost:1234/v1. The OpenClaw docs currently call LM Studio running a large model the best local stack.

vLLM / SGLang (vllm, sglang): bundled plugins for self-hosted inference servers at 127.0.0.1:8000/v1 and 127.0.0.1:30000/v1.

One caveat before you plan a fully local agent: the docs put the comfortable hardware floor for a full agent loop at a multi-GPU rig costing tens of thousands of dollars. A single 24 GB card handles lighter prompts with real latency. For the trade-offs, see our guide to running local AI models.

How to Add an LLM Provider in OpenClaw

On a fresh install: run onboarding

openclaw onboard

The wizard detects AI access you already have, offers OpenAI, Anthropic, xAI, Google, and OpenRouter up front (everything else sits under More), live-tests the credential you give it, and saves the model and credential only after a passing completion. That last part matters: if onboarding finishes cleanly, your provider genuinely works.

Onboarding also configures the workspace, Gateway, channels, agents, and plugins. The full first-run flow is covered in our OpenClaw onboarding guide.

On an existing install: add a provider without breaking anything

Either of these adds a provider without disturbing your current setup:

openclaw configure
openclaw models auth login --provider openrouter

Both add authentication without touching your current default model. That is deliberate: adding a provider and switching to it are separate decisions in OpenClaw. Pass --set-default on the login command if you do want the switch immediately.

Scripted installs can skip the prompts entirely with choices like openclaw onboard --auth-choice openai-api-key.

Where API keys actually go

Put provider keys in ~/.openclaw/.env (the documented recommendation) or in the Gateway process environment.

Do not put them in your project or workspace .env. OpenClaw deliberately ignores provider credentials placed there, as a security measure. This one fact resolves a surprising share of "my key is set but nothing works" complaints.

If you run at volume, OpenClaw also supports key rotation: set OPENAI_API_KEYS as a comma-separated list (or numbered OPENAI_API_KEY_1, OPENAI_API_KEY_2 variables) and it rotates keys on rate-limit errors.

Add a Custom Provider to OpenClaw (Any OpenAI-Compatible API)

Sixty-plus listed providers still will not cover everyone. Maybe your models sit behind a LiteLLM proxy or a company gateway with its own base URL. OpenClaw handles them all the same way: a custom provider entry pointed at any OpenAI-compatible or Anthropic-compatible endpoint.

The fastest path is the wizard you already know. Run openclaw configure, choose Local (this machine) when it asks where the Gateway will run, pick the Model section, and choose Custom provider when it asks for a Model / Auth Provider. It then walks you through:

API Base URL: your provider's root endpoint, such as https://api.your-provider.com/v1.

Endpoint compatibility: OpenAI-compatible for an OpenAI-style /v1 API, OpenAI Responses-compatible for an endpoint that implements OpenAI's /v1/responses API, Anthropic-compatible for Anthropic's Messages API, or Unknown to let OpenClaw auto-detect.

API key: choose Paste API key now and paste it; OpenClaw stores it as an auth profile.

Model ID: the upstream model name, for example solar-pro3.

Alias: an optional friendly display name.

Endpoint ID: a short id like myproxy that becomes the provider half of your model ref.

Verify with openclaw models list: the new model appears as <endpoint-id>/<model-id>, here myproxy/solar-pro3, and openclaw models set myproxy/solar-pro3 makes it your default. The same steps cover any endpoint OpenClaw does not list.

Prefer editing config directly? Say your proxy serves Upstage's solar-pro3. The same result lives under models.providers in ~/.openclaw/openclaw.json:

{
  models: {
    providers: {
      myproxy: {
        baseUrl: "https://api.your-provider.com/v1",
        apiKey: "${MYPROXY_API_KEY}",
        api: "openai-completions",
        models: [{ id: "solar-pro3", name: "Upstage Solar Pro 3" }],
      },
    },
  },
}

Set api to "openai-responses" only if your endpoint supports OpenAI's /v1/responses API; "openai-completions" is the safe default everywhere else. If a turn fails after setup, check the four usual suspects: the base URL includes the right API path (usually /v1), the model ID exactly matches the provider's catalog, the compatibility type (OpenAI vs. Anthropic) is correct, and your API key has active billing.

Rather watch it done? The whole flow, end to end:

Set the Default Model and Fallbacks

Model selection lives in one optional JSON5 file at ~/.openclaw/openclaw.json:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.6", "openrouter/auto"]
      }
    }
  }
}

If the file is missing, OpenClaw uses safe defaults. The Gateway watches the file and hot-reloads your edits.

Prefer the CLI? Same result:

openclaw models set anthropic/claude-opus-4-6
openclaw models fallbacks add openai/gpt-5.6

Fallbacks fire in order when the primary fails. OpenClaw first rotates auth profiles inside the failing provider, then moves down your fallback list, and posts a visible model-fallback notice in the chat so you always know which model actually answered.

One warning: config validation is strict. A single unknown key or malformed type stops the Gateway from starting. If you hand-edit the file and break it, openclaw doctor --fix repairs the config and restores the last known good state.

Verify the Provider Is Working

Four checks, fastest first:

openclaw models status shows the active model, auth state per provider, and warns about OAuth tokens expiring within 24 hours.

openclaw models list --provider openai prints the exact refs available to you.

/model status inside any chat shows which auth candidates and endpoints the session resolves to.

Message your agent. If it answers, the loop is closed.

Guided onboarding already live-tests credentials before saving them, and the Control UI's Model Providers settings page shows per-provider auth state and model availability, with a Refresh action that re-reads credential state. Keys you add by hand-editing config or env files are not validated until first use, so run the checks above after any manual change.

Switching Providers Later

Switching is a one-liner: openclaw models set <provider/model> changes the configured default. Inside a chat, /model opens a numbered picker that changes the model for that session only, and /model default reverts it. Session picks are strict by design: if your chosen model goes down, the run fails visibly rather than silently falling back.

For the full wizard walkthrough, including verification steps, see how to change the default AI model in OpenClaw.

Fixing Common OpenClaw LLM Provider Errors

"Model is not allowed". You have a model allowlist configured under agents.defaults.modelPolicy.allow, and the ref you asked for is not on it. Add the full provider-prefixed ref (for local models too: ollama/gemma4:26b, not the bare model name), or clear the allowlist.

The provider reported as not configured, or the model as unsupported. Current builds surface this as "Unknown model: provider/model": either the provider has no entry or auth profile, so the ref cannot resolve, or your installed release's catalog does not include that model yet. Run openclaw models status, re-authenticate the provider, check the ref spelling (refs are lowercase and split on the first slash), and upgrade OpenClaw if the model is newer than your install. Its sibling, "No credentials found for profile", means the Gateway has no stored credential for that provider. Re-run auth for it.

Gateway refuses to start after a config edit. Strict validation rejected an unknown key or a malformed type. Run openclaw doctor --fix.

Your key is set but never used. It is sitting in a workspace .env, which OpenClaw ignores for provider credentials. Move it to ~/.openclaw/.env.

Ollama connects but tool calls come out as raw JSON text. You pointed OpenClaw at Ollama's /v1 OpenAI-compatible URL. Use the native URL without /v1; the docs are explicit that the /v1 path breaks tool calling.

You added a new provider but the model did not change. Working as designed. Adding auth preserves your primary model. Run openclaw models set or redo the login with --set-default.

Which LLM Provider Should You Pick?

Three heuristics:

Default choice: Anthropic or OpenAI. Most tested with OpenClaw, least surprising in agent loops.

Cost-sensitive: DeepSeek, Kimi, or GLM directly, or route through OpenRouter and let openrouter/auto optimize.

Privacy-first: local via Ollama or LM Studio, if you have the hardware for it.

Model-by-model comparisons, agent cost math, and speed trade-offs live in our dedicated guide to the best AI models for OpenClaw.

Run It Always-On

A perfectly configured provider only answers while OpenClaw itself is running. Close the laptop and your agent goes dark mid-conversation.

That is why most people end up moving OpenClaw somewhere always-on. Agent37 hosts OpenClaw from $3.99/mo: your instance deploys in one click, you get a full web terminal to run every command in this guide, and keys stay yours. Each instance is an isolated container, and your API keys go straight from your container to the model provider.

Fair warning on cost, because OpenClaw itself is free software: you pay the model provider for tokens, plus whatever always-on machine runs the agent. The full math is in our OpenClaw hosting pricing breakdown.

Configure the provider once, put it somewhere that never sleeps, and your agent stops being a demo and starts being staff.