模型故障转移

Model Failover（模型故障转移）确保当主模型不可用时，Agent 自动切换到备用模型继续服务，最大限度减少用户体验中断。

Failover 链配置

定义主模型和备用模型的优先级链：

# 基础配置
model: openai/gpt-4o

failover:
  - anthropic/claude-3-5-sonnet     # 第一备选
  - deepseek/deepseek-chat          # 第二备选
  - google/gemini-2.0-flash         # 第三备选

当主模型调用失败时，按序尝试备用模型：

openai/gpt-4o  ──失败──▶  anthropic/claude-3-5-sonnet
                                    │
                                    失败
                                    ▼
                          deepseek/deepseek-chat
                                    │
                                    失败
                                    ▼
                          google/gemini-2.0-flash
                                    │
                                    失败
                                    ▼
                              返回错误给用户

触发 Failover 的错误类型

不同错误类型触发不同的处理策略：

错误类型	错误码	处理
服务不可用	503	Failover
速率限制	429	先重试，后 Failover
认证失败	401/403	Failover（跳过此 Provider）
请求超时	Timeout	先重试，后 Failover
模型不存在	404	Failover（跳过此模型）
内容过滤	400	不 Failover（用户端问题）
网络错误	Network	先重试，后 Failover
服务器错误	500	Failover

瞬态 vs 永久错误

瞬态错误（Transient）如超时和速率限制会先重试，多次失败后再触发 Failover。永久错误（Permanent）如认证失败会立即触发 Failover。

重试 vs Failover 决策

错误发生
    │
    ▼
┌─────────────────┐
│ 错误分类         │
│ Transient?       │
│ Permanent?       │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
Transient  Permanent
    │         │
    ▼         │
重试（最多 N 次）│
    │         │
    ├─成功──▶ 返回结果
    │         │
    ▼         ▼
全部重试失败   │
    │         │
    └────┬────┘
         │
         ▼
    Failover
    切换下一个模型

重试配置

retry:
  maxRetries: 3              # 最大重试次数
  initialDelay: 1000         # 初始延迟（毫秒）
  maxDelay: 30000            # 最大延迟（毫秒）
  backoffMultiplier: 2       # 指数退避乘数
  retryableErrors:           # 可重试的错误类型
    - 429                    # 速率限制
    - 503                    # 服务不可用
    - timeout                # 超时
    - network                # 网络错误

指数退避（Exponential Backoff）示例：

第 1 次重试: 等待 1000ms
第 2 次重试: 等待 2000ms
第 3 次重试: 等待 4000ms
→ 3 次均失败 → 触发 Failover

Failover 高级配置

failover:
  - model: anthropic/claude-3-5-sonnet
    conditions:
      - error: 429            # 仅在速率限制时使用
      - error: 503
      
  - model: deepseek/deepseek-chat
    conditions:
      - error: "*"            # 任何错误都可使用
    
  - model: ollama/llama3:70b
    conditions:
      - error: "*"
    fallbackOnly: true         # 仅作为最后手段

成本优化

可以将高性价比模型放在 Failover 链的后面位置。当主模型不可用时，自动使用更便宜的备选方案。

Failover 日志

每次 Failover 操作都会记录详细日志：

[FAILOVER] Session general::user123
  - Primary: openai/gpt-4o
  - Error: 429 Too Many Requests
  - Retries: 3/3 (all failed)
  - Switched to: anthropic/claude-3-5-sonnet
  - Result: Success (1,234ms)

健康检查

OpenClaw 持续监控 Provider 健康状态：

healthCheck:
  enabled: true
  interval: 60000            # 每 60 秒检查一次
  timeout: 5000              # 健康检查超时

不健康的 Provider 会被临时标记，减少不必要的 Failover 延迟：

Provider 状态：
  openai:     ✅ Healthy (98ms)
  anthropic:  ✅ Healthy (156ms)
  deepseek:   ⚠️ Degraded (2,340ms)
  google:     ❌ Unhealthy (timeout)

配置示例

高可用配置

model: openai/gpt-4o
failover:
  - anthropic/claude-3-5-sonnet
  - deepseek/deepseek-chat
  - google/gemini-2.0-flash
  - ollama/llama3:70b
retry:
  maxRetries: 2
  initialDelay: 500

成本优先配置

model: deepseek/deepseek-chat
failover:
  - openai/gpt-4o-mini
  - ollama/llama3:70b
retry:
  maxRetries: 3
  initialDelay: 1000

离线优先配置

model: ollama/llama3:70b
failover:
  - deepseek/deepseek-chat
  - openai/gpt-4o-mini
retry:
  maxRetries: 1

🇨🇳 中国用户须知

• 建议在 Failover 链中包含至少一个国产模型（如 DeepSeek）作为可靠备选
• 国际模型在国内可能因网络问题更频繁触发 Failover
• 本地 Ollama 模型作为最后手段可确保完全离线可用

下一步

• 了解 重试策略 的详细配置
• 查看 模型提供商 配置服务
• 探索 用量追踪 监控 Failover 频率