模型命令列介面

模型參照（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 儲存別名與各模型設定。新增項目不會限制模型覆寫。
• agents.defaults.modelPolicy.allow 是選用的覆寫允許清單。請使用完整參照，或使用結尾前綴萬用字元，例如 provider/* 和 provider/namespace/*；省略此項或設為 [] 即允許任何模型。各代理程式的 agents.entries.*.modelPolicy.allow 會取代該代理程式的預設政策。
• agents.defaults.utilityModel 是選用的低成本模型，用於簡短的內部工作，例如產生儀表板工作階段標題、支援的頻道討論串／主題標題及進度敘述。各代理程式的 agents.entries.*.utilityModel 可覆寫此設定。未設定時，若主要供應商有宣告小型模型預設值，OpenClaw 便會使用該值（OpenAI → gpt-5.6-luna、Anthropic → claude-haiku-4-5）；否則使用代理程式的主要模型。將其設為空字串可停用公用工作路由。若不同的公用工作模型失敗，產生標題時會使用主要模型重試一次。對於儀表板標題，自動推導公用工作模型與一般備援會遵循有效工作階段的供應商及認證設定檔；明確指定的公用工作模型則保留其設定的供應商／認證。空白的公用工作模型只會略過替代的小型模型路由，不會略過儀表板標題的產生。公用工作是獨立的模型呼叫，且可能會將有限的工作內容傳送至所選的模型供應商。
• agents.defaults.imageModel 僅在主要模型無法接受圖片時使用。
• agents.defaults.pdfModel 由 pdf 工具使用。若未設定，該工具會依序改用 imageModel，再使用解析後的工作階段／預設模型。
• agents.defaults.mediaModels.{image,music,video} 支援共用媒體產生工具。若未設定，每個工具會推斷具有認證支援的供應商預設值：先使用目前的預設供應商，再依供應商 ID 順序嘗試其餘已為該能力註冊的供應商。跨供應商備援是固定的預設行為。
• 各代理程式的 agents.entries.*.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，而非完整的內建目錄。
• 控制介面的模型選擇器會向閘道要求其已設定的模型檢視。明確的 modelPolicy.allow 會篩選該檢視，包括結尾前綴萬用字元項目；否則會顯示已設定的模型，以及具有可用認證的供應商。完整的內建目錄僅保留給明確的瀏覽檢視（帶有 view: "all" 的 models.list，或 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.modelPolicy.allow 非空白，它會成為 /model、工作階段覆寫和 --model 的允許清單。選擇清單以外的模型時，會在產生任何一般回覆前返回。各代理程式的 agents.entries.*.modelPolicy.allow 會取代該代理程式的預設政策。

agents.defaults.modelPolicy.allow 不允許模型覆寫 "provider/model"。請將 "provider/model"、"provider/*" 或更精確的 "provider/namespace/*" 前綴新增至 agents.defaults.modelPolicy.allow，或移除／清空清單以允許任何模型。

修正方式包括：將模型或供應商萬用字元新增至指定的 modelPolicy.allow 鍵、移除／清空該清單，或從 /model list 選擇模型。若遭拒絕的命令包含 /model openai/gpt-5.5 --runtime codex 等執行環境覆寫，請先修正允許清單，再重試相同的命令。

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

若要限制供應商而不逐一列出每個模型，請使用結尾前綴萬用字元項目。涵蓋整個供應商的 provider/* 會符合該供應商下的所有模型；較精確的前綴（例如 clawrouter/anthropic/*）則只會符合該命名空間：

{  agents: {    defaults: {      modelPolicy: {        allow: ["openai/*", "vllm/*"],      },    },  },}

/model、/models 和模型選擇器接著只會顯示這些供應商的已探索目錄，且新模型無須編輯允許清單即可出現。混合使用完整的 provider/model 項目與 provider/* 項目，即可納入其他供應商的某個特定模型。

包含別名與各模型設定的允許清單範例：

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

openclaw config set agents.defaults.modelPolicy.allow '["openai/gpt-5.4","anthropic/*"]' --strict-json

聊天中的 /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 和其他代理程式迴圈執行階段
• 設定參考 — 模型設定鍵
• 圖片生成 — 圖片模型設定
• 模型容錯移轉 — 容錯移轉鏈
• 模型供應商 — 供應商路由與驗證
• 模型命令列介面參考 — 完整命令與旗標參考
• 音樂生成 — 音樂模型設定
• 影片生成 — 影片模型設定