模型 CLI

OpenClaw 的模型 CLI 管理模型選擇、供應商驗證及備援配置，包括完整的 CLI 命令和設定說明。

概覽

相關文件：模型備援請參閱 /concepts/model-failover，供應商概覽請參閱 /concepts/model-providers。

模型選擇機制

OpenClaw 依以下順序選擇模型：

Primary 模型（agents.defaults.model.primary 或 agents.defaults.model）。
Fallbacks，在 agents.defaults.model.fallbacks 中（依序）。
供應商驗證備援在移至下一個模型之前，發生在供應商內部。

相關設定：

agents.defaults.models 是 OpenClaw 可使用的模型允許清單/目錄（加上別名）。
agents.defaults.imageModel 僅在主要模型無法處理圖片時使用。
每個 Agent 的預設值可透過 agents.list[].model 加上綁定覆寫 agents.defaults.model（請參閱多 Agent 路由）。

設定精靈（建議）

若不想手動編輯設定，請執行入門精靈：

openclaw onboard

它可以為常見供應商設定模型與驗證，包括 OpenAI Code (Codex) 訂閱（OAuth）和 Anthropic（建議使用 API 金鑰；也支援 claude setup-token）。

設定鍵（概覽）

agents.defaults.model.primary 和 agents.defaults.model.fallbacks
agents.defaults.imageModel.primary 和 agents.defaults.imageModel.fallbacks
agents.defaults.models（允許清單 + 別名 + 供應商參數）
models.providers（自訂供應商寫入 models.json）

模型參照正規化為小寫。供應商別名如 z.ai/* 正規化為 zai/*。

供應商設定範例（包括 OpenCode Zen）位於 Gateway 設定。

「Model is not allowed」（以及回覆停止的原因）

若設定了 agents.defaults.models，它會成為 /model 和工作階段覆寫的允許清單。當使用者選擇不在允許清單中的模型時，OpenClaw 回傳：

Model "provider/model" is not allowed. Use /model to list available models.

這發生在正常回覆生成之前，因此訊息看起來可能像是「沒有回應」。修復方式為：

將模型加入 agents.defaults.models，或
清除允許清單（移除 agents.defaults.models），或
從 /model list 中選擇一個模型。

允許清單設定範例：

{
  agent: {
    model: { primary: "anthropic/claude-sonnet-4-5" },
    models: {
      "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
      "anthropic/claude-opus-4-6": { alias: "Opus" },
    },
  },
}

在聊天中切換模型（`/model`）

你可以在不重新啟動的情況下切換當前工作階段的模型：

/model
/model list
/model 3
/model openai/gpt-5.2
/model status

注意事項：

/model（和 /model list）是精簡的編號選擇器（模型系列 + 可用供應商）。
在 Discord 上，/model 和 /models 會開啟互動式選擇器，包含供應商和模型下拉選單以及提交步驟。
/model <#> 從該選擇器中選擇。
/model status 是詳細檢視（驗證候選及已設定的供應商端點 baseUrl + api 模式）。
模型參照透過在第一個 / 處分割來解析。輸入 /model <ref> 時使用 provider/model 格式。
若模型 ID 本身包含 /（OpenRouter 風格），你必須包含供應商前綴（例如：/model openrouter/moonshotai/kimi-k2）。
若省略供應商，OpenClaw 將輸入視為別名或預設供應商的模型（僅在模型 ID 中沒有 / 時有效）。

完整命令行為/設定：斜線命令。

CLI 命令

openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>

openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

openclaw models image-fallbacks list
openclaw models image-fallbacks add <provider/model>
openclaw models image-fallbacks remove <provider/model>
openclaw models image-fallbacks clear

openclaw models（無子命令）是 models status 的快捷方式。

`models list`

預設顯示已設定的模型。實用的旗標：

--all：完整目錄
--local：僅本地供應商
--provider <name>：依供應商過濾
--plain：每行一個模型
--json：機器可讀輸出

`models status`

顯示解析後的主要模型、備援、圖片模型，以及已設定供應商的驗證概覽。還會呈現在驗證儲存中找到的設定檔的 OAuth 到期狀態（預設在 24 小時內警告）。--plain 僅輸出解析後的主要模型。

OAuth 狀態始終顯示（並包含在 --json 輸出中）。若已設定的供應商沒有憑證，models status 會輸出 Missing auth 區段。

JSON 包含 auth.oauth（警告視窗 + 設定檔）和 auth.providers（每個供應商的有效驗證）。

使用 --check 進行自動化（遺失/過期時退出 1，即將過期時退出 2）。

建議的 Anthropic 驗證方式是 Claude Code CLI setup-token（可在任何地方執行；若需要可在 Gateway 主機上貼上）：

claude setup-token
openclaw models status

掃描（OpenRouter 免費模型）

openclaw models scan 檢查 OpenRouter 的免費模型目錄，並可選擇性地探測模型的工具和圖片支援。

主要旗標：

--no-probe：跳過即時探測（僅元資料）
--min-params <b>：最小參數量（十億）
--max-age-days <days>：跳過較舊的模型
--provider <name>：供應商前綴過濾
--max-candidates <n>：備援清單大小
--set-default：將 agents.defaults.model.primary 設為第一個選擇
--set-image：將 agents.defaults.imageModel.primary 設為第一個圖片選擇

探測需要 OpenRouter API 金鑰（來自驗證設定檔或 OPENROUTER_API_KEY）。沒有金鑰時，使用 --no-probe 僅列出候選。

掃描結果依以下項目排序：

圖片支援
工具延遲
上下文大小
參數數量

輸入來源：

OpenRouter /models 清單（過濾 :free）
需要來自驗證設定檔或 OPENROUTER_API_KEY 的 OpenRouter API 金鑰
可選過濾器：--max-age-days、--min-params、--provider、--max-candidates
探測控制：--timeout、--concurrency

在 TTY 中執行時，你可以互動式選擇備援。在非互動模式下，傳遞 --yes 以接受預設值。

模型登錄（`models.json`）

models.providers 中的自訂供應商會寫入 Agent 目錄下的 models.json（預設 ~/.openclaw/agents/<agentId>/models.json）。除非 models.mode 設為 replace，否則此檔案預設為合併模式。

匹配供應商 ID 的合併模式優先順序：

Agent models.json 中已存在的非空 apiKey/baseUrl 優先。
空的或缺失的 Agent apiKey/baseUrl 回退到設定中的 models.providers。
其他供應商欄位會從設定和正規化的目錄資料中重新整理。