模型 CLI

模型 ref 會選擇提供者和模型。它們通常不會選擇低階代理執行階段。例如，openai/gpt-5.5 可以透過一般 OpenAI 提供者路徑執行，也可以透過 Codex app-server 執行階段執行，取決於 agents.defaults.agentRuntime.id。在 Codex 執行階段模式中，openai/gpt-* ref 不代表 API 金鑰計費；Auth 可以來自 Codex 帳戶或 openai-codex Auth 設定檔。請參閱代理執行階段。

# 模型選擇如何運作

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

# 選擇來源與備援行為

相同的 provider/model 可能會依其來源代表不同含義：

• 已設定的預設值（agents.defaults.model.primary 和代理專屬主要模型）是一般起點，並使用 agents.defaults.model.fallbacks。
• 自動備援選擇是暫時復原狀態。它們會以 modelOverrideSource: "auto" 儲存，讓後續回合能繼續使用備援鏈，而不必先探測已知有問題的主要模型。
• 使用者工作階段選擇是精確的。/model、模型選擇器、session_status(model=...) 和 sessions.patch 會儲存 modelOverrideSource: "user"；如果該選取的提供者/模型無法連線，OpenClaw 會明確失敗，而不是落入另一個已設定的模型。
• Cron --model / payload model 是每個工作的主要模型。除非工作提供明確的 payload fallbacks，否則它仍會使用已設定的備援（若要嚴格執行 cron，請使用 fallbacks: []）。
• CLI 預設模型和允許清單選擇器會遵守 models.mode: "replace"，列出明確的 models.providers.*.models，而不是載入完整的內建目錄。
• Control UI 模型選擇器會向 Gateway 詢問其已設定的模型檢視：存在時使用 agents.defaults.models，否則使用明確的 models.providers.*.models 加上具有可用 Auth 的提供者。完整內建目錄保留給明確瀏覽檢視，例如含有 view: "all" 的 models.list 或 openclaw models list --all。

# 快速模型政策

• 將主要模型設定為你可用的最強最新世代模型。
• 對成本/延遲敏感任務和較低風險聊天使用備援。
• 對於啟用工具的代理或不受信任的輸入，避免使用較舊/較弱的模型層級。

# 入門設定（建議）

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

openclaw onboard

它可以為常見提供者設定模型 + Auth，包括 OpenAI Code (Codex) 訂閱（OAuth）和 Anthropic（API 金鑰或 Claude CLI）。

# 設定鍵（概覽）

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

# 安全的允許清單編輯

手動更新 agents.defaults.models 時，請使用加法寫入：

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge

# 「模型不被允許」（以及回覆停止的原因）

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

Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

當被拒絕的命令包含執行階段覆寫，例如 /model openai/gpt-5.5 --runtime codex，請先修正允許清單，然後重試相同的 /model ... --runtime ... 命令。對於原生 Codex 執行，選取的模型仍是 openai/gpt-5.5；codex 執行階段會選擇 harness，並另外使用 Codex Auth。

對於本機/GGUF 模型，請將完整的 provider-prefixed ref 儲存在允許清單中， 例如 ollama/gemma4:26b、lmstudio/Gemma4-26b-a4-it-gguf，或 openclaw models list --provider <provider> 顯示的 確切 provider/model。當允許清單啟用時，單獨的本機檔名或顯示名稱並不足夠。

允許清單設定範例：

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

# 在聊天中切換模型 (/model)

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

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

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

# 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

預設顯示已設定／可用驗證的模型。實用旗標：

--allboolean

完整目錄。包含在設定驗證之前由內建提供者擁有的靜態目錄列，因此僅供探索的檢視可以顯示在新增相符提供者憑證之前無法使用的模型。

--localboolean

僅限本機提供者。

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> 依提供者 ID 篩選，例如 moonshot。不接受互動式選擇器中的顯示標籤。

--plainboolean

每行一個模型。

--jsonboolean

機器可讀輸出。

# models status

顯示解析後的主要模型、備用模型、影像模型，以及已設定提供者的驗證概覽。它也會揭露驗證儲存區中找到的設定檔 OAuth 到期狀態（預設會在 24 小時內發出警告）。--plain 只會列印解析後的主要模型。

範例（Claude CLI）：

claude auth login
openclaw models status

# 掃描（OpenRouter 免費模型）

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

--no-probeboolean

略過即時探測（僅中繼資料）。

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

將 agents.defaults.model.primary 設為第一個選項。

--set-imageboolean

將 agents.defaults.imageModel.primary 設為第一個影像選項。

掃描結果排序依據：

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

輸入：

• OpenRouter /models 清單（篩選 :free）
• 即時探測需要來自驗證設定檔或 OPENROUTER_API_KEY 的 OpenRouter API 金鑰（請參閱環境變數）
• 選用篩選器：--max-age-days、--min-params、--provider、--max-candidates
• 請求／探測控制：--timeout、--concurrency

當即時探測在 TUI 中執行時，你可以互動式選取備用模型。在非互動模式下，傳入 --yes 以接受預設值。僅中繼資料結果僅供參考；--set-default 和 --set-image 需要即時探測，這樣 OpenClaw 才不會設定無法使用、沒有金鑰的 OpenRouter 模型。

# 模型登錄檔（models.json）

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

# 相關

• 代理執行階段 — PI、Codex 和其他代理迴圈執行階段
• 設定參考 — 模型設定鍵
• 影像生成 — 影像模型設定
• 模型容錯移轉 — 備用鏈
• 模型提供者 — 提供者路由與驗證
• 音樂生成 — 音樂模型設定
• 影片生成 — 影片模型設定