模型容錯移轉

OpenClaw 分兩個階段處理失敗：

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

執行階段流程

此設計刻意比「儲存並還原整個工作階段」更為限縮。回覆執行器只會保存其為備援所擁有的模型選擇欄位：providerOverride、modelOverride、modelOverrideSource、authProfileOverride、authProfileOverrideSource、authProfileOverrideCompactionCount。這可防止失敗的備援重試覆寫較新的無關工作階段變更，例如手動執行 /model 變更，或在嘗試執行期間發生的工作階段輪替更新。

選擇來源原則

選擇來源會控制是否允許使用備援鏈：

• 已設定的預設值：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 會將其視為使用者覆寫，避免明確的舊選擇在未告知的情況下轉換為備援行為。
• 排程承載資料模型：排程工作的 payload.model／--model 是工作主要模型，而非使用者工作階段覆寫。除非工作提供 payload.fallbacks，否則它會使用已設定的備援；payload.fallbacks: [] 會讓排程執行採嚴格模式。

OpenClaw 會依工作階段與主要模型記住最近的主要模型探測，避免在每一輪都重試失敗的主要模型。工作階段轉移至備援時會傳送可見通知，返回所選主要模型時也會傳送另一則通知；在每一輪固定使用備援時不會重複通知。

驗證失敗略過快取

依預設，每一個新回合都會維持現有的備援重試行為：OpenClaw 會再次重試每個已設定的備援候選項目，包括最近因 auth 或 auth_permanent 而失敗的非主要候選項目。

若要選擇啟用並抑制重複的驗證失敗，請使用：

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

啟用後，非主要備援候選項目發生驗證類別失敗時，OpenClaw 會記錄一個位於記憶體中、限定於工作階段的略過標記，其索引鍵由工作階段 ID、提供者和模型組成。主要候選項目絕不會被略過，因此使用者明確選取模型時仍會顯示真正的驗證錯誤。此快取僅限目前程序，並會在閘道重新啟動時清除。

此值是以毫秒為單位的存留時間。設為 0 或未設定時會停用快取。正值會限制在 1 秒至 10 分鐘之間。

使用者可見的備援通知

工作階段轉移至自動選取的備援時，OpenClaw 會在相同的回覆介面中傳送狀態通知：

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

後續探測成功且工作階段返回所選主要模型時，OpenClaw 會傳送：

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

這些通知是操作訊息，而非助理內容。每次狀態變更只會傳送一次，包括可行時僅有副作用而無回覆內容的回合，但固定使用備援的回合不會重複傳送。其傳送會略過一般的來源回覆抑制、不會占用討論串型頻道中的第一個助理回覆位置，且不會納入文字轉語音與承諾擷取。

驗證儲存空間（金鑰與 OAuth）

OpenClaw 對 API 金鑰與 OAuth 權杖都使用驗證設定檔。

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

更多詳細資料：OAuth

憑證類型：

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? }（部分提供者另有 projectId／enterpriseUrl）
• type: "token" → 靜態持有人權杖，可選擇設定到期時間；OpenClaw 不會重新整理它（用於 aws-sdk 與其他憑證鏈驗證模式）

設定檔 ID

OAuth 登入會建立不同的設定檔，讓多個帳號可以共存。

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

設定檔位於每個代理程式的 openclaw-agent.sqlite 驗證設定檔儲存區中。

輪替順序

當提供者有多個設定檔時，OpenClaw 會依下列方式選擇順序：

如果未設定明確順序，OpenClaw 會使用循環輪替順序：

• **主要索引鍵：**設定檔類型（依序為 OAuth、靜態權杖、API 金鑰）。
• 次要索引鍵：usageStats.lastUsed（每種類型中最舊的優先）。
• 處於冷卻／停用狀態的設定檔會移至末尾，並依最快到期者排序。

工作階段黏著性（有利於快取）

OpenClaw 會將所選驗證設定檔固定至各工作階段，以維持提供者快取的熱度。它不會在每個請求中輪替。固定的設定檔會重複使用，直到：

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

透過 /model …@<profileId> 手動選取會為該工作階段設定使用者覆寫，且在新工作階段開始前不會自動輪替。

OpenAI Codex 訂閱加上 API 金鑰備援

對 OpenAI 代理程式模型而言，驗證與執行階段彼此分離。openai/gpt-* 會繼續使用 Codex 執行框架，而驗證則可在 Codex 訂閱設定檔與 OpenAI API 金鑰備援之間輪替。

使用 auth.order.openai 設定面向使用者的順序：

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

ChatGPT／Codex OAuth 設定檔與 OpenAI API 金鑰設定檔都使用 openai:*。當訂閱達到 Codex 使用量限制時，如果 Codex 提供確切的重設時間，OpenClaw 會記錄該時間、嘗試下一個依序排列的驗證設定檔，並讓執行持續留在 Codex 執行框架內。重設時間過後，訂閱設定檔會再次符合使用資格，下一次自動選擇即可返回該設定檔。

只有在您想強制該工作階段使用特定帳號／金鑰時，才使用使用者固定的設定檔。使用者固定的設定檔刻意採嚴格模式，不會在未告知的情況下跳至其他設定檔。

冷卻

當設定檔因驗證／速率限制錯誤（或看似速率限制的逾時）而失敗時，OpenClaw 會將其標記為冷卻狀態，並移至下一個設定檔。

一般（非計費、非永久驗證）冷卻期會依設定檔近期的錯誤次數增加：

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

設定檔的失敗時間窗經過後，計數器便會重設（auth.cooldowns.failureWindowHours，預設為 24）。

狀態會儲存在每個代理程式的 SQLite 驗證狀態中，位於 usageStats 下：

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

因計費而停用

