Model Failover

OpenClaw 分两个阶段处理故障：

认证配置轮换：在当前 Provider 内轮换。
模型故障转移：切换到 agents.defaults.model.fallbacks 中的下一个模型。

本文档解释了运行时规则和背后的数据机制。

认证存储（密钥 + OAuth）

OpenClaw 使用认证配置来管理 API 密钥和 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）

Profile ID

OAuth 登录会创建独立的配置，这样多个账号可以共存。

默认：当没有邮箱信息时使用 provider:default。
带邮箱的 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 使用轮询（round-robin）顺序：

主键： 配置类型（OAuth 优先于 API 密钥）。
次键： usageStats.lastUsed（每种类型内，最久未用的优先）。
冷却/禁用的配置 移到末尾，按最快到期时间排序。

Session 粘性（缓存友好）

OpenClaw 为每个 Session 固定选定的认证配置，以保持 Provider 缓存热度。它不会在每次请求时轮换。固定的配置会一直使用，直到：

Session 被重置（/new / /reset）
Compaction 完成（compaction 计数增加）
配置处于冷却/禁用状态

通过 /model …@<profileId> 手动选择会为该 Session 设置用户覆盖，在新 Session 开始前不会自动轮换。

自动固定的配置（由 Session 路由器选择）被视为偏好：会优先尝试，但在遇到速率限制/超时时，OpenClaw 可能会轮换到其他配置。用户固定的配置会锁定在该配置上；如果失败且配置了模型故障转移，OpenClaw 会切换到下一个模型，而不是切换配置。

为什么 OAuth 可能”看起来丢失了”

如果你为同一个 Provider 同时有 OAuth 配置和 API 密钥配置，轮询机制可能会在消息间切换它们，除非固定。要强制使用单个配置：

用 auth.order[provider] = ["provider:profileId"] 固定，或
通过 /model … 使用每 Session 覆盖（如果你的 UI/聊天界面支持）。

冷却机制

当配置因认证/速率限制错误（或看起来像速率限制的超时）失败时，OpenClaw 会将其标记为冷却状态并切换到下一个配置。格式/无效请求错误（例如 Cloud Code Assist 工具调用 ID 验证失败）也被视为需要故障转移，使用相同的冷却机制。

冷却使用指数退避：

1 分钟
5 分钟
25 分钟
1 小时（上限）

状态存储在 auth-profiles.json 的 usageStats 下：

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

账单禁用

账单/额度失败（例如”额度不足”/“余额过低”）被视为需要故障转移，但它们通常不是暂时性的。OpenClaw 不会使用短暂的冷却，而是将配置标记为禁用（使用更长的退避时间）并轮换到下一个配置/Provider。

状态存储在 auth-profiles.json 中：

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

默认值：

账单退避从 5 小时开始，每次账单失败翻倍，上限为 24 小时。
如果配置在 24 小时内没有失败，退避计数器会重置（可配置）。

模型故障转移

如果一个 Provider 的所有配置都失败了，OpenClaw 会切换到 agents.defaults.model.fallbacks 中的下一个模型。这适用于认证失败、速率限制和耗尽配置轮换的超时（其他错误不会推进故障转移）。

当运行以模型覆盖开始时（hooks 或 CLI），故障转移仍会在尝试所有配置的故障转移后结束于 agents.defaults.model.primary。