模型命令列介面

模型參照（provider/model）會選擇供應商與模型，而非底層 代理程式執行階段。當未設定執行階段原則或設為 auto 時，OpenAI 供應商所擁有的 路由原則可能只會針對完全相符的官方 HTTPS Platform Responses 或 ChatGPT Responses 路由選擇 Codex，且要求沒有自行指定的請求覆寫； 僅有 openai/* 前綴絕不會選擇 Codex。Completions 轉接器、自訂 端點，以及自行指定的請求行為仍會由 OpenClaw 處理。官方的純文字 HTTP 端點會遭拒絕。請參閱 OpenAI 隱含代理程式執行階段。

訂閱版 Copilot 參照（github-copilot/*）可選擇使用外部 GitHub Copilot 代理程式執行階段外掛，但此路徑一律必須明確指定（絕不會 由 auto 選取）。執行階段覆寫應設於供應商／模型原則，而非 整個代理程式或工作階段。執行階段選擇不會決定計費方式： OpenAI API 金鑰與 ChatGPT/Codex 訂閱認證資訊仍彼此獨立。請參閱 代理程式執行階段與 GitHub Copilot 代理程式執行階段。

選擇順序

相關模型設定介面：

• agents.defaults.models 是 OpenClaw 可使用模型的允許清單／目錄，並包含別名。使用 provider/* 項目即可允許供應商中所有已探索到的模型，無須逐一列出。
• agents.defaults.utilityModel 是選用的低成本模型，用於簡短的內部工作，例如產生儀表板工作階段標題、受支援頻道的討論串／主題標題，以及進度敘述。每個代理程式的 agents.list[].utilityModel 會覆寫此設定。未設定時，若主要供應商宣告了小型模型預設值，OpenClaw 便會使用該值（OpenAI → gpt-5.6-luna、Anthropic → claude-haiku-4-5）；否則會使用代理程式的主要模型。將其設為空字串即可停用公用模型路由。公用工作是獨立的模型呼叫，且可能會將有限範圍的工作內容傳送給所選的模型供應商。
• agents.defaults.imageModel 僅在主要模型無法接收圖片時使用。
• agents.defaults.pdfModel 由 pdf 工具使用。若未設定，該工具會依序退回使用 imageModel，再使用已解析的工作階段／預設模型。
• agents.defaults.imageGenerationModel、musicGenerationModel 和 videoGenerationModel 支援共用媒體產生工具。若未設定，每個工具會推斷具認證支援的供應商預設值：先使用目前的預設供應商，再依供應商 ID 順序使用其餘已註冊且支援該功能的供應商。設定 agents.defaults.mediaGenerationAutoProviderFallback: false 可停用此跨供應商推斷，同時保留明確指定的備援模型。
• 每個代理程式的 agents.list[].model（加上繫結）會覆寫 agents.defaults.model — 請參閱多代理程式路由。

完整設定鍵參考、預設值與 JSON5 範例：設定參考。

選擇來源與備援嚴格程度

相同的 provider/model 會因其來源而有不同的行為：

其他選擇規則：

• 變更 agents.defaults.model.primary 不會改寫現有的工作階段固定設定。如果狀態回報 This session is pinned to X; config primary Y will apply to new/unpinned sessions.，請執行 /model default 清除固定設定。
• 當 models.mode: "replace" 時，命令列介面的預設模型與允許清單選擇器只會列出 models.providers.*.models，而非完整的內建目錄。
• Control UI 模型選擇器會向閘道要求其已設定的模型檢視：若有設定 agents.defaults.models，便使用該設定（包括 provider/* 萬用字元項目）；否則使用 models.providers.*.models，再加上具有可用認證的供應商。完整的內建目錄僅供明確瀏覽檢視使用（models.list 搭配 view: "all"，或 openclaw models list --all）。
• 供應商清單使用者介面會使用搭配 view: "provider-config" 的 models.list，顯示來源所指定的 models.providers.*.models 資料列，而不套用選擇器允許清單。

完整機制：模型容錯移轉。

快速模型原則

• 將主要模型設為你可用的最強新一代模型。
• 對成本／延遲敏感的工作與風險較低的聊天使用備援模型。
• 對啟用工具的代理程式或不受信任的輸入，請避免使用較舊／較弱的模型層級。

初始設定

openclaw onboard

為常見供應商設定模型與認證，無須手動編輯設定，包括 OpenAI Codex 訂閱 OAuth 和 Anthropic（API 金鑰或重複使用 Claude 命令列介面）。

若未設定主要模型，全新的 OpenAI API 金鑰設定會選擇 openai/gpt-5.6；不含層級的直接 API ID 會解析至 Sol 層級。全新的 ChatGPT/Codex OAuth 設定會選擇完全相符的 openai/gpt-5.6-sol 目錄參照。 重新驗證會保留現有且明確指定的主要模型，包括 openai/gpt-5.5。若帳戶無法使用 GPT-5.6，請明確選擇 openai/gpt-5.5；OpenClaw 不會在未告知的情況下將其降級。

“不允許使用模型”（以及回覆為何停止）

若已設定 agents.defaults.models，它就會成為 /model 和工作階段覆寫的允許清單。在產生任何一般回覆前，選取允許清單外的模型會傳回：

不允許使用模型 "provider/model"。請使用 /models 列出供應商，或使用 /models <provider> 列出模型。使用以下命令新增：openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

修正方式是將模型加入 agents.defaults.models、完全清除允許清單（移除該鍵），或從 /model list 選擇模型。如果遭拒的命令包含執行階段覆寫，例如 /model openai/gpt-5.5 --runtime codex，請先修正允許清單，再重試相同的 /model ... --runtime ... 命令。

對於本機／GGUF 模型，允許清單需要包含完整且帶有供應商前綴的參照，例如 ollama/gemma4:26b 或 lmstudio/Gemma4-26b-a4-it-gguf — 請查看 openclaw models list --provider <provider> 以取得確切字串。允許清單啟用後，僅有檔案名稱或顯示名稱並不足夠。

若要限制供應商而不逐一列出每個模型，請使用 provider/* 萬用字元項目：

{  agents: {    defaults: {      models: {        "openai/*": {},        "vllm/*": {},      },    },  },}

之後，/model、/models 和模型選擇器只會顯示這些供應商探索到的目錄，而且無須編輯允許清單即可顯示新模型。你可以混用精確的 provider/model 項目與 provider/* 項目，以納入另一個供應商的特定模型。

包含別名的允許清單範例：

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

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

聊天中的 /model

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

• /model 和 /model list 會顯示精簡的編號選擇器（模型系列 + 可用的供應商）；/model <#> 會從中選取。在 Discord 上，這會開啟供應商／模型下拉式選單，並包含 Submit 步驟；在 Telegram 上，選擇器的選取結果僅限於工作階段，絕不會改寫 openclaw.json 中代理程式的持久預設值。/models add 已棄用，會傳回訊息，而不會從聊天中註冊模型。
• /model 會立即保存新的工作階段選擇。如果代理程式處於閒置狀態，下一次執行會立即使用它；如果已有執行正在進行，切換會排入佇列，於下一個乾淨的重試點套用（如果工具活動或回覆輸出已開始，則於更後面的重試點套用）。
• /model default 會清除工作階段選擇，使其再次繼承已設定的主要模型。
• 使用者透過 /model 選取的參照對該工作階段具有嚴格約束：如果該模型變得無法連線，回覆會明確失敗，而不會透過 agents.defaults.model.fallbacks 靜默切換。已設定的預設值與排程工作的主要模型仍會使用後備鏈。
• /model status 是詳細檢視：顯示每個供應商的驗證候選項目，以及（若已設定）供應商端點 baseUrl 與 api 模式。
• 模型參照會在第一個 / 處分割進行剖析；請輸入 provider/model。如果模型 ID 本身包含 /（OpenRouter 風格），請包含供應商前綴，例如 /model openrouter/moonshotai/kimi-k2。如果省略供應商，OpenClaw 會依序嘗試：(1) 別名符合項目、(2) 該未加前綴之確切模型 ID 的唯一已設定供應商符合項目、(3) 已設定的預設供應商（已棄用的後備機制）——如果該供應商已不再提供已設定的預設模型，則改用第一個已設定的供應商／模型，以避免顯示已移除供應商的過時預設值。
• 模型參照會正規化為小寫；除此之外，供應商 ID 必須完全相符，因此請使用外掛公布的 ID。

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

命令列介面

openclaw models statusopenclaw models listopenclaw models set <provider/model>openclaw models set-image <provider/model>openclaw models scanopenclaw models aliases list|add|removeopenclaw models fallbacks list|add|remove|clearopenclaw models image-fallbacks list|add|remove|clearopenclaw models auth list|add|login|paste-api-key|paste-token|setup-token|order

沒有子命令的 openclaw models 是 models status 的捷徑，後者也會顯示驗證儲存區設定檔的 OAuth 到期時間（預設在 24 小時內到期時發出警告）。完整旗標、JSON 結構與驗證設定檔子命令：模型命令列介面參考。

模型登錄檔（models.json）

在 models.providers 下設定的自訂供應商會寫入代理程式目錄中的 models.json（預設為 ~/.openclaw/agents/<agentId>/agent/models.json）。供應商外掛目錄會分別儲存為產生的外掛自有目錄分片，並自動載入。此檔案預設會與設定合併；設定 models.mode: "replace" 即可只使用你設定的供應商。

標記保存以來源為準：每當 OpenClaw 重新產生 models.json 時（包括由命令驅動的路徑，例如 openclaw agent），都會從使用中的來源設定快照（解析前）寫入標記，而不是從已解析的執行階段密鑰值寫入。

相關內容

• 代理程式執行階段 — OpenClaw、Codex 與其他代理程式迴圈執行階段
• 設定參考 — 模型設定鍵
• 圖片生成 — 圖片模型設定
• 模型容錯移轉 — 後備鏈
• 模型供應商 — 供應商路由與驗證
• 模型命令列介面參考 — 完整命令與旗標參考
• 音樂生成 — 音樂模型設定
• 影片生成 — 影片模型設定