​

Model providers

​

Quick rules

• model ref는 provider/model 형식을 사용합니다 (예: opencode/claude-opus-4-6)
• agents.defaults.models를 설정하면 allowlist가 됩니다
• CLI helper: openclaw onboard, openclaw models list, openclaw models set <provider/model>

​

API key rotation

• 선택된 provider에 대해 generic provider rotation을 지원합니다
• 여러 key는 다음 방식으로 설정합니다
  • OPENCLAW_LIVE_<PROVIDER>_KEY (single live override, 최우선)
  • <PROVIDER>_API_KEYS (comma 또는 semicolon list)
  • <PROVIDER>_API_KEY (primary key)
  • <PROVIDER>_API_KEY_* (번호 목록, 예: <PROVIDER>_API_KEY_1)
• Google provider는 GOOGLE_API_KEY도 fallback으로 포함합니다
• key selection order는 priority를 보존하고 value를 dedupe합니다
• request는 rate-limit response에서만 다음 key로 retry합니다 (예: 429, rate_limit, quota, resource exhausted)
• rate-limit이 아닌 failure는 즉시 실패하며 key rotation을 시도하지 않습니다
• 모든 candidate key가 실패하면 마지막 시도의 error를 반환합니다

​

Built-in providers (pi-ai catalog)

​

OpenAI

• Provider: openai
• Auth: OPENAI_API_KEY
• Optional rotation: OPENAI_API_KEYS, OPENAI_API_KEY_1, OPENAI_API_KEY_2, 그리고 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
• 기본 transport는 auto (WebSocket-first, SSE fallback)
• model별 override: agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket", "auto")
• OpenAI Responses WebSocket warm-up은 params.openaiWsWarmup (true/false)로 기본 활성화
• OpenAI priority processing은 agents.defaults.models["openai/<model>"].params.serviceTier로 활성화 가능

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

​

Anthropic

• Provider: anthropic
• Auth: ANTHROPIC_API_KEY 또는 claude setup-token
• Optional rotation: ANTHROPIC_API_KEYS, ANTHROPIC_API_KEY_1, ANTHROPIC_API_KEY_2, 그리고 OPENCLAW_LIVE_ANTHROPIC_KEY (single override)
• Example model: anthropic/claude-opus-4-6
• CLI: openclaw onboard --auth-choice token (setup-token 붙여 넣기) 또는 openclaw models auth paste-token --provider anthropic
• Policy note: setup-token 지원은 기술적 호환성을 의미합니다. Anthropic은 과거 Claude Code 외부의 일부 subscription usage를 막은 적이 있으므로, 현재 terms를 확인하고 risk tolerance에 맞게 판단하세요
• Recommendation: Anthropic API key auth가 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 또는 openclaw models auth login --provider openai-codex
• 기본 transport는 auto (WebSocket-first, SSE fallback)
• model별 override: agents.defaults.models["openai-codex/<model>"].params.transport ("sse", "websocket", "auto")
• Policy note: OpenAI Codex OAuth는 OpenClaw 같은 external tool/workflow에서의 사용이 명시적으로 지원됩니다

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

​

OpenCode

• Auth: OPENCODE_API_KEY (또는 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 또는 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, OPENCLAW_LIVE_GEMINI_KEY (single override)
• Example models: google/gemini-3.1-pro-preview, google/gemini-3-flash-preview
• Compatibility: legacy OpenClaw config의 google/gemini-3.1-flash-preview는 google/gemini-3-flash-preview로 normalize됩니다
• CLI: openclaw onboard --auth-choice gemini-api-key

​

Google Vertex, Antigravity, and Gemini CLI

• Providers: google-vertex, google-antigravity, google-gemini-cli
• Auth: Vertex는 gcloud ADC, Antigravity/Gemini CLI는 각자의 auth flow 사용
• Caution: Antigravity와 Gemini CLI OAuth는 OpenClaw에서 unofficial integration입니다. 일부 사용자는 third-party client 사용 후 Google account restriction을 경험했다고 보고했습니다. 진행하기로 했다면 Google terms를 검토하고 중요하지 않은 account를 사용하는 편이 낫습니다
• Antigravity OAuth는 bundled plugin (google-antigravity-auth)으로 제공되며 기본 비활성화
  • Enable: openclaw plugins enable google-antigravity-auth
  • Login: openclaw models auth login --provider google-antigravity --set-default
• Gemini CLI OAuth는 bundled plugin (google-gemini-cli-auth)으로 제공되며 기본 비활성화
  • Enable: openclaw plugins enable google-gemini-cli-auth
  • Login: openclaw models auth login --provider google-gemini-cli --set-default
  • Note: client id나 secret을 openclaw.json에 붙여 넣지 않습니다. CLI login flow는 token을 gateway host의 auth profile에 저장합니다

​

Z.AI (GLM)

• Provider: zai
• Auth: ZAI_API_KEY
• Example model: zai/glm-5
• CLI: openclaw onboard --auth-choice zai-api-key
  • Alias: z.ai/*, z-ai/*는 zai/*로 normalize

​

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에는 GLM-5 Free, MiniMax M2.5 Free, GPT-5.2, Gemini 3 Pro Preview, Gemini 3 Flash Preview, Grok Code Fast 1, Kimi K2.5가 포함됩니다

​

Other built-in providers

• 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
• 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)
  • Cerebras의 GLM model id는 zai-glm-4.7, 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: huggingface (HUGGINGFACE_HUB_TOKEN 또는 HF_TOKEN) — OpenAI-compatible router
  • Example model: huggingface/deepseek-ai/DeepSeek-R1
  • CLI: openclaw onboard --auth-choice huggingface-api-key
  • 문서: Hugging Face (Inference)

​

Providers via models.providers (custom/base URL)

​

Moonshot AI (Kimi)

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

• 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

• 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)

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

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

​

Volcano Engine (Doubao)

• 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" } },
  },
}

• 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)

• 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)

• 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" } },
  },
}

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

• 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

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

​

Ollama

• Provider: ollama
• Auth: 필요 없음 (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" } },
  },
}

​

vLLM

• Provider: vllm
• Auth: optional (server 설정에 따름)
• Default base URL: http://127.0.0.1:8000/v1

export VLLM_API_KEY="vllm-local"

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

​

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

{
  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,
          },
        ],
      },
    },
  },
}

• custom provider에서 reasoning, input, cost, contextWindow, maxTokens는 optional입니다
• 생략하면 OpenClaw 기본값은 다음과 같습니다
  • reasoning: false
  • input: ["text"]
  • cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
  • contextWindow: 200000
  • maxTokens: 8192
• Recommendation: proxy/model의 실제 제한에 맞는 explicit 값을 설정하는 편이 좋습니다
• api: "openai-completions"를 non-native endpoint에서 쓸 때 (baseUrl이 비어 있지 않고 host가 api.openai.com이 아님), OpenClaw는 unsupported developer role로 인한 provider 400 error를 피하려고 compat.supportsDeveloperRole: false를 강제합니다
• baseUrl이 비어 있거나 생략되면, OpenClaw는 기본 OpenAI behavior를 유지합니다 (api.openai.com으로 resolve)
• 안전을 위해 explicit compat.supportsDeveloperRole: true도 non-native openai-completions endpoint에서는 override됩니다

​

CLI examples

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