OpenClaw API速率限制与429错误处理

问题描述

在使用 OpenClaw 时，当多个用户同时发送消息或消息量较大时，日志中可能出现以下错误：

[openclaw:gateway] Error calling model API: 429 Too Many Requests
[openclaw:gateway] Rate limit exceeded. Retry after 20 seconds.
[openclaw:gateway] Headers: x-ratelimit-remaining-requests: 0, x-ratelimit-reset-requests: 20s

用户侧看到的表现是机器人回复延迟明显增加，或者收到错误提示：

机器人回复：服务暂时繁忙，请稍后再试。

429 错误表示你的 API 请求已超过模型提供商的速率限制。不同的 AI 模型提供商对 API 调用有不同的限制策略，通常包括每分钟请求数（RPM）、每分钟 token 数（TPM）以及每天的总调用量。

各提供商的限制标准

常见的限制（以免费/低级别为例）：

提供商	RPM	TPM	每日限制
OpenAI (Tier 1)	500	30,000	无
Anthropic (Build)	50	40,000	无
Google Gemini (Free)	15	32,000	1,500

实际限制取决于你的账户等级和使用的具体模型。

诊断步骤

查看 OpenClaw 的速率限制统计：

openclaw stats rate-limit

输出示例：

Provider    Model           RPM Used    RPM Limit    Status
openai      gpt-4o          45/60       60           ⚠️ Warning
anthropic   claude-sonnet   12/50       50           ✓ OK

启用详细的 API 日志来追踪请求频率：

DEBUG=openclaw:api* openclaw start

检查最近一小时的请求日志：

openclaw logs --filter "api" --since 1h

解决方案

方案一：启用内置的速率限制器

OpenClaw 内置了速率限制器，可以在发送请求前主动控制频率，避免触发提供商的限制：

{
  "api": {
    "rateLimiter": {
      "enabled": true,
      "strategy": "sliding-window",
      "limits": {
        "openai": {
          "requestsPerMinute": 50,
          "tokensPerMinute": 25000
        },
        "anthropic": {
          "requestsPerMinute": 40,
          "tokensPerMinute": 35000
        }
      }
    }
  }
}

建议将限制值设置为提供商实际限额的 80%，留出余量。

方案二：配置自动重试与退避

当遇到 429 错误时，让 OpenClaw 自动等待并重试：

{
  "api": {
    "retry": {
      "enabled": true,
      "maxRetries": 3,
      "backoff": {
        "type": "exponential",
        "initialDelay": 5000,
        "maxDelay": 60000,
        "factor": 2
      },
      "retryOn": [429, 500, 502, 503]
    }
  }
}

这样当收到 429 响应时，OpenClaw 会等待 5 秒后重试第一次，10 秒后重试第二次，20 秒后重试第三次。

方案三：配置用户级别的速率限制

限制每个用户的消息发送频率，从源头减少 API 调用：

{
  "users": {
    "rateLimit": {
      "messagesPerMinute": 10,
      "cooldownMessage": "您发送消息过于频繁，请等待 {remaining} 秒后再试。"
    }
  }
}

方案四：多 API Key 轮换

配置多个 API Key 进行轮换，成倍提升可用额度：

{
  "providers": {
    "openai": {
      "apiKeys": [
        "sk-key-1-xxxxx",
        "sk-key-2-xxxxx",
        "sk-key-3-xxxxx"
      ],
      "keyRotation": "round-robin"
    }
  }
}

OpenClaw 支持两种轮换策略：

round-robin：按顺序轮流使用每个 Key
least-used：优先使用当前使用量最低的 Key

如果某个 Key 遇到 429 错误，OpenClaw 会自动跳过该 Key 并使用下一个可用的 Key。

方案五：设置模型降级

当主模型被限流时，自动降级到备选模型：

{
  "models": {
    "default": {
      "provider": "openai",
      "model": "gpt-4o",
      "fallback": [
        {
          "provider": "anthropic",
          "model": "claude-sonnet-4-20250514"
        },
        {
          "provider": "openai",
          "model": "gpt-4o-mini"
        }
      ]
    }
  }
}

当 gpt-4o 返回 429 错误时，OpenClaw 会自动尝试使用 fallback 列表中的下一个模型处理请求。

方案六：配置请求队列

将并发请求排入队列，按顺序处理，避免瞬时请求数过高：

{
  "api": {
    "queue": {
      "enabled": true,
      "concurrency": 3,
      "maxQueueSize": 100,
      "timeout": 120000
    }
  }
}

concurrency 控制同时进行的 API 请求数量，超出的请求会排队等待。

监控建议

配置仪表板或告警来监控 API 使用情况：

# 查看实时的API使用统计
openclaw stats api --watch

# 导出使用报告
openclaw stats api --export csv --period 7d > api-usage.csv

定期检查 API 使用报告可以帮助你合理规划额度、及时升级 API 账户等级。