Gateway 锁

最后更新：2025-12-11

为什么需要

• 确保同一主机上、同一 base port 只运行一个 gateway 实例；额外的 gateway 必须使用隔离的 profile 与唯一端口。
• 在崩溃/SIGKILL 后仍能正常恢复，不会遗留陈旧的 lock 文件。
• 当 control 端口已被占用时，快速失败并给出清晰错误。

机制

• gateway 在启动时立即绑定 WebSocket 监听端口（默认 ws://127.0.0.1:18789），使用独占的 TCP listener。
• 如果绑定失败并返回 EADDRINUSE，启动会抛出 GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")。
• 操作系统会在任何进程退出（包括崩溃与 SIGKILL）时自动释放该 listener——不需要单独的 lock 文件或清理步骤。
• 在关闭时，gateway 会关闭 WebSocket server 以及底层 HTTP server，以便尽快释放端口。

错误呈现

• 如果端口被另一个进程占用，启动会抛出 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 gateway --port <port> 选择另一个端口。
• macOS app 在启动 gateway 前仍会维护一个轻量级的 PID guard；但运行时的锁由 WebSocket bind 强制保证。