OpenClaw报API Rate Limit Reached 如何排查？（CodingPlan版)

写在前面

「⚠️ API rate limit reached. Please try again later」该报错并非模型服务商API的直接报错，而是 OpenClaw 系统针对各类“调用受限”情况的统一封装提示，在终端通过命令 openclaw logs --follow 查看日志也会不打印原始的报错信息，排查起来相对麻烦，本文主要介绍了几种可能与火山 CodingPlan 相关的场景及解决方案。

报错来源

在 OpenClaw 项目中，报错 "⚠️ API rate limit reached. Please try again later. " 是由 src/agents/pi-embedded-helpers/errors.ts 文件中的常量 RATE_LIMIT_ERROR_USER_MESSAGE 定义的。

这个错误会在检测到 API 速率限制（Rate Limit）相关的错误信息时触发。

触发条件

具体来说，当 API 返回的原始错误信息包含以下任意关键词或模式（不区分大小写）时，就会显示该错误：

"rate limit"
"rate_limit"
"too many requests"
"429" (HTTP 状态码)
"model_cooldown"
"exceeded your current quota"
"resource has been exhausted"
"quota exceeded"
"resource_exhausted"
"usage limit"
"tpm" (作为完整单词出现，意为 Tokens Per Minute)
"tokens per minute"

代码位置引用

错误消息定义 : errors.ts:L41

const RATE_LIMIT_ERROR_USER_MESSAGE = "⚠️ API rate limit reached. Please try again later.";

匹配逻辑 : failover-matches.ts:L7-L17

rateLimit: [
    /rate[_ ]limit|too many requests|429/,
    "model_cooldown",
    "exceeded your current quota",
    "resource has been exhausted",
    "quota exceeded",
    "resource_exhausted",
    "usage limit",
    /\btpm\b/i,
    "tokens per minute",
],

排查方向与解决方案

该报错是 OpenClaw 系统针对各类“调用受限”情况的统一封装提示，由于 openclaw logs --follow 也不打印原始的报错日志，排查相对麻烦，有可能与 CodingPlan 套餐模型有关，如有遇到可排查以下情况：

情况一：CodingPlan 套餐用量已耗尽（优先确认是否套餐限额）

底层报错通常是

429 AccountQuotaExceeded

You have exceeded the 5-hour usage quota. It will reset at 2026-xx-xx xx:xx:xx +0800 CST. We recommend upgrading your plan for more quota, or waiting for the reset.

You have exceeded the weekly usage quota. It will reset at 2026-xx-xx xx:xx:xx +0800 CST. We recommend upgrading your plan for more quota, or waiting for the reset.

You have exceeded the monthly usage quota. It will reset at 2026-xx-xx xx:xx:xx +0800 CST. We recommend upgrading your plan for more quota, or waiting for the reset.

检查套餐限额：确认当前套餐是否已达到每日或每月的调用上限。
1. 查看当前用量：前往控制台查看
3. 查看套餐说明：点击查看详情
解决方案：
1. 升级套餐：获取更多配额。
2. 等待重置：等待限额周期（如五小时后/次日/次月）重置后再使用。

情况二：模型出现 RequestBurstTooFast 或 ServerOverloaded 等429报错（有概率出现，服务负载高导致）

底层报错通常是

429 {"error":{"code":"RequestBurstTooFast","message":"System protection triggered by request burst. Please slow down traffic growth and increase requests gradually before retrying. Request id: 0217710558840347c52c410876ab8649e200d8680cedfa015a2a1","param":"","type":"TooManyRequests"}}

429 {"error":{"code":"ServerOverloaded","message":"The service is currently unable to handle additional requests due to server overload. Please retry later. Request id: 02177070906905982d9a25dc868c42aa6f70cb2f9d1da6affbebf","param":"","type":"TooManyRequests"}}

负载高时可能会出现，若出现可先尝试重试，若重试仍不行，可暂时先切换套餐内的其它模型使用，一般不会所有模型都同时负载高，火山后端通常也会有自动扩容机制，等待扩容后一般就恢复了。

情况三：使用的是火山方舟在线推理接口（按量计费），触发了“安心体验模式”的保护机制（比较少见，CodingPlan 不会出现，按量计费推理接口才有）

检查安心体验模式：安心体验模式下，赠送的免费额度（通常为 50万 Token）用完后，服务会自动暂停以避免产生费用。
排查步骤：
1. 进入开通管理页面，可查看是否开启安心体验模式
3. 在模型列表中，查看您使用的模型是否显示 “安心体验” 或 “服务暂停” 标识。
解决方案：
1. 如需继续使用，请点击关闭安心体验模式。
2. 注意： 关闭后将开始按实际使用量进行计费，若账户内无余额将会欠费

情况四：未必是火山的问题，也可能是 OpenClaw 自身、聊天渠道（飞书、企微）的报错

正如上所说，这个是个兜底报错，如果情况一、二、三都排除了，那未必是火山的问题，可进一步从其他方向继续排查。