openclaw/docs/gateway/gateway-lock.md at 8f277e4b7f4f06a4cd7825a39b3739d396fb942c

vultr/openclaw

mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 21:40:44 +00:00

Files

Peter Steinberger 24b45a038c fix(gateway): bound supervised lock recovery

2026-04-27 22:44:37 +01:00

summary, read_when, title

summary

read_when

title

Gateway singleton guard using the WebSocket listener bind

Running or debugging the gateway process

Investigating single-instance enforcement

Gateway lock

Why

Ensure only one gateway instance runs per base port on the same host; additional gateways must use isolated profiles and unique ports.
Survive crashes/SIGKILL without leaving stale lock files.
Fail fast with a clear error when the control port is already occupied.

The gateway first acquires a per-config lock file under the state lock directory and probes the configured port for an existing listener.
If the recorded lock owner is gone, the port is free, or the lock is stale, startup reclaims the lock and continues.
The gateway then binds the HTTP/WebSocket listener (default ws://127.0.0.1:18789) using an exclusive TCP listener.
If the bind fails with EADDRINUSE, startup throws GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>").
On shutdown the gateway closes the HTTP/WebSocket server and removes the lock file.

If another process holds the port, startup throws GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>").
Other bind failures surface as GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …").

If the port is occupied by another process, the error is the same; free the port or choose another with openclaw gateway --port <port>.
Under a service supervisor, a new gateway process that sees an existing healthy /healthz responder exits successfully and leaves that process in control. If the existing process never becomes healthy, retries are bounded and startup fails with a clear lock error instead of looping forever.
The macOS app still maintains its own lightweight PID guard before spawning the gateway; the runtime lock is enforced by the lock file plus HTTP/WebSocket bind.