> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/openclaw_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/04_config_models/4.4_failover.md).

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

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

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

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

* **配置/鉴权类（快速失败）**：例如 401/403、密钥缺失、字段写错层级。应快速失败并给出可操作指引；不要在同一条链路里盲目重试放大故障窗口。
* **瞬时故障类（有界重试）**：例如短暂超时、抖动、偶发 5xx。可重试，但必须设预算（次数与总耗时）。
* **持续不可用类（触发回退）**：例如持续限流（429）、供应商长时间不可用、网络侧持续失败。应尽快切到回退目标以维持连续性。

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

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

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

```javascript
{
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-5.4",
        fallbacks: [
          // 回退：跨供应商模型（常用于应对上游或网络侧持续故障）
          "anthropic/claude-sonnet-4-6",
        ],
      },
    },
  },
}
```

建议按“连续性优先但要可解释”来排序：越靠前的回退目标越应该稳定、可用、并且成本与质量波动可接受。OpenAI agent 模型引用使用 `openai/*`；ChatGPT/Codex 订阅 OAuth 由 Codex/OpenAI auth profile 与运行时表达，历史 `openai-codex/*` 模型引用应通过 `openclaw doctor --fix` 迁移。不要把模型引用、认证 profile 和运行时混成一层配置。

需要注意覆盖语义：`agents.defaults.model.fallbacks` 是全局默认链；agent、session、cron job 或工具 payload 中的显式 fallback override 会替换默认链，显式空数组可用于禁用全局 fallback。如果只覆盖 primary 而没有覆盖 fallback，运行时仍可能在没有显式 override 的路径上把配置 primary 追加为恢复候选，用于主链路恢复探针。

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

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

* **有界重试**：限制最大次数与总时长，避免在不可用窗口里把队列与成本放大。
* **回退优先级**：把更稳的备用模型放在更前面；同供应商与跨供应商各留一条兜底。
* **可观测恢复**：当主链路恢复后再切回，避免反复抖动导致输出质量与成本不可预测。

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

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

冷却梯度：

| 失败次数 | 冷却时长     |
| ---- | -------- |
| 1    | 30 秒     |
| 2    | 1 分钟     |
| 3+   | 5 分钟（上限） |

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

更准确地说，`auth-profiles.json` 负责保存 secrets / profiles，本轮转里的冷却、禁用与最近可用顺序等运行时状态应以 `auth-state.json` 为准。更多 auth 级可靠性机制见第 11 章。

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

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

1. **基线**：`models status` 显示认证档案没有缺失或过期；再用 `models status --probe` 验证主/备 provider 的 live auth 与网络可用性。
2. **观测**：跟随结构化日志，确保你能看到回退决策事件（当前常见事件名为 `model_fallback_decision`，并包含 `fallbackStep*` 等字段）。
3. **注入**：人为制造“主链路失败、备链路仍可用”的条件（例如临时撤销主链路密钥或触发主模型限流）。
4. **对账**：确认日志里出现回退事件，并且命中目标与 `fallbacks` 顺序一致。

操作示例（观测窗口）：

```bash
openclaw models status
openclaw models status --probe
openclaw logs --follow --json
```