> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 速率限制

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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "gateway": {
    "auth": {
      "rateLimit": {
        "maxAttempts": 10,
        "windowMs": 60000,
        "lockoutMs": 300000,
        "exemptLoopback": true
      }
    }
  }
}
```

Gateway 网关日志中反复出现 `AUTH_RATE_LIMITED` 条目，意味着有人正在
猜测凭据；请参阅[暴露运行手册](/zh-CN/gateway/security/exposure-runbook)。

### 浏览器来源的连接

携带浏览器 `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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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；请参阅[受信任代理身份验证](/zh-CN/gateway/trusted-proxy-auth)，了解
  代理标头在能够影响该 IP 之前如何经过验证。
* 不同表面的重试信号有所不同：Gateway 网关 RPC 限制器返回
  `retryable: true` 和 `retryAfterMs`，Webhook 入口使用 HTTP 429
  并附带 `Retry-After` 标头，ACP 则将等待时间嵌入错误消息。
  在所有情况下，都应按指示的时长退避，而不是立即重试。