模型供應商

LLM/模型供應商的參考資料（不是 WhatsApp/Telegram 這類聊天頻道）。如需模型選擇規則，請參閱模型。

# 快速規則

# Plugin 擁有的供應商行為

大多數供應商專屬邏輯都位於 provider plugins（registerProvider(...)）中，而 OpenClaw 保留通用推論迴圈。Plugins 擁有上線流程、模型目錄、驗證環境變數對應、傳輸/設定正規化、工具結構描述清理、容錯移轉分類、OAuth 重新整理、用量回報、thinking/reasoning 設定檔，以及更多內容。

provider-SDK hooks 和 bundled-plugin 範例的完整清單位於 Provider plugins。需要完全自訂請求執行器的供應商屬於另一個更深層的擴充介面。

# API 金鑰輪替

# 內建供應商（pi-ai 目錄）

OpenClaw 隨附 pi-ai 目錄。這些供應商不需要任何 models.providers 設定；只要設定驗證並選擇模型即可。

# OpenAI

• 供應商：openai
• 驗證：OPENAI_API_KEY
• 選用輪替：OPENAI_API_KEYS、OPENAI_API_KEY_1、OPENAI_API_KEY_2，加上 OPENCLAW_LIVE_OPENAI_KEY（單一覆寫）
• 範例模型：openai/gpt-5.5、openai/gpt-5.4-mini
• 如果特定安裝或 API 金鑰的行為不同，請使用 openclaw models list --provider openai 驗證帳戶/模型可用性。
• CLI：openclaw onboard --auth-choice openai-api-key
• 預設傳輸為 auto（優先 WebSocket，SSE 備援）
• 透過 agents.defaults.models["openai/<model>"].params.transport 針對每個模型覆寫（"sse"、"websocket" 或 "auto"）
• OpenAI Responses WebSocket 預熱預設會透過 params.openaiWsWarmup 啟用（true/false）
• OpenAI 優先處理可透過 agents.defaults.models["openai/<model>"].params.serviceTier 啟用
• /fast 和 params.fastMode 會將直接的 openai/* Responses 請求對應到 api.openai.com 上的 service_tier=priority
• 當你想要明確層級，而不是共享的 /fast 切換時，請使用 params.serviceTier
• 隱藏的 OpenClaw 歸因標頭（originator、version、User-Agent）只套用於前往 api.openai.com 的原生 OpenAI 流量，不適用於通用 OpenAI 相容代理
• 原生 OpenAI 路由也會保留 Responses store、提示快取提示，以及 OpenAI reasoning 相容酬載塑形；代理路由不會
• openai/gpt-5.3-codex-spark 在 OpenClaw 中刻意被抑制，因為即時 OpenAI API 請求會拒絕它，且目前的 Codex 目錄不公開它

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

# Anthropic

• 供應商：anthropic
• 驗證：ANTHROPIC_API_KEY
• 選用輪替：ANTHROPIC_API_KEYS、ANTHROPIC_API_KEY_1、ANTHROPIC_API_KEY_2，加上 OPENCLAW_LIVE_ANTHROPIC_KEY（單一覆寫）
• 範例模型：anthropic/claude-opus-4-6
• CLI：openclaw onboard --auth-choice apiKey
• 直接公開 Anthropic 請求支援共享的 /fast 切換和 params.fastMode，包括傳送到 api.anthropic.com 的 API 金鑰和 OAuth 驗證流量；OpenClaw 會將其對應到 Anthropic service_tier（auto 與 standard_only）
• 建議的 Claude CLI 設定會保留標準模型參照，並另外選擇 CLI 後端：anthropic/claude-opus-4-7 搭配 agents.defaults.agentRuntime.id: "claude-cli"。舊版 claude-cli/claude-opus-4-7 參照仍可相容使用。

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

# OpenAI Codex OAuth

• 供應商：openai-codex
• 驗證：OAuth (ChatGPT)
• PI 模型參照：openai-codex/gpt-5.5
• 原生 Codex 應用程式伺服器工具鏈參照：openai/gpt-5.5 搭配 agents.defaults.agentRuntime.id: "codex"
• 原生 Codex 應用程式伺服器工具鏈文件：Codex 工具鏈
• 舊版模型參照：codex/gpt-*
• Plugin 邊界：openai-codex/* 會載入 OpenAI Plugin；原生 Codex 應用程式伺服器 Plugin 只會由 Codex 工具鏈執行環境或舊版 codex/* 參照選取。
• CLI：openclaw onboard --auth-choice openai-codex 或 openclaw models auth login --provider openai-codex
• 預設傳輸為 auto（優先 WebSocket，SSE 備援）
• 透過 agents.defaults.models["openai-codex/<model>"].params.transport 針對每個 PI 模型覆寫（"sse"、"websocket" 或 "auto"）
• params.serviceTier 也會在原生 Codex Responses 請求（chatgpt.com/backend-api）上轉送
• 隱藏的 OpenClaw 歸因標頭（originator、version、User-Agent）只會附加到前往 chatgpt.com/backend-api 的原生 Codex 流量，不適用於通用 OpenAI 相容代理
• 與直接 openai/* 共用相同的 /fast 切換和 params.fastMode 設定；OpenClaw 會將其對應到 service_tier=priority
• openai-codex/gpt-5.5 使用 Codex 目錄原生的 contextWindow = 400000 和預設執行環境 contextTokens = 272000；可使用 models.providers.openai-codex.models[].contextTokens 覆寫執行環境上限
• 政策備註：OpenAI Codex OAuth 明確支援 OpenClaw 這類外部工具/工作流程。
• 對於常見的訂閱加原生 Codex 執行環境路由，請使用 openai-codex 驗證登入，但設定 openai/gpt-5.5 加上 agents.defaults.agentRuntime.id: "codex"。
• 只有當你想透過 PI 使用 Codex OAuth/訂閱路由時，才使用 openai-codex/gpt-5.5；當你的 API 金鑰設定和本機目錄公開公用 API 路由時，請使用不含 Codex 執行環境覆寫的 openai/gpt-5.5。
• 較舊的 openai-codex/gpt-5.1*、openai-codex/gpt-5.2* 和 openai-codex/gpt-5.3* 參照已被抑制，因為 ChatGPT/Codex OAuth 帳戶會拒絕它們；請改用 openai-codex/gpt-5.5 或原生 Codex 執行環境路由。

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

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

# 其他訂閱式託管選項

# OpenCode

• 驗證：OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY）
• Zen 執行環境供應商：opencode
• Go 執行環境供應商：opencode-go
• 範例模型：opencode/claude-opus-4-6、opencode-go/kimi-k2.6
• 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 金鑰）

• 提供者：google
• 驗證：GEMINI_API_KEY
• 選用輪替：GEMINI_API_KEYS、GEMINI_API_KEY_1、GEMINI_API_KEY_2、GOOGLE_API_KEY 後援，以及 OPENCLAW_LIVE_GEMINI_KEY（單一覆寫）
• 範例模型：google/gemini-3.1-pro-preview、google/gemini-3-flash-preview
• 相容性：使用 google/gemini-3.1-flash-preview 的舊版 OpenClaw 設定會正規化為 google/gemini-3-flash-preview
• 別名：接受 google/gemini-3.1-pro，並正規化為 Google 的即時 Gemini API id：google/gemini-3.1-pro-preview
• CLI：openclaw onboard --auth-choice gemini-api-key
• 思考：/think adaptive 使用 Google 動態思考。Gemini 3/3.1 會省略固定的 thinkingLevel；Gemini 2.5 會傳送 thinkingBudget: -1。
• 直接 Gemini 執行也接受 agents.defaults.models["google/<model>"].params.cachedContent（或舊版 cached_content），以轉發提供者原生的 cachedContents/... 控制代碼；Gemini 快取命中會顯示為 OpenClaw cacheRead

# Google Vertex 和 Gemini CLI

• 提供者：google-vertex、google-gemini-cli
• 驗證：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程

Gemini CLI OAuth 會作為內建 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 回覆會從 response 解析；用量會後援到 stats，並將 stats.cached 正規化為 OpenClaw cacheRead。

# Z.AI (GLM)

• 提供者：zai
• 驗證：ZAI_API_KEY
• 範例模型：zai/glm-5.1
• CLI：openclaw onboard --auth-choice zai-api-key
  • 別名：z.ai/* 和 z-ai/* 會正規化為 zai/*
  • zai-api-key 會自動偵測相符的 Z.AI 端點；zai-coding-global、zai-coding-cn、zai-global 和 zai-cn 會強制使用特定介面

# Vercel AI Gateway

• 提供者：vercel-ai-gateway
• 驗證：AI_GATEWAY_API_KEY
• 範例模型：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

• 提供者：kilocode
• 驗證：KILOCODE_API_KEY
• 範例模型：kilocode/kilo/auto
• CLI：openclaw onboard --auth-choice kilocode-api-key
• 基底 URL：https://api.kilo.ai/api/gateway/
• 靜態後援目錄隨附 kilocode/kilo/auto；即時 https://api.kilo.ai/api/gateway/models 探索可以進一步擴充執行階段目錄。
• kilocode/kilo/auto 背後的確切上游路由由 Kilo Gateway 擁有，不是在 OpenClaw 中硬編碼。

設定詳細資訊請參閱 /providers/kilocode。

# 其他內建提供者 Plugin

# 值得知道的特殊情況

# 透過 models.providers 使用提供者（自訂/基底 URL）

使用 models.providers（或 models.json）新增自訂提供者或 OpenAI/Anthropic 相容代理。

下方許多內建提供者 Plugin 已經發布預設目錄。只有在你想覆寫預設基底 URL、標頭或模型清單時，才使用明確的 models.providers.<id> 項目。

Gateway 模型能力檢查也會讀取明確的 models.providers.<id>.models[] 中繼資料。如果自訂或代理模型接受圖像，請在該模型上設定 input: ["text", "image"]，讓 WebChat 和 Node 來源附件路徑以原生模型輸入傳遞圖像，而不是純文字媒體參照。

# Moonshot AI (Kimi)

Moonshot 以內建提供者 Plugin 隨附。預設使用內建提供者，只有在需要覆寫基底 URL 或模型中繼資料時，才新增明確的 models.providers.moonshot 項目：

• 提供者：moonshot
• 驗證：MOONSHOT_API_KEY
• 範例模型：moonshot/kimi-k2.6
• CLI：openclaw onboard --auth-choice moonshot-api-key 或 openclaw onboard --auth-choice moonshot-api-key-cn

Kimi K2 模型 ID：

• moonshot/kimi-k2.6
• 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 使用 Moonshot AI 的 Anthropic 相容端點：

• 提供者：kimi
• 驗證：KIMI_API_KEY
• 範例模型：kimi/kimi-code

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

Legacy kimi/k2p5 仍可作為相容性模型 ID 接受。

# Volcano Engine (Doubao)

Volcano Engine (火山引擎) 在中國提供 Doubao 與其他模型的存取能力。

• 提供者：volcengine（編碼：volcengine-plan）
• 驗證：VOLCANO_ENGINE_API_KEY
• 範例模型：volcengine-plan/ark-code-latest
• CLI：openclaw onboard --auth-choice volcengine-api-key

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

入門設定預設使用編碼介面，但一般 volcengine/* 目錄也會同時註冊。

在入門設定/設定模型選擇器中，Volcengine 驗證選項會優先顯示 volcengine/* 與 volcengine-plan/* 兩種列。如果這些模型尚未載入，OpenClaw 會改為回退到未篩選的目錄，而不是顯示空的提供者範圍選擇器。

# BytePlus（國際）

BytePlus ARK 為國際使用者提供與 Volcano Engine 相同模型的存取能力。

• 提供者：byteplus（編碼：byteplus-plan）
• 驗證：BYTEPLUS_API_KEY
• 範例模型：byteplus-plan/ark-code-latest
• CLI：openclaw onboard --auth-choice byteplus-api-key

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

入門設定預設使用編碼介面，但一般 byteplus/* 目錄也會同時註冊。

在入門設定/設定模型選擇器中，BytePlus 驗證選項會優先顯示 byteplus/* 與 byteplus-plan/* 兩種列。如果這些模型尚未載入，OpenClaw 會改為回退到未篩選的目錄，而不是顯示空的提供者範圍選擇器。

# Synthetic

Synthetic 透過 synthetic 提供者提供 Anthropic 相容模型：

• 提供者：synthetic
• 驗證：SYNTHETIC_API_KEY
• 範例模型：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 透過 models.providers 設定，因為它使用自訂端點：

• MiniMax OAuth（全球）：--auth-choice minimax-global-oauth
• MiniMax OAuth（中國）：--auth-choice minimax-cn-oauth
• MiniMax API 金鑰（全球）：--auth-choice minimax-global-api
• MiniMax API 金鑰（中國）：--auth-choice minimax-cn-api
• 驗證：minimax 使用 MINIMAX_API_KEY；minimax-portal 使用 MINIMAX_OAUTH_TOKEN 或 MINIMAX_API_KEY

如需設定詳細資訊、模型選項與設定片段，請參閱 /providers/minimax。

Plugin 擁有的能力分割：

• 文字/聊天預設值維持在 minimax/MiniMax-M2.7
• 圖片生成是 minimax/image-01 或 minimax-portal/image-01
• 圖片理解是 Plugin 擁有的 MiniMax-VL-01，適用於兩種 MiniMax 驗證路徑
• 網頁搜尋維持在提供者 ID minimax

# LM Studio

LM Studio 以內建提供者 Plugin 形式提供，並使用原生 API：

• 提供者：lmstudio
• 驗證：LM_API_TOKEN
• 預設推論基礎 URL：http://localhost:1234/v1

接著設定模型（請替換為 http://localhost:1234/api/v1/models 傳回的其中一個 ID）：

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

OpenClaw 使用 LM Studio 的原生 /api/v1/models 與 /api/v1/models/load 進行探索與自動載入，並預設使用 /v1/chat/completions 進行推論。如果你想讓 LM Studio JIT 載入、TTL 與自動逐出負責模型生命週期，請設定 models.providers.lmstudio.params.preload: false。如需設定與疑難排解，請參閱 /providers/lmstudio。

# Ollama

Ollama 以內建提供者 Plugin 形式提供，並使用 Ollama 的原生 API：

• 提供者：ollama
• 驗證：不需要（本機伺服器）
• 範例模型：ollama/llama3.3
• 安裝：https://ollama.com/download

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

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

當你使用 OLLAMA_API_KEY 選擇加入時，Ollama 會在本機 http://127.0.0.1:11434 被偵測到，且內建提供者 Plugin 會將 Ollama 直接加入 openclaw onboard 與模型選擇器。如需入門設定、雲端/本機模式與自訂設定，請參閱 /providers/ollama。

# vLLM

vLLM 以內建提供者 Plugin 形式提供，用於本機/自行託管的 OpenAI 相容伺服器：

• 提供者：vllm
• 驗證：選用（取決於你的伺服器）
• 預設基礎 URL：http://127.0.0.1:8000/v1

若要選擇加入本機自動探索（如果你的伺服器未強制驗證，任何值都可使用）：

export VLLM_API_KEY="vllm-local"

接著設定模型（請替換為 /v1/models 傳回的其中一個 ID）：

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

詳細資訊請參閱 /providers/vllm。

# SGLang

SGLang 以內建提供者 Plugin 形式提供，用於快速自行託管的 OpenAI 相容伺服器：

• 提供者：sglang
• 驗證：選用（取決於你的伺服器）
• 預設基礎 URL：http://127.0.0.1:30000/v1

若要選擇加入本機自動探索（如果你的伺服器未強制驗證，任何值都可使用）：

export SGLANG_API_KEY="sglang-local"

接著設定模型（請替換為 /v1/models 傳回的其中一個 ID）：

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

詳細資訊請參閱 /providers/sglang。

# 本機 Proxy（LM Studio、vLLM、LiteLLM 等）

範例（OpenAI 相容）：

{
  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 範例

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

另請參閱：設定 以取得完整設定範例。

# 相關

• 設定參考 - 模型設定鍵
• 模型容錯移轉 - 備援鏈與重試行為
• 模型 - 模型設定與別名
• 提供者 - 各提供者設定指南