Gateway 单实例锁

为什么需要锁机制

• 确保同一主机的同一端口上只运行一个 Gateway 实例；如需多实例，必须使用独立的 profile 和不同的端口。
• 进程崩溃或被 SIGKILL 后无需手动清理，不留下"僵尸锁文件"。
• 端口已被占用时立即报错，不静默失败。

实现原理

• Gateway 启动时立即以独占 TCP 监听器绑定 WebSocket 端口（默认 ws://127.0.0.1:18789）。
• 若绑定失败并返回 EADDRINUSE，启动流程抛出 GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")。
• OS 会在进程退出时自动释放该监听器——包括崩溃和 SIGKILL——因此无需额外的锁文件或清理步骤。
• 关闭时，Gateway 会主动关闭 WebSocket 服务器和底层 HTTP 服务器，及时释放端口。

小贴士：养龙虾讲究独门独院——每只龙虾（Gateway 实例）必须占用独立的端口，不能抢地盘。

错误说明

• 若其他进程占用了该端口，启动时抛出：GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")
• 其他绑定失败情况报：GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")

运维注意事项

• 若端口被其他非 OpenClaw 进程占用，报错内容相同；请释放该端口或使用 openclaw gateway --port <port> 指定新端口。
• macOS 应用在启动 Gateway 子进程前还维护了一套轻量 PID 守卫；运行时锁由 WebSocket 绑定机制负责执行。