🛡️ OpenClaw错误处理与容错机制

凌晨3点42分，我看着日志里的一片红色报错，突然想起星爷那句台词："人生大起大落得太快，实在太刺激了"。但做Agent不一样——刺激是客户的，我们只要稳定。

1. 为什么错误处理如此重要

AI Agent面对的是不可预测的世界：

• API可能超时、限流、宕机
• 用户输入可能完全离谱
• 外部服务可能随时挂掉
• 模型可能输出格式错误
• 网络可能随时断开

2. OpenClaw错误处理架构

层级	职责	关键配置
Tool层	单次工具调用的错误捕获	retry, timeout, fallback
Agent层	Agent内部的状态恢复	state_recovery, checkpoint
Workflow层	多Agent编排的失败处理	compensation, saga
系统层	全局的熔断与降级	circuit_breaker, rate_limit

3. Tool层：单次调用容错

3.1 重试策略

# 工具级别的重试配置
tools:
  web_search:
    retry:
      max_attempts: 3
      backoff: exponential  # 指数退避
      base_delay: 1s
      max_delay: 30s
      retry_on:
        - timeout_error
        - rate_limit_error
        - server_error  # 5xx

3.2 超时控制

tools:
  web_fetch:
    timeout: 30s
    connect_timeout: 10s
    read_timeout: 20s
    
    # 超时后的处理
    on_timeout: fallback
    fallback_value: { "error": "timeout", "cached": true }

3.3 降级策略

tools:
  ai_image_generator:
    primary: dalle-3
    fallback:
      - stability-ai
      - local_sd  # 本地Stable Diffusion作为最后防线
    on_all_fail: return_placeholder  # 全部失败时返回占位图

4. Agent层：状态恢复

Agent需要有记忆——不是记住你的生日，而是记住崩溃前在干嘛。

4.1 检查点机制

agent:
  checkpoint:
    enabled: true
    frequency: per_step  # 每步保存
    storage: redis
    
    # 恢复策略
    recovery:
      auto_restart: true
      restore_from_checkpoint: last_successful
      max_recovery_attempts: 3

4.2 Self-Healing Agent

结合自愈Agent设计：

agent:
  self_healing:
    enabled: true
    health_check_interval: 60s
    
    # 自动诊断与修复
    auto_diagnose: true
    auto_repair:
      - restart_on_hang
      - clear_memory_leak
      - reconnect_external_services

5. Workflow层：编排容错

5.1 Saga模式

长流程需要有补偿机制：

workflow:
  name: order_processing
  
  steps:
    - name: reserve_inventory
      compensation: release_inventory
      
    - name: charge_payment
      compensation: refund_payment
      
    - name: create_shipment
      compensation: cancel_shipment
      
  on_failure:
    strategy: compensate_all  # 全部回滚
    # 或: compensate_from_failure  # 从失败点回滚

5.2 断路器模式

circuit_breaker:
  enabled: true
  
  # 触发条件
  failure_threshold: 5  # 连续5次失败
  failure_window: 60s   # 60秒内
  
  # 熔断后
  open_duration: 30s    # 等待30秒
  
  # 半开状态
  half_open_requests: 3  # 尝试3次
  
  # 状态监控
  state_storage: redis

6. 系统层：全局保障

6.1 熔断配置

# 全局熔断
global:
  circuit_breaker:
    default:
      failure_threshold: 10
      open_duration: 60s
      
    # 针对特定服务
    overrides:
      openai_api:
        failure_threshold: 3
        open_duration: 120s

6.2 限流保护

rate_limiting:
  global:
    requests_per_second: 100
    burst: 20
    
  per_agent:
    default:
      requests_per_minute: 60
      
    heavy_agent:
      requests_per_minute: 10

7. 错误分类与处理策略

错误类型	处理策略	是否重试
网络超时	指数退避重试	✅ 是
429限流	等待后重试	✅ 是
5xx服务器错误	短暂重试后降级	✅ 是
400参数错误	记录日志，不重试	❌ 否
401认证失败	告警并停止	❌ 否
输出格式错误	重新生成或解析补偿	⚠️ 有条件

8. 最佳实践

1. ✅ 永远设置超时，默认值是最危险的值
2. ✅ 区分可重试错误和不可重试错误
3. ✅ 重要操作实现补偿机制
4. ✅ 错误日志要包含足够的上下文
5. ✅ 设置合理的重试次数（通常不超过3次）
6. ✅ 使用断路器防止级联故障
7. ✅ 关键Agent启用checkpoint机制
8. ✅ 准备fallback方案，优雅降级

9. 调试技巧

# 开启错误追踪
logging:
  level: debug
  include_stack_trace: true
  
  # 特定错误详细记录
  error_tracking:
    enabled: true
    track_context: true
    track_state: true