模型容錯移轉

Documentation Index

Fetch the complete documentation index at: https://docs2.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 清除。沒有明確 heartbeat.model 的 Heartbeat 執行，在其來源不再符合目前已設定預設值時，也會清除直接的自動覆寫。
• 使用者工作階段覆寫：/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 計數增加）
• 設定檔處於冷卻/停用狀態

​

OpenAI Codex 訂閱加 API 金鑰備援

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

​

冷卻

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

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

​

帳單停用

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

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

​

模型 fallback

​

候選鏈規則

​

哪些錯誤會推進 fallback

​

冷卻略過與探測行為

​

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

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

​

可觀測性與失敗摘要

• 嘗試的提供者/模型
• 原因（rate_limit、overloaded、billing、auth、model_not_found 與類似的 failover 原因）
• 選用狀態/代碼
• 人類可讀的錯誤摘要

• 與嘗試的提供者/模型鏈不相關的模型範圍速率限制會被忽略
• 如果剩餘阻擋是相符的模型範圍速率限制，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 路由