​

模型失敗切換

1. 5. 目前供應商內的 驗證設定檔輪替。
2. 模型後備切換 到 agents.defaults.model.fallbacks 中的下一個模型。

6. 本文件說明執行階段規則及其背後支撐的資料。

​

身分驗證儲存（金鑰 + OAuth）

• 祕密資料儲存在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（舊版：~/.openclaw/agent/auth-profiles.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:[email protected]）。

​

輪替順序

1. 明確設定：auth.order[provider]（若有設定）。
2. 已設定的設定檔：auth.profiles（依提供者過濾）。
3. 已儲存的設定檔：該提供者在 auth-profiles.json 中的項目。

• 主要鍵值： 設定檔類型（OAuth 先於 API 金鑰）。
• 次要鍵值： usageStats.lastUsed（在各類型內由舊到新）。
• 冷卻中／停用的設定檔 會被移到最後，並依最早到期時間排序。

​

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

8. OpenClaw 會在每個工作階段固定所選的驗證設定檔，以保持供應商快取溫熱。
9. 它不會在每次請求時輪替。 固定的設定檔會被重複使用，直到：

• 工作階段被重置（/new / /reset）
• 12. 一次壓縮完成（壓縮計數遞增）
• 13. 設定檔進入冷卻/被停用

14. 透過 /model …@<profileId> 進行的手動選擇，會為該工作階段設定 使用者覆寫 並且在新的工作階段開始之前不會自動輪替。
15. 自動固定的設定檔（由工作階段路由器選擇）被視為一種 偏好： 會優先嘗試，但在遇到速率限制/逾時時，OpenClaw 可能會輪替到另一個設定檔。 使用者固定的設定檔會鎖定在該設定檔；若其失敗且已設定模型回退， OpenClaw 會改用下一個模型，而不是切換設定檔。

​

為什麼 OAuth 會「看起來不見」

• 使用 auth.order[provider] = ["provider:profileId"] 固定，或
• 使用 /model … 的每工作階段覆寫並指定設定檔覆寫（當你的 UI/聊天介面支援時）。

​

19. 冷卻時間

20. 當設定檔因驗證/速率限制錯誤（或看起來像速率限制的逾時）而失敗時， OpenClaw 會將其標記為冷卻中，並移至下一個設定檔。 格式/無效請求錯誤（例如 Cloud Code Assist 工具呼叫 ID 驗證失敗）會被視為值得回退，並使用相同的冷卻機制。

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

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

​

計費停用

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

25. 預設：

• 計費退避起始為 5 小時，每次計費失敗倍增，並在 24 小時 封頂。
• 若設定檔 24 小時 內未再失敗（可設定），退避計數會重設。

​

模型後備

​

相關設定

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel 路由