4.4 故障转移基础：回退链路与恢复策略

本节介绍回退链路的配置方法、触发时机及其与重试机制的联动关系。配置的核心在于利用 agents.defaults.model.primary 和 agents.defaults.model.fallbacks 设定主模型及按优先级排列的回退目标。此外，本节还将提供一套基于“故障注入与观测”的验证方案，确保持续可用性与回退机制的真实生效。

4.4.1 故障分类：把错误映射为动作

回退的关键不是“失败就换”，而是“不同失败用不同动作”。建议把错误先按“可操作性”分三类：

• 配置/鉴权类（快速失败） ：例如 401/403、密钥缺失、字段写错层级。应快速失败并给出可操作指引；不要在同一条链路里盲目重试放大故障窗口。

• 瞬时故障类（有界重试） ：例如短暂超时、抖动、偶发 5xx。可重试，但必须设预算（次数与总耗时）。

• 持续不可用类（触发回退） ：例如持续限流（429）、供应商长时间不可用、网络侧持续失败。应尽快切到回退目标以维持连续性。

把三类错误混在一起会导致两种反效果：该快速失败的问题被无意义重试拖垮；该回退的问题没有及时切流。

4.4.2 回退配置：agents.defaults.model.fallbacks

最小可用写法是：主模型 + 顺序回退列表。系统会在主模型失败时，按顺序尝试备选模型。

{
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-5.2",
        fallbacks: [
          // 第一回退：同供应商小模型（常用于应对并发限流）
          "openai/gpt-5-mini",
          // 第二回退：跨供应商模型（常用于应对上游或网络侧持续故障）
          "anthropic/claude-sonnet-4-5",
        ],
      },
    },
  },
}

建议按“连续性优先但要可解释”来排序：越靠前的回退目标越应该稳定、可用、并且成本与质量波动可接受。

4.4.3 与重试联动：避免故障窗口内放大

回退链路要和重试一起设计，否则会出现“重试拖死”或“无声切换”。

• 有界重试 ：限制最大次数与总时长，避免在不可用窗口里把队列与成本放大。

• 回退优先级 ：把更稳的备用模型放在更前面；同供应商与跨供应商各留一条兜底。

• 可观测恢复 ：当主链路恢复后再切回，避免反复抖动导致输出质量与成本不可预测。

4.4.4 Auth-profile 级冷却：同供应商多账号的内置轮转

除了跨模型的 fallbacks 链路，OpenClaw 还在同一 provider 内维护一套 auth-profile 轮转机制。当一个密钥或账号触发失败后，系统会自动切到同 provider 的下一个可用凭据，而不立即跨模型跳转。

冷却梯度：

失败次数	冷却时长
1	1 分钟
2	5 分钟
3	25 分钟
4+	1 小时（上限）

billing 相关禁用（如 402 结算失败）有独立梯度：从 5 小时起步，每次失败翻倍，上限 24 小时；24 小时未出错则自动重置。

冷却状态持久化在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 的 usageStats 字段，重启后仍有效。更多 auth 级可靠性机制见第 11 章。

4.4.5 验证方法：故障注入与对账

回退不是写进配置就算完成，必须验证它真的会触发，并且能被对账。

1. 基线 ：models status --check 通过，说明主/备 provider 的认证与网络都可用。

2. 观测 ：跟随结构化日志，确保你能看到回退事件（常见事件名为 model_fallback）。

3. 注入 ：人为制造“主链路失败、备链路仍可用”的条件（例如临时撤销主链路密钥或触发主模型限流）。

4. 对账 ：确认日志里出现回退事件，并且命中目标与 fallbacks 顺序一致。

操作示例（观测窗口）：

openclaw models status --check
openclaw logs --follow --json