2026 OpenClaw MeshMac in Production: Shared Gateway Rate Limits & Session Concurrency

Why Shared Gateways Burst (and How Multi-Node Teams Stay Polite)

A shared gateway is a single listener (or a small HA pair) that every automation path hits: GitHub Actions calling a webhook, Matrix or Teams connectors posting build events, and local agents on each Mac node opening long-lived sessions. Without explicit budgets, those paths are additive: ten nodes each running two concurrent jobs can still present twenty parallel sessions to the same process, even when the queue behind the gateway is healthy. Multi-node collaboration therefore needs three agreements: a published gateway capacity model (RPS and max sessions), matching limits on CI and chat dispatchers, and identical limiter parameters on every gateway replica behind the load balancer. For load distribution and failover baselines, start from OpenClaw MeshMac load balancing and failover steps; for edge TLS and where to attach HTTP rate-limit modules, compare proxies in Nginx vs Caddy TLS proxy matrix.

Step-by-Step: Gateway Limiter Design (Reproducible)

1. Inventory routes. List every HTTP path or gRPC method the gateway exposes. Tag each as interactive, ci_ingest, or internal_worker. This becomes your route_class in logs.
2. Pick identities. Decide whether limits key off client IP, API key, OAuth subject, or a custom tenant_id header from CI. Stable identities prevent one noisy neighbor from starving others.
3. Set two numbers per class. Define (a) sustained requests per second after a burst allowance, and (b) maximum concurrent sessions or upstream connections for that class. The first is a token bucket; the second is a connection or semaphore cap.
4. Document queue interaction. If OpenClaw hands work to a central queue, ensure gateway admission control is tighter than queue depth growth: rejecting at the edge is cheaper than dequeueing poisoned work. Retry behavior belongs in task queue and retry steps.
5. Roll out with dark-run metrics. Run limiters in “observe only” mode for one release: emit counters for would-block events without returning 429. Then enable enforcement and watch p95 latency.

Token Bucket vs Connection and Session Thresholds

A token bucket smooths bursty HTTP: you refill tokens at rate r and allow a burst of size B. It protects the gateway from short spikes (for example, twenty webhooks in one second) while preserving average throughput. A connection or session cap bounds how many simultaneous TLS streams, WebSockets, or OpenClaw “sessions” may run; this matters when each session holds GPU locks, subprocesses, or large memory maps. In practice you almost always need both: token bucket for request arrivals, semaphore for concurrent expensive work.

CI Pipelines and Message Channels: Concurrency Coupling

Gateway limits are useless if CI ignores them. Set GitHub Actions concurrency groups so only one deploy workflow talks to the gateway per environment, and cap matrix parallelism so fan-out jobs do not each open a session. For chat-driven automation, throttle outbound connector retries and inbound webhook fan-in the same way you throttle HTTP clients: one Matrix room with five bots can duplicate traffic unless each bot has its own budget. Treat “messages per minute” as a second token bucket layered beside HTTP RPS. When skills or hooks are prewarmed on nodes, cap prewarm concurrency and stagger it against merged health probes so cold starts do not coincide with gateway reopen storms.

Health Checks and Automatic Shedding

Link limiters to health state so the gateway fails closed gracefully. Expose a cheap /healthz that checks disk, queue ping, and critical dependencies. When the merged probe fails—or when rolling latency exceeds an SLO—flip an internal flag: return 503 with Retry-After for new sessions, while allowing in-flight work to complete or drain with a short deadline. Optionally tighten token refill rates automatically when CPU > 80% for N seconds, and relax them when healthy for M minutes. Load balancers should use the same probe so unhealthy replicas stop receiving traffic before they melt down.

Failure Observation and Log Fields

Operators should grep one schema across nodes. Emit one JSON line per rejected or shed request with at least the following fields:

Alert on sustained 429 ratio per tenant (misconfiguration) and on 503 spikes with failing health (capacity incident). Combine with traces so you can tell “limited at edge” from “worker timeout.”

FAQ