模型容錯切換

OpenClaw 分兩個階段處理失敗：

驗證設定檔輪替：在當前 provider 內輪替。
模型回退：切換到 agents.defaults.model.fallbacks 中的下一個模型。

本文說明背後的執行規則和支撐資料。

驗證儲存（key + OAuth）

OpenClaw 對 API key 和 OAuth token 都使用驗證設定檔。

機密資訊存放在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（舊版：~/.openclaw/agent/auth-profiles.json）。
設定中的 auth.profiles / auth.order 僅為中繼資料 + 路由（不含機密）。
舊版僅用於匯入的 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）

設定檔 ID

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

預設：provider:default（無 email 可用時）。
有 email 的 OAuth：provider:<email>（例如 google-antigravity:[email protected]）。

設定檔存放在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 的 profiles 下。

輪替順序

當一個 provider 有多個設定檔時，OpenClaw 按以下方式決定順序：

明確設定：auth.order[provider]（如果有設定的話）。
已設定的設定檔：auth.profiles 中篩選出該 provider 的部分。
已儲存的設定檔：auth-profiles.json 中該 provider 的條目。

如果沒有明確的順序設定，OpenClaw 使用循環輪替：

主要排序：設定檔類型（OAuth 優先於 API key）。
次要排序：usageStats.lastUsed（同類型中，最久未用的優先）。
冷卻中/已停用的設定檔移到最後，按最早到期排序。

Session 黏著（快取友好）

OpenClaw 會在每個 session 中釘住選定的驗證設定檔，以保持 provider 快取的熱度。它不會每次請求都輪替。釘住的設定檔會一直使用，直到：

session 被重設（/new / /reset）
壓縮完成（壓縮次數遞增）
設定檔處於冷卻/停用狀態

透過 /model …@<profileId> 手動選擇會為該 session 設定一個使用者覆寫，在新 session 開始前不會自動輪替。

自動釘住的設定檔（由 session 路由器選擇）被視為偏好：優先嘗試，但 OpenClaw 可能在遇到速率限制/逾時時輪替到其他設定檔。使用者釘住的設定檔則鎖定在該設定檔；如果失敗且有設定模型回退，OpenClaw 會轉到下一個模型，而不是切換設定檔。

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

如果你同時有同一個 provider 的 OAuth 設定檔和 API key 設定檔，循環輪替可能在不同訊息間切換，除非釘住。要強制使用單一設定檔：

用 auth.order[provider] = ["provider:profileId"] 釘住，或
透過 /model … 的 per-session 覆寫搭配設定檔指定（如果你的 UI/聊天介面支援的話）。

冷卻機制

當設定檔因認證/速率限制錯誤（或看起來像速率限制的逾時）而失敗時，OpenClaw 會將其標記為冷卻中，然後移到下一個設定檔。格式/無效請求錯誤（例如 Cloud Code Assist 工具呼叫 ID 驗證失敗）也被視為可容錯切換的錯誤，使用相同的冷卻機制。 OpenAI 相容的 stop-reason 錯誤如 Unhandled stop reason: error、stop reason: error 和 reason: error 被歸類為逾時/容錯切換訊號。

冷卻使用指數退避：

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

狀態存在 auth-profiles.json 的 usageStats 下：

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

帳單停用

帳單/額度失敗（例如「insufficient credits」/「credit balance too low」）被視為可容錯切換的錯誤，但通常不是暫時性的。OpenClaw 不使用短暫冷卻，而是將設定檔標記為已停用（使用較長的退避），並輪替到下一個設定檔/provider。

狀態存在 auth-profiles.json：

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

預設值：

帳單退避從 5 小時開始，每次帳單失敗加倍，上限 24 小時。
如果設定檔 24 小時內沒有失敗，退避計數器會重設（可設定）。

模型回退

如果某個 provider 的所有設定檔都失敗，OpenClaw 會移到 agents.defaults.model.fallbacks 中的下一個模型。這適用於認證失敗、速率限制和耗盡設定檔輪替的逾時（其他錯誤不會推進回退）。

當 run 以模型覆寫啟動（hook 或 CLI）時，回退在嘗試完所有設定的 fallback 後仍會結束於 agents.defaults.model.primary。