$cd ../troubleshooting/
API 速率限制已达到（429）— OpenAI、Anthropic、Gemini
// '⚠️ API rate limit reached' 错误意味着您的提供商账户已达到每分钟请求数（RPM）或每分钟 Token 数（TPM）上限。这在免费/试用层以及大量使用 cron/心跳时会发生。
diagnose.sh
🔍 这是您的问题吗？
?您看到 '⚠️ API rate limit reached. Please try again later.'
?错误出现在不同的 AI 提供商中（不止一个）
?在高峰时段或长时间对话后更频繁出现
openclaw.yaml
✅ 修复方法 1 — 添加提供商备用链
添加到 openclaw.yaml — 429 时自动故障转移
providers:
- id: primary
type: openai
apiKey: sk-...
- id: fallback1
type: anthropic
apiKey: sk-ant-...
- id: fallback2
type: google
apiKey: AIza...
agents:
defaults:
provider: primary
fallbackProviders:
- fallback1
- fallback2provider_backoff.yaml
✅ 修复方法 2 — 启用限流退避
对 429 响应使用指数退避
providers:
- id: primary
type: openai
apiKey: sk-...
rateLimit:
retries: 3
backoffMs: 2000
maxBackoffMs: 30000heartbeat.yaml
✅ 修复方法 3 — 降低心跳/Cron 频率
降低心跳频率以减少 RPM 使用
agents:
defaults:
heartbeat:
interval: "*/30 * * * *" # 每 30 分钟（原来 5 分钟）
maxTokens: 512 # 减少每次运行的 token 用量tier_info.txt
✅ 修复方法 4 — 升级提供商套餐
提供商套餐对比
# OpenAI：在 platform.openai.com 升级到 Tier 2+ # Anthropic：在 console.anthropic.com 升级 # Google：在 console.cloud.google.com 启用计费 # 免费层限制（近似值）： # OpenAI Tier 1: 500 RPD，10K TPM # Anthropic 免费：5 RPM，25K TPM # Gemini 免费： 15 RPM，每天 1M token
💡 专业技巧：使用多个提供商
配置 2-3 个提供商的备用链。当一个达到速率限制时，OpenClaw 会自动切换到下一个。这是最可靠的长期解决方案。
❓ 常见问题
Q1. 如何查看当前的速率限制层级？
OpenAI 用户请访问 platform.openai.com/account/limits——它按模型显示您的 RPM、TPM 和 RPD 限制。Anthropic 用户请访问 console.anthropic.com/settings/limits。Google Gemini 用户请查看 console.cloud.google.com/apis/api/generativelanguage.googleapis.com/quotas。免费层通常允许 3-10 RPM，付费用户从 Tier 1 开始，达到消费门槛后可申请升级。
Q2. 切换到本地模型可以完全避免速率限制吗？
是的。本地运行 Ollama 没有速率限制，因为模型完全在您的硬件上运行。这是自托管 AI 的主要优势——您拥有推理能力。代价是需要合适的硬件（7B 模型推荐 8GB+ 显存）且延迟高于快速硬件上的云端 API。对于全天候运行的 agent，本地推理通常比云端 API 更便宜、更可靠。
Q3. 对 429 错误重试会使问题更严重吗？
如果使用指数退避则不会。OpenClaw 内置了递增延迟（2s、4s、8s、16s……）的重试逻辑，可防止频繁请求 API 并触发更长时间的封禁。免费 API 密钥应避免将重试间隔设置为 10 秒以下。最糟糕的做法是实现紧密的重试循环——可能触发持续数小时的 IP 级速率限制。
Q4. 为什么我发消息不多却还是触发了速率限制？
OpenClaw agent 可以在没有可见用户交互的情况下在后台消耗 token。常见原因：(1) 每 5 分钟运行一次、系统提示很长的心跳 agent——即使没有用户在聊天，每次心跳也会消耗 TPM；(2) 触发每条用户消息多次模型调用的工具；(3) 频繁重新建立连接的流式响应。查看提供商仪表盘的使用量图表——每隔 N 分钟出现峰值表明心跳或定时任务是罪魁祸首。
Q5. 可以使用多个 API 密钥来增加有效速率限制吗？
技术上可以，但这可能违反提供商的服务条款。OpenAI 的条款禁止使用多个账号规避速率限制。受支持的方式是在回退链中使用多个不同的提供商——一个 OpenAI 密钥加一个 Anthropic 密钥加一个 Gemini 密钥，可获得三个独立的速率限制桶，从容量角度看各提供商的免费或付费层是叠加的。
Q6. 如何知道哪个 agent 或技能触发了速率限制？
在 OpenClaw 中启用调试日志（log_level: debug），观察带有提供商名称标签的行。每次 API 调用都会记录 agent ID、token 计数和所用提供商。您也可以查看提供商仪表盘的使用量明细——如果为每个 agent 使用单独的 API 密钥，OpenAI 会按密钥显示使用量。或者在 config.yaml 中为每个 agent 设置 maxTokens 限制，以限制每次运行的消耗量。