# OpenClaw 429 限流怎么恢复？等待、冷却与回退排查

> 遇到 OpenClaw 429，先停止反复提交整条任务。临时限流按 Retry-After 等待并降低并发；套餐周期或余额耗尽要等实际重置或恢复访问。ClawHub 下载单独排查，重启不会清除持久冷却，已配置的备用模型也要满足当前会话的回退规则。

- URL: https://blog.laozhang.ai/zh/posts/openclaw-rate-limit-exceeded-429
- Published: 2026-02-04
- Updated: 2026-10-05
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: 故障排查
- Tags: OpenClaw, 429 错误, rate limit exceeded, 速率限制, 模型回退, ClawHub

---
**OpenClaw 报 `429` 或 `rate limit exceeded` 时，先停止重复提交整条任务，确认失败的是模型调用还是 ClawHub 下载。** 模型的临时速率限制按上游 `Retry-After` 等待，并减少同时发请求的任务；套餐日、周、月用量耗尽则要等真实重置时间或恢复账户访问，不能靠多等一分钟、换同账户的 key 或重启 Gateway 增加额度。

当前 OpenClaw 会对符合条件的模型临时限流做有上限的自动恢复，并沿用原记录保留已完成工作。界面仍显示重试等待时，不要再启动同一任务；已经终止时，先核对工具结果与已改文件，再继续未完成部分。ClawHub 技能下载有自己的限流和认证，模型 API key 无法替它解除限制。[官方重试规则](https://docs.openclaw.ai/concepts/retry)与[ClawHub 排障说明](https://docs.openclaw.ai/clawhub/troubleshooting)分别规定了这两条路径。

以下步骤依据截至 2026 年 10 月 5 日核对的官方说明；认证与回退部分同时使用 10 月 4 日保存、5 日复读的文档。命令供你在自己的 Gateway 环境中核对，本文没有执行真实 OpenClaw 恢复、账户登录或付费模型调用。

## 先决定继续等待，还是停止追加请求

找到**最先发生的错误**，不要只凭最后一句 `all in cooldown` 下结论。先记录时间、原始状态码、错误内容、服务商、模型、agent 和重置提示，再按下表行动。

| 实际看到的情况 | 现在做什么 | 什么时候再继续 |
|---|---|---|
| 模型 `429`，有有效的 `Retry-After`，没有用量周期耗尽证据 | 保留当前自动恢复，暂停其他并发任务；至少等到上游要求的时间 | 当前恢复完成，或等待到期后用较小请求核对 |
| 明确提示日、周、月额度或订阅用量耗尽 | 停止向耗尽路线追加请求，查看该账户的真实重置时间；有合格备用才转向 | 周期恢复、对应访问问题解决，或备用路线实际完成请求 |
| `insufficient credits`、支出上限或账户访问受限 | 处理对应账户、组织或项目限制；不要持续原样重试 | 上游恢复访问且本地路线重新可用之后 |
| `skills install`、`clawhub` 或下载接口返回 `429` | 停止重复安装，读下载响应的重试/重置头，核对该安装流程的认证 | ClawHub 要求的等待到期后，完成一次所需下载 |
| 只看到 `all in cooldown` | 查此前各候选的失败原因和冷却到期时间 | 对应限制恢复，或有符合条件的其他候选可用 |
| 错误已经变为 `401` 或明确上下文超限 | 按新错误处理，不继续把它当临时限流 | 新阻塞修复后，再恢复原任务 |

若最早错误是 `invalid bearer token` 或 `missing authentication header`，转到 [OpenClaw 401 认证失败排查](https://blog.laozhang.ai/zh/posts/openclaw-401-authentication-error)。若明确是 `context_length_exceeded`、`input too long`，则使用 [保留工作后恢复上下文超限](https://blog.laozhang.ai/zh/posts/openclaw-context-length-exceeded) 的流程。429 可以与这些问题先后发生，但状态码本身不能证明历史过长或 key 失效。

![按最早错误区分模型临时限流、周期额度、ClawHub 下载和冷却](https://blog.laozhang.ai/posts/zh/openclaw-rate-limit-exceeded-429/img/rate-limit-next-action.webp)


## 查真实模型、会话选择和对应日志

在 Gateway 实际运行的主机、服务用户和 profile 下查看状态。下面 `YOUR_AGENT_ID` 是占位符，替换成失败 agent 的准确 ID：

```bash
openclaw --version
openclaw models status --agent YOUR_AGENT_ID
openclaw logs --limit 200 --max-bytes 250000 --plain
```

多个 Gateway profile 时，给命令使用正确的根级 `--profile`。例如 profile 确实叫 `work`，可查看：

```bash
openclaw --profile work logs --limit 200 --max-bytes 250000 --plain
```

当前 `openclaw logs` 可通过 RPC 读取所选 Gateway 的日志，文件按 profile 与日期滚动；不要假设固定存在 `~/.openclaw/logs/openclaw.log`。持续观察时可用 `openclaw logs --follow`，找到对应失败后用 Ctrl+C 结束。日志流断线、重连或读取失败，不等于模型服务商又返回一次 429；不同日志来源还可能重叠输出相同记录。[日志 CLI 文档](https://docs.openclaw.ai/cli/logs)说明了这些行为。

然后在**原来报错的聊天会话**中查看：

```text
/model status
```

`models status --agent` 解释 agent 的默认、备用、认证与运行时状态，不检查聊天会话固定的模型；`/model status` 才能帮助确认本会话的选择。再把它与失败日志中的实际 `provider/model` 对照：界面选定的模型、失败候选和最终回答模型可能不同。[模型状态文档](https://docs.openclaw.ai/cli/models)明确区分了配置状态与真实调用。

重点保留这几项证据：

- 最早上游错误的状态码、`type`/`code`、请求 ID 和错误摘要。
- 请求实际发给哪个服务商或兼容网关，由哪个账户、组织或项目承担额度。
- `Retry-After`、明确的周期重置提示，以及不可用 profile 的原因和到期时间。
- 是否尝试备用模型；日志中的 `model_fallback_decision`、`fallbackStepFromModel`、`fallbackStepToModel` 与最终结果。

提交给对应服务商或维护者时脱敏凭据、私人提示与业务内容。`models status` 正常或 `--check` 返回 0，只证明没有发现相应配置认证/运行时问题，不证明模型请求成功。`--probe` 则会发起真实请求，可能消耗额度和触发限流；排查期间不要把它当免费的状态查询反复运行。

## 模型 429 要等多久？看上游提示与错误类型

临时限流有有效的 `Retry-After` 时，把它作为**最短等待时间**。没有提示时，采用有上限、逐渐增加间隔并带随机延迟的重试，同时降低其他请求源的负载；不要每隔几秒原样重发大任务。OpenAI 明确说明失败请求也会计入每分钟限制，连续重发会继续消耗可用空间。[OpenAI 速率限制说明](https://developers.openai.com/api/docs/guides/rate-limits)给出了重试与计量规则。

在当前 OpenClaw 模型恢复中，临时限流最多 **10 次总尝试**。普通退避间隔约从 1 秒开始增加、带随机延迟，退避上限是 30 秒；上游要求的更长等待仍可决定最短间隔。其他临时故障的“8 次重试、90 秒连续故障窗口”是另一套条件，不能解释成全部 429 都在 90 秒后恢复。取消和运行截止时间也能终止恢复。[官方模型重试说明](https://docs.openclaw.ai/concepts/retry)是这些数值的适用范围。

有两个容易混淆的 60 秒设置：

| 控制位置 | 当前文档含义 |
|---|---|
| 恢复控制器的已保存 `retry.provider.maxRetryDelayMs`，默认 60 秒 | 已配置 fallback 时，更长的服务端最短等待可直接转向合格备用；没有 fallback 时仍尊重完整等待，设为 `0` 可关闭这项上限 |
| OpenClaw 对部分 SDK 内部重试的 60 秒等待上限 | 让 SDK 把较长等待的错误及时交回 OpenClaw 控制器；由 `OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS` 控制 |

这两者都不是“上游 60 秒必解限”。也不要把会话运行时的重试设置随意加入 `openclaw.json`，或再套一个无限循环：SDK、原生后端和 OpenClaw 控制器可能各有请求恢复，叠加会放大调用次数。

### 配额耗尽时，等待要对应真实周期

明确的订阅、每日、每周或每月用量耗尽会转向有资格的认证记录或模型备用，不走普通临时故障的完整等待预算。但仅有一个 `Retry-After` 不能证明周期额度已经耗尽。核对原始错误和实际账户限额；没有重置时间时保留未知，不用“统一等 1 分钟”代替判断。

OpenAI 的 RPM、TPM、RPD、TPD 等限制各自计算，并作用于组织或项目；部分模型还共享限额池。同组织新增 key 或换共享池内模型，不等于新增容量。支出提醒与硬支出上限也不同：提醒可以只通知，硬上限会让受影响请求返回 429。[OpenAI 官方限制说明](https://developers.openai.com/api/docs/guides/rate-limits)同时解释了这些区别。

Anthropic 的 429 可以来自速率限制、用量层级月支出上限或 Claude Code 工作区支出限制。层级支出上限的 429 没有 `retry-after`，访问恢复前会继续失败，因此缺少该头不应触发无限重试。[Claude API 错误说明](https://platform.claude.com/docs/en/api/errors)给出了这项条件。

使用其他服务商、Coding Plan 或兼容代理时，也应看那条实际路线的套餐周期、并发限制与原始错误。通用 `rate limit exceeded` 或 `RESOURCE_EXHAUSTED` 不足以确定用量耗尽的种类；代理自己的限制和底层模型服务商的限制还可能分开存在。

## 重启后仍在冷却：检查持久状态，而不是清额度

**重启 Gateway 不会清除上游额度，也不会普遍清除 OpenClaw 的持久冷却。** 当前冷却记录保存在 agent 的 SQLite 认证状态中，包括 `usageStats` 下的 `cooldownUntil`、`disabledUntil` 等信息；应从状态与逐次尝试记录确认原因和到期时间，不手工删除数据库来强迫请求。[官方 model failover 说明](https://docs.openclaw.ai/concepts/model-failover)描述了存储和恢复行为。

普通、非计费且非永久认证故障的冷却随近期失败次数增长：第一次 30 秒、第二次 1 分钟、第三次及以后最高 5 分钟。**这是本地普通冷却规则，不是所有服务商的重置周期。** 速率限制还可能按模型生效：同一服务商的另一个模型或许可用；计费禁用则覆盖整个 profile，不能凭换模型绕过。

余额或计费失败会先产生 10 分钟禁用窗口，再尝试合格候选；充值本身不会立即清除已有持久状态。内联 key 在活动禁用窗口内不能重试，存储的认证记录则可能通过受限的主候选探测恢复。窗口已到期仍失败时，查看新的上游原因；系统也可能在临近到期时受限探测主候选，因而恢复不依赖重启。

![持久冷却与上游额度分别核对原因、到期和合格备用](https://blog.laozhang.ai/posts/zh/openclaw-rate-limit-exceeded-429/img/persistent-cooldown-recovery.webp)


确有需要通过重启加载新的服务配置时，按自己版本的 Gateway 管理流程操作；“冷却尚未到期”本身不构成反复重启的理由。只有可选的进程内认证失败跳过缓存会随重启清除，这与持久冷却和上游限制是不同对象。

## 配了备用模型，为什么没有切换？

先确认**本次选择允许回退**，再检查备用凭据、模型、运行时与额度。当前规则下，共享默认模型可使用 `agents.defaults.model.fallbacks`；原生 agent 自己的 primary 需要自己的回退列表；用户在会话中明确选择的模型则是严格选择，失败会直接报告。配置了一条全局链，不代表每个固定会话都会采用它。[当前选择来源规则](https://docs.openclaw.ai/concepts/model-failover#selection-source-policy)解释了这个差异。

如果你希望报错会话重新跟随已配置的默认策略，可在该会话使用：

```text
/model default
```

先确认默认主模型及备用路线正是你希望使用的方案；这个动作不增加额度，也不保证默认链里的候选可用。需要接入备用模型时，按 [OpenClaw 模型配置指南](https://blog.laozhang.ai/zh/posts/openclaw-llm-setup) 完成对应认证、准确模型选择和验证，再加入自己希望使用的链，避免复制 `claude-current` 或 `gpt-current` 这类不存在的占位模型。

按下列顺序排查一次失败的备用链：

1. 对照会话选择与 agent 配置，确认没有固定模型、独立 primary 或空 `fallbacks` 禁止回退。
2. 从日志确认主候选最先失败的原因，以及下一候选究竟是“被跳过”“已尝试失败”还是“已经回答”。
3. 核对备用的准确模型 ID、认证来源、运行时是否就绪，及它是否真的有独立可用容量。多个 key 共用一个耗尽账户，或所有备用都经过同一个受限网关，仍可能全部失败。
4. 检查是否已到运行截止时间、明确取消或其他终止条件。已经终止的运行不能通过加一条备用就无限继续。
5. 确认原任务状态，选择一个合格候选恢复未完成部分；成功后再逐步增加任务负载。

模型限流、认证失败、计费禁用、过载或合格的 `model_not_found` 等都可能推进备用，因此不能概括成“fallback 只处理 429”。但格式错误通常直接终止，上下文超限有自己的压缩/恢复处理，ClawHub 下载限制也不属于模型链。成功的备用只用于当前回合，下一回合仍从所选模型开始；它不会永久替换 primary。

### 只有长会话触发 `Extra usage is required for long context requests`

如果 Anthropic 429 的完整原文是 `Extra usage is required for long context requests`，应查**长上下文资格和实际路线**，不能只按短时请求过快处理。保存当前工作后，可选普通窗口的模型、使用确有相应资格的认证方式，或采用满足前述选择规则的合格备用。较旧、非 GA 模型的遗留 `context1m` 设置是单独分支，不能无条件删除当前 GA 模型设置；也不应为了消除错误自动开启付费额外用量。[官方长上下文 429 排障](https://docs.openclaw.ai/es/gateway/troubleshooting#anthropic-429%3A-se-requiere-uso-adicional-para-contextos-largos)给出了这些选项。

## ClawHub 搜索或下载 429：单独恢复安装流程

如果失败发生在技能搜索、`openclaw skills install`、`clawhub install` 或 `/api/v1/download` 等下载步骤，先停止重复安装，读取 **ClawHub 这一次响应**。ClawHub 的读取、写入与下载使用不同限流类别；匿名请求按 IP，带有效 Bearer token 的请求按用户计算，缺失或无效 token 会回到 IP 限制。共享出口 IP 因而可能让个人很少的请求也被拒绝。[HTTP API 说明](https://docs.openclaw.ai/clawhub/http-api)规定了这些条件。

有 `Retry-After` 时至少等它给出的秒数；没有时再读 reset 头，注意单位不同：

| ClawHub 响应头 | 如何读 |
|---|---|
| `Retry-After` | 重试前要等待的秒数 |
| `RateLimit-Reset` | 距重置还有多少秒 |
| `X-RateLimit-Reset` | Unix 绝对时间戳，单位为秒；需要与当前时间比较 |
| `RateLimit-Remaining` / `X-RateLimit-Remaining` | 存在时表示准确剩余预算；429 时为 0 |

成功响应可能省略 remaining 头，不能因此认定无限额度。这套 reset 单位也不能套给 OpenAI 的 `x-ratelimit-reset-tokens` 等可能采用时长字符串的头。恢复时只重试实际需要的一次搜索或下载，并减少并行更新与重复拉取。

使用单独 ClawHub CLI 的认证工作流时，可以按 [ClawHub 登录与排障说明](https://docs.openclaw.ai/clawhub/troubleshooting) 在本地运行：

```bash
clawhub login
clawhub whoami
```

按 CLI 打印的验证 URL 与代码完成授权；凭据留在本地。`whoami` 只确认这个 CLI 的登录身份，**不能证明原生 `openclaw skills install` 使用了同一 token**。当前官方区分原生 OpenClaw 安装命令与单独 ClawHub CLI 的注册表认证流程，应核对真正失败的客户端及其认证来源，再按响应等待；登录也不保证每种 429 立即消失。[ClawHub 概览](https://docs.openclaw.ai/clawhub)说明了两种流程的用途。

下载恢复后，先选出确实需要的技能，再检查已有技能与依赖；可以按 [OpenClaw Skills 的任务选择与首次验收指南](https://blog.laozhang.ai/zh/posts/openclaw-best-skills-guide) 确认下一步，减少重复安装。

## 降低后续压力，并从已完成工作继续

限流恢复后，先让请求量低于造成失败时的负载，再逐步恢复。若 RPM 或并发先触顶，减少同时运行的子任务、定时任务和其他消费者；若 TPM 压力突出，缩小每次输入与工具输出，避免反复送入整页网页、完整仓库或长日志。OpenAI 的 `slow_down` 429 还可能来自请求量增长过快，即使未超过标称 RPM/TPM，也需要降低速率并平稳增加。[官方速率限制说明](https://developers.openai.com/api/docs/guides/rate-limits)支持这些判断。

长历史需要压缩或交接时，先保存目标、已修改文件、完成动作及结果 ID、未知状态、未完成请求与下一步。不要为了限流删除历史；新会话可以减少历史输入，却不会重置服务商额度，也不会解除账户资格限制。具体压缩和新会话步骤交给 [上下文超限恢复指南](https://blog.laozhang.ai/zh/posts/openclaw-context-length-exceeded)。

终止后可用下面这份简短交接，替换为自己的真实状态：

```text
目标：……
已完成：文件/结果……，对应检查……。
已执行动作：……已成功，结果ID……；……的状态仍未知。
本次阻塞：实际服务商/模型……，最早错误……，最短等待或重置时间……。
未完成：……
下一步：先读取已有结果核对，只继续……；状态未知的动作不要重复。
```

恢复成功至少要看到：同一实际 agent 的小请求**完整结束**，知道究竟由主模型还是备用回答，原来的失败原因没有在下一步立即重现，并且原任务所需工具结果真实存在。云端短请求也可能计费，因此按需要做一次有限验证，随后只继续剩余工作。仅看到 Gateway 正常、status 正常、首个 token 或“冷却倒计时下降”，都还不能证明原任务恢复。

当所有合格候选仍受限、没有可确认的恢复时间、同一错误未改变却重复出现，或已执行动作状态未知时，停止追加同样请求。把版本、实际路线、最早错误、等待提示、逐次备用结果及已做的修正交给对应服务商或 OpenClaw 维护者，等待可改变结论的信息后再继续。

## 常见问题

### OpenClaw 429 要统一等 60 秒吗？

不统一。有有效 `Retry-After` 时至少等它要求的时间；周期用量耗尽则等真实重置或恢复访问。OpenClaw 的 60 秒等待设置控制恢复与 SDK 交还控制的时机，不是所有上游的限流周期。[官方重试说明](https://docs.openclaw.ai/concepts/retry)给出了适用条件。

### 重启 Gateway 能清除 `all in cooldown` 吗？

不能作为通用清冷却办法。当前冷却与禁用状态持久保存在 agent 的 SQLite 中，上游额度也不受重启影响。先看各候选最早错误和到期时间；进程内可选跳过缓存能随重启清除，与持久冷却不同。[官方回退说明](https://docs.openclaw.ai/concepts/model-failover)区分了这些状态。

### 多加几把同账户的 API key 能避免限流吗？

不一定。OpenAI 等服务有组织、项目或共享模型池限制，同账户多 key 不会自然产生独立容量。备用是否有用要看实际认证、模型、运行时和限额归属，不能按 key 数量估算倍增额度。[OpenAI 官方限制说明](https://developers.openai.com/api/docs/guides/rate-limits)是核对入口。

### `/model` 固定了模型，为什么全局 fallback 没接手？

当前显式会话模型选择是严格选择。若希望采用已配置默认链，可先核对默认路线，再用 `/model default`；原生 agent 自己的 primary 还需自己的回退列表。成功备用只处理当前回合。[当前选择来源规则](https://docs.openclaw.ai/concepts/model-failover#selection-source-policy)说明了这个区别。

### 模型聊天正常，为什么安装技能还报 429？

因为技能下载由 ClawHub 的独立限流控制。读取安装响应的等待/重置信息，核对真正使用的客户端认证，减少重复安装；模型服务商恢复不证明下载预算已恢复。[ClawHub 排障说明](https://docs.openclaw.ai/clawhub/troubleshooting)给出了对应操作。

## 参考来源

本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-10-05。

- [官方重试规则](https://docs.openclaw.ai/concepts/retry) (docs.openclaw.ai)
- [ClawHub 排障说明](https://docs.openclaw.ai/clawhub/troubleshooting) (docs.openclaw.ai)
- [日志 CLI 文档](https://docs.openclaw.ai/cli/logs) (docs.openclaw.ai)
- [模型状态文档](https://docs.openclaw.ai/cli/models) (docs.openclaw.ai)
- [OpenAI 速率限制说明](https://developers.openai.com/api/docs/guides/rate-limits) (developers.openai.com)
- [Claude API 错误说明](https://platform.claude.com/docs/en/api/errors) (platform.claude.com)
- [官方 model failover 说明](https://docs.openclaw.ai/concepts/model-failover) (docs.openclaw.ai)
- [官方长上下文 429 排障](https://docs.openclaw.ai/es/gateway/troubleshooting) (docs.openclaw.ai)
- [HTTP API 说明](https://docs.openclaw.ai/clawhub/http-api) (docs.openclaw.ai)
- [ClawHub 概览](https://docs.openclaw.ai/clawhub) (docs.openclaw.ai)