模型容錯移轉

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

1. 在目前提供者內進行驗證設定檔輪替。
2. 模型備援到 agents.defaults.model.fallbacks 中的下一個模型。

​

執行階段流程

• providerOverride
• modelOverride
• modelOverrideSource
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

選取來源政策

• 已設定的預設值：agents.defaults.model.primary 會使用 agents.defaults.model.fallbacks。
• 代理主要模型：agents.list[].model 是嚴格的，除非該代理模型物件包含自己的 fallbacks。使用 fallbacks: [] 可明確指定嚴格行為，或提供非空清單讓該代理選擇加入模型備援。
• 自動備援覆寫：執行階段備援會在重試前寫入 providerOverride、modelOverride 和 modelOverrideSource: "auto"。該自動覆寫可以繼續沿著已設定的備援鏈前進，並由 /new、/reset 和 sessions.reset 清除。
• 使用者工作階段覆寫：/model、模型選擇器、session_status(model=...) 和 sessions.patch 會寫入 modelOverrideSource: "user"。這是精確的工作階段選取。如果選定的提供者/模型在產生回覆前失敗，OpenClaw 會回報失敗，而不是從無關的已設定備援回答。
• 舊版工作階段覆寫：較舊的工作階段項目可能有 modelOverride，但沒有 modelOverrideSource。OpenClaw 會將這些視為使用者覆寫，因此明確的舊選取不會被默默轉換成備援行為。
• Cron 承載模型：Cron 工作的 payload.model / --model 是工作主要模型，不是使用者工作階段覆寫。除非該工作提供 payload.fallbacks，否則會使用已設定的備援；payload.fallbacks: [] 會讓 Cron 執行採用嚴格模式。

​

驗證儲存（金鑰 + OAuth）

• 機密存放在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（舊版：~/.openclaw/agent/auth-profiles.json）。
• 執行階段驗證路由狀態存放在 ~/.openclaw/agents/<agentId>/agent/auth-state.json。
• 設定 auth.profiles / auth.order 僅為中繼資料 + 路由（不含機密）。
• 舊版僅匯入 OAuth 檔案：~/.openclaw/credentials/oauth.json（首次使用時匯入至 auth-profiles.json）。

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? }（部分提供者另有 projectId/enterpriseUrl）

​

設定檔 ID

• 預設：沒有可用電子郵件時為 provider:default。
• 有電子郵件的 OAuth：provider:<email>（例如 google-antigravity:user@gmail.com）。

​

輪替順序

• **主要鍵：**設定檔類型（OAuth 優先於 API 金鑰）。
• 次要鍵：usageStats.lastUsed（各類型內最舊的優先）。
• 冷卻/停用的設定檔會移至最後，並依最早到期時間排序。

​

工作階段黏著性（快取友善）

• 工作階段被重設（/new / /reset）
• Compaction 完成（Compaction 計數增加）
• 設定檔處於冷卻/停用狀態

​

為什麼 OAuth 可能「看起來遺失」

• 使用 auth.order[provider] = ["provider:profileId"] 固定，或
• 透過 /model … 搭配設定檔覆寫使用每個工作階段覆寫（當你的 UI/聊天介面支援時）。

​

冷卻

• 1 分鐘
• 5 分鐘
• 25 分鐘
• 1 小時（上限）

{
  "usageStats": {
    "provider:profile": {
      "lastUsed": 1736160000000,
      "cooldownUntil": 1736160600000,
      "errorCount": 2
    }
  }
}

​

帳單停用

{
  "usageStats": {
    "provider:profile": {
      "disabledUntil": 1736178000000,
      "disabledReason": "billing"
    }
  }
}

• 帳單退避從 5 小時開始，並在每次帳單失敗後加倍，上限為 24 小時。
• 如果設定檔已 24 小時沒有失敗，退避計數器會重設（可設定）。
• 過載重試允許在模型備援前進行 1 次同提供者設定檔輪替。
• 過載重試預設使用 0 毫秒退避。

​

模型備援

​

候選鏈規則

​

哪些錯誤會推進備援

​

冷卻略過與探測行為

​

工作階段覆寫與即時模型切換

• 只有明確由使用者驅動的模型變更會標記待處理的即時切換。這包含 /model、session_status(model=...) 和 sessions.patch。
• 系統驅動的模型變更，例如備援輪替、Heartbeat 覆寫或 Compaction，本身絕不會標記待處理的即時切換。
• 使用者驅動的模型覆寫會被視為備援政策的精確選擇，因此無法連線的已選提供者會浮現為失敗，而不是被 agents.defaults.model.fallbacks 掩蓋。
• 在備援重試開始前，回覆執行器會將選取的備援覆寫欄位持久化到工作階段項目。
• 自動備援覆寫會在後續回合保持選取狀態，讓 OpenClaw 不會在每則訊息都探測已知故障的主要模型。/new、/reset 和 sessions.reset 會清除自動來源的覆寫，並將工作階段返回已設定的預設值。
• /status 會顯示選取的模型，且當備援狀態不同時，顯示作用中的備援模型與原因。
• 即時工作階段協調會優先使用持久化的工作階段覆寫，而不是過期的執行階段模型欄位。
• 如果即時切換錯誤指向作用中備援鏈中的較後候選，OpenClaw 會直接跳到該選取模型，而不是先走訪不相關候選。
• 如果備援嘗試失敗，執行器只會回復它寫入的覆寫欄位，而且只有當它們仍符合該失敗候選時才會回復。

​

可觀測性與失敗摘要

• 已嘗試的提供者/模型
• 原因（rate_limit、overloaded、billing、auth、model_not_found，以及類似的容錯移轉原因）
• 選用的狀態/代碼
• 人類可讀的錯誤摘要

• 對已嘗試的提供者/模型鏈而言不相關的模型範圍速率限制會被忽略
• 如果剩餘阻擋是相符的模型範圍速率限制，OpenClaw 會回報仍阻擋該模型的最後相符到期時間

​

相關設定

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel 路由