11.2 冷却与禁用：故障窗口内的止血机制

本节以官方 failover 语义为准，讲清故障窗口内的止血手段：auth profile 冷却机制在供应商内部自动轮换并抑制重试放大；模型级 fallback 在 auth 层全部耗尽后跨模型切换；恢复依赖探针与观测，而不是盲目全量放开。

11.2.1 冷却解决什么：防止重试放大

在供应商抖动或限流时，如果系统持续对同一目标重试，会出现放大链条：失败触发重试，重试挤占并发与配额，队列堆积导致端到端超时。

冷却的目标是在故障窗口内降低无效尝试，把资源留给仍可能成功的路径。

11.2.2 Auth Profile 冷却：官方分级机制

OpenClaw 在 auth-profiles 层面内置了冷却分级机制。当某个 auth profile（API key 或 OAuth）持续报错时，系统自动施加指数退避冷却，并在 profile 轮转时将冷却中的 profile 移至末位。参考：https://docs.openclaw.ai/concepts/model-failover。

冷却分级（按失败次数递增）：

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

冷却状态存储在 auth-profiles.json 的 usageStats 字段中：

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

Billing disable 退避（计费错误专项）：

• 起步 5 小时，每次 billing 失败翻倍，上限 24 小时。

• disabledReason: "billing" 单独标记，与普通冷却区分。

• 24 小时内无失败则计数重置。

可配置字段（openclaw.json）：

{
  auth: {
    cooldowns: {
      billingBackoffHours: 5,           // billing 退避起步时长（小时）
      billingBackoffHoursByProvider: {  // 按供应商覆盖起步时长
        openai: 3,
      },
      billingMaxHours: 24,              // billing 最大禁用时长
      failureWindowHours: 24,           // 无失败后重置计数的窗口
    },
  },
}

11.2.3 模型级回退：fallbacks 顺序尝试

除了 auth profile 层级的冷却，OpenClaw 还支持模型级的顺序回退。通过 fallbacks 字段声明遇到错误时依次尝试的备用模型：

{
  agents: {
    defaults: {
      model: {
        primary: 'openai/gpt-5.2',
        fallbacks: [
          'openai/gpt-5-mini',
          'anthropic/claude-sonnet-4-5',
        ],
      },
    },
  },
}

两层机制的关系：auth profile 冷却在供应商内部轮换密钥/profile；模型 fallback 在模型之间跨级切换。先走 auth 层轮换，全部 profile 耗尽后才触发模型级 fallback。

11.2.4 验收与排障

• 如果回退频繁发生但主链路看起来正常，优先检查 auth-profiles.json 中 usageStats 的 cooldownUntil 与 errorCount 字段，确认是否存在持续触发冷却的 profile。

• 如果 billing disable 持续触发，检查 disabledReason 与 auth.cooldowns.* 配置，评估是否需要调整退避起步时长。

• 如果故障已恢复但仍长时间走备用链路，检查 cooldownUntil 时间戳是否已过期；若已过期仍未恢复，用探针命令主动验证。

操作示例：

openclaw models status --check
openclaw status --deep