第31章 模型故障转移 (Model Failover) —— 如何提高可用性

模型 API 不是 100% 可用，会有超时、限流、宕机。OpenClaw 设计了模型故障转移机制，主模型不可用时自动切备用模型，保证你的任务能继续跑。本章讲解故障转移配置和最佳实践。

什么是模型故障转移

故障转移 = 主模型挂了自动切下一个：

你配置：primary: A, fallbacks: [B, C]

• 正常情况用 A
• A 超时/限流/报错 → 自动试 B
• B 也不行 → 自动试 C
• 都不行 → 才告诉你失败

这样大大提高可用性，不会因为一个模型宕机整个任务就废了。

为什么需要故障转移

• API 限流：Anthropic/OpenAI 都会限流，高峰期你可能命中限流
• 服务宕机：云端 API 也会有 downtime
• 网络问题：你的网络临时抽风，连不上
• 额度用完：额度不小心花完了，切备用模型继续跑

有了故障转移，这些问题自动处理，不用你立刻手动切。

配置方法

全局默认配置

配置写在你的主配置文件 ~/.openclaw/openclaw.json 的 agents.defaults.model 下：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: [
          "anthropic/claude-sonnet-4-6",
          "openai/gpt-5",
          "ollama/llama3.3:70b",
        ],
      },
    },
  },
}

单个 Agent 覆盖

配置写在你的主配置文件 ~/.openclaw/openclaw.json 的 agents.list[] 下（每个 Agent 独立配置）：

{
  agents: {
    list: [
      {
        id: "coding-agent",
        model: {
          primary: "anthropic/claude-opus-4-6",
          fallbacks: ["openai/gpt-5"],
        },
      },
    ],
  },
}

每个模型可以有独立配置

配置写在你的主配置文件 ~/.openclaw/openclaw.json 的 agents.defaults.models 下：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["anthropic/claude-sonnet-4-6"],
      },
      models: {
        "anthropic/claude-opus-4-6": {
          params: {
            cacheRetention: "long",
          },
        },
        "anthropic/claude-sonnet-4-6": {
          params: {
            cacheRetention: "short",
          },
        },
      },
    },
  },
}

触发故障转移的条件

哪些错误会触发切 fallback：

设计原则：只有模型服务本身不可用时才转移，客户端错误不用转移。

重试策略

默认重试策略：

1. 主模型失败 → 等 1 秒 → 试第一个 fallback
2. 失败 → 等 2 秒 → 试第二个 fallback
3. 失败 → 等 3 秒 → 试第三个
4. 全失败 → 返回错误给用户

指数退避，避免雪崩。

配置可以改重试间隔，写在你的主配置文件 ~/.openclaw/openclaw.json 的根级别：

{
  failover: {
    retryIntervalMs: 1000, // 初始间隔
    backoffMultiplier: 2,  // 每次乘这个数
    maxRetries: 3,          // 最多重试几次
  },
}

成本优化策略

故障转移可以配合成本分级：

这样：

• 正常情况用最好的模型出最好结果
• 主模型不行自动降级，至少能完成任务
• 成本也控制住了，不会随便切贵的模型

最佳实践

1. 跨提供商 fallback

不要：primary: anthropic/claude-opus, fallbacks: [anthropic/claude-sonnet]
（Anthropic 整个挂了你还是用不了）

要：primary: anthropic/claude-opus, fallbacks: [openai/gpt-5]
（不同提供商，一个提供商挂了另一个顶上）

availability 比同提供商高很多。

2. 能力匹配

fallback 模型能力不要差太多：

• 主模型 1M 上下文，fallback 也选有大上下文的
• 主模型支持工具调用，fallback 也要支持
• 不然切过去也做不了任务

3. 不要太多 fallback

2-3 个足够了，太多也没意义：

• 前两个都不行，第三个大概率也不行
• 多等半天不如早点告诉用户

4. 监控告警

配置了故障转移也要监控：

• 记录主模型失败次数
• 失败多了自动通知你
• 可能主模型配额用完了或者密钥过期了，你要处理

日志排查

看哪些失败触发了故障转移：

openclaw models status

显示：

• 每个模型调用成功次数
• 每个模型失败次数
• 多少次触发了 failover

看详细日志：

openclaw logs --grep "failover"

能看到：什么时候哪个模型失败，切到哪个模型了。

常见问题

Q: 故障转移会多花钱吗？
A: 只有主模型失败才会切 fallback，正常情况不切。如果你搭配成本分级，主模型用贵的好的，fallback 用便宜的，总体成本不会增加多少，可用性提高很多。

Q: 上下文会带到 fallback 模型吗？
A: 会的，整个对话上下文完整带过去，用户不用重新说一遍。

Q: 流式输出也支持故障转移吗？
A: 支持，主模型流式输出断了，fallback 会重新完整输出，用户看到完整结果。

Q: 可以关掉故障转移吗？
A: 可以，fallbacks 留空数组就关掉了，主模型失败直接报错。

本章小结

• 模型故障转移自动处理 API 不可用情况，主模型失败自动切备用
• 配置简单：primary + fallbacks 数组就好了
• 只在服务端错误触发，客户端错误不切
• 最佳实践：跨提供商 fallback，能力匹配，2-3 个足够
• 配合成本分级，可用性提高很多，成本不会增加多少