本页介绍 OpenClaw 的模型故障转移（Model Failover）机制：先在当前 provider 内轮换 Auth Profile，耗尽后切换 agents.defaults.model.fallbacks 中的下一个模型。覆盖冷却策略（限流/账单/超时分级）、会话 stickiness、以及哪些错误触发 Fallback。

模型故障转移（Model Failover）

OpenClaw 的故障处理分两个阶段：

1. 在当前 provider 内轮换 Auth Profile
2. 切换到 agents.defaults.model.fallbacks 中的下一个模型

运行时流程

普通文本请求时，OpenClaw 按以下顺序评估候选：

1. 当前会话选中的模型
2. 配置的 agents.defaults.model.fallbacks（按顺序）
3. 若本轮从 override 开始，最后回退到配置的主模型

每个候选模型内部，先尝试 Auth Profile 故障转移，再切换到下一个模型候选。

高层流程：

1. 解析当前会话模型和 Auth Profile 偏好
2. 构建模型候选链
3. 用 Auth Profile 轮换/冷却规则尝试当前 provider
4. 该 provider 因可 failover 的错误耗尽时，切换到下一个模型候选
5. 重试开始前持久化选中的 fallback override，确保其他会话读取器看到同一 provider/model
6. Fallback 候选失败时，只回滚该候选拥有的 session override 字段
7. 所有候选都失败时，抛出 FallbackSummaryError，包含每次尝试的详情和最早的冷却到期时间

Auth 存储（API Key + OAuth）

OpenClaw 对 API Key 和 OAuth token 统一使用 Auth Profile 管理：

• 密钥存储：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• 配置中的 auth.profiles / auth.order 仅是元数据和路由（不含密钥）

Credential 类型：

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? }

轮换顺序

provider 有多个 profile 时，OpenClaw 按以下优先级排序：

1. 显式配置：auth.order[provider]（若已设置）
2. 配置的 profiles：auth.profiles 中该 provider 的条目
3. 存储的 profiles：auth-profiles.json 中该 provider 的条目

无显式顺序时，使用轮转（round-robin）：

• 主键：profile 类型（OAuth 优先于 API Key）
• 次键：usageStats.lastUsed（同类型内最久未用的优先）
• 冷却/禁用的 profile 移到末尾，按最快到期排序

会话粘性（Session Stickiness）

OpenClaw 每个会话锁定一个 Auth Profile，保持 provider 缓存温热，不在每次请求时轮换。已锁定的 profile 持续使用，直到：

• 会话重置（/new / /reset）
• 压缩完成（compaction count 递增）
• 该 profile 进入冷却/禁用状态

冷却机制（Cooldowns）

profile 因 Auth/限流错误（或看起来像限流的超时）失败时，标记为冷却状态并切换到下一个 profile。

触发冷却的错误包括：429、rate_limit、Too many concurrent requests、ThrottlingException、workers_ai ... quota limit exceeded、weekly/monthly limit reached 等。

冷却使用指数退避：

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

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

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

账单禁用（Billing Disables）

账单/余额不足错误（如"insufficient credits"）视为可 failover，但通常不是临时性的。OpenClaw 将 profile 标记为禁用（更长退避），而非短期冷却，并切换到下一个 profile/provider。

默认值：

• 账单退避从 5 小时开始，每次账单失败翻倍，上限 24 小时
• 24 小时无失败后，退避计数重置

模型 Fallback

所有 provider 的 profile 都失败后，OpenClaw 切换到 agents.defaults.model.fallbacks 中的下一个模型。

触发 Fallback 的错误：Auth 失败、限流、冷却耗尽、overloaded/provider-busy、超时型故障转移错误、账单禁用

不触发 Fallback 的错误：

• 非超时/非故障转移型的主动中止
• 上下文溢出错误（request_too_large、context length exceeded 等）——应留在压缩/重试逻辑内处理
• 无候选剩余时的最终未知错误

相关配置

详见Gateway 配置：

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• agents.defaults.model.primary / agents.defaults.model.fallbacks

常见问题

Q: 怎么强制一直用某个账号，不让 OpenClaw 轮换？

A: 设置 auth.order[provider] = ["provider:profileId"]，或在会话中用 /model ...@<profileId> 锁定。

Q: 限流冷却时间能缩短吗？

A: 可以通过 auth.cooldowns.* 调整退避参数。但冷却的存在是为了保护账号不被 ban，不建议设得太短。

Q: 怎么知道当前用的是哪个 auth profile？

A: 运行 openclaw models status 或查看 Gateway 日志，会显示当前会话绑定的 profile ID。