OpenClaw Rate Limiting: What It Protects and How to Handle a Denied Request

OpenClawBlog Team · Published June 21, 2026

Rate limiting in OpenClaw is easy to misread. A denied request may be a brute-force lockout, a webhook authentication throttle, a post-auth control-plane backstop, an ACP session cap, a restart cooldown, an upstream model-provider limit, or a separate ClawHub response. They share vocabulary, not purpose.

The short answer is simple: rate limiting protects selected boundaries from repeated attempts and runaway loops. It does not replace authentication, authorization, sandboxing, or network isolation. When a request is denied, preserve the exact error, identify the surface that produced it, wait for the supplied delay, fix the caller or configuration, and then retry in a controlled way. OpenClaw's rate-limiting reference documents these paths separately.

Start with the boundary, not the status code

The Gateway does not use one universal bucket. Its limiters have different keys, defaults, and error shapes. A failed token attempt is counted before normal request handling. A configuration write is counted after the caller is already authorized. An ACP session burst belongs to the translator instance. A restart request is coalesced and delayed rather than rejected in the same way.

That distinction changes the response. Waiting is the right first move for a temporary authentication lockout. Waiting without correcting a bad webhook credential only repeats the failure. Increasing a Gateway authentication limit cannot repair a provider quota or a ClawHub 429.

There is also a larger security boundary to keep in view. The OpenClaw HTTP API documentation says that a valid shared Gateway token or password is equivalent to an owner or operator credential for that endpoint, and recommends keeping the surface on loopback, a tailnet, or another private ingress. A rate limiter can slow guesses; it cannot make a stolen valid token narrow or harmless. See the OpenAI chat completions documentation for that distinction.

What OpenClaw's limiters protect

These behaviors are documented in the Gateway reference. The important point is that the controls protect different failure modes. Authentication throttling is the brute-force guard for an exposed Gateway. The post-auth write limiter is explicitly described as a backstop for runaway clients or agents, not as an authorization boundary. ACP limiting bounds clients that create sessions in a loop.

How to handle a denied request

1. Keep the complete error

Do not diagnose from a notification that only says rate limited. Save the status code, structured error fields, response headers, method, target origin, and approximate time. The Gateway authentication path can return an AUTH_RATE_LIMITED detail with retryable: true, retryAfterMs, and a recommendation to wait. A control-plane write can instead return UNAVAILABLE with the method name and delay. ACP may provide only a message containing the wait time.

A 403 caused by an unconfigured same-host reverse proxy is a different problem. The Gateway can reject unattributable forwarded requests with proxy_attribution_required before credentials or fallback authentication are checked. Treating every denial as a bad token can make the diagnosis worse.

2. For authentication lockouts, wait before changing anything

OpenClaw's session-attachment documentation classifies this condition as rate-limited: wait for the lockout to expire, then retry. It specifically says not to rotate credentials merely because the Gateway is rate-limited. That is a useful operational rule. Rotation may be appropriate when a secret is suspected to be exposed, but it is not the normal cure for a temporary failed-attempt bucket.

After the delay, check that the client is using the intended Gateway origin and credential source. A shell variable, service environment, Control UI session, and stored device token may not refer to the same connection. A successful authentication does not consume the failed-auth budget and normally resets the matching credential-class counter for that IP. Attempts from another resolved IP are not locked out by the first IP's bucket.

Repeated AUTH_RATE_LIMITED entries deserve investigation. They may indicate guessing, a stale deployment secret, or a client that keeps reconnecting with an old credential. Do not respond by disabling the guard or by restarting the Gateway just to clear the symptom.

3. For webhook denials, fix the sender

The /hooks limiter is separate from Gateway authentication. It counts failed webhook authentications per client IP, does not exempt loopback, and returns HTTP 429 with a Retry-After header. The documented limit is fixed, so there is no Gateway setting to raise.

The recovery path is to inspect the webhook sender's configured credential, endpoint, and proxy route. Correct the sender, wait for the indicated delay, and send one controlled retry. If a legitimate integration repeatedly trips the limiter, repeated retries are evidence of a configuration problem, not a reason to make the throttle more permissive.

4. For control-plane or ACP denials, stop the loop

A post-auth denial means the caller already has authority. The 30-per-minute control-plane limit does not decide whether config.patch, plugins.install, or gateway.restart.request is allowed. It limits how quickly an authorized client can repeat that method. The Gateway says interactive use should normally remain below the limit and that each method has its own bucket.

Look for a retry loop, duplicate event delivery, an agent repeatedly applying the same change, or a controller sharing one proxy IP with other clients. Honor retryAfterMs, stop issuing new requests during the wait, and make the caller recognize that the previous operation may already have succeeded before sending another one. The last part is an operational recommendation, not a claim that OpenClaw makes every external operation idempotent.

ACP has a different signal. Its session cap has no structured retryAfterMs field; the error text carries the wait. Parse that message only as far as needed to stop the burst and delay the next creation attempt. Restart requests have their own 30-second cooldown and are scheduled after the cooldown, so issuing more restart requests adds noise.

5. Separate Gateway limits from provider limits

If the error comes from the model provider, changing gateway.auth.rateLimit will not help. OpenClaw's models-and-auth FAQ describes provider rate limits broadly: 429 responses, concurrency limits, throttling messages, resource exhaustion, and periodic usage-window limits can all be treated as failover-worthy. Its documented recovery path is profile rotation within the provider, followed by fallback to the next configured model, with cooldowns for failing profiles.

That is a different reliability problem from an attacker guessing a Gateway token. Record which provider and profile failed, let the configured failover policy work if it is suitable for the task, and check whether the workload is exceeding a provider's quota or concurrency budget. Do not mask an upstream capacity problem by weakening local authentication controls.

6. Treat ClawHub 429s as a separate service response

ClawHub has its own API limits. Its HTTP API documentation distinguishes anonymous IP buckets from authenticated user buckets and tells clients to honor Retry-After, use jittered backoff, and cache public results. A ClawHub search or install denial therefore belongs to the registry client path, not to the Gateway's authentication limiter.

Changing the Gateway limit safely

The configurable failed-auth limiter lives under gateway.auth.rateLimit. The documented shape is:

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

Change these values only after deciding what problem you are solving. A lower threshold can reduce the time available for guessing but can also lock out a badly configured operator sooner. A longer lockout increases the cost of repeated guesses but increases the impact of a stale secret. The exemptLoopback setting is not a blanket exemption for browser-origin connections; the browser-origin path keeps the exemption off.

Do not assume that every limiter is configurable. Webhook failure limits, control-plane write limits, ACP session caps, and restart cooldowns have fixed or internal settings in the reference. The safer adjustment is usually in the caller: reduce duplicate work, correct credentials, use a stable client identity, or narrow the exposed route.

Reverse proxies deserve their own check. Configure gateway.trustedProxies narrowly, and have the proxy overwrite or rebuild forwarding headers. If the Gateway cannot safely attribute a forwarded request, it rejects the route rather than trusting a caller-supplied IP. The Gateway exposure runbook recommends an identity-aware proxy, TLS, rate limits, and strict allowlists for rare public deployments.

What rate limiting does not solve

The Gateway limiters are in memory and scoped per process. Multiple Gateway processes do not share counters, and replacing the process clears Gateway-owned authentication, webhook, and control-plane buckets. The restart cooldown is the exception described by the documentation: it survives in-process restart cycles and resets only with the process.

This means the limits are useful brakes, not a central abuse ledger. A per-IP bucket is not a global quota across many addresses. A valid bearer token is not slowed by failed-auth counting. A limiter also does not decide whether a message is malicious, whether a tool should be available, or whether users on one Gateway should be treated as mutually untrusted tenants. The exposure runbook recommends separate Gateways, users, or hosts when trust boundaries differ materially.

The practical inference is that rate limiting should sit inside a layered design. Keep the Gateway private when possible, use authentication and allowlists, limit tools for exposed agents, and keep a rollback path. A denial is useful evidence about one layer, not proof that the whole deployment is secure.

A proposed verification plan

The following is a test plan, not a report of a hands-on test. Run it in a disposable or maintenance environment with an approved test client, access to Gateway logs, and a clear record of the proxy path and source IP.

1. Confirm that an authorized connection succeeds through the intended origin and that an unauthorized connection is denied.
2. With controlled test credentials, verify that failed authentication eventually produces the documented structured rate-limit signal, then wait for the supplied delay and retry once.
3. Check that a separate resolved IP is not locked out by the first IP's failed-auth bucket. For browser-origin WebSocket clients, confirm that the page origin is treated as the relevant identity on loopback.
4. Send one deliberately invalid webhook authentication through the approved test path and confirm the 429 response and Retry-After behavior.
5. Exercise a bounded control-plane or ACP client loop and verify that it stops when the retryable error appears instead of issuing more requests.
6. Record an upstream provider rate-limit response separately from Gateway logs and confirm that the intended profile or model fallback policy is the one being exercised.
7. If you change bind, proxy, or channel exposure, run openclaw security audit --deep, repeat the authorized and unauthorized connection checks, and document any accepted residual warnings.

OpenClaw rate limiting is easiest to operate when the denial is treated as a typed event. Identify the boundary, honor its delay, correct the cause, and keep the access-control decision separate from the retry decision.

Sources

• Rate limiting - OpenClaw (accessed 2026-09-13)
• OpenAI chat completions - OpenClaw (accessed 2026-09-13)
• Session synchronization and attachment - OpenClaw (accessed 2026-09-13)
• FAQ: models and auth - OpenClaw (accessed 2026-09-13)
• HTTP API - OpenClaw (accessed 2026-09-13)
• Gateway exposure runbook - OpenClaw (accessed 2026-09-13)