Model providers

Reference for LLM/model providers (not chat channels like WhatsApp/Telegram). For model selection rules, see Models.

Quick rules

Plugin-owned provider behavior

Most provider-specific logic lives in provider plugins (registerProvider(...)) while OpenClaw keeps the generic inference loop. Plugins own onboarding, model catalogs, auth env-var mapping, transport/config normalization, tool-schema cleanup, failover classification, OAuth refresh, usage reporting, thinking/reasoning profiles, and more.

The full list of provider-SDK hooks and bundled-plugin examples lives in Provider plugins. A provider that needs a totally custom request executor is a separate, deeper extension surface.

API key rotation

Official provider plugins

Official provider plugins publish their own model catalog rows. These providers require no models.providers model entries; enable the provider plugin, set auth, and pick a model. Use models.providers only for explicit custom providers or narrow request settings such as timeouts.

OpenAI

• Provider: openai
• Auth: OPENAI_API_KEY
• Optional rotation: OPENAI_API_KEYS, OPENAI_API_KEY_1, OPENAI_API_KEY_2, plus OPENCLAW_LIVE_OPENAI_KEY (single override)
• Example models: openai/gpt-5.5, openai/gpt-5.4-mini
• Verify account/model availability with openclaw models list --provider openai if a specific install or API key behaves differently.
• CLI: openclaw onboard --auth-choice openai-api-key
• Default transport is auto; OpenClaw passes the transport choice to the shared model runtime.
• Override per model via agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket", or "auto")
• OpenAI priority processing can be enabled via agents.defaults.models["openai/<model>"].params.serviceTier
• /fast and params.fastMode map direct openai/* Responses requests to service_tier=priority on api.openai.com
• Use params.serviceTier when you want an explicit tier instead of the shared /fast toggle
• Hidden OpenClaw attribution headers (originator, version, User-Agent) apply only on native OpenAI traffic to api.openai.com, not generic OpenAI-compatible proxies
• Native OpenAI routes also keep Responses store, prompt-cache hints, and OpenAI reasoning-compat payload shaping; proxy routes do not
• openai/gpt-5.3-codex-spark is intentionally suppressed in OpenClaw because live OpenAI API requests reject it and the current Codex catalog does not expose it

{  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },}

Anthropic

• Provider: anthropic
• Auth: ANTHROPIC_API_KEY
• Optional rotation: ANTHROPIC_API_KEYS, ANTHROPIC_API_KEY_1, ANTHROPIC_API_KEY_2, plus OPENCLAW_LIVE_ANTHROPIC_KEY (single override)
• Example model: anthropic/claude-opus-4-6
• CLI: openclaw onboard --auth-choice apiKey
• Direct public Anthropic requests support the shared /fast toggle and params.fastMode, including API-key and OAuth-authenticated traffic sent to api.anthropic.com; OpenClaw maps that to Anthropic service_tier (auto vs standard_only)
• Preferred Claude CLI config keeps the model ref canonical and selects the CLI backend separately: anthropic/claude-opus-4-8 with model-scoped agentRuntime.id: "claude-cli". Legacy claude-cli/claude-opus-4-7 refs still work for compatibility.

{  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },}

OpenAI ChatGPT/Codex OAuth

• Provider: openai
• Auth: OAuth (ChatGPT)
• Legacy OpenAI Codex model ref: openai/gpt-5.5
• Native Codex app-server harness ref: openai/gpt-5.5
• Native Codex app-server harness docs: Codex harness
• Legacy model refs: codex/gpt-*
• Plugin boundary: openai/* loads the OpenAI plugin; the native Codex app-server plugin is selected by the Codex harness runtime.
• CLI: openclaw onboard --auth-choice openai or openclaw models auth login --provider openai
• Default transport is auto (WebSocket-first, SSE fallback)
• Override per OpenAI Codex model via agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket", or "auto")
• params.serviceTier is also forwarded on native Codex Responses requests (chatgpt.com/backend-api)
• Hidden OpenClaw attribution headers (originator, version, User-Agent) are only attached on native Codex traffic to chatgpt.com/backend-api, not generic OpenAI-compatible proxies
• Shares the same /fast toggle and params.fastMode config as direct openai/*; OpenClaw maps that to service_tier=priority
• openai/gpt-5.5 uses the Codex catalog native contextWindow = 400000 and default runtime contextTokens = 272000; override the runtime cap with models.providers.openai.models[].contextTokens
• Policy note: OpenAI Codex OAuth is explicitly supported for external tools/workflows like OpenClaw.
• For the common subscription plus native Codex runtime route, sign in with openai auth and configure openai/gpt-5.5; OpenAI agent turns select Codex by default.
• Use provider/model agentRuntime.id: "openclaw" only when you want the built-in OpenClaw route; otherwise keep openai/gpt-5.5 on the default Codex harness.
• legacy Codex GPT refs are legacy state, not a live provider route. Use openai/gpt-5.5 on the native Codex runtime for new agent config, and run openclaw doctor --fix to migrate old legacy Codex model refs to canonical openai/* refs.

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.5" },    },  },}

{  models: {    providers: {      openai: {        models: [{ id: "gpt-5.5", contextTokens: 160000 }],      },    },  },}

Other subscription-style hosted options

OpenCode

• Auth: OPENCODE_API_KEY (or OPENCODE_ZEN_API_KEY)
• Zen runtime provider: opencode
• Go runtime provider: opencode-go
• Example models: opencode/claude-opus-4-6, opencode-go/kimi-k2.6
• CLI: openclaw onboard --auth-choice opencode-zen or openclaw onboard --auth-choice opencode-go

{  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },}

Google Gemini (API key)

• Provider: google
• Auth: GEMINI_API_KEY
• Optional rotation: GEMINI_API_KEYS, GEMINI_API_KEY_1, GEMINI_API_KEY_2, GOOGLE_API_KEY fallback, and OPENCLAW_LIVE_GEMINI_KEY (single override)
• Example models: google/gemini-3.1-pro-preview, google/gemini-3-flash-preview
• Compatibility: legacy OpenClaw config using google/gemini-3.1-flash-preview is normalized to google/gemini-3-flash-preview
• Alias: google/gemini-3.1-pro is accepted and normalized to Google's live Gemini API id, google/gemini-3.1-pro-preview
• CLI: openclaw onboard --auth-choice gemini-api-key
• Thinking: /think adaptive uses Google dynamic thinking. Gemini 3/3.1 omit a fixed thinkingLevel; Gemini 2.5 sends thinkingBudget: -1.
• Direct Gemini runs also accept agents.defaults.models["google/<model>"].params.cachedContent (or legacy cached_content) to forward a provider-native cachedContents/... handle; Gemini cache hits surface as OpenClaw cacheRead

Google Vertex and Gemini CLI

• Providers: google-vertex, google-gemini-cli
• Auth: Vertex uses gcloud ADC; Gemini CLI uses its OAuth flow

Gemini CLI OAuth is shipped as part of the bundled google plugin.

brew install gemini-cli

npm install -g @google/gemini-cli

openclaw plugins enable google

openclaw models auth login --provider google-gemini-cli --set-default

Gemini CLI JSON replies are parsed from response; usage falls back to stats, with stats.cached normalized into OpenClaw cacheRead.

Z.AI (GLM)

• Provider: zai
• Auth: ZAI_API_KEY
• Example model: zai/glm-5.2
• CLI: openclaw onboard --auth-choice zai-api-key
  • Model refs use the canonical zai/* provider ID.
  • zai-api-key auto-detects the matching Z.AI endpoint; zai-coding-global, zai-coding-cn, zai-global, and zai-cn force a specific surface

Vercel AI Gateway

• Provider: vercel-ai-gateway
• Auth: AI_GATEWAY_API_KEY
• Example models: vercel-ai-gateway/anthropic/claude-opus-4.6, vercel-ai-gateway/moonshotai/kimi-k2.6
• CLI: openclaw onboard --auth-choice ai-gateway-api-key

Kilo Gateway

• Provider: kilocode
• Auth: KILOCODE_API_KEY
• Example model: kilocode/kilo/auto
• CLI: openclaw onboard --auth-choice kilocode-api-key
• Base URL: https://api.kilo.ai/api/gateway/
• Static fallback catalog ships kilocode/kilo/auto; live https://api.kilo.ai/api/gateway/models discovery can expand the runtime catalog further.
• Exact upstream routing behind kilocode/kilo/auto is owned by Kilo Gateway, not hard-coded in OpenClaw.

See /providers/kilocode for setup details.

Other bundled provider plugins

Quirks worth knowing

Providers via models.providers (custom/base URL)

Use models.providers (or models.json) to add custom providers or OpenAI/Anthropic-compatible proxies.

Many of the bundled provider plugins below already publish a default catalog. Use explicit models.providers.<id> entries only when you want to override the default base URL, headers, or model list.

Gateway model capability checks also read explicit models.providers.<id>.models[] metadata. If a custom or proxy model accepts images, set input: ["text", "image"] on that model so WebChat and node-origin attachment paths pass images as native model inputs instead of text-only media refs.

agents.defaults.models["provider/model"] only controls model visibility, aliases, and per-model metadata for agents. It does not register a new runtime model by itself. For custom provider models, also add models.providers.<provider>.models[] with at least the matching id.

Moonshot AI (Kimi)

Moonshot ships as a bundled provider plugin. Use the built-in provider by default, and add an explicit models.providers.moonshot entry only when you need to override the base URL or model metadata:

• Provider: moonshot
• Auth: MOONSHOT_API_KEY
• Example model: moonshot/kimi-k2.6
• CLI: openclaw onboard --auth-choice moonshot-api-key or openclaw onboard --auth-choice moonshot-api-key-cn

Kimi K2 model IDs:

• moonshot/kimi-k2.6
• moonshot/kimi-k2.7-code
• moonshot/kimi-k2.5
• moonshot/kimi-k2-thinking
• moonshot/kimi-k2-thinking-turbo
• moonshot/kimi-k2-turbo

{  agents: {    defaults: { model: { primary: "moonshot/kimi-k2.6" } },  },  models: {    mode: "merge",    providers: {      moonshot: {        baseUrl: "https://api.moonshot.ai/v1",        apiKey: "${MOONSHOT_API_KEY}",        api: "openai-completions",        models: [{ id: "kimi-k2.6", name: "Kimi K2.6" }],      },    },  },}

Kimi coding

Kimi Coding uses Moonshot AI's Anthropic-compatible endpoint:

• Provider: kimi
• Auth: KIMI_API_KEY
• Example model: kimi/kimi-for-coding

{  env: { KIMI_API_KEY: "sk-..." },  agents: {    defaults: { model: { primary: "kimi/kimi-for-coding" } },  },}

Legacy kimi/kimi-code and kimi/k2p5 remain accepted as compatibility model ids and normalize to Kimi's stable API model id.

Volcano Engine (Doubao)

Volcano Engine (火山引擎) provides access to Doubao and other models in China.

• Provider: volcengine (coding: volcengine-plan)
• Auth: VOLCANO_ENGINE_API_KEY
• Example model: volcengine-plan/ark-code-latest
• CLI: openclaw onboard --auth-choice volcengine-api-key

{  agents: {    defaults: { model: { primary: "volcengine-plan/ark-code-latest" } },  },}

Onboarding defaults to the coding surface, but the general volcengine/* catalog is registered at the same time.

In onboarding/configure model pickers, the Volcengine auth choice prefers both volcengine/* and volcengine-plan/* rows. If those models are not loaded yet, OpenClaw falls back to the unfiltered catalog instead of showing an empty provider-scoped picker.

BytePlus (International)

BytePlus ARK provides access to the same models as Volcano Engine for international users.

• Provider: byteplus (coding: byteplus-plan)
• Auth: BYTEPLUS_API_KEY
• Example model: byteplus-plan/ark-code-latest
• CLI: openclaw onboard --auth-choice byteplus-api-key

{  agents: {    defaults: { model: { primary: "byteplus-plan/ark-code-latest" } },  },}

Onboarding defaults to the coding surface, but the general byteplus/* catalog is registered at the same time.

In onboarding/configure model pickers, the BytePlus auth choice prefers both byteplus/* and byteplus-plan/* rows. If those models are not loaded yet, OpenClaw falls back to the unfiltered catalog instead of showing an empty provider-scoped picker.

Synthetic

Synthetic provides Anthropic-compatible models behind the synthetic provider:

• Provider: synthetic
• Auth: SYNTHETIC_API_KEY
• Example model: synthetic/hf:MiniMaxAI/MiniMax-M2.5
• CLI: openclaw onboard --auth-choice synthetic-api-key

{  agents: {    defaults: { model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" } },  },  models: {    mode: "merge",    providers: {      synthetic: {        baseUrl: "https://api.synthetic.new/anthropic",        apiKey: "${SYNTHETIC_API_KEY}",        api: "anthropic-messages",        models: [{ id: "hf:MiniMaxAI/MiniMax-M2.5", name: "MiniMax M2.5" }],      },    },  },}

MiniMax

MiniMax is configured via models.providers because it uses custom endpoints:

• MiniMax OAuth (Global): --auth-choice minimax-global-oauth
• MiniMax OAuth (CN): --auth-choice minimax-cn-oauth
• MiniMax API key (Global): --auth-choice minimax-global-api
• MiniMax API key (CN): --auth-choice minimax-cn-api
• Auth: MINIMAX_API_KEY for minimax; MINIMAX_OAUTH_TOKEN or MINIMAX_API_KEY for minimax-portal

See /providers/minimax for setup details, model options, and config snippets.

Plugin-owned capability split:

• Text/chat defaults stay on minimax/MiniMax-M3
• Image generation is minimax/image-01 or minimax-portal/image-01
• Image understanding is plugin-owned MiniMax-VL-01 on both MiniMax auth paths
• Web search stays on provider id minimax

LM Studio

LM Studio ships as a bundled provider plugin which uses the native API:

• Provider: lmstudio
• Auth: LM_API_TOKEN
• Default inference base URL: http://localhost:1234/v1

Then set a model (replace with one of the IDs returned by http://localhost:1234/api/v1/models):

{  agents: {    defaults: { model: { primary: "lmstudio/openai/gpt-oss-20b" } },  },}

OpenClaw uses LM Studio's native /api/v1/models and /api/v1/models/load for discovery + auto-load, with /v1/chat/completions for inference by default. If you want LM Studio JIT loading, TTL, and auto-evict to own model lifecycle, set models.providers.lmstudio.params.preload: false. See /providers/lmstudio for setup and troubleshooting.

Ollama

Ollama ships as a bundled provider plugin and uses Ollama's native API:

• Provider: ollama
• Auth: None required (local server)
• Example model: ollama/llama3.3
• Installation: https://ollama.com/download

# Install Ollama, then pull a model:ollama pull llama3.3

{  agents: {    defaults: { model: { primary: "ollama/llama3.3" } },  },}

Ollama is detected locally at http://127.0.0.1:11434 when you opt in with OLLAMA_API_KEY, and the bundled provider plugin adds Ollama directly to openclaw onboard and the model picker. See /providers/ollama for onboarding, cloud/local mode, and custom configuration.

vLLM

vLLM ships as a bundled provider plugin for local/self-hosted OpenAI-compatible servers:

• Provider: vllm
• Auth: Optional (depends on your server)
• Default base URL: http://127.0.0.1:8000/v1

To opt in to auto-discovery locally (any value works if your server doesn't enforce auth):

export VLLM_API_KEY="vllm-local"

Then set a model (replace with one of the IDs returned by /v1/models):

{  agents: {    defaults: { model: { primary: "vllm/your-model-id" } },  },}

See /providers/vllm for details.

SGLang

SGLang ships as a bundled provider plugin for fast self-hosted OpenAI-compatible servers:

• Provider: sglang
• Auth: Optional (depends on your server)
• Default base URL: http://127.0.0.1:30000/v1

To opt in to auto-discovery locally (any value works if your server does not enforce auth):

export SGLANG_API_KEY="sglang-local"

Then set a model (replace with one of the IDs returned by /v1/models):

{  agents: {    defaults: { model: { primary: "sglang/your-model-id" } },  },}

See /providers/sglang for details.

Local proxies (LM Studio, vLLM, LiteLLM, etc.)

Example (OpenAI-compatible):

{  agents: {    defaults: {      model: { primary: "lmstudio/my-local-model" },      models: { "lmstudio/my-local-model": { alias: "Local" } },    },  },  models: {    providers: {      lmstudio: {        baseUrl: "http://localhost:1234/v1",        apiKey: "${LM_API_TOKEN}",        api: "openai-completions",        timeoutSeconds: 300,        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 200000,            maxTokens: 8192,          },        ],      },    },  },}

CLI examples

openclaw onboard --auth-choice opencode-zenopenclaw models set opencode/claude-opus-4-6openclaw models list

See also: Configuration for full configuration examples.

Related

• Configuration reference - model config keys
• Model failover - fallback chains and retry behavior
• Models - model configuration and aliases
• Providers - per-provider setup guides