OpenClaw 故障轉移與自動輪替機制：確保 AI 服務高可用

寫程式最煩的就是 API 突然噴 429 Rate Limit，或是半夜 Key 過期導致服務掛掉。為了讓你的 AI 代理能穩定運作，OpenClaw 設計了一套自動化的故障轉移機制。

OpenClaw 處理失敗主要分為兩個階段：

1. Auth profile 輪詢：在目前的 Provider 內切換不同的驗證帳號。
2. 模型備援 (Model fallback)：如果該 Provider 的帳號都不能用，就切換到 agents.defaults.model.fallbacks 設定的下一個模型。

這份文件會說明運作規則以及背後的數據邏輯。

驗證儲存 (Auth storage)

OpenClaw 使用 auth profiles 來管理 API keys 和 OAuth tokens。

• 秘密資訊儲存在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (舊版路徑：~/.openclaw/agent/auth-profiles.json)。
• 配置中的 auth.profiles / auth.order 僅作為 Metadata 與路由使用，不包含秘密資訊。
• 舊版僅供匯入使用的 OAuth 檔案：~/.openclaw/credentials/oauth.json (首次使用時會匯入至 auth-profiles.json)。

更多細節請參考：/concepts/oauth

憑證類型：

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (部分 Provider 可能包含 projectId/enterpriseUrl)

Profile ID 識別

OAuth 登入會建立獨立的 Profile，讓多個帳號可以並存。

• 預設值：當沒有 Email 資訊時，使用 provider:default。
• 帶有 Email 的 OAuth：例如 google-antigravity:user@gmail.com。

這些 Profile 會儲存在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 的 profiles 欄位下。

輪詢順序 (Rotation order)

當一個 Provider 有多個 Profile 時，OpenClaw 會依據以下邏輯排序：

1. 優先看配置：參考 auth.order[provider] 的明確設定。
2. 參考 Profile 列表：依據 auth.profiles 與 auth-profiles.json 中的紀錄進行過濾。

如果沒有設定明確順序，OpenClaw 會使用 Round-robin 輪詢：

• 類型優先：OAuth 優於 API keys。
• 使用時間：參考 usageStats.lastUsed（越久沒用的排越前面）。
• 異常處理：冷卻中或停用的 Profile 會被移到最後面。
• 排序邏輯：依據恢復時間先後排列。

Session 黏著性

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

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