Skip to main content
ClawCentral

In ClawCentral, AI providers and API keys are configured via Admin UI → Settings → AI Providers. The openclaw.json config examples and CLI commands (openclaw onboard, openclaw models set) described below apply to self-hosted OpenClaw deployments.

Model providers

This page covers LLM/model providers (not chat channels like WhatsApp/Telegram). For model selection rules, see /concepts/models.

Quick rules​

  • Model refs use provider/model (example: opencode/claude-opus-4-6).
  • If you set agents.defaults.models, it becomes the allowlist.
  • CLI helpers: openclaw onboard, openclaw models list, openclaw models set <provider/model>.
  • Provider plugins can inject model catalogs via registerProvider({ catalog }); OpenClaw merges that output into models.providers before writing models.json.
  • Provider manifests can declare providerAuthEnvVars so generic env-based auth probes do not need to load plugin runtime. The remaining core env-var map is now just for non-plugin/core providers and a few generic-precedence cases such as Anthropic API-key-first onboarding.
  • Provider plugins can also own provider runtime behavior via resolveDynamicModel, prepareDynamicModel, normalizeResolvedModel, capabilities, prepareExtraParams, wrapStreamFn, formatApiKey, refreshOAuth, buildAuthDoctorHint, isCacheTtlEligible, buildMissingAuthMessage, suppressBuiltInModel, augmentModelCatalog, isBinaryThinking, supportsXHighThinking, resolveDefaultThinkingLevel, isModernModelRef, prepareRuntimeAuth, resolveUsageAuth, and fetchUsageSnapshot.
  • Note: provider runtime capabilities is shared runner metadata (provider family, transcript/tooling quirks, transport/cache hints). It is not the same as the public capability model which describes what a plugin registers (text inference, speech, etc.).

Plugin-owned provider behavior​

Provider plugins can now own most provider-specific logic while OpenClaw keeps the generic inference loop.

Typical split:

  • auth[].run / auth[].runNonInteractive: provider owns onboarding/login flows for openclaw onboard, openclaw models auth, and headless setup
  • wizard.setup / wizard.modelPicker: provider owns auth-choice labels, legacy aliases, onboarding allowlist hints, and setup entries in onboarding/model pickers
  • catalog: provider appears in models.providers
  • resolveDynamicModel: provider accepts model ids not present in the local static catalog yet
  • prepareDynamicModel: provider needs a metadata refresh before retrying dynamic resolution
  • normalizeResolvedModel: provider needs transport or base URL rewrites
  • capabilities: provider publishes transcript/tooling/provider-family quirks
  • prepareExtraParams: provider defaults or normalizes per-model request params
  • wrapStreamFn: provider applies request headers/body/model compat wrappers
  • formatApiKey: provider formats stored auth profiles into the runtime apiKey string expected by the transport
  • refreshOAuth: provider owns OAuth refresh when the shared pi-ai refreshers are not enough
  • buildAuthDoctorHint: provider appends repair guidance when OAuth refresh fails
  • isCacheTtlEligible: provider decides which upstream model ids support prompt-cache TTL
  • buildMissingAuthMessage: provider replaces the generic auth-store error with a provider-specific recovery hint
  • suppressBuiltInModel: provider hides stale upstream rows and can return a vendor-owned error for direct resolution failures
  • augmentModelCatalog: provider appends synthetic/final catalog rows after discovery and config merging
  • isBinaryThinking: provider owns binary on/off thinking UX
  • supportsXHighThinking: provider opts selected models into xhigh
  • resolveDefaultThinkingLevel: provider owns default /think policy for a model family
  • isModernModelRef: provider owns live/smoke preferred-model matching
  • prepareRuntimeAuth: provider turns a configured credential into a short lived runtime token
  • resolveUsageAuth: provider resolves usage/quota credentials for /usage and related status/reporting surfaces
  • fetchUsageSnapshot: provider owns the usage endpoint fetch/parsing while core still owns the summary shell and formatting

