模型 CLI

認證設定檔輪替、冷卻機制及其與回退的互動方式請參閱 /concepts/model-failover。 Provider 快速總覽 + 範例：/concepts/model-providers。

模型選擇的運作方式

OpenClaw 按以下順序選擇模型：

  1. 主要模型（agents.defaults.model.primary 或 agents.defaults.model）。
  2. 回退模型：agents.defaults.model.fallbacks（按順序）。
  3. Provider 認證容錯在切換到下一個模型之前，先在 provider 內部執行。

相關：

  • agents.defaults.models 是 OpenClaw 可使用的模型允許清單/目錄（加上別名）。
  • agents.defaults.imageModel 只在主要模型無法接受圖片時使用。
  • Per-agent 預設值可透過 agents.list[].model 加上綁定覆寫 agents.defaults.model（請參閱 /concepts/multi-agent）。

模型選用策略

  • 將主要模型設為你可用的最強最新世代模型。
  • 用回退模型處理對成本/延遲敏感的任務和較輕鬆的聊天。
  • 對於啟用工具的 agent 或不受信任的輸入，避免使用較舊/較弱的模型。

設定精靈（建議使用）

如果不想手動編輯設定，執行上線精靈：

openclaw onboard

它可以為常用 provider 設定模型 + 認證，包括 OpenAI Code (Codex) 訂閱（OAuth）和 Anthropic（API key 或 claude setup-token）。

設定鍵（概覽）

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

模型引用會正規化為小寫。Provider 別名如 z.ai/* 正規化為 zai/*。

Provider 設定範例（包括 OpenCode）在 /gateway/configuration。

「Model is not allowed」（以及為什麼回覆停了）

如果設定了 agents.defaults.models，它就成為 /model 和 session 覆寫的允許清單。當使用者選擇了不在允許清單中的模型時，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）

你可以在不重啟的情況下為當前 session 切換模型：

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

注意事項：

  • /model（和 /model list）是精簡的編號選擇器（模型系列 + 可用 provider）。
  • 在 Discord 上，/model 和 /models 會開啟一個互動式選擇器，有 provider 和模型下拉選單加上提交步驟。
  • /model <#> 從選擇器中選取。
  • /model status 是詳細檢視（認證候選者，設定時還會顯示 provider 端點 baseUrl + api 模式）。
  • 模型引用以第一個 / 為分隔符解析。輸入 /model <ref> 時使用 provider/model 格式。
  • 如果模型 ID 本身包含 /（OpenRouter 風格），必須包含 provider 前綴（例如：/model openrouter/moonshotai/kimi-k2）。
  • 省略 provider 時，OpenClaw 會把輸入視為別名或預設 provider 的模型（只在模型 ID 不含 / 時有效）。

完整指令行為/設定：Slash commands。

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
  • --provider <name>：按 provider 篩選
  • --plain：每行一個模型
  • --json：機器可讀輸出

models status

顯示解析後的主要模型、回退模型、圖片模型，以及已設定 provider 的認證概覽。也會顯示驗證儲存中找到的 OAuth 到期狀態（預設在 24 小時內警告）。--plain 只印出解析後的主要模型。 OAuth 狀態始終顯示（也包含在 --json 輸出中）。如果已設定的 provider 沒有認證，models status 會印出 Missing auth 區段。 JSON 包含 auth.oauth（警告視窗 + 設定檔）和 auth.providers（每個 provider 的有效認證）。 用 --check 做自動化（缺失/過期時退出碼 1，即將過期時 2）。

認證選擇取決於 provider/帳號。對於需要全天候運行的 gateway 主機，API key 通常是最可預測的；也支援訂閱 token 流程。

範例（Anthropic setup-token）：

claude setup-token
openclaw models status

掃描（OpenRouter 免費模型）

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

主要旗標：

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

探測需要 OpenRouter API key（從驗證設定檔或 OPENROUTER_API_KEY）。沒有 key 時，用 --no-probe 僅列出候選者。

掃描結果排序依據：

  1. 圖片支援
  2. 工具延遲
  3. 上下文大小
  4. 參數量

輸入

  • OpenRouter /models 清單（篩選 :free）
  • 需要 OpenRouter API key（從驗證設定檔或 OPENROUTER_API_KEY，請參閱 /environment）
  • 可選篩選器：--max-age-days、--min-params、--provider、--max-candidates
  • 探測控制：--timeout、--concurrency

在 TTY 中執行時，可以互動式選擇回退模型。非互動模式下傳 --yes 接受預設值。

模型登錄檔（models.json）

models.providers 中的自訂 provider 會寫入 agent 目錄下的 models.json（預設 ~/.openclaw/agents/<agentId>/agent/models.json）。除非 models.mode 設為 replace，否則預設以合併模式處理。

合併模式中，匹配 provider ID 的優先順序：

  • agent models.json 中已有的非空 baseUrl 優先。
  • agent models.json 中的非空 apiKey 只在該 provider 不受當前設定/驗證設定檔上下文的 SecretRef 管理時才優先。
  • 受 SecretRef 管理的 provider apiKey 值會從來源標記（環境變數引用的 ENV_VAR_NAME，檔案/exec 引用的 secretref-managed）重新整理，而非持久化已解析的機密。
  • 受 SecretRef 管理的 provider 標頭值會從來源標記（環境變數引用的 secretref-env:ENV_VAR_NAME，檔案/exec 引用的 secretref-managed）重新整理。
  • 空或缺失的 agent apiKey/baseUrl 回退到設定中的 models.providers。
  • 其他 provider 欄位從設定和正規化的目錄資料重新整理。

標記持久化是來源權威的：OpenClaw 從啟用的來源設定快照（解析前）寫入標記，而非從已解析的執行時機密值。 這適用於 OpenClaw 重新生成 models.json 的所有情境，包括 openclaw agent 等指令驅動的路徑。

arrow_back
上一頁
Models
下一頁
Model Providers
arrow_forward