网关锁

为何需要

• 确保同一主机上每个基础端口只运行一个网关实例；若要多开网关，须使用独立配置和不同端口。
• 进程崩溃或被 SIGKILL 时不会留下陈旧的锁文件。
• 控制端口已被占用时，立即报错并给出明确提示。

机制

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

错误表现

• 若端口被其他进程占用，启动会抛出 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>: …") 的形式报出。

运维说明

• 若端口被其他进程占用，报错相同；可释放该端口或使用 moltbot gateway --port <port> 换用其他端口。
• macOS 应用在启动网关前仍会做轻量级 PID 校验；运行时的锁由 WebSocket 绑定强制执行。