Prevent OpenClaw Gateway Port Conflicts with Exclusive Locks

Gateway lock

Ever had a service fail to start because a ghost instance was still running in the background? It’s a common frustration when you’re trying to manage local tools and end up fighting with stale lock files or mysterious port conflicts.

Why

• You want to ensure only one gateway instance runs per base port on the same host, meaning extra gateways need isolated profiles and unique ports. This approach also helps you fail fast with a clear error if the control port is already occupied.
• Survive crashes or a SIGKILL without leaving stale lock files behind.

Mechanism

• 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 EADDRINUSE, startup throws GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>").
• 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.

Error surface

• 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>: …").

Operational notes

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

Related

• Multiple Gateways — running multiple instances with unique ports
• Troubleshooting — diagnosing EADDRINUSE and port conflicts

AI Setup Assistant