OpenClaw 模型配置指南：設定 Primary 與 Fallback 機制

身為開發者，你一定遇過這種情況：想換個最新的模型試試看效果，卻得在好幾個設定檔之間跳來跳去，還要擔心 API key 有沒有設定對。如果模型突然掛了，或是額度用完，手動切換備援方案簡直是場災難。

管理一堆 API key 和不同 Provider 的模型清單，本來應該是簡單的事，卻往往變成開發過程中的絆腳石。OpenClaw 的 Models CLI 就是為了幫你搞定這些瑣事而設計的，讓你專注在開發 AI 應用，而不是在設定檔裡迷路。

關於認證設定檔輪換、冷卻時間以及它們如何與備援機制互動，請參考 /concepts/model-failover。 快速 Provider 總覽與範例請見：/concepts/model-providers。

模型選擇的運作方式

OpenClaw 會依照以下順序選擇模型：

1. Primary 模型（agents.defaults.model.primary 或 agents.defaults.model）。
2. agents.defaults.model.fallbacks 中的 Fallbacks（依序選擇）。
3. 在移動到下一個模型之前，會在 Provider 內部先進行 Provider auth failover（認證故障轉移）。

相關說明：

• agents.defaults.models 是 OpenClaw 可以使用的模型白名單/目錄（加上別名）。
• agents.defaults.imageModel 僅在主要模型無法接受圖片時使用。
• agents.defaults.imageGenerationModel 由共用的圖片生成功能使用。如果省略，image_generate 仍可以從相容且有認證支援的圖片生成外掛中推斷 Provider 預設值。如果你設定了特定的 Provider/模型，也請配置該 Provider 的認證/API key。
• 每個 Agent 的預設值可以透過 agents.list[].model 加上綁定（bindings）來覆蓋 agents.defaults.model（請參閱 /concepts/multi-agent）。

快速模型策略

• 將你的 Primary 模型設定為你能使用的最強最新一代模型。
• 對於成本/延遲敏感的任務以及低風險的聊天，請使用 Fallbacks。
• 對於啟用工具的 Agent 或不受信任的輸入，請避免使用較舊或較弱的模型層級。

新手引導（推薦）

如果你不想手動編輯設定，請執行 onboarding：

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.imageGenerationModel.primary 和 agents.defaults.imageGenerationModel.fallbacks
• agents.defaults.models（白名單 + 別名 + Provider 參數）
• models.providers（寫入 models.json 的自定義 Provider）

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

Provider 設定範例（包括 OpenCode）位於 /providers/opencode。

「模型不被允許」（以及為何回覆會停止）

如果設定了 agents.defaults.models，它就會變成 /model 和 session 覆蓋的 白名單 (allowlist)。當用戶選擇了一個不在該白名單中的模型時，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-6" },
    models: {
      "anthropic/claude-sonnet-4-6": { 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 會立即更新 session 選擇。如果 Agent 處於閒置狀態，下一次執行會立即使用新模型。如果 Agent 正在忙碌，正在執行的任務會先完成，之後佇列中或未來的任務會使用新模型。
• /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

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

• --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 的 免費模型目錄 (free model catalog)，並可以選擇性地探測模型對工具和圖片的支援。

關鍵 flags：

• --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（請參閱 /help/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 優先。
• 僅當該 Provider 在當前設定/認證設定檔上下文中不是由 SecretRef 管理時，Agent models.json 中的非空 apiKey 優先。
• SecretRef 管理的 Provider apiKey 值會從來源標記（環境變數引用為 ENV_VAR_NAME，檔案/執行引用為 secretref-managed）重新整理，而不是持久化解析後的秘密值。
• SecretRef 管理的 Provider header 值會從來源標記（環境變數引用為 secretref-env:ENV_VAR_NAME，檔案/執行引用為 secretref-managed）重新整理。
• 空白或缺失的 Agent apiKey/baseUrl 會回退到設定檔的 models.providers。
• 其他 Provider 欄位會從設定檔和標準化的目錄數據中重新整理。

標記持久化是以來源為準的：OpenClaw 會從活躍的來源設定快照（解析前）寫入標記，而不是從解析後的執行時秘密值寫入。這適用於 OpenClaw 重新生成 models.json 的任何時候，包括像 openclaw agent 這樣的命令驅動路徑。

相關內容

• 模型供應商 — Provider 路由與認證
• 模型故障轉移 — 備援鏈
• 圖片生成 — 圖片模型設定
• 設定參考 — 模型設定鍵值

下一步

• 設定你的第一個 Agent
• 了解如何處理 API 錯誤

想要更快速地完成設定嗎？試試我們的 AI Setup Assistant。