hansjone/oclaw
1
0
Fork 0
mirror of https://github.com/hansjone/oclaw.git synced 2026-10-09 22:40:45 +08:00
Code Issues Projects Releases Packages Wiki Activity Actions
oclaw/openclaw/docs/gateway/gateway-lock.md
oliver dbbe3add6a 重构主控编排与运行时预热链路，统一工作区提示词/专家调度协议并补齐 wiki 记忆注入与写回闭环。 
同时收敛启动与运维脚本默认行为（含 wiki worker）、更新 Admin 可观测性与相关测试，降低首轮时延并提高运行稳定性。

Made-with: Cursor
2026-04-26 08:34:33 +08:00

1.8 KiB
Raw Blame History

summary read_when title
Gateway singleton guard using the WebSocket listener bind
Running or debugging the gateway process
Investigating single-instance enforcement
Gateway Lock

Gateway lock

Why

  • Ensure only one gateway instance runs per base port on the same host; additional gateways must use isolated profiles and unique ports.
  • Survive crashes/SIGKILL without leaving stale lock files.
  • Fail fast with a clear error when the control port is already occupied.

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