速率限制

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 质询签发。

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

{
  "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 下调整此限制：

{
  "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——而是一项后备保护，用于限制失控的客户端或智能体循环反复调用高成本操作。交互式使用永远不会触发此限制；每种方法都有自己的桶，因此切换插件不会消耗配置写入的配额。超过限制时，请求将失败并返回可重试错误：

{
  "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 字段）：

超过 <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 则将等待时间嵌入错误消息。在所有情况下，都应按指示的时长退避，而不是立即重试。

网关

远程访问

安全

Nodes and media

Web 界面

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

浏览器来源的连接

Webhooks

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

ACP 会话创建

重启冷却

运维说明

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

​浏览器来源的连接

​Webhooks

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

​ACP 会话创建

​重启冷却

​运维说明

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

浏览器来源的连接

Webhooks

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

ACP 会话创建

重启冷却

运维说明