Gateway 锁确保同一主机上每个端口只运行一个 Gateway 实例，防止崩溃后遗留过期锁文件，并在控制端口被占用时快速失败并给出清晰错误。
工作机制
- Gateway 首先获取 state lock 目录下的 per-config 锁文件，并探测配置端口是否已有监听器
- 若锁文件所有者已消失、端口空闲或锁已过期，则重新获取锁并继续启动
- Gateway 绑定 HTTP/WebSocket 监听器（默认
ws://127.0.0.1:18789），使用独占 TCP 监听器 - 若绑定失败（
EADDRINUSE），抛出GatewayLockError - 关闭时 Gateway 关闭 HTTP/WebSocket 服务器并删除锁文件
错误类型
- 端口被其他 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 gateway --port <port>指定其他端口 - 在 systemd 下，检测到已有健康
/healthz响应的 Gateway 时，新进程退出码为 78（防止Restart=always循环） - macOS app 在启动 Gateway 前维护自己的轻量级 PID 守卫
多 Gateway 场景
需要多个 Gateway 实例时，必须使用独立的 profile 和唯一端口。
相关链接
- gateway-troubleshooting — 诊断
EADDRINUSE和端口冲突 - gateway-health — 健康检查