OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

快速开始

速率限制

Gateway 网关实施多项彼此独立的速率限制。它们保护不同的 边界、基于不同的身份确定键值，并以不同的错误形式失败。 本页是所有这些限制的参考。

概览：

范围 限制（默认） 键值依据 可配置
身份验证失败（令牌/密码/设备） 60 秒内失败 10 次，锁定 5 分钟 IP + 凭据范围 gateway.auth.rateLimit
浏览器来源的 WS 身份验证失败 相同，local loopback 不豁免 IP，或来自回环地址的页面来源 gateway.auth.rateLimit
Webhook（/hooks）身份验证失败 60 秒内失败 20 次，锁定 60 秒 IP 否
控制平面写入 RPC 每种方法 60 秒内 30 个请求 方法 + 设备 + IP 否
ACP 会话创建 10 秒内 120 个会话 转换器实例 内部
Gateway 网关重启周期 两次重启之间冷却 30 秒 进程 否

身份验证尝试（身份验证前）

在处理任何请求之前，系统会按客户端 IP 限制失败的身份验证尝试。 这是针对暴露的 Gateway 网关的暴力破解防护机制。

  • 只有_错误的_凭据才会计数。缺少凭据（客户端从未 发送令牌）和身份验证成功不会消耗配额；身份验证成功会重置该 IP 的计数器。
  • 默认值：每 60 秒允许失败 10 次，之后该 IP 将被锁定 5 分钟。
  • 默认豁免 local loopback（127.0.0.1 / ::1），因此本地 CLI 会话 不会被锁定。
  • 计数器按凭据类别划分范围，因此针对一个表面的请求洪泛 不会挤占另一个表面的配额。范围包括共享的 Gateway 网关 令牌/密码、设备令牌、节点配对、已配对节点重新审批、 设备引导令牌以及 watchOS 质询签发。

锁定期间，连接尝试将失败并返回：

json
{  "code": "INVALID_REQUEST",  "message": "unauthorized: too many failed authentication attempts (retry later)",  "retryable": true,  "retryAfterMs": 297000,  "details": {    "code": "AUTH_RATE_LIMITED",    "authReason": "rate_limited",    "recommendedNextStep": "wait_then_retry"  }}

锁定期间，来自其他 IP（包括 local loopback）的尝试不受影响。

在 openclaw.json 的 gateway.auth.rateLimit 下调整此限制：

json
{  "gateway": {    "auth": {      "rateLimit": {        "maxAttempts": 10,        "windowMs": 60000,        "lockoutMs": 300000,        "exemptLoopback": true      }    }  }}

Gateway 网关日志中反复出现 AUTH_RATE_LIMITED 条目，意味着有人正在 猜测凭据；请参阅暴露运行手册。

浏览器来源的连接

携带浏览器 Origin 标头的 WebSocket 连接使用相同的 限制，但 local loopback 豁免始终关闭——本地浏览器中的恶意页面 仍是不受信任的客户端，因此 localhost 在该路径上不会获得豁免。 当此类连接_来自_回环地址时，其失败次数按规范化后的页面来源确定键值 （例如 browser-origin:https://evil.example），而不是按共享的回环 IP， 因此每个来源都有自己的桶；来自非回环地址时，键值仍为客户端 IP。 此行为不可配置。

Webhooks

HTTP /hooks 入口有自己的失败限制器：每个客户端 IP 每 60 秒允许 20 次身份验证失败，之后锁定 60 秒。 local loopback 不豁免。Hook 身份验证成功会重置计数器。受到限流的 请求会收到纯 HTTP 429 Too Many Requests 响应，其中包含 Retry-After 标头（秒）。限制固定；如果合法集成触发了此限制， 应修复其凭据，而不是更频繁地重试。

控制平面写入（身份验证后的后备保护）

写入侧管理 RPC（config.apply、config.patch、plugins.install、 plugins.setEnabled、plugins.uninstall、update.run、worktrees.*、 gateway.restart.request、……）在授权之后还会受到额外的速率限制： 按每个 deviceId+clientIp、每种方法计算，每 60 秒 30 个请求。

这并非安全边界——调用方已持有 operator.admin——而是一项 后备保护，用于限制失控的客户端或智能体循环反复调用高成本操作。 交互式使用永远不会触发此限制；每种方法都有自己的桶，因此切换插件 不会消耗配置写入的配额。

超过限制时，请求将失败并返回可重试错误：

json
{  "code": "UNAVAILABLE",  "message": "rate limit exceeded for config.patch; retry after 35s",  "retryable": true,  "retryAfterMs": 34539,  "details": { "method": "config.patch", "limit": "30 per 60s" }}

客户端应遵循 retryAfterMs。此限制固定（不可配置）； 桶会自行过期，并由 Gateway 网关维护任务清理。

ACP 会话创建

ACP 转换器将每个转换器实例的会话创建限制为每 10 秒最多 120 个 新会话。超过限制时，请求将失败，错误消息中会包含等待时间 （此路径上没有结构化的 retryAfterMs 字段）：

Code
超过 <method> 的 ACP 会话创建速率限制；请在 <n> 秒后重试。

这可以限制循环创建会话的失控客户端；正常的 IDE 和 智能体使用量远低于此限制。

重启冷却

Gateway 网关重启请求会先合并，然后在重启周期之间实施 30 秒的冷却。 在冷却期间发出的重启请求不会被拒绝，而是安排在冷却结束后执行。 这与上述控制平面限制器相互独立：gateway.restart.request 会消耗一个 控制平面配额槽，_并且_由此产生的重启也必须遵守冷却时间。

运维说明

  • 所有限制器均位于内存中且按进程隔离，多个 Gateway 网关不会 共享状态。替换 Gateway 网关进程会清除由 Gateway 网关拥有的 计数器（身份验证锁定、Webhook 限流和控制平面桶）。重启冷却会 特意跨进程内重启周期保留——这正是它要限制的对象——并且仅随进程 重置。ACP 会话上限属于其转换器实例，并在该实例重新创建时重置， 而不是在 Gateway 网关重启时重置。
  • 桶映射有界（硬性条目上限加定期清理），因此 唯一键洪泛不会导致内存无限增长。
  • 当客户端位于反向代理之后时，有效 IP 是解析出的 客户端 IP；请参阅受信任代理身份验证，了解 代理标头在能够影响该 IP 之前如何经过验证。
  • 不同表面的重试信号有所不同：Gateway 网关 RPC 限制器返回 retryable: true 和 retryAfterMs，Webhook 入口使用 HTTP 429 并附带 Retry-After 标头，ACP 则将等待时间嵌入错误消息。 在所有情况下，都应按指示的时长退避，而不是立即重试。
Was this useful?
On this page

On this page