OpenClaw Rate Limit Exceeded 429：Provider、ClawHub、Cooldown 与 Fallback 当前修复

OpenClaw 的 429 错误不是同一种问题。修复前先判断失败 surface：模型服务商 quota 或 token-per-minute 限制、ClawHub skill 下载限制、Gateway 重试后叠加的 cooldown、没有配置 fallback 链，或 agent session/context 过大导致一个任务打出太多 provider 请求。

最快恢复方式不是立刻换 key，也不是反复重启 gateway，而是先读原始错误。看到 OpenAI organization、Anthropic request id、Gemini RESOURCE_EXHAUSTED、TPM/RPM、retry-after，通常是 provider 侧限制；看到 clawhub、/api/v1/download、skill install，则是 ClawHub 下载/认证限制；看到 cooldown 很长或一直不切到下一个 provider，就先查 fallback 和 cooldown 状态。

快速诊断：先分支再修复

先运行这些命令，不要先改配置：

bash

openclaw models status

# 查看最近的 429、retry-after、resource exhausted 或 clawhub 错误
grep -i "429\|rate.limit\|resource_exhausted\|retry-after\|clawhub" ~/.openclaw/logs/openclaw.log | tail -40

openclaw models status 告诉你当前 provider 是否 cooling down、fallback 是否存在、请求是否卡在同一个耗尽的 provider。日志原文告诉你该去 provider 控制台、ClawHub 登录、等待 retry-after、降低上下文，还是补 fallback。

如果错误是 authentication_error、invalid api key 或 missing auth，它不是 429 分支。先看 OpenClaw Anthropic API Key 错误指南 或 OpenClaw API Key 错误修复。

要点速览

• Provider 429：尊重 retry-after，查 provider dashboard，降低上下文和并发，再配置可用 fallback。
• ClawHub 429：如果发生在 skill 下载或 hub 访问，不要轮换模型 key；先停止重试、登录/认证当前 hub 流程，或等待滚动窗口恢复。
• Cooldown / fallback 问题：OpenClaw 可能把 provider 放入冷却。没有测试过的 fallback 链时，它不会自动救你。
• Context 压力：长历史、后台轮询、子任务和重复 tool calls 会把一个可见任务放大成很多 provider 请求。先清会话、拆任务、限制并发。
• 关键证据：openclaw models status + 原始日志行，决定修复分支。

立即恢复服务

1. 先按 retry-after 等待，停止重试风暴

如果原始响应带 retry-after，按它等。不要每隔几秒手动重试同一个大请求；这会延长 cooldown、浪费 quota，并让 OpenClaw 继续把同一个 provider 打到失败。

如果 provider dashboard 已经显示 quota 或 billing exhausted，短等不会解决。你需要降低上下文、降低并发、提升 provider 额度，或切换到已验证的 fallback route。

2. ClawHub 下载 429：不要换模型 key

如果错误包含 clawhub、skill、/api/v1/download，失败 surface 不是 Anthropic、OpenAI 或 Gemini。此时应该停止重复安装/下载，按当前版本支持的 ClawHub/OpenClaw 登录流程认证，或等待匿名下载窗口恢复。

3. 只在 stale cooldown 时重启 gateway

当 provider 的真实 retry-after 已过期，但 OpenClaw 仍然显示旧 cooldown，可以重启 gateway：

bash
openclaw stop
openclaw start

# 使用后台服务时
systemctl restart openclaw
brew services restart openclaw

重启不是第一修复。如果 provider 仍在返回 429，重启只会短暂掩盖问题，并可能制造新的请求风暴。

4. 切到已验证的 fallback provider

只有在 fallback 已经配置、凭据有效、模型名已测试时，它才有用：

bash
openclaw models status

找 available 的 provider。Claude 侧限流时，可以临时切到 OpenAI、Gemini 或企业网关；但如果问题是 ClawHub、认证错误、无效 header 或本地 agent 循环，fallback 不会解决。

按 owner 理解 429

Anthropic / Claude：看 Claude Console、request id、rate-limit headers、spend limit 和 retry-after。429 可能来自 RPM、input tokens、output tokens、spend limit 或账号级限制。

OpenAI：看 owning organization 和 project。OpenAI 风格 429 往往会提到 org、project、model、requests、tokens、quota 或 billing。改 OpenClaw 本地配置不能修复一个耗尽的 org quota。

Google Gemini：RESOURCE_EXHAUSTED 通常指向 project quota、model quota、daily free-tier 或 billing。修复点在 Google Cloud / AI Studio，不在 OpenClaw router。

ClawHub：skill 下载或 hub 访问的 429 是单独分支。认证、降低下载频率、等待窗口，才是正确动作。

配置 Fallback 的正确边界

Fallback 是防 provider 429 的保险，不是所有 429 的万能解。它只在“模型 provider 受限”且“备用 provider 已认证、模型名有效、有额度”时发挥作用。它不会修复 ClawHub 下载限制、错误 API key、invalid beta header、billing exhausted 或无限循环的 agent。

示例结构应表达 owner 和备用路线，而不是照抄旧模型名：

yaml
agents:
  defaults:
    model:
      primary: "anthropic/claude-current"
      fallbacks:
        - "openai/gpt-current"
        - "google/gemini-current"

上线前逐个测试 fallback。不要等主 provider 失败后才发现备用 key 没权限、模型名不存在或 fallback route 也被同一个代理限制。

Context 压力也会制造 429

很多 OpenClaw 429 不是因为单次请求太快，而是 agent workflow 把请求数量放大了。长会话会让每次请求携带更多历史；大工具输出会被反复送回模型；多个子任务并发会同时消耗 provider RPM/TPM；失败重试又会叠加更多请求。

可操作的降载顺序：

1. 用 /clear 或新会话切断旧 context。
2. 把大文件、大日志、大网页输出先摘要，再交给模型。
3. 限制并发任务和后台轮询。
4. 降低单次任务范围，避免一个 prompt 拉完整 repo。
5. 用 openclaw models status 观察 cooldown 是否下降。

预防

• 为主 provider 配一个跨 provider 的 fallback，并定期测试。
• 在 provider dashboard 里设置 billing 和 quota alert。
• 让长任务分批运行，避免把所有日志、文件和历史一次性塞进 context。
• 记录每次 429 的 owner：provider、ClawHub、gateway cooldown、fallback miss、context pressure。
• 在团队文档里写清楚：哪些错误应等 retry-after，哪些应查 ClawHub，哪些应切 provider。

FAQ

OpenClaw 429 一定是 API key 不够额度吗？

不一定。它可能是 provider quota、ClawHub download limit、cooldown 状态、fallback 缺失或 context 压力。先读原始日志。

我应该等多久？

有 retry-after 就按它。没有时先停止重试，查 provider dashboard 和 openclaw models status。固定“等 60 秒”只适合一部分短 burst。

重启 OpenClaw 有用吗？

只有 cooldown 已经过期但 gateway 状态没恢复时有用。provider 仍在限流时，重启会继续失败。

Fallback 为什么没有自动切换？

常见原因是 fallback 没配置、备用 key 无效、模型名不可用、所有 provider 走同一耗尽代理，或错误根本不是 provider 429。

ClawHub 429 怎么办？

停止重复下载，按当前版本的登录/认证流程处理，或等待匿名下载窗口恢复。不要把模型 API key 当成 ClawHub key 来修。