OpenClaw错误处理与容错设计 - 重试/降级/熔断/自愈

导读：AI Agent在生产环境中会遇到各种异常：API超时、模型报错、工具失败、网络中断...本教程教你如何设计健壮的错误处理机制，让你的Agent在任何情况下都能优雅降级、自动恢复。

🔄 错误处理流程

请求 → 正常响应 → 返回结果
↓ 异常
检测错误类型 → 重试？ → 成功 → 返回结果
↓ 失败
降级策略 → 备用模型 → 成功 → 返回结果
↓ 失败
熔断机制 → 快速失败 → 通知用户
↓ 恢复
自愈检测 → 自动恢复 → 正常服务

🎯 常见错误类型

错误类型	原因	影响	处理策略
API超时	模型响应慢	请求阻塞	重试 + 降级
Rate Limit	请求过频	被拒绝	等待 + 重试
模型错误	模型内部异常	无法生成	切换模型
工具失败	工具执行异常	任务中断	重试 + 跳过
网络中断	网络不稳定	连接断开	重连 + 缓存
上下文溢出	Token超限	请求被拒	压缩 + 截断

🔧 策略一：智能重试

1. 基础重试配置

# ~/.openclaw/config.yaml
retry:
  enabled: true
  maxRetries: 3
  backoff:
    strategy: "exponential"  # 指数退避
    initialDelay: 1000       # 初始延迟1秒
    maxDelay: 30000          # 最大延迟30秒
    multiplier: 2            # 每次翻倍

2. 针对不同错误的重试策略

# 细粒度重试策略
retry:
  rules:
    # API超时：重试3次
    - error: "timeout"
      maxRetries: 3
      backoff: "exponential"
      
    # Rate Limit：等待后重试
    - error: "rate_limit"
      maxRetries: 5
      backoff: "fixed"
      delay: 60000  # 固定等待60秒
      
    # 网络错误：快速重试
    - error: "network"
      maxRetries: 3
      backoff: "linear"
      delay: 2000
      
    # 模型错误：切换模型
    - error: "model_error"
      maxRetries: 1
      fallback: true

3. 重试代码示例

# OpenClaw内部自动处理重试
# Agent无需关心重试逻辑

# 也可以在Agent中手动处理
try:
    result = call_model(prompt)
except TimeoutError:
    # 自动重试由OpenClaw处理
    # 如果所有重试失败，会抛出最终错误
    handle_failure()

🔧 策略二：模型降级

1. 自动降级链

# 配置模型降级链
agents:
  default:
    model: "gpt-4o"
    
    # 降级策略
    fallback:
      enabled: true
      chain:
        - "gpt-4o"           # 首选
        - "gpt-4o-mini"      # 降级1
        - "claude-3-5-sonnet" # 降级2
        - "ollama/qwen2:7b"  # 最终降级（本地）
      
      # 降级触发条件
      triggers:
        - "timeout"
        - "rate_limit"
        - "server_error"
      
      # 降级后通知
      notify: true

2. 按错误类型降级

# 不同错误使用不同降级策略
fallback:
  rules:
    # 超时：切换到更快的模型
    - trigger: "timeout"
      fallbackModel: "gpt-4o-mini"
      
    # Rate Limit：切换到其他提供商
    - trigger: "rate_limit"
      fallbackModel: "claude-3-5-sonnet"
      
    # 所有云端都失败：使用本地模型
    - trigger: "all_cloud_failed"
      fallbackModel: "ollama/qwen2:7b"

🔧 策略三：熔断机制

当某个模型或服务持续失败时，暂时停止调用，避免资源浪费。

熔断配置

# 熔断器配置
circuitBreaker:
  enabled: true
  
  # 熔断触发条件
  failureThreshold: 5       # 连续5次失败
  failureWindow: 300000     # 5分钟内
  
  # 熔断状态
  states:
    closed:     # 正常状态
      timeout: 60000  # 1分钟后尝试恢复
    open:       # 熔断状态
      timeout: 300000 # 5分钟后半开
    halfOpen:   # 半开状态
      successThreshold: 3  # 连续3次成功后恢复

熔断流程

正常状态（Closed）→ 连续5次失败 → 熔断状态（Open）
↓ 5分钟后
半开状态（HalfOpen）→ 尝试请求 → 成功 → 正常状态
↓ 失败
重新熔断

🔧 策略四：自愈恢复

1. 健康检查

