模型故障转移

概述

OpenClaw 的故障转移分两个阶段：先在当前 Provider 内轮换 auth profile，再回退到 agents.defaults.model.fallbacks 中的下一个模型。

核心要点

运行时流程：

1. 解析 Session 状态（当前模型 + auth profile 偏好）
2. 构建候选链（当前模型 + 回退策略）
3. 尝试当前 Provider（auth profile 轮换/冷却规则）
4. 遇到可故障转移的错误时，移动到下一个候选模型
5. 回退前持久化 modelOverrideSource: "auto" 到 Session
6. 失败时仅回滚回退拥有的字段
7. 所有候选失败时抛出 FallbackSummaryError

Auth Profile 轮换顺序：

1. auth.order[provider]（显式配置）
2. auth.profiles 按 provider 过滤
3. auth-profiles.json 中的条目

Session 粘性：每个 Session 固定使用一个 auth profile（保持 provider 缓存热），直到 Session 重置、压缩完成或 profile 进入冷却。

冷却机制（指数退避）：

• 1 分钟 → 5 分钟 → 25 分钟 → 1 小时（上限）
• 触发条件：429、Too many concurrent requests、ThrottlingException、quota limit exceeded 等
• 账单失败（“insufficient credits”）：更长退避，5 小时起，最长 24 小时

触发回退的错误：auth 失败、限速、超时、账单禁用 不触发回退的错误：显式中止、上下文溢出（应走压缩/重试逻辑）

选择来源与回退策略：

• configured default：使用配置回退链
• user session override（/model）：严格模式，失败直接报错
• auto fallback override：可继续走回退链，/new//reset 清除
• cron payload model：使用配置回退链，除非 fallbacks: []

配置/使用

{
  auth: {
    order: {
      openai: ["openai-codex:user@example.com", "openai:api-key-backup"]
    },
    cooldowns: {
      billingBackoffHours: 5,
      billingMaxHours: 24,
      overloadedProfileRotations: 1,
      overloadedBackoffMs: 0
    }
  }
}

存储位置：

• Auth profiles：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• Auth 路由状态：~/.openclaw/agents/<agentId>/agent/auth-state.json

相关页面

• models — 模型选择与配置
• model-providers — Provider 路由与认证
• session — Session 状态与模型覆盖