Rate limiting

Rate limiting 문서는 OpenClaw 공식 문서(gateway/security/rate-limiting)를 한국어로 정리한 가이드입니다. Reference for every Gateway rate limit: pre-auth lockouts, browser and webhook throttles, the control-plane write backstop, ACP session caps, and restart cooldown 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Reference for every Gateway rate limit: pre-auth lockouts, browser and webhook throttles, the control-plane write backstop, ACP session caps, and restart cooldown

한국어 가이드 범위: gateway/security/rate-limiting 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Authentication attempts (pre-auth)
Browser-origin connections
Webhooks
Control-plane writes (post-auth backstop)
ACP session creation
Restart cooldown
Operational notes

상세 내용

본문

The Gateway enforces several independent rate limits. They protect different boundaries, key on different identities, and fail with different error shapes. This page is the reference for all of them.

Surface	Limit (default)	Keyed by	Configurable
Failed auth (token/password/device)	10 failures / 60s, 5 min lockout	IP + credential scope	`gateway.auth.rateLimit`
Browser-origin WS auth failures	same, loopback not exempt	IP, or page origin from loopback	`gateway.auth.rateLimit`
Webhook (`/hooks`) auth failures	20 failures / 60s, 60s lockout	IP	no
Control-plane write RPCs	30 requests / 60s per method	method + device + IP	no
ACP session creation	120 sessions / 10s	translator instance	internal
Gateway restart cycles	30s cooldown between restarts	process	no

Authentication attempts (pre-auth)

Failed authentication attempts are throttled per client IP, before any request handling. This is the brute-force guard for exposed Gateways.

주요 항목:

Only wrong credentials count. Missing credentials (a client that never
Defaults: 10 failures per 60 seconds, then a 5 minute lockout for that IP.
Loopback (127.0.0.1 / ::1) is exempt by default so local CLI sessions
Counters are scoped per credential class, so a flood against one surface

{
  "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"
  }
}

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

Browser-origin connections

WebSocket connections that carry a browser Origin header use the same limits but with the loopback exemption always off — a malicious page in a local browser is still an untrusted client, so localhost gets no free pass on that path. When such a connection arrives from a loopback address, its failures are keyed by the normalized page origin (for example browser-origin:https://evil.example) rather than the shared loopback IP, so each origin gets its own bucket; from non-loopback addresses the key stays the client IP. This is not configurable.

Webhooks

The HTTP /hooks ingress has its own failure limiter: 20 failed authentications per 60 seconds per client IP, then a 60 second lockout. Loopback is not exempt. Successful hook auth resets the counter. Throttled requests receive plain HTTP 429 Too Many Requests with a Retry-After header (seconds). Limits are fixed; if a legitimate integration trips this, fix its credentials rather than retrying harder.

Control-plane writes (post-auth backstop)

Write-side admin RPCs (config.apply, config.patch, plugins.install, plugins.setEnabled, plugins.uninstall, update.run, worktrees.*, gateway.restart.request, ...) are additionally rate-limited after authorization: 30 requests per 60 seconds, per method, per deviceId+clientIp.

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

ACP session creation

The ACP translator caps session creation at 120 new sessions per 10 second window per translator instance. Exceeding it fails the request with an error whose message carries the wait time (there is no structured retryAfterMs field on this path):

ACP session creation rate limit exceeded for <method>; retry after <n>s.

Restart cooldown

Gateway restart requests coalesce, then enforce a 30 second cooldown between restart cycles. A restart requested during the cooldown is scheduled after it expires rather than rejected. This is separate from the control-plane limiter above: gateway.restart.request consumes a control-plane budget slot and the resulting restart obeys the cooldown.

Operational notes

share state. Replacing the Gateway process clears the Gateway-owned counters (auth lockouts, webhook throttle, control-plane buckets). The restart cooldown deliberately survives in-process restart cycles — that is what it throttles — and resets only with the process. The ACP session cap belongs to its translator instance and resets when that instance is recreated, not on Gateway restart.

주요 항목:

All limiters are in-memory and per-process, and multiple Gateways do not
Bucket maps are bounded (hard entry caps plus periodic pruning), so
When a client is behind a reverse proxy, the effective IP is the resolved
Retry signaling varies by surface: Gateway RPC limiters return

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/security/rate-limiting
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

{
  "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"
  }
}

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

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

ACP session creation rate limit exceeded for <method>; retry after <n>s.

Rate limiting

핵심 요약

Reference for every Gateway rate limit: pre-auth lockouts, browser and webhook throttles, the control-plane write backstop, ACP session caps, and restart cooldown

한국어 가이드 범위: gateway/security/rate-limiting 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Authentication attempts (pre-auth)
Browser-origin connections
Webhooks
Control-plane writes (post-auth backstop)
ACP session creation
Restart cooldown
Operational notes

상세 내용

본문

The Gateway enforces several independent rate limits. They protect different boundaries, key on different identities, and fail with different error shapes. This page is the reference for all of them.

Surface	Limit (default)	Keyed by	Configurable
Failed auth (token/password/device)	10 failures / 60s, 5 min lockout	IP + credential scope	`gateway.auth.rateLimit`
Browser-origin WS auth failures	same, loopback not exempt	IP, or page origin from loopback	`gateway.auth.rateLimit`
Webhook (`/hooks`) auth failures	20 failures / 60s, 60s lockout	IP	no
Control-plane write RPCs	30 requests / 60s per method	method + device + IP	no
ACP session creation	120 sessions / 10s	translator instance	internal
Gateway restart cycles	30s cooldown between restarts	process	no

Authentication attempts (pre-auth)

Failed authentication attempts are throttled per client IP, before any request handling. This is the brute-force guard for exposed Gateways.

주요 항목:

Only wrong credentials count. Missing credentials (a client that never
Defaults: 10 failures per 60 seconds, then a 5 minute lockout for that IP.
Loopback (127.0.0.1 / ::1) is exempt by default so local CLI sessions
Counters are scoped per credential class, so a flood against one surface

{
  "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"
  }
}

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

Browser-origin connections

Webhooks

Control-plane writes (post-auth backstop)

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

ACP session creation

ACP session creation rate limit exceeded for <method>; retry after <n>s.

Restart cooldown

Operational notes

주요 항목:

All limiters are in-memory and per-process, and multiple Gateways do not
Bucket maps are bounded (hard entry caps plus periodic pruning), so
When a client is behind a reverse proxy, the effective IP is the resolved
Retry signaling varies by surface: Gateway RPC limiters return

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/security/rate-limiting
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

{
  "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"
  }
}

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

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

ACP session creation rate limit exceeded for <method>; retry after <n>s.

Rate limiting

핵심 요약

문서 구성

상세 내용

본문

Authentication attempts (pre-auth)

Browser-origin connections

Webhooks

Control-plane writes (post-auth backstop)

ACP session creation

Restart cooldown

Operational notes

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Rate limiting

핵심 요약

문서 구성

상세 내용

본문

Authentication attempts (pre-auth)

Browser-origin connections

Webhooks

Control-plane writes (post-auth backstop)

ACP session creation

Restart cooldown

Operational notes

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드