Current bundled examples:

  • anthropic: Claude 4.6 forward-compat fallback, auth repair hints, usage endpoint fetching, and cache-TTL/provider-family metadata
  • openrouter: pass-through model ids, request wrappers, provider capability hints, and cache-TTL policy
  • github-copilot: onboarding/device login, forward-compat model fallback, Claude-thinking transcript hints, runtime token exchange, and usage endpoint fetching
  • openai: GPT-5.4 forward-compat fallback, direct OpenAI transport normalization, Codex-aware missing-auth hints, Spark suppression, synthetic OpenAI/Codex catalog rows, thinking/live-model policy, and provider-family metadata
  • google and google-gemini-cli: Gemini 3.1 forward-compat fallback and modern-model matching; Gemini CLI OAuth also owns auth-profile token formatting, usage-token parsing, and quota endpoint fetching for usage surfaces
  • moonshot: shared transport, plugin-owned thinking payload normalization
  • kilocode: shared transport, plugin-owned request headers, reasoning payload normalization, Gemini transcript hints, and cache-TTL policy
  • zai: GLM-5 forward-compat fallback, tool_stream defaults, cache-TTL policy, binary-thinking/live-model policy, and usage auth + quota fetching
  • mistral, opencode, and opencode-go: plugin-owned capability metadata
  • byteplus, cloudflare-ai-gateway, huggingface, kimi-coding, modelstudio, nvidia, qianfan, synthetic, together, venice, vercel-ai-gateway, and volcengine: plugin-owned catalogs only
  • qwen-portal: plugin-owned catalog, OAuth login, and OAuth refresh
  • minimax and xiaomi: plugin-owned catalogs plus usage auth/snapshot logic

The bundled openai plugin now owns both provider ids: openai and openai-codex.

That covers providers that still fit OpenClaw's normal transports. A provider that needs a totally custom request executor is a separate, deeper extension surface.

API key rotation​

  • Supports generic provider rotation for selected providers.
  • Configure multiple keys via:
    • OPENCLAW_LIVE_<PROVIDER>_KEY (single live override, highest priority)
    • <PROVIDER>_API_KEYS (comma or semicolon list)
    • <PROVIDER>_API_KEY (primary key)
    • <PROVIDER>_API_KEY_* (numbered list, e.g. <PROVIDER>_API_KEY_1)
  • For Google providers, GOOGLE_API_KEY is also included as fallback.
  • Key selection order preserves priority and deduplicates values.
  • Requests are retried with the next key only on rate-limit responses (for example 429, rate_limit, quota, resource exhausted).
  • Non-rate-limit failures fail immediately; no key rotation is attempted.
  • When all candidate keys fail, the final error is returned from the last attempt.

Built-in providers (pi-ai catalog)​

OpenClaw ships with the pi‑ai catalog. These providers require no models.providers config; just set auth + pick a model.

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.4, openai/gpt-5.4-pro
  • CLI: openclaw onboard --auth-choice openai-api-key
  • Default transport is auto (WebSocket-first, SSE fallback)
  • Override per model via agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket", or "auto")
  • OpenAI Responses WebSocket warm-up defaults to enabled via params.openaiWsWarmup (true/false)
  • OpenAI priority processing can be enabled via agents.defaults.models["openai/<model>"].params.serviceTier
  • OpenAI fast mode can be enabled per model via agents.defaults.models["<provider>/<model>"].params.fastMode
  • openai/gpt-5.3-codex-spark is intentionally suppressed in OpenClaw because the live OpenAI API rejects it; Spark is treated as Codex-only
{
  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
}

Anthropic​

  • Provider: anthropic
  • Auth: ANTHROPIC_API_KEY or claude setup-token
  • 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 token (paste setup-token) or openclaw models auth paste-token --provider anthropic
  • Direct API-key models support the shared /fast toggle and params.fastMode; OpenClaw maps that to Anthropic service_tier (auto vs standard_only)
  • Policy note: setup-token support is technical compatibility; Anthropic has blocked some subscription usage outside Claude Code in the past. Verify current Anthropic terms and decide based on your risk tolerance.
  • Recommendation: Anthropic API key auth is the safer, recommended path over subscription setup-token auth.
{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

OpenAI Code (Codex)​

  • Provider: openai-codex
  • Auth: OAuth (ChatGPT)
  • Example model: openai-codex/gpt-5.4
  • CLI: openclaw onboard --auth-choice openai-codex or openclaw models auth login --provider openai-codex
  • Default transport is auto (WebSocket-first, SSE fallback)
  • Override per model via agents.defaults.models["openai-codex/<model>"].params.transport ("sse", "websocket", or "auto")
  • Shares the same /fast toggle and params.fastMode config as direct openai/*
  • openai-codex/gpt-5.3-codex-spark remains available when the Codex OAuth catalog exposes it; entitlement-dependent
  • Policy note: OpenAI Codex OAuth is explicitly supported for external tools/workflows like OpenClaw.
{
  agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
}

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.5
  • 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
  • CLI: openclaw onboard --auth-choice gemini-api-key

Google Vertex and Gemini CLI​

  • Providers: google-vertex, google-gemini-cli
  • Auth: Vertex uses gcloud ADC; Gemini CLI uses its OAuth flow
  • Caution: Gemini CLI OAuth in OpenClaw is an unofficial integration. Some users have reported Google account restrictions after using third-party clients. Review Google terms and use a non-critical account if you choose to proceed.
  • Gemini CLI OAuth is shipped as part of the bundled google plugin.
    • Enable: openclaw plugins enable google
    • Login: openclaw models auth login --provider google-gemini-cli --set-default
    • Note: you do not paste a client id or secret into openclaw.json. The CLI login flow stores tokens in auth profiles on the gateway host.

Z.AI (GLM)​

  • Provider: zai
  • Auth: ZAI_API_KEY
  • Example model: zai/glm-5
  • CLI: openclaw onboard --auth-choice zai-api-key
    • Aliases: z.ai/* and z-ai/* normalize to zai/*

Vercel AI Gateway​

  • Provider: vercel-ai-gateway
  • Auth: AI_GATEWAY_API_KEY
  • Example model: vercel-ai-gateway/anthropic/claude-opus-4.6
  • CLI: openclaw onboard --auth-choice ai-gateway-api-key

Kilo Gateway​

  • Provider: kilocode
  • Auth: KILOCODE_API_KEY
  • Example model: kilocode/anthropic/claude-opus-4.6
  • CLI: openclaw onboard --kilocode-api-key <key>
  • Base URL: https://api.kilo.ai/api/gateway/
  • Expanded built-in catalog includes GLM-5 Free, MiniMax M2.5 Free, GPT-5.2, Gemini 3 Pro Preview, Gemini 3 Flash Preview, Grok Code Fast 1, and Kimi K2.5.

See /providers/kilocode for setup details.

Other bundled provider plugins​

  • OpenRouter: openrouter (OPENROUTER_API_KEY)
  • Example model: openrouter/anthropic/claude-sonnet-4-5
  • Kilo Gateway: kilocode (KILOCODE_API_KEY)
  • Example model: kilocode/anthropic/claude-opus-4.6
  • MiniMax: minimax (MINIMAX_API_KEY)
  • Moonshot: moonshot (MOONSHOT_API_KEY)
  • Kimi Coding: kimi-coding (KIMI_API_KEY or KIMICODE_API_KEY)
  • Qianfan: qianfan (QIANFAN_API_KEY)
  • Model Studio: modelstudio (MODELSTUDIO_API_KEY)
  • NVIDIA: nvidia (NVIDIA_API_KEY)
  • Together: together (TOGETHER_API_KEY)
  • Venice: venice (VENICE_API_KEY)
  • Xiaomi: xiaomi (XIAOMI_API_KEY)
  • Vercel AI Gateway: vercel-ai-gateway (AI_GATEWAY_API_KEY)
  • Hugging Face Inference: huggingface (HUGGINGFACE_HUB_TOKEN or HF_TOKEN)
  • Cloudflare AI Gateway: cloudflare-ai-gateway (CLOUDFLARE_AI_GATEWAY_API_KEY)
  • Volcengine: volcengine (VOLCANO_ENGINE_API_KEY)
  • BytePlus: byteplus (BYTEPLUS_API_KEY)
  • xAI: xai (XAI_API_KEY)
  • Mistral: mistral (MISTRAL_API_KEY)
  • Example model: mistral/mistral-large-latest
  • CLI: openclaw onboard --auth-choice mistral-api-key
  • Groq: groq (GROQ_API_KEY)
  • Cerebras: cerebras (CEREBRAS_API_KEY)
    • GLM models on Cerebras use ids zai-glm-4.7 and zai-glm-4.6.
    • OpenAI-compatible base URL: https://api.cerebras.ai/v1.
  • GitHub Copilot: github-copilot (COPILOT_GITHUB_TOKEN / GH_TOKEN / GITHUB_TOKEN)
  • Hugging Face Inference example model: huggingface/deepseek-ai/DeepSeek-R1; CLI: openclaw onboard --auth-choice huggingface-api-key. See Hugging Face (Inference).

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.

Moonshot AI (Kimi)​

Moonshot uses OpenAI-compatible endpoints, so configure it as a custom provider:

  • Provider: moonshot
  • Auth: MOONSHOT_API_KEY
  • Example model: moonshot/kimi-k2.5

Kimi K2 model IDs:

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

Kimi Coding​

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

  • Provider: kimi-coding
  • Auth: KIMI_API_KEY
  • Example model: kimi-coding/k2p5
{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: { model: { primary: "kimi-coding/k2p5" } },
  },
}

Qwen OAuth (free tier)​

Qwen provides OAuth access to Qwen Coder + Vision via a device-code flow. The bundled provider plugin is enabled by default, so just log in:

openclaw models auth login --provider qwen-portal --set-default

Model refs:

  • qwen-portal/coder-model
  • qwen-portal/vision-model

See /providers/qwen for setup details and notes.

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/doubao-seed-1-8-251228
  • CLI: openclaw onboard --auth-choice volcengine-api-key
{
  agents: {
    defaults: { model: { primary: "volcengine/doubao-seed-1-8-251228" } },
  },
}

Available models:

  • volcengine/doubao-seed-1-8-251228 (Doubao Seed 1.8)
  • volcengine/doubao-seed-code-preview-251028
  • volcengine/kimi-k2-5-260127 (Kimi K2.5)
  • volcengine/glm-4-7-251222 (GLM 4.7)
  • volcengine/deepseek-v3-2-251201 (DeepSeek V3.2 128K)

Coding models (volcengine-plan):

  • volcengine-plan/ark-code-latest
  • volcengine-plan/doubao-seed-code
  • volcengine-plan/kimi-k2.5
  • volcengine-plan/kimi-k2-thinking
  • volcengine-plan/glm-4.7

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/seed-1-8-251228
  • CLI: openclaw onboard --auth-choice byteplus-api-key
{
  agents: {
    defaults: { model: { primary: "byteplus/seed-1-8-251228" } },
  },
}

Available models:

  • byteplus/seed-1-8-251228 (Seed 1.8)
  • byteplus/kimi-k2-5-260127 (Kimi K2.5)
  • byteplus/glm-4-7-251222 (GLM 4.7)

Coding models (byteplus-plan):

  • byteplus-plan/ark-code-latest
  • byteplus-plan/doubao-seed-code
  • byteplus-plan/kimi-k2.5
  • byteplus-plan/kimi-k2-thinking
  • byteplus-plan/glm-4.7

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 (Anthropic‑compatible): --auth-choice minimax-api
  • Auth: MINIMAX_API_KEY

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

Ollama​

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

# 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/minimax-m2.5-gs32" },
      models: { "lmstudio/minimax-m2.5-gs32": { alias: "Minimax" } },
    },
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "LMSTUDIO_KEY",
        api: "openai-completions",
        models: [
          {
            id: "minimax-m2.5-gs32",
            name: "MiniMax M2.5",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

Notes:

  • For custom providers, reasoning, input, cost, contextWindow, and maxTokens are optional. When omitted, OpenClaw defaults to:
    • reasoning: false
    • input: ["text"]
    • cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
    • contextWindow: 200000
    • maxTokens: 8192
  • Recommended: set explicit values that match your proxy/model limits.
  • For api: "openai-completions" on non-native endpoints (any non-empty baseUrl whose host is not api.openai.com), OpenClaw forces compat.supportsDeveloperRole: false to avoid provider 400 errors for unsupported developer roles.
  • If baseUrl is empty/omitted, OpenClaw keeps the default OpenAI behavior (which resolves to api.openai.com).
  • For safety, an explicit compat.supportsDeveloperRole: true is still overridden on non-native openai-completions endpoints.

CLI examples​

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

See also: /gateway/configuration for full configuration examples.