模型容錯移轉

1. Auth profile 輪替，在目前供應商內進行。
2. 模型備援，切換到 agents.defaults.model.fallbacks 中的下一個模型。

​

執行階段流程

​

選擇來源政策

• 已設定的預設值：agents.defaults.model.primary 使用 agents.defaults.model.fallbacks。
• 代理主要模型：agents.list[].model 預設為嚴格，除非該代理的模型物件包含自己的 fallbacks。使用 fallbacks: [] 可明確表示嚴格行為，或使用非空清單讓該代理選擇加入模型備援。
• 自動備援覆寫：執行階段備援會在重試前寫入 providerOverride、modelOverride、modelOverrideSource: "auto"，以及選取的來源模型。此覆寫會持續沿著已設定的備援鏈前進，而不會在每則訊息都探測主要模型，但 OpenClaw 每 5 分鐘探測一次已設定的來源（不可設定），並在其復原後清除此覆寫。/new、/reset 和 sessions.reset 也會清除自動來源覆寫。在沒有明確 heartbeat.model 的情況下執行的心跳偵測，當其來源不再符合目前已設定的預設值時，會清除直接自動覆寫。
• 使用者工作階段覆寫：/model、模型選擇器、session_status(model=...) 和 sessions.patch 會寫入 modelOverrideSource: "user"。這是精確的工作階段選擇。如果選取的供應商/模型在產生回覆前失敗，OpenClaw 會回報失敗，而不是從無關的已設定備援回答。
• 舊版工作階段覆寫：較舊的工作階段項目可能有 modelOverride，但沒有 modelOverrideSource。OpenClaw 會將這些視為使用者覆寫，因此明確的舊選擇不會被靜默轉換成備援行為。
• Cron 承載模型：cron 工作的 payload.model / --model 是工作主要模型，不是使用者工作階段覆寫。除非工作提供 payload.fallbacks，否則它會使用已設定的備援；payload.fallbacks: [] 會讓 cron 執行變為嚴格。

​

Auth 失敗略過快取

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

​

使用者可見的備援通知

↪️ Model Fallback: <fallback> (selected <primary>; <reason>)

↪️ Model Fallback cleared: <primary> (was <fallback>)

​

Auth 儲存（金鑰 + OAuth）

• 機密與執行階段 auth 路由狀態位於 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite。
• 設定 auth.profiles / auth.order 僅為中繼資料 + 路由（不含機密）。
• 舊版僅匯入 OAuth 檔案：~/.openclaw/credentials/oauth.json（首次使用時匯入每個代理的 auth 儲存）。
• 舊版 auth-profiles.json、auth-state.json，以及每個代理的 auth.json 檔案會由 openclaw doctor --fix 匯入。

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? }（部分供應商另有 projectId/enterpriseUrl）
• type: "token" → 靜態 bearer 風格權杖，可選擇性到期；OpenClaw 不會重新整理它（用於 aws-sdk 和其他憑證鏈 auth 模式）

​

Profile ID

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

​

輪替順序

• 主要鍵： profile 類型（OAuth，接著靜態權杖，接著 API 金鑰）。
• 次要鍵： usageStats.lastUsed（每種類型內最舊者優先）。
• 冷卻/停用的 profile 會移至末尾，依最早到期排序。

​

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

• 工作階段被重設（/new / /reset）
• 壓縮完成（壓縮計數遞增）
• profile 處於冷卻/停用狀態

​

OpenAI Codex 訂閱加上 API 金鑰備份

{
  auth: {
    order: {
      openai: ["openai:user@example.com", "openai:api-key-backup"],
    },
  },
}

​

冷卻

• 第 1 次失敗：30 秒
• 第 2 次失敗：1 分鐘
• 第 3 次以上失敗：5 分鐘（上限）

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

​

帳務停用

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

​

模型後援

​

候選鏈規則

​

哪些錯誤會推進後援

​

冷卻略過與探測行為

​

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

• 只有明確由使用者驅動的模型變更會標記待處理的即時切換。這包含 /model、session_status(model=...) 和 sessions.patch。
• 系統驅動的模型變更，例如後援輪轉、心跳偵測覆寫或壓縮，本身絕不會標記待處理的即時切換。
• 使用者驅動的模型覆寫會被視為後援政策的精確選擇，因此無法連線的已選提供者會浮現為失敗，而不是被 agents.defaults.model.fallbacks 掩蓋。
• 在後援重試開始前，回覆執行器會將選取的後援覆寫欄位持久化到工作階段項目。
• 自動後援覆寫會在後續輪次保持選取，讓 OpenClaw 不會在每則訊息都探測已知失敗的主要模型。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.authPermanentBackoffMinutes / auth.cooldowns.authPermanentMaxMinutes
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel 路由