# 定期检查服务健康状态
healthCheck:
  enabled: true
  interval: 60000  # 每分钟检查一次
  
  checks:
    # 检查模型可用性
    - name: "model-availability"
      type: "ping"
      target: "gpt-4o"
      timeout: 5000
      
    # 检查本地模型
    - name: "local-model"
      type: "http"
      target: "http://localhost:11434/api/tags"
      timeout: 3000
      
    # 检查工具可用性
    - name: "tools"
      type: "execute"
      command: "openclaw tools list"
      timeout: 10000

2. 自动恢复策略

# 自动恢复配置
autoRecovery:
  enabled: true
  
  # 恢复策略
  strategies:
    # 模型恢复：重新初始化连接
    - name: "model-reconnect"
      trigger: "model_unavailable"
      action: "reinitialize"
      maxAttempts: 3
      
    # 工具恢复：重新加载工具
    - name: "tool-reload"
      trigger: "tool_failure"
      action: "reload"
      maxAttempts: 2
      
    # 服务恢复：重启服务
    - name: "service-restart"
      trigger: "service_crash"
      action: "restart"
      maxAttempts: 1
      notify: true  # 通知管理员

🔧 策略五：优雅降级

当所有恢复措施都失败时，提供降级服务而不是完全失败。

降级响应示例

# Agent中定义降级行为
## 错误处理规则
- 当AI模型不可用时，使用预设模板回复
- 当工具调用失败时，告知用户并提供替代方案
- 当网络中断时，使用缓存数据回复
- 当上下文溢出时，压缩历史记录后重试

# 降级回复模板
降级回复：
  模型不可用: "抱歉，AI服务暂时不可用。请稍后再试，或联系管理员。"
  工具失败: "这个操作暂时无法完成。你可以尝试：1) 刷新页面重试 2) 稍后再试"
  网络中断: "网络连接不稳定，我使用了缓存数据回复。最新数据请稍后查看。"

📊 错误监控与告警

1. 错误日志

# 启用详细错误日志
logging:
  level: "warn"
  
  # 错误日志格式
  format: "json"
  
  # 日志文件
  file: "~/.openclaw/logs/error.log"
  
  # 日志轮转
  rotation:
    maxSize: "100mb"
    maxFiles: 10

2. 错误告警

# 错误告警配置
alerts:
  enabled: true
  
  # 告警规则
  rules:
    # 错误率告警
    - name: "high-error-rate"
      condition: "error_rate > 10%"
      window: "5m"
      notify: "feishu"
      message: "⚠️ 错误率超过10%，请检查服务状态"
      
    # 连续失败告警
    - name: "consecutive-failures"
      condition: "consecutive_failures > 5"
      notify: "feishu"
      message: "🔴 连续5次失败，服务可能不可用"
      
    # 模型不可用告警
    - name: "model-unavailable"
      condition: "model_status == 'down'"
      notify: "feishu"
      message: "🔴 AI模型不可用，已切换到备用模型"

📋 最佳实践清单

✅ 始终配置重试：网络请求必须有重试机制
✅ 设置超时：所有外部调用都要有超时限制
✅ 模型降级链：至少配置2个备用模型
✅ 熔断保护：防止故障扩散
✅ 优雅降级：失败时提供有用的信息
✅ 错误日志：记录所有错误便于排查
✅ 告警通知：关键错误及时通知
✅ 定期演练：模拟故障测试恢复能力

🏭 生产环境配置模板

# 生产级错误处理完整配置
# ~/.openclaw/config.yaml

# 重试配置
retry:
  enabled: true
  maxRetries: 3
  backoff: "exponential"

# 模型降级
agents:
  default:
    model: "gpt-4o"
    fallback:
      enabled: true
      chain: ["gpt-4o", "gpt-4o-mini", "ollama/qwen2:7b"]

# 熔断器
circuitBreaker:
  enabled: true
  failureThreshold: 5
  recoveryTimeout: 300000

# 健康检查
healthCheck:
  enabled: true
  interval: 60000

# 错误告警
alerts:
  enabled: true
  channel: "feishu"
  rules:
    - condition: "error_rate > 10%"
      message: "⚠️ AI服务错误率异常"

# 日志
logging:
  level: "warn"
  file: "~/.openclaw/logs/error.log"

💡 经验总结

        🎯 核心原则：

        1. 假设一切都会失败 - 为每个外部调用设计错误处理

        2. 快速失败优于慢速失败 - 设置合理的超时

        3. 降级优于崩溃 - 提供降级服务而不是完全不可用

        4. 自动化恢复 - 能自动恢复的不要人工干预

        5. 可观测性 - 日志、监控、告警缺一不可

监控方案安全指南本地模型成本优化快速入门记忆管理