OpenClaw "API rate limit reached" 涵盖三种不同根因，按出现频率排序：**① Provider 429**（LLM API 超速，存在 Issue #43879 的冷却逻辑 bug，多 Profile 配置是当前最有效的临时方案）→ **② ClawHub 安装限速**（`clawhub login` 登录后解决）→ **③ OpenClaw 内置限速**（`rateLimit` 配置调优）。高频使用场景下，配置多 API Key + `ratelimit-retry` 社区插件，或通过七牛云 MaaS 统一接入多国内模型，是降低触碰限速概率的最彻底解决方案。OpenClaw 中的 "API rate limit reached" 错误分为三种完全不同的场景：Provider 返回 429（LLM 调用超过提供商限速阈值）、ClawHub 安装时 rate limit exceeded（npx clawhub@latest install 未登录）、以及 OpenClaw 内置限速触发（多 Agent 并发请求超过配置上限）。三种场景的根因和修复路径完全不同，需要先通过报错位置定位类型再对症处理。根据 GitHub issue 记录（截至 2026 年 3 月），Provider 429 是最常见也是最难彻底解决的一类，因为 OpenClaw 当前版本对 429 的回退逻辑存在已知 regression（Issue #43879）。
三类 rate limit 速查表
| 错误信息 | 出现位置 | 根因 | 快速修复 |
|---|---|---|---|
⚠️ API rate limit reached. Please try again later. |
对话界面 | Provider 返回 HTTP 429，OpenClaw 触发限速冷却 | 等待冷却结束，或配置多 API Key / 备用 Provider |
Rate limit exceeded |
npx clawhub@latest install 命令行 |
ClawHub 安装工具未登录，匿名请求触发 Registry 限速 | 先执行 clawhub login --token <token> 再安装 |
| 请求卡住不响应（无错误弹窗） | 后台日志 | OpenClaw 内置 rateLimit.maxRequestsPerMinute 触发静默排队 |
调整 agents.defaults.rateLimit 配置 |
场景 1：Provider 返回 429（最常见）
错误现象
对话界面弹出 ⚠️ API rate limit reached. Please try again later.，此后请求进入指数退避冷却（硬编码序列：1 分钟 → 5 分钟 → 25 分钟 → 1 小时），期间不显示冷却剩余时间，用户侧表现为「卡死」。
受影响 Provider（根据 GitHub issue 归类）：
| Provider | 触发条件 | 特殊问题 |
|---|---|---|
| Google / Gemini | 免费层 RPM（请求/分钟）上限 | 429 会阻塞整个 Provider，而非单一模型（Issue #43879） |
| Anthropic (Claude) | rate_limit_error / Token 配额耗尽 |
高频工具调用场景易触发 |
| OpenAI | Quota exceeded | 共享 API Key 环境下多用户竞争 |
| Kimi / Moonshot | 余额不足时返回 429 而非 402 | 误判为限速，实为账户欠费（Issue #43932） |
已知 Bug：冷却逻辑错误（Issue #43879）
根因：auth-profile 的冷却状态是按 Profile 级别 记录的，而非 Model 级别。当某一模型触发 429 后，整个 Profile 下的所有模型都进入冷却，即使其他模型仍有可用配额，也无法作为 fallback。
临时绕过方案：为同一 Provider 创建多个独立 Profile，每个 Profile 使用不同 API Key：
{"profiles": [{"id": "openai-primary","type": "api-key","provider": "openai","apiKey": "sk-key-1"},{"id": "openai-backup","type": "api-key","provider": "openai","apiKey": "sk-key-2"}],"default": "openai-primary"
}
OpenClaw 的 failover 逻辑会在 openai-primary 冷却期间自动切换到 openai-backup（Issue #44477 追踪此功能，已标记为高优先级）。
标准排查步骤
# Step 1：查看哪个 Provider 触发了 429
openclaw logs --follow --level debug | grep "429\|rate_limit\|cooldown"# Step 2：查看当前各 Profile 的冷却状态
openclaw profiles status# Step 3：手动重置冷却（强制恢复，需版本 ≥ 2026.3.8）
openclaw profiles reset-cooldown --profile openai-primary# Step 4：临时切换到备用 Profile
openclaw config set defaultProfile openai-backup
Kimi 429 特殊情况：欠费误报
Kimi API 在账户余额不足时返回 HTTP 429，而非标准的 402 Payment Required。OpenClaw 无法区分此类 429 与真正的限速 429，会进入无效的冷却等待循环。
诊断：
# 直接测试 Kimi API 余额状态
curl -s https://api.moonshot.cn/v1/users/me \-H "Authorization: Bearer 你的kimi-key" | python3 -m json.tool
# 查看 "balance" 字段是否为 0 或负数
场景 2：ClawHub 安装时 rate limit exceeded（Issue #589）
错误信息：npx clawhub@latest install <skill-name> 返回 Rate limit exceeded。
根因：ClawHub Registry 对未登录的匿名请求设置了严格的速率上限，AWS、主机服务商、或同一局域网内的多个用户共用同一出口 IP 时，匿名配额很快耗尽。
修复步骤：
# Step 1：从 ClawHub 控制台获取 CLI Token
# https://clawhub.ai/settings → CLI Token → 生成新 Token# Step 2：使用 Token 登录
clawhub login --token <your-cli-token># Step 3：验证登录状态
clawhub whoami# Step 4：重新安装技能
clawhub install <skill-name>
备选方案（不依赖 ClawHub Registry）：
# 从 skills.sh 安装（兼容 OpenClaw，无 ClawHub 账号要求）
npx skills add <skill-name># 直接从 GitHub 安装
npx skills add https://github.com/用户名/技能仓库
注：ClawHub Registry 与
registry.clawhub.comDNS 故障（Issue #44839，2026 年 3 月 13 日确认）是两个独立问题——DNS 故障影响所有用户；rate limit exceeded 仅影响未登录用户。
场景 3：OpenClaw 内置限速配置
OpenClaw 支持在 agents.defaults.rateLimit 中配置全局请求速率上限，防止多 Agent 并发任务在短时间内耗尽 Provider 配额（Issue #27213 追踪此功能）。
配置示例（~/.openclaw/config.yaml 或 openclaw.json）：
{"agents": {"defaults": {"rateLimit": {"maxRequestsPerMinute": 10,"burstAllowance": 3,"throttleDelayMs": 1000}}}
}
参数说明：
| 参数 | 默认值 | 说明 |
|---|---|---|
maxRequestsPerMinute |
不限 | 每分钟最大请求数，10 兼容所有订阅层级 |
burstAllowance |
0 | 触发节流前允许的突发请求数 |
throttleDelayMs |
0 | 每次突发后的强制等待时间（毫秒） |
适用场景：Cron 定时任务、多 Agent 并行编排、高频工具调用（如每隔几秒自动触发 web search）。
多 API Key 防限速配置（推荐方案）
对于高频使用场景，最彻底的防限速方案是配置多个 API Key 实现自动 failover。
方案 A：同一 Provider 多 Key（针对场景 1 的 Issue #43879）
{"profiles": [{ "id": "anthropic-key1", "type": "api-key", "provider": "anthropic", "apiKey": "sk-ant-key-1" },{ "id": "anthropic-key2", "type": "api-key", "provider": "anthropic", "apiKey": "sk-ant-key-2" },{ "id": "anthropic-key3", "type": "api-key", "provider": "anthropic", "apiKey": "sk-ant-key-3" }],"default": "anthropic-key1"
}
方案 B：跨 Provider 备份
当主 Provider 触发 429 时自动切换到备用 Provider：
{"profiles": [{"id": "primary","type": "api-key","provider": "anthropic","apiKey": "sk-ant-primary","fallbackProfile": "backup"},{"id": "backup","type": "api-key","provider": "openai","apiKey": "sk-openai-backup"}]
}
方案 C：七牛云 MaaS 统一接入
通过七牛云 MaaS 在单一 API Key 下调度多个国内模型（DeepSeek、Kimi、GLM、MiniMax），由 MaaS 层统一管理各模型的速率分配，减少单一 Provider 触碰限速的频率：
{"profiles": [{"id": "qiniu-maas","type": "api-key","provider": "openai","apiKey": "你的七牛云-api-key","baseURL": "https://api.qnaigc.com/v1","model": "deepseek-chat"}]
}
ratelimit-retry 社区插件（Issue #44330）
OpenClaw 社区维护了 ratelimit-retry 插件，实现更精细的重试策略，包括：指数退避、Jitter 随机化、按模型独立冷却（解决 Issue #43879 的 Profile 级冷却 bug）。
安装：
clawhub install ratelimit-retry
# 或从 skills.sh 安装
npx skills add ratelimit-retry
配置（安装后在 plugins 块启用）：
plugins:ratelimit-retry:enabled: truemaxRetries: 3initialDelayMs: 2000backoffFactor: 2.0jitterMs: 500perModelCooldown: true # 修复 per-profile 冷却 bug
完整诊断流程
# Step 1：确认错误类型（Provider 429 / ClawHub 限速 / 内置限速）
openclaw logs --level debug --last 50 | grep -i "rate\|429\|limit\|cooldown"# Step 2：查看 Provider 配额使用情况（以 Anthropic 为例）
curl -s https://api.anthropic.com/v1/messages \-H "x-api-key: 你的key" \-H "anthropic-version: 2023-06-01" \-d '{"model":"claude-haiku-4-5-20251001","max_tokens":1,"messages":[{"role":"user","content":"hi"}]}' \-I | grep -i "x-ratelimit"
# 响应头中 x-ratelimit-remaining-requests 显示剩余配额# Step 3：查看各 Profile 冷却状态
openclaw profiles status# Step 4：如果是 ClawHub 安装限速，检查登录状态
clawhub whoami# Step 5：运行诊断工具
openclaw doctor
常见问题
Q：OpenClaw 遇到 429 后会自动重试吗？
会，但当前版本（2026.3.x）的重试逻辑存在已知 bug（Issue #43879）——冷却是按 Profile 而非按模型记录的，导致 fallback 逻辑失效。临时解决方案是配置多个独立 Profile，或安装 ratelimit-retry 社区插件启用 per-model 冷却。
Q：Provider 429 冷却期间能做什么？
可以在 ~/.openclaw/config.yaml 中临时切换 defaultProfile 到备用 Profile，无需等待冷却结束。也可以通过 openclaw profiles reset-cooldown 命令手动重置（需版本 ≥ 2026.3.8）。
Q：Kimi 429 和真正的限速 429 怎么区分？
Kimi 在余额不足时返回 429（而非 402），通过 curl https://api.moonshot.cn/v1/users/me 查看 balance 字段可快速区分：余额为 0 或负数说明是欠费，充值即可解决；余额正常则是真正的速率限制，等待冷却或降低请求频率。
Q：clawhub install 的 rate limit exceeded 和 Provider 429 是同一个问题吗？
不是。clawhub install 的限速是 ClawHub Registry 对匿名用户的 IP 级请求频率限制，与 LLM Provider 的 API 调用限速完全无关。前者通过 clawhub login 登录后解决，后者需要配置多 API Key 或调整调用频率。
Q：如何预防 Cron 定时任务触发限速？
在 agents.defaults.rateLimit 中设置 maxRequestsPerMinute，将 Cron 任务的请求频率控制在 Provider 免费层的 RPM 上限以内（通常为 10-20 RPM）。同时启用 burstAllowance: 2 允许少量突发，不影响正常对话体验。
总结
OpenClaw "API rate limit reached" 涵盖三种不同根因，按出现频率排序：① Provider 429（LLM API 超速，存在 Issue #43879 的冷却逻辑 bug，多 Profile 配置是当前最有效的临时方案）→ ② ClawHub 安装限速（clawhub login 登录后解决）→ ③ OpenClaw 内置限速（rateLimit 配置调优）。高频使用场景下，配置多 API Key + ratelimit-retry 社区插件，或通过七牛云 MaaS 统一接入多国内模型，是降低触碰限速概率的最彻底解决方案。
本文内容基于 2026 年 3 月 OpenClaw GitHub 公开 issue 整理，具体版本行为可能随迭代变化，建议结合 openclaw --version 和最新 Release Notes 确认。
延伸资源
- OpenClaw Issue #43879（冷却逻辑 per-profile bug）：https://github.com/openclaw/openclaw/issues/43879
- OpenClaw Issue #44477（多 API Key 支持）：https://github.com/openclaw/openclaw/issues/44477
- OpenClaw Issue #44330（ratelimit-retry 社区插件）：https://github.com/openclaw/openclaw/issues/44330
- ClawHub Issue #589（安装时 rate limit exceeded）：https://github.com/openclaw/clawhub/issues/589