重试策略

Retry（重试）是 OpenClaw 处理临时性故障的核心机制。当 LLM 调用或工具执行遇到瞬态错误时，系统会自动重试以恢复服务。

错误分类

OpenClaw 将错误分为两类，决定是否执行重试：

瞬态错误（Transient Errors）

临时性故障，重试可能成功：

错误	HTTP 码	说明
速率限制	429	Too Many Requests
服务不可用	503	Service Unavailable
网关超时	504	Gateway Timeout
请求超时	—	Connection Timeout
网络错误	—	DNS 解析失败、连接重置
服务器内部错误	500	Internal Server Error

永久错误（Permanent Errors）

结构性问题，重试不会改变结果：

错误	HTTP 码	说明
认证失败	401	Invalid API Key
权限不足	403	Forbidden
模型不存在	404	Model Not Found
请求无效	400	Bad Request（格式错误）
内容过滤	400	Content Filtered（安全拦截）
配额耗尽	402	Quota Exceeded

处理差异

瞬态错误触发重试。永久错误直接触发 Failover（如配置）或返回错误给用户。

指数退避（Exponential Backoff）

重试间隔按指数增长，避免在服务恢复期间造成更大压力：

重试次数    等待时间
  1        1,000ms  (1 秒)
  2        2,000ms  (2 秒)
  3        4,000ms  (4 秒)
  4        8,000ms  (8 秒)
  5       16,000ms  (16 秒)

计算公式：

delay = min(initialDelay × backoffMultiplier^(attempt-1), maxDelay)

抖动（Jitter）

为避免多个请求同时重试造成惊群效应（Thundering Herd），OpenClaw 在延迟中加入随机抖动：

actual_delay = delay × (0.5 + random() × 0.5)

示例（第 3 次重试，理论延迟 4000ms）：
  - 最小: 4000 × 0.5 = 2000ms
  - 最大: 4000 × 1.0 = 4000ms
  - 实际: 随机值在 2000ms ~ 4000ms 之间

配置

retry:
  maxRetries: 3                 # 最大重试次数
  initialDelay: 1000            # 初始延迟（毫秒）
  maxDelay: 30000               # 最大延迟（毫秒）
  backoffMultiplier: 2          # 退避乘数
  jitter: true                  # 启用抖动
  retryableErrors:              # 可重试的错误类型
    - 429
    - 500
    - 503
    - 504
    - timeout
    - network

重试流程

LLM 调用
    │
    ▼
┌───────────┐
│ 调用成功？ │
└─────┬─────┘
   ┌──┴──┐
   │     │
  成功   失败
   │     │
   ▼     ▼
 返回  ┌───────────┐
 结果  │ 错误分类   │
       └─────┬─────┘
          ┌──┴──┐
          │     │
       瞬态   永久
          │     │
          ▼     ▼
       ┌──────┐  Failover
       │ 重试  │  或返回错误
       │ 次数  │
       │ < max?│
       └──┬───┘
       ┌──┴──┐
       │     │
      是    否
       │     │
       ▼     ▼
    等待退避  Failover
    重新调用  或返回错误

429 速率限制特殊处理

429 错误通常包含 Retry-After 响应头，指示需要等待的时间：

retry:
  respectRetryAfter: true      # 遵循 Retry-After 头
  maxRetryAfterDelay: 60000    # Retry-After 最大等待时间

收到 429 响应
  │
  ▼
检查 Retry-After 头
  │
  ├── 有 Retry-After: 等待指定时间后重试
  │
  └── 无 Retry-After: 使用指数退避

Retry-After 上限

如果 Retry-After 指示的等待时间超过 maxRetryAfterDelay，OpenClaw 会直接触发 Failover 而非长时间等待。

工具执行重试

除 LLM 调用外，工具执行也可配置重试：

toolRetry:
  enabled: true
  maxRetries: 2
  retryableTools:
    - web_search                # 网络搜索可能超时
    - api_call                  # API 调用可能临时失败
  nonRetryableTools:
    - file_write                # 文件操作不应重试（幂等性问题）

重试日志

[RETRY] openai/gpt-4o - Attempt 1/3
  Error: 429 Too Many Requests
  Retry-After: 2s
  Next attempt in: 2000ms

[RETRY] openai/gpt-4o - Attempt 2/3
  Error: 429 Too Many Requests
  Next attempt in: 4000ms

[RETRY] openai/gpt-4o - Attempt 3/3
  Error: 429 Too Many Requests
  Max retries reached → Triggering failover

[FAILOVER] Switching to anthropic/claude-3-5-sonnet

配置示例

激进重试

# 适合网络不稳定的环境
retry:
  maxRetries: 5
  initialDelay: 500
  maxDelay: 60000
  backoffMultiplier: 2
  jitter: true

快速失败

# 适合需要快速响应的场景
retry:
  maxRetries: 1
  initialDelay: 1000
  maxDelay: 5000
  backoffMultiplier: 1

无重试

# 完全依赖 Failover
retry:
  maxRetries: 0

🇨🇳 中国用户须知

• 国内访问国际模型 API 可能遇到更多网络超时，建议增大 maxRetries
• 使用国内 API 代理时，注意代理本身可能引入额外延迟
• 国产模型的速率限制策略可能与国际模型不同，注意调整配置

下一步

• 了解 模型故障转移 的切换机制
• 查看 模型提供商 了解 Provider 配置
• 探索 用量追踪 监控重试带来的额外消耗