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

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

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

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

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

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

若最早错误是 invalid bearer token 或 missing authentication header，转到 OpenClaw 401 认证失败排查。若明确是 context_length_exceeded、input too long，则使用 保留工作后恢复上下文超限 的流程。429 可以与这些问题先后发生，但状态码本身不能证明历史过长或 key 失效。

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

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

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

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

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 文档说明了这些行为。

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

/model status

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

重点保留这几项证据：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

/model default

先确认默认主模型及备用路线正是你希望使用的方案；这个动作不增加额度，也不保证默认链里的候选可用。需要接入备用模型时，按 OpenClaw 模型配置指南 完成对应认证、准确模型选择和验证，再加入自己希望使用的链，避免复制 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 排障给出了这些选项。

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

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

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

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

使用单独 ClawHub CLI 的认证工作流时，可以按 ClawHub 登录与排障说明 在本地运行：

clawhub login
clawhub whoami

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

下载恢复后，先选出确实需要的技能，再检查已有技能与依赖；可以按 OpenClaw Skills 的任务选择与首次验收指南 确认下一步，减少重复安装。

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

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

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

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

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

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

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

常见问题

OpenClaw 429 要统一等 60 秒吗？

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

重启 Gateway 能清除 all in cooldown 吗？

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

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

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

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

当前显式会话模型选择是严格选择。若希望采用已配置默认链，可先核对默认路线，再用 /model default；原生 agent 自己的 primary 还需自己的回退列表。成功备用只处理当前回合。当前选择来源规则说明了这个区别。

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

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