> 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-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/11_reliability_security/11.3_fallback_rules.md).

# 11.3 模型回退链路与错误分流

本节把“失败如何处理”落到官方 failover 规则上：通过 `fallbacks` 字符串列表声明按顺序尝试的回退目标，并把错误分流成可执行动作，而不是一句“重试一下”。重点包括回退链路的可解释性、证据链字段、以及通过故障注入证明回退确实生效。回退配置的基础结构见 [4.4 故障转移基础](/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/04_config_models/4.4_failover.md)。

## 11.3.1 回退目标：连续性优先但要可解释

回退的目标通常是服务连续性优先，但不能变成无声切换。否则输出质量下降、成本上升时无法定位原因。

建议每次回退至少记录：

* 触发原因：错误类型与原始目标。
* 命中规则：命中的回退顺序与策略版本。
* 回退路径：从哪个模型切到哪个模型。
* 后续动作：是否进入退避、限流保护或人工介入。

## 11.3.2 规则设计：按顺序分流

错误分流不仅依靠失败后的切换，更需要依靠重试预算的设置。全局默认 `agents.defaults.model.fallbacks` 是按顺序尝试的回退链，因此需将备用模型按可靠性排序：

* `primary`：优先使用的主力提供商模型。
* 第一回退：同供应商小模型（应对主模型并发限流）。
* 第二回退：备用供应商对应模型（应对主供应商网络或 API 错误）。

覆盖规则也要写清：显式 fallback override 会替换全局默认链，空数组可用于禁用全局回退；如果某个 job / session / agent 只覆盖 primary 而没有 fallback override，系统可能把配置中的 primary 作为恢复探针候选追加到尝试链末尾。不要把所有路径都简化成固定的 `primary -> fallbacks[]`。

下面的流程图展示了回退链路的决策逻辑：

```mermaid
flowchart TD
  req["模型调用请求"] --> p["primary: openai/gpt-5.4"]
  p -->|"成功"| ok["正常返回"]
  p -->|"限流/失败"| f1["fallback 1: anthropic/claude-sonnet-4-6"]
  f1 -->|"成功"| ok
  f1 -->|"失败"| f2["fallback 2: 本地或其他已验证模型"]
  f2 -->|"成功"| ok
  f2 -->|"全部耗尽"| degrade["降级响应 + 告警"]

  style p fill:#e6f2ff,stroke:#66b2ff
  style f1 fill:#fff5e6,stroke:#ffb347
  style f2 fill:#ffece6,stroke:#ff7a59
```

图 11-4：模型回退链路的决策逻辑

示例：

```javascript
{
  agents: {
    defaults: {
      model: {
        primary: 'openai/gpt-5.4',
        fallbacks: [
          'anthropic/claude-sonnet-4-6', // 应对跨供应商网络或架构故障
        ],
      },
    },
  },
}
```

两层机制的关系：auth profile 冷却（[11.2](/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/11_reliability_security/11.2_rotation_cooldown.md)）会优先在同一 provider 内轮换 profile；模型 fallback 才是在模型之间跨级切换。但“先走 auth 层轮换”不等于“必须把所有 profile 都耗尽”：对于 overloaded / rate-limit 这类瞬时错误，系统会先消耗 `overloadedProfileRotations` / `rateLimitedProfileRotations` 预算，预算耗尽后就可以继续进入模型级 fallback。OpenAI agent 模型引用使用 `openai/*`；ChatGPT/Codex 订阅 OAuth 由 Codex/OpenAI auth profile 与运行时策略表达凭据和执行路径，历史 `openai-codex/*` 模型引用应通过 `openclaw doctor --fix` 迁移。

## 11.3.3 回退链路中的智能行为

以下是对排障至关重要的几个回退行为细节：

**上下文溢出错误不触发回退。** 系统会检测 `request_too_large`、`context_window_exceeded` 等错误模式。一旦识别为上下文溢出，直接抛出错误而不尝试回退——因为更小的备选模型只会更快失败。此时正确的做法是触发压缩（Compaction）而非换模型。

**冷却期间的探针机制。** 当候选模型或 profile 处于临时冷却中时，系统可能在接近冷却到期时进行受限探针；探针按 provider / fallback run 节流，而不是固定每 30 秒轮询。这避免了“冷却刚过就瞬间全量恢复”导致的流量尖峰，实现了类似断路器“半开”状态的渐进恢复。

**计费错误的指数退避公式。** 具体公式为 `baseMs × 2^(min(disableCount-1, 10))`，其中 `disableCount` 来自当前禁用原因对应的 failure count，时长上限为 `billingMaxHours`（默认 24 小时）。与通用冷却相比，计费冷却的退避曲线更陡峭——这反映了计费问题通常需要人工介入才能恢复。

**聚合型供应商旁路。** 部分聚合型模型供应商（如 OpenRouter 等）默认跳过 auth 冷却检查，因为它们自身有内部的供应商轮转机制。使用这类聚合服务时，OpenClaw 的冷却策略不会生效。

**错误原因归因。** 当所有 profile 都不可用时，系统会先按错误原因出现情况打分，再用优先级链做并列裁决：`auth_permanent` > `auth` > `billing` > `format` > `model_not_found` > `overloaded` > `timeout` > `rate_limit` > `empty_response` > `no_error_details` > `unclassified` > `unknown`。这个结果决定了对外暴露的错误类型和建议操作。

## 11.3.4 验证方法：故障注入加日志对账

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

1. 基线通过：`models status` 没有认证缺失/过期，`models status --probe` 的 live auth 探针正常。
2. 制造故障：触发限流或人为制造网络/上游 API 错误。
3. 观察日志：出现回退事件，并且命中目标与配置一致。

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

如果日志里无法对账回退原因，优先补齐结构化日志字段与审计，而不是继续加规则。