> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 模型供應商

**LLM／模型供應商**的參考資料（非 WhatsApp／Telegram 等聊天頻道）。模型選擇規則請參閱[模型](/zh-TW/concepts/models)。

## 快速規則

<AccordionGroup>
  <Accordion title="模型參照與命令列介面輔助工具">
    * 模型參照使用 `provider/model`（範例：`opencode/claude-opus-4-6`）。
    * `agents.defaults.models` 儲存別名與各模型設定；`agents.defaults.modelPolicy.allow` 是選用的明確覆寫允許清單。
    * 命令列介面輔助工具：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
    * `models.providers.*.contextWindow`／`contextTokens`／`maxTokens` 設定供應商層級的預設值；`models.providers.*.models[].contextWindow`／`contextTokens`／`maxTokens` 則針對各模型覆寫這些值。
    * 備援規則、冷卻探測與工作階段覆寫持久化：[模型容錯移轉](/zh-TW/concepts/model-failover)。
  </Accordion>

  <Accordion title="新增供應商驗證不會變更主要模型">
    新增供應商或重新驗證供應商時，`openclaw configure` 會保留現有的 `agents.defaults.model.primary`。除非傳入 `--set-default`，否則 `openclaw models auth login` 也會如此。供應商外掛仍可能在其驗證設定修補中傳回建議的預設模型，但若主要模型已存在，OpenClaw 會將其視為「讓此模型可供使用」，而非「取代目前的主要模型」。

    若要刻意切換預設模型，請使用 `openclaw models set <provider/model>` 或 `openclaw models auth login --provider <id> --set-default`。
  </Accordion>

  <Accordion title="OpenAI 供應商／執行階段分離">
    OpenAI 模型參照與代理程式執行階段彼此分離：

    * `openai/<model>` 選擇標準 OpenAI 供應商與模型。僅有前綴絕不會選取 Codex。
    * 當未設定供應商／模型執行階段原則，或設為 `auto` 時，只有在確切的官方 HTTPS Platform Responses 或 ChatGPT Responses 路由，且沒有自行設定的要求覆寫時，OpenAI 才可能隱含選取 Codex。
    * 自行設定的 Completions 轉接器、自訂端點，以及含有自行設定要求行為的路由會繼續使用 OpenClaw。官方明文 HTTP 端點會遭拒絕。
    * 舊版 Codex 模型參照屬於舊版設定，doctor 會將其改寫為 `openai/<model>`。
    * 供應商／模型 `agentRuntime.id: "openclaw"` 會明確讓原本符合資格的路由繼續使用 OpenClaw。`agentRuntime.id: "codex"` 要求使用 Codex；若有效路由與 Codex 不相容，則會以封閉方式失敗。

    請參閱 [OpenAI 隱含代理程式執行階段](/zh-TW/providers/openai#implicit-agent-runtime)與 [Codex 控制框架](/zh-TW/plugins/codex-harness)。若供應商／執行階段的分離令人困惑，請先閱讀[代理程式執行階段](/zh-TW/concepts/agent-runtimes)。

    外掛自動啟用遵循相同邊界：隱含相容於 Codex 的有效路由可以啟用 Codex 外掛，而明確的供應商／模型 `agentRuntime.id: "codex"` 或舊版 `codex/<model>` 參照則要求啟用該外掛。僅有 `openai/*` 前綴並不會如此。

    全新的 OpenAI 設定會使用路由專屬的 GPT-5.6 參照：API 金鑰設定會選取
    `openai/gpt-5.6`（在直接 API 上，裸露的 ID 會解析為 Sol），而
    ChatGPT／Codex OAuth 會為原生 Codex
    目錄選取確切的 `openai/gpt-5.6-sol`。新增或重新整理 OpenAI 驗證時，會
    保留現有的明確主要模型，包括 `openai/gpt-5.5`。對於無法
    存取 GPT-5.6 的帳號，GPT-5.5 仍可透過任一執行階段作為明確的復原選項。
  </Accordion>

  <Accordion title="命令列介面執行階段">
    命令列介面執行階段使用相同的分離方式：選擇 `anthropic/claude-*` 或 `google/gemini-*` 等標準模型參照，然後在需要本機命令列介面後端時，將供應商／模型執行階段原則設為 `claude-cli` 或 `google-gemini-cli`。

    舊版 `claude-cli/*` 與 `google-gemini-cli/*` 參照會遷移回標準供應商參照，執行階段則會另行記錄。舊版 `codex-cli/*` 參照會遷移至 `openai/*` 並使用 Codex 應用程式伺服器路由；OpenClaw 不再保留隨附的 Codex 命令列介面後端。
  </Accordion>
</AccordionGroup>

## 在控制介面中設定供應商

在控制介面中開啟 **Settings → Model Providers**，以新增、取代或移除儲存在 `models.providers.<id>.apiKey` 中的供應商 API 金鑰。此頁面會指出各 API 金鑰來自 OpenClaw 設定還是環境變數，而不會顯示認證資訊。由環境提供的金鑰仍由閘道程序環境管理。

使用 **Test connection** 執行即時供應商探測，並查看延遲或經分類的驗證、速率限制、帳務、逾時或回應錯誤。探測會發出實際的供應商要求，並可能耗用少量權杖。也可以從供應商卡片登出 OAuth 與權杖設定檔。

**Default models** 卡片可管理主要模型、依序排列的備援模型，以及設定模型目錄中的公用程式模型。選擇模型後，一併儲存至現有的 `agents.defaults.model` 與 `agents.defaults.utilityModel` 設定。對於公用程式模型，**Automatic** 會讓設定保持未設定，而 **Disabled** 則會儲存空字串，以關閉公用程式路由。

## 外掛擁有的供應商行為

多數供應商專屬邏輯都位於供應商外掛（`registerProvider(...)`）中，而 OpenClaw 會保留通用推論迴圈。外掛負責新手引導、模型目錄、驗證環境變數對應、傳輸／設定正規化、工具結構描述清理、容錯移轉分類、OAuth 重新整理、用量報告、思考／推理設定檔等功能。

供應商 SDK 掛鉤與隨附外掛範例的完整清單位於[供應商外掛](/zh-TW/plugins/sdk-provider-plugins)。需要完全自訂要求執行器的供應商屬於另一個更深層的擴充介面。

<Note>
  供應商擁有的執行器行為位於明確的供應商掛鉤上，例如重播原則、工具結構描述正規化、串流包裝，以及傳輸／要求輔助工具。舊版 `ProviderPlugin.capabilities` 靜態集合僅供相容性使用，共用執行器邏輯已不再讀取它。
</Note>

## API 金鑰輪替

<AccordionGroup>
  <Accordion title="金鑰來源與優先順序">
    可透過下列方式設定多個金鑰：

    * `OPENCLAW_LIVE_<PROVIDER>_KEY`（單一即時覆寫，優先順序最高）
    * `<PROVIDER>_API_KEYS`（以逗號或分號分隔的清單）
    * `<PROVIDER>_API_KEY`（主要金鑰）
    * `<PROVIDER>_API_KEY_*`（編號清單，例如 `<PROVIDER>_API_KEY_1`）

    對於 Google 供應商，也會納入 `GOOGLE_API_KEY` 作為備援。金鑰選取順序會保留優先順序並移除重複值。
  </Accordion>

  <Accordion title="何時啟動輪替">
    * 只有遇到速率限制回應時，要求才會使用下一個金鑰重試（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或週期性用量限制訊息）。
    * 非速率限制失敗會立即失敗；不會嘗試金鑰輪替。
    * 當所有候選金鑰都失敗時，會傳回最後一次嘗試的最終錯誤。
  </Accordion>
</AccordionGroup>

## 官方供應商外掛

官方供應商外掛會發布自己的模型目錄資料列。這些供應商**不需要** `models.providers` 模型項目；啟用供應商外掛、設定驗證並選擇模型即可。僅針對明確的自訂供應商，或逾時等有限的要求設定使用 `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.6`；在直接 API 上，裸露的 ID 會解析為 Sol。
* 模型範例：`openai/gpt-5.6`、`openai/gpt-5.6-terra`、`openai/gpt-5.6-luna`、`openai/gpt-5.5`
* 若特定安裝或 API 金鑰的行為不同，請使用 `openclaw models list --provider openai` 驗證帳號／模型可用性。
* 命令列介面：`openclaw onboard --auth-choice openai-api-key`
* 預設傳輸為 `auto`；OpenClaw 會將傳輸選項傳遞給共用模型執行階段。
* 透過 `agents.defaults.models["openai/<model>"].params.transport`（`"sse"`、`"websocket"` 或 `"auto"`）針對各模型覆寫
* 可透過 `agents.defaults.models["openai/<model>"].params.serviceTier` 啟用 OpenAI 優先處理
* `/fast` 與 `params.fastMode` 會將直接的 `openai/*` Responses 要求對應至 `api.openai.com` 上的 `service_tier=priority`
* 若要使用明確層級，而非共用的 `/fast` 切換，請使用 `params.serviceTier`
* 隱藏的 OpenClaw 歸屬標頭（`originator`、`version`、`User-Agent`）僅套用於前往 `api.openai.com` 的原生 OpenAI 流量，不適用於通用的 OpenAI 相容 Proxy
* 原生 OpenAI 路由也會保留 Responses `store`、提示快取提示，以及 OpenAI 推理相容承載資料塑形；Proxy 路由則不會
* `openai/gpt-5.3-codex-spark` 僅可透過 ChatGPT／Codex OAuth 使用；直接 OpenAI API 金鑰與 Azure API 金鑰路由會拒絕它

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: { defaults: { model: { primary: "openai/gpt-5.6" } } },
}
```

若 API 組織未提供 GPT-5.6，請明確設定
`openai/gpt-5.5`。一般新手引導與重新驗證會保留
現有的明確主要模型；`models auth login --set-default` 與
`models set` 是刻意取代模型的途徑。

### Anthropic

* 供應商：`anthropic`
* 驗證：`ANTHROPIC_API_KEY`
* 選用輪替：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（單一覆寫）
* 模型範例：`anthropic/claude-opus-5`
* 命令列介面：`openclaw onboard --auth-choice apiKey`
* 直接的公開 Anthropic 要求支援共用的 `/fast` 切換與 `params.fastMode`，包括傳送至 `api.anthropic.com` 的 API 金鑰與 OAuth 驗證流量；OpenClaw 會將其對應至 Anthropic `service_tier`（`auto` 與 `standard_only`）
* 偏好的 Claude 命令列介面設定會維持標準模型參照，並另行選取命令列介面
  後端：`anthropic/claude-opus-5` 搭配
  模型範圍的 `agentRuntime.id: "claude-cli"`。舊版
  `claude-cli/claude-opus-4-7` 參照仍可用於相容性。

<Note>
  Claude 命令列介面重複使用（`claude -p`）是 OpenClaw 認可的整合途徑。Anthropic 設定權杖驗證仍受支援，但 OpenClaw 會優先使用 Claude 命令列介面重複使用（若可用）。
</Note>

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-5" } } },
}
```

### OpenAI ChatGPT／Codex OAuth

* 供應商：`openai`
* 驗證：OAuth (ChatGPT)
* 全新原生 Codex app-server 測試框架參照：`openai/gpt-5.6-sol`
* 原生 Codex app-server 測試框架文件：[Codex 測試框架](/zh-TW/plugins/codex-harness)
* 舊版模型參照：`codex/gpt-*`、`openai-codex/gpt-*`
* 外掛邊界：`openai/*` 會載入 OpenAI 外掛；由明確的執行階段原則或供應商擁有的有效路由決定是否選取原生 Codex app-server 外掛。
* 命令列介面：`openclaw onboard --auth-choice openai` 或 `openclaw models auth login --provider openai`
* OpenClaw 內嵌的 ChatGPT Responses 傳輸預設為 `auto`（優先使用 WebSocket，SSE 作為備援）。
* `agents.defaults.models["openai/<model>"].params.transport`、`params.serviceTier` 和 `params.fastMode` 是明確設定的內嵌請求設定。它們讓隱含的執行階段選取仍由 OpenClaw 負責；原生 Codex 則自行管理其 app-server 傳輸與服務層級。
* 隱藏的 OpenClaw 歸屬標頭（`originator`、`version`、`User-Agent`）只會附加至前往 `chatgpt.com/backend-api` 的原生 Codex 流量，不會附加至一般的 OpenAI 相容代理伺服器
* 共用的 `/fast` 切換選項仍可作為執行階段控制使用；它與明確設定的模型參數不同。
* 原生 Codex 目錄可依帳戶存取權限公開確切的 `openai/gpt-5.6-sol`、`openai/gpt-5.6-terra` 和 `openai/gpt-5.6-luna` 參照。它不會在用戶端套用直接 API 的裸 `gpt-5.6` 別名。
* `openai/gpt-5.5` 使用 Codex 目錄原生的 `contextWindow = 400000` 與預設執行階段 `contextTokens = 272000`；可使用 `models.providers.openai.models[].contextTokens` 覆寫執行階段上限
* 使用 `openai` 驗證登入，並使用 `openai/gpt-5.6-sol` 建立由訂閱支援的全新設定。如果該 Codex 工作區未公開 GPT-5.6，請明確選取 `openai/gpt-5.5`。
* 使用供應商／模型 `agentRuntime.id: "openclaw"`，讓原本符合資格的路由繼續使用內建執行階段。當執行階段未設定或為 `auto` 時，只有完全符合官方 HTTPS Responses／ChatGPT 相容格式，且沒有明確請求覆寫的路由，才能隱含選取 Codex。
* 舊版 Codex GPT 參照屬於舊版狀態，不是有效的供應商路由。新代理程式設定請使用標準 `openai/*` 參照，並執行 `openclaw doctor --fix` 來遷移 `codex/*` 和 `openai-codex/*` 參照，同時透過模型範圍的 `agentRuntime.id: "codex"` 保留其原生 Codex 語意。現有明確選取的標準 `openai/gpt-5.5` 不會升級。

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  plugins: { entries: { codex: { enabled: true } } },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.6-sol" },
    },
  },
}
```

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  models: {
    providers: {
      openai: {
        models: [{ id: "gpt-5.5", contextTokens: 160000 }],
      },
    },
  },
}
```

### 其他訂閱形式的託管選項

<CardGroup cols={3}>
  <Card title="MiniMax" href="/zh-TW/providers/minimax">
    MiniMax Coding Plan OAuth 或 API 金鑰存取。
  </Card>

  <Card title="Qwen Cloud" href="/zh-TW/providers/qwen">
    Qwen Cloud 供應商介面，以及 Alibaba DashScope 和 Coding Plan 端點對應。
  </Card>

  <Card title="Z.AI (GLM)" href="/zh-TW/providers/zai">
    Z.AI Coding Plan 或一般 API 端點。
  </Card>
</CardGroup>

### OpenCode

* 驗證：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）
* Zen 執行階段供應商：`opencode`
* Go 執行階段供應商：`opencode-go`
* 模型範例：`opencode/claude-opus-4-6`、`opencode-go/kimi-k2.6`
* 命令列介面：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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.5-flash`
* 相容性：使用 `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`
* 命令列介面：`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 流程

<Warning>
  OpenClaw 中的 Gemini CLI OAuth 是非官方整合。部分使用者回報，使用第三方用戶端後其 Google 帳戶受到限制。若你選擇繼續，請檢閱 Google 條款並使用非關鍵帳戶。
</Warning>

Gemini CLI OAuth 隨內建的 `google` 外掛一同提供。

<Steps>
  <Step title="安裝 Gemini CLI">
    <Tabs>
      <Tab title="brew">
        ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
        brew install gemini-cli
        ```
      </Tab>

      <Tab title="npm">
        ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
        npm install -g @google/gemini-cli
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="啟用外掛">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw plugins enable google
    ```
  </Step>

  <Step title="登入">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw models auth login --provider google-gemini-cli --set-default
    ```

    預設模型：`google-gemini-cli/gemini-3-flash-preview`。你**不需要**將用戶端 ID 或密鑰貼入 `openclaw.json`。命令列介面登入流程會將權杖儲存在閘道主機的驗證設定檔中。
  </Step>

  <Step title="設定專案（如有需要）">
    如果登入後請求失敗，請在閘道主機上設定 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。
  </Step>
</Steps>

Gemini CLI 預設使用 `stream-json`。OpenClaw 會讀取助理串流
訊息，並將 `stats.cached` 正規化為 `cacheRead`；舊版
`--output-format json` 覆寫仍會從 `response` 讀取回覆文字。

### Z.AI (GLM)

* 供應商：`zai`
* 驗證：`ZAI_API_KEY`
* 模型範例：`zai/glm-5.2`
* 命令列介面：`openclaw onboard --auth-choice zai-api-key`
  * 模型參照使用標準 `zai/*` 供應商 ID。
  * `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`
* 命令列介面：`openclaw onboard --auth-choice ai-gateway-api-key`

### 其他內建供應商外掛

| 供應商                                           | ID                               | 驗證環境變數                                               | 範例模型                                                   |
| --------------------------------------------- | -------------------------------- | ---------------------------------------------------- | ------------------------------------------------------ |
| Arcee                                         | `arcee`                          | `ARCEEAI_API_KEY` 或 `OPENROUTER_API_KEY`             | `arcee/trinity-large-thinking`                         |
| BytePlus                                      | `byteplus` / `byteplus-plan`     | `BYTEPLUS_API_KEY`                                   | `byteplus-plan/ark-code-latest`                        |
| Cerebras                                      | `cerebras`                       | `CEREBRAS_API_KEY`                                   | `cerebras/zai-glm-4.7`                                 |
| Chutes                                        | `chutes`                         | `CHUTES_API_KEY` 或 `CHUTES_OAUTH_TOKEN`              | `chutes/zai-org/GLM-5-TEE`                             |
| ClawRouter                                    | `clawrouter`                     | `CLAWROUTER_API_KEY`                                 | `clawrouter/anthropic/claude-sonnet-4-6`               |
| Cohere                                        | `cohere`                         | `COHERE_API_KEY`                                     | `cohere/command-a-plus-05-2026`                        |
| DeepInfra                                     | `deepinfra`                      | `DEEPINFRA_API_KEY`                                  | `deepinfra/deepseek-ai/DeepSeek-V4-Flash`              |
| DeepSeek                                      | `deepseek`                       | `DEEPSEEK_API_KEY`                                   | `deepseek/deepseek-v4-flash`                           |
| Featherless AI                                | `featherless`                    | `FEATHERLESS_API_KEY`                                | `featherless/Qwen/Qwen3-32B`                           |
| GitHub Copilot                                | `github-copilot`                 | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | -                                                      |
| GMI Cloud                                     | `gmi`                            | `GMI_API_KEY`                                        | `gmi/google/gemini-3.1-flash-lite`                     |
| Groq                                          | `groq`                           | `GROQ_API_KEY`                                       | `groq/llama-3.3-70b-versatile`                         |
| Hugging Face Inference                        | `huggingface`                    | `HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`                 | `huggingface/deepseek-ai/DeepSeek-R1`                  |
| MiniMax                                       | `minimax` / `minimax-portal`     | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN`            | `minimax/MiniMax-M3`                                   |
| Mistral                                       | `mistral`                        | `MISTRAL_API_KEY`                                    | `mistral/mistral-large-latest`                         |
| Moonshot                                      | `moonshot`                       | `MOONSHOT_API_KEY`                                   | `moonshot/kimi-k2.6`                                   |
| NVIDIA                                        | `nvidia`                         | `NVIDIA_API_KEY`                                     | `nvidia/nvidia/nemotron-3-ultra-550b-a55b`             |
| NovitaAI                                      | `novita`                         | `NOVITA_API_KEY`                                     | `novita/deepseek/deepseek-v3-0324`                     |
| [Ollama Cloud](/zh-TW/providers/ollama-cloud) | `ollama-cloud`                   | `OLLAMA_API_KEY`                                     | `ollama-cloud/kimi-k2.6`                               |
| OpenRouter                                    | `openrouter`                     | OpenRouter OAuth 或 `OPENROUTER_API_KEY`              | `openrouter/auto`                                      |
| Qianfan                                       | `qianfan`                        | `QIANFAN_API_KEY`                                    | `qianfan/deepseek-v3.2`                                |
| Tencent TokenHub                              | `tencent-tokenhub`               | `TOKENHUB_API_KEY`                                   | `tencent-tokenhub/hy3-preview`                         |
| Together                                      | `together`                       | `TOGETHER_API_KEY`                                   | `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`     |
| Venice                                        | `venice`                         | `VENICE_API_KEY`                                     | -                                                      |
| Vercel AI Gateway                             | `vercel-ai-gateway`              | `AI_GATEWAY_API_KEY`                                 | `vercel-ai-gateway/anthropic/claude-opus-4.6`          |
| Volcano Engine（豆包）                            | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY`                             | `volcengine-plan/ark-code-latest`                      |
| xAI                                           | `xai`                            | SuperGrok/X Premium OAuth 或 `XAI_API_KEY`            | `xai/grok-4.3`                                         |
| Xiaomi                                        | `xiaomi` / `xiaomi-token-plan`   | `XIAOMI_API_KEY` / `XIAOMI_TOKEN_PLAN_API_KEY`       | `xiaomi/mimo-v2.5` / `xiaomi-token-plan/mimo-v2.5-pro` |

#### 值得瞭解的特殊行為

<AccordionGroup>
  <Accordion title="OpenRouter">
    僅在已驗證的 `openrouter.ai` 路由上套用其應用程式歸屬標頭和 Anthropic `cache_control` 標記。DeepSeek、Moonshot 和 ZAI 參照可使用 OpenRouter 管理的提示快取之快取 TTL，但不會收到 Anthropic 快取標記。由於這是代理形式的 OpenAI 相容路徑，因此會略過僅適用於原生 OpenAI 的格式調整（`serviceTier`、Responses `store`、提示快取提示、OpenAI 推理相容性）。以 Gemini 為後端的參照只保留代理 Gemini 的思維簽章清理。
  </Accordion>

  <Accordion title="Kilo Gateway">
    以 Gemini 為後端的參照會遵循相同的代理 Gemini 清理路徑；`kilocode/kilo-auto/balanced` 和其他不支援代理推理的參照會略過代理推理注入。
  </Accordion>

  <Accordion title="MiniMax">
    API 金鑰上線流程會寫入明確的 M3 和 M2.7 聊天模型定義；圖片理解仍使用由外掛擁有的 `MiniMax-VL-01` 媒體供應商。
  </Accordion>

  <Accordion title="NVIDIA">
    模型 ID 使用 `nvidia/<vendor>/<model>` 命名空間（例如 `nvidia/nvidia/nemotron-...`）；選擇器會保留字面上的 `<provider>/<model-id>` 組合，而傳送至 API 的標準鍵仍只加上一個前綴。
  </Accordion>

  <Accordion title="xAI">
    使用 xAI Responses 路徑。建議使用 SuperGrok/X Premium OAuth；API 金鑰仍可透過 `XAI_API_KEY` 或外掛設定使用，而 Grok `web_search` 會先重複使用相同的驗證設定檔，再回退至 API 金鑰。在可用之處，可選擇 Grok 4.5 進行聊天、程式設計和代理式工作；`grok-4.3` 仍是適用各區域的內建預設值。較舊的 `/fast` 和 `params.fastMode: true` 設定仍會透過 xAI 的 Grok 4.3 相容性重新導向進行解析，但新設定應直接選擇目前的模型。`tool_stream` 預設開啟；可透過 `agents.defaults.models["xai/<model>"].params.tool_stream=false` 停用。
  </Accordion>
</AccordionGroup>

## 透過 `models.providers` 使用供應商（自訂／基礎 URL）

使用 `models.providers`（或 `models.json`）新增**自訂**供應商或 OpenAI／Anthropic 相容代理。

下列許多內建供應商外掛已發布預設目錄。只有在需要覆寫預設基礎 URL、標頭或模型清單時，才使用明確的 `models.providers.<id>` 項目。

內建和目錄中已知的路由會從其所屬的供應商外掛取得 `compat` 功能。設定中的 `compat` 區塊適用於自訂供應商／模型，或端點合約已經過驗證的不同 `api`/`baseUrl` 路由；請參閱[自訂供應商功能指南](/zh-TW/gateway/config-tools#custom-provider-capability-declarations)。Doctor 會移除僅重複目錄內容的舊版值，並保留相異的值供操作人員檢閱。

閘道模型功能檢查也會讀取明確的 `models.providers.<id>.models[]` 中繼資料。如果自訂或代理模型接受圖片，請在該模型上設定 `input: ["text", "image"]`，使 WebChat 和源自節點的附件路徑能以原生模型輸入傳遞圖片，而非僅文字的媒體參照。

`agents.defaults.models["provider/model"]` 控制代理程式的別名和個別模型中繼資料。它本身既不限制覆寫，也不註冊新的執行階段模型。對於自訂供應商模型，也請新增 `models.providers.<provider>.models[]`，並至少包含相符的 `id`；若要限制覆寫，請另行使用 `agents.defaults.modelPolicy.allow`。

### Moonshot AI（Kimi）

上線前請安裝 `@openclaw/moonshot-provider`。只有在需要覆寫基礎 URL 或模型中繼資料時，才新增明確的 `models.providers.moonshot` 項目：

* 供應商：`moonshot`
* 驗證：`MOONSHOT_API_KEY`
* 範例模型：`moonshot/kimi-k3`
* 命令列介面：`openclaw onboard --auth-choice moonshot-api-key` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`

Kimi 模型 ID：

[//]: # "moonshot-kimi-k2-model-refs:start"

* `moonshot/kimi-k2.6`
* `moonshot/kimi-k3`
* `moonshot/kimi-k2.7-code`
* `moonshot/kimi-k2.7-code-highspeed`
* `moonshot/kimi-k2.5`

[//]: # "moonshot-kimi-k2-model-refs:end"

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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" }],
      },
    },
  },
}
```

完整設定指南請參閱 [Moonshot AI（Kimi + Kimi Coding）](/zh-TW/providers/moonshot)。

### Kimi Coding

Kimi Coding 使用 Moonshot AI 的 Anthropic 相容端點：

* 供應商：`kimi`
* 驗證：`KIMI_API_KEY`
* Kimi K3：`kimi/k3`（256K）或 `kimi/k3[1m]`（1M 方案）
* Kimi Code：`kimi/kimi-for-coding`
* Kimi Code HighSpeed：`kimi/kimi-for-coding-highspeed`

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: { model: { primary: "kimi/kimi-for-coding" } },
  },
}
```

舊版 `kimi/kimi-code` 和 `kimi/k2p5` 仍可作為相容性模型 ID 使用，並會正規化為 Kimi 的穩定 API 模型 ID。

### Volcano Engine（豆包）

Volcano Engine（火山引擎）在中國提供豆包和其他模型的存取服務。

* 供應商：`volcengine`（程式設計：`volcengine-plan`）
* 驗證：`VOLCANO_ENGINE_API_KEY`
* 範例模型：`volcengine-plan/ark-code-latest`
* 命令列介面：`openclaw onboard --auth-choice volcengine-api-key`

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: { model: { primary: "volcengine-plan/ark-code-latest" } },
  },
}
```

上線流程預設使用程式設計介面，但也會同時註冊一般的 `volcengine/*` 目錄。

在上線／設定模型選擇器中，Volcengine 驗證選項會優先顯示 `volcengine/*` 和 `volcengine-plan/*` 兩列。如果這些模型尚未載入，OpenClaw 會回退至未篩選的目錄，而非顯示空白的供應商範圍選擇器。

<Tabs>
  <Tab title="標準模型">
    * `volcengine/doubao-seed-1-8-251228`（豆包 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）
  </Tab>

  <Tab title="程式設計模型 (volcengine-plan)">
    * `volcengine-plan/ark-code-latest`
    * `volcengine-plan/doubao-seed-code`
  </Tab>
</Tabs>

### BytePlus（國際版）

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

* 提供者：`byteplus`（程式設計：`byteplus-plan`）
* 驗證：`BYTEPLUS_API_KEY`
* 模型範例：`byteplus-plan/ark-code-latest`
* 命令列介面：`openclaw onboard --auth-choice byteplus-api-key`

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: { model: { primary: "byteplus-plan/ark-code-latest" } },
  },
}
```

初始設定預設使用程式設計介面，但同時也會註冊一般的 `byteplus/*` 目錄。

在初始設定／配置的模型選擇器中，BytePlus 驗證選項會優先顯示 `byteplus/*` 和 `byteplus-plan/*` 兩列。若尚未載入這些模型，OpenClaw 會改用未篩選的目錄，而不會顯示空白的提供者範圍選擇器。

<Tabs>
  <Tab title="標準模型">
    * `byteplus/seed-1-8-251228` (Seed 1.8)
    * `byteplus/kimi-k2-5-260127` (Kimi K2.5)
    * `byteplus/glm-4-7-251222` (GLM 4.7)
  </Tab>

  <Tab title="程式設計模型 (byteplus-plan)">
    * `byteplus-plan/ark-code-latest`
    * `byteplus-plan/kimi-k2.5`
    * `byteplus-plan/glm-4.7`
  </Tab>
</Tabs>

### Synthetic

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

* 提供者：`synthetic`
* 驗證：`SYNTHETIC_API_KEY`
* 模型範例：`synthetic/hf:MiniMaxAI/MiniMax-M3`
* 命令列介面：`openclaw onboard --auth-choice synthetic-api-key`

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: { model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M3" } },
  },
  models: {
    mode: "merge",
    providers: {
      synthetic: {
        baseUrl: "https://api.synthetic.new/anthropic",
        apiKey: "${SYNTHETIC_API_KEY}",
        api: "anthropic-messages",
        models: [{ id: "hf:MiniMaxAI/MiniMax-M3", name: "MiniMax M3" }],
      },
    },
  },
}
```

### 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_API_KEY` 用於 `minimax`；`MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY` 用於 `minimax-portal`

如需設定詳細資訊、模型選項和配置片段，請參閱 [/providers/minimax](/zh-TW/providers/minimax)。

<Note>
  在 MiniMax 的 Anthropic 相容串流路徑上，除非明確設定，否則 OpenClaw 預設會停用 M2.x 系列的思考功能；MiniMax-M3（以及 M3.x）則預設維持提供者的省略／自適應思考路徑。`/fast on` 會將 `MiniMax-M2.7` 改寫為 `MiniMax-M2.7-highspeed`。
</Note>

由外掛擁有的功能分工：

* 文字／聊天預設維持使用 `minimax/MiniMax-M3`
* 影像生成使用 `minimax/image-01` 或 `minimax-portal/image-01`
* 兩種 MiniMax 驗證路徑上的影像理解，皆由外掛擁有的 `MiniMax-VL-01` 負責
* 網頁搜尋維持使用提供者 ID `minimax`

### LM Studio

LM Studio 以使用原生 API 的內建提供者外掛形式提供：

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

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: { model: { primary: "lmstudio/openai/gpt-oss-20b" } },
  },
}
```

OpenClaw 使用 LM Studio 的原生 `/api/v1/models` 和 `/api/v1/models/load` 進行探索與自動載入，並預設使用 `/v1/chat/completions` 進行推論。若要讓 LM Studio 的即時載入、TTL 和自動逐出功能管理模型生命週期，請設定 `models.providers.lmstudio.params.preload: false`。如需設定與疑難排解，請參閱 [/providers/lmstudio](/zh-TW/providers/lmstudio)。

### Ollama

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 安裝 Ollama，然後拉取模型：
ollama pull llama3.3
```

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: { model: { primary: "ollama/llama3.3" } },
  },
}
```

使用 `OLLAMA_API_KEY` 選擇啟用後，系統會在本機的 `http://127.0.0.1:11434` 偵測 Ollama，而內建提供者外掛會將 Ollama 直接加入 `openclaw onboard` 和模型選擇器。如需初始設定、雲端／本機模式及自訂配置，請參閱 [/providers/ollama](/zh-TW/providers/ollama)。

### vLLM

vLLM 以適用於本機／自行託管 OpenAI 相容伺服器的內建提供者外掛形式提供：

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

若要在本機選擇啟用自動探索（如果你的伺服器未強制要求驗證，任何值皆可）：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
export VLLM_API_KEY="vllm-local"
```

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: { model: { primary: "vllm/your-model-id" } },
  },
}
```

詳細資訊請參閱 [/providers/vllm](/zh-TW/providers/vllm)。

### SGLang

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

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

若要在本機選擇啟用自動探索（如果你的伺服器未強制要求驗證，任何值皆可）：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
export SGLANG_API_KEY="sglang-local"
```

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: { model: { primary: "sglang/your-model-id" } },
  },
}
```

詳細資訊請參閱 [/providers/sglang](/zh-TW/providers/sglang)。

### 本機代理伺服器（LM Studio、vLLM、LiteLLM 等）

範例（OpenAI 相容）：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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,
          },
        ],
      },
    },
  },
}
```

<AccordionGroup>
  <Accordion title="預設選用欄位">
    對於自訂提供者，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 皆為選用。省略時，OpenClaw 的預設值如下：

    * `reasoning: false`
    * `input: ["text"]`
    * `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
    * `contextWindow: 200000`
    * `maxTokens: 8192`

    建議：設定與代理伺服器／模型限制相符的明確值。
  </Accordion>

  <Accordion title="代理路由塑形規則">
    * 對於非原生端點上的 `api: "openai-completions"`（任何主機不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 會強制使用 `compat.supportsDeveloperRole: false`，以避免不支援 `developer` 角色而導致提供者傳回 400 錯誤。
    * 代理型 OpenAI 相容路由也會略過僅適用於原生 OpenAI 的請求塑形：不使用 `service_tier`、不使用 Responses `store`、不使用 Completions `store`、不使用提示詞快取提示、不執行 OpenAI 推理相容承載資料塑形，也不加入隱藏的 OpenClaw 歸屬標頭。
    * 若 OpenAI 相容的 Completions 代理伺服器需要廠商特定欄位，請設定 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），以將額外 JSON 合併至送出的請求本文。
    * 若要控制 vLLM 聊天範本，請設定 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。當工作階段的思考層級為關閉時，內建 vLLM 外掛會自動為 `vllm/nemotron-3-*` 傳送 `enable_thinking: false` 和 `force_nonempty_content: true`。
    * 對於速度較慢的本機模型或遠端 LAN／tailnet 主機，請設定 `models.providers.<id>.timeoutSeconds`。這會延長提供者模型 HTTP 請求的處理時間，包括連線、標頭、本文串流及整體受保護擷取的中止時間，但不會延長整個代理程式執行階段的逾時時間。若 `agents.defaults.timeoutSeconds` 或執行作業特定的逾時時間較短，也請提高該上限；提供者逾時時間無法延長整體執行作業。
    * 模型提供者 HTTP 呼叫僅針對所配置提供者的 `baseUrl` 主機名稱，允許 `198.18.0.0/15` 和 `fc00::/7` 中的 Surge、Clash 與 sing-box 假 IP DNS 回應。自訂／本機提供者端點也會信任該配置的確切 `scheme://host:port` 來源，以進行受保護的模型請求，包括回送、LAN 和 tailnet 主機。這並非新的配置選項；你配置的 `baseUrl` 只會針對該來源擴充請求政策。允許假 IP 主機名稱與信任確切來源是彼此獨立的機制。其他私有、回送、連結本機、metadata 目的地及不同連接埠，仍需明確選擇啟用 `models.providers.<id>.request.allowPrivateNetwork: true`。設定 `models.providers.<id>.request.allowPrivateNetwork: false` 可選擇停用確切來源信任。
    * 若 `baseUrl` 為空白／省略，OpenClaw 會保留預設的 OpenAI 行為（解析結果為 `api.openai.com`）。
    * 基於安全考量，在非原生 `openai-completions` 端點上，明確設定的 `compat.supportsDeveloperRole: true` 仍會被覆寫。
    * 對於非直接端點上的 `api: "anthropic-messages"`（除標準 `anthropic` 以外的任何提供者，或主機不是公開 `api.anthropic.com` 端點的自訂 `models.providers.anthropic.baseUrl`），OpenClaw 會抑制隱含的 Anthropic Beta 標頭，例如 `claude-code-20250219`、`interleaved-thinking-2025-05-14` 和 OAuth 標記，使自訂 Anthropic 相容代理伺服器不會拒絕不支援的 Beta 旗標。若代理伺服器需要特定 Beta 功能，請明確設定 `models.providers.<id>.headers["anthropic-beta"]`。
  </Accordion>
</AccordionGroup>

## 命令列介面範例

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw onboard --auth-choice opencode-zen
openclaw models set opencode/claude-opus-4-6
openclaw models list
```

另請參閱：[配置](/zh-TW/gateway/configuration)，其中提供完整的配置範例。

## 相關內容

* [配置參考](/zh-TW/gateway/config-agents#agent-defaults) - 模型配置鍵
* [模型容錯移轉](/zh-TW/concepts/model-failover) - 備援鏈與重試行為
* [模型](/zh-TW/concepts/models) - 模型配置與別名
* [提供者](/zh-TW/providers) - 各提供者的設定指南