Gateway Lock

Last updated: 2025-12-11

• 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 binds the WebSocket listener (default ws://127.0.0.1:18789) immediately on startup using an exclusive TCP listener.
• If the bind fails with <code>EADDRINUSE</code>, startup throws <code>GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")</code>.
• The OS releases the listener automatically on any process exit, including crashes and SIGKILL—no separate lock file or cleanup step is needed.
• On shutdown the gateway closes the WebSocket server and underlying HTTP server to free the port promptly.

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

• If the port is occupied by another process, the error is the same; free the port or choose another with <code>openclaw gateway --port <port>'</code>.
• The macOS app still maintains its own lightweight PID guard before spawning the gateway; the runtime lock is enforced by the WebSocket bind.