計費／額度失敗（例如「額度不足」／「額度餘額過低」）會被視為需要進行容錯移轉，但通常並非暫時性問題。OpenClaw 不會採用短暫冷卻期，而會將設定檔標記為已停用（使用較長的退避時間），並輪替至下一個設定檔／提供者。

高度確定的永久驗證失敗（已撤銷／停用的金鑰、已停用的工作區）會進入類似的停用類別，但復原時間會比計費問題短得多，因為某些提供者在事件期間可能會暫時回傳看似驗證失敗的承載資料。

狀態會儲存在每個代理程式的 SQLite 驗證狀態中：

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

預設值（auth.cooldowns.*）：

過載和速率限制錯誤的處理比計費冷卻期更積極：OpenClaw 預設允許重試一次相同提供者的驗證設定檔，接著不等待便切換至下一個已設定的後備模型。

模型後備切換

如果某個提供者的所有設定檔都失敗，OpenClaw 會移至 agents.defaults.model.fallbacks 中的下一個模型。這適用於驗證失敗、速率限制，以及已用盡設定檔輪替的逾時（其他錯誤不會推進後備切換）。對於未提供足夠詳細資訊的提供者錯誤，後備狀態仍會使用精確標籤：empty_response 表示提供者未傳回可用的訊息或狀態，no_error_details 表示提供者明確傳回 Unknown error (no error details in response)，而 unclassified 表示 OpenClaw 保留了原始預覽，但尚無任何分類器與之相符。

ModelNotReadyException 等提供者忙碌訊號會歸入過載類別，並遵循與速率限制相同的「輪替一次後再進行後備切換」政策（請參閱上方的預設值表格）。

當執行是從已設定的預設主要模型、排程作業的主要模型、具有明確後備模型的代理程式主要模型，或自動選取的後備覆寫開始時，OpenClaw 可以依序走訪相符的已設定後備鏈。未明確設定後備模型的代理程式主要模型，以及使用者明確選取的模型（例如 /model ollama/qwen3.5:27b、模型選擇器、sessions.patch，或單次命令列介面提供者／模型覆寫）會採用嚴格模式：若該提供者／模型無法連線，或在產生回覆前失敗，OpenClaw 會回報失敗，而不會改用不相關的後備模型回答。

候選鏈規則

OpenClaw 會根據目前要求的 provider/model 加上已設定的後備模型來建立候選清單。

哪些錯誤會推進後備切換

略過冷卻期與探測行為

當某個提供者的所有驗證設定檔都已進入冷卻期時，OpenClaw 不會自動永遠略過該提供者，而是針對每個候選模型分別決定：

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

工作階段模型變更屬於共用狀態。作用中的執行器、/model 命令、壓縮／工作階段更新，以及即時工作階段協調，都會讀取或寫入同一工作階段項目的部分內容。

這表示後備重試必須與即時模型切換協調：

• 只有由使用者明確觸發的模型變更才會標記待處理的即時切換，包括 /model、session_status(model=...) 和 sessions.patch。
• 系統驅動的模型變更（例如後備輪替、心跳偵測覆寫或壓縮）絕不會自行標記待處理的即時切換。
• 使用者驅動的模型覆寫會被視為後備政策中的精確選取，因此無法連線至所選提供者時會直接顯示失敗，而不會被 agents.defaults.model.fallbacks 掩蓋。
• 開始後備重試前，回覆執行器會將選取的後備覆寫欄位持久化至工作階段項目。
• 自動後備覆寫會在後續回合中維持選取狀態，讓 OpenClaw 不會在每則訊息中探測已知有問題的主要模型。OpenClaw 會定期再次探測已設定的原始模型，並在其復原後清除自動覆寫；/new、/reset 和 sessions.reset 會立即清除自動產生的覆寫。
• 每次狀態變更時，使用者回覆會各通知一次後備切換，以及後備狀態清除後的復原。持續使用後備模型的回合不會重複通知。
• /status 會顯示選取的模型；若後備狀態不同，也會顯示作用中的後備模型及原因。
• 即時工作階段協調會優先採用持久化的工作階段覆寫，而非過時的執行階段模型欄位。
• 如果即時切換錯誤指向作用中後備鏈裡較後面的候選模型，OpenClaw 會直接跳至該選取模型，而不會先走訪不相關的候選模型。
• 如果後備嘗試失敗，執行器只會回復其寫入的覆寫欄位，且僅在這些欄位仍與該失敗候選模型相符時才會回復。

這可防止典型的競爭狀況：

持久化的後備覆寫會消除此時間窗，而精確限定的回復操作則會保留較新的手動或執行階段工作階段變更。

可觀測性與失敗摘要

runWithModelFallback(...) 會記錄每次嘗試的詳細資料，用於日誌和面向使用者的冷卻期訊息：

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

當候選項目失敗、遭到略過，或後續容錯移轉成功時，結構化的 model_fallback_decision 記錄也會包含扁平的 fallbackStep* 欄位。這些欄位會明確標示所嘗試的轉換（fallbackStepFromModel、fallbackStepToModel、fallbackStepFromFailureReason、fallbackStepFromFailureDetail、fallbackStepFinalOutcome），讓記錄與診斷匯出器即使在最終容錯移轉也失敗時，仍能重建主要失敗原因。

當所有候選項目都失敗時，OpenClaw 會擲出 FallbackSummaryError。外層回覆執行器可利用此錯誤建構更具體的訊息，例如「所有模型目前都受到速率限制」，並在已知時納入最早的冷卻到期時間。

該冷卻摘要會識別模型：

• 對於所嘗試的供應商/模型鏈，會忽略無關且僅限特定模型的速率限制
• 如果剩餘的封鎖是相符且僅限特定模型的速率限制，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 路由

請參閱模型，了解更廣泛的模型選擇與容錯移轉概覽。