Gateway Lock

Cập nhật lần cuối: 11/12/2025

Tại sao cần Gateway Lock

Đảm bảo chỉ có một Gateway instance chạy trên mỗi base port của cùng một máy; các Gateway bổ sung phải dùng profile riêng biệt và port khác nhau.
Tồn tại qua các lần crash/SIGKILL mà không để lại file lock cũ.
Báo lỗi nhanh và rõ ràng khi control port đã bị chiếm dụng.

Gateway bind WebSocket listener (mặc định ws://127.0.0.1:18789) ngay khi khởi động bằng một exclusive TCP listener.
Nếu bind thất bại với lỗi EADDRINUSE, quá trình khởi động sẽ throw GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>").
Hệ điều hành tự động giải phóng listener khi process thoát (bao gồm cả crash và SIGKILL)—không cần file lock riêng hay bước cleanup nào cả.
Khi shutdown, Gateway đóng WebSocket server và HTTP server bên dưới để giải phóng port ngay lập tức.

Nếu một process khác đang giữ port, quá trình khởi động sẽ throw GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>").
Các lỗi bind khác sẽ hiển thị dưới dạng GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …").

Nếu port bị chiếm bởi một process khác, lỗi sẽ giống nhau; các bạn cần giải phóng port hoặc chọn port khác bằng lệnh openclaw gateway --port <port>.
Ứng dụng macOS vẫn duy trì cơ chế PID guard nhẹ riêng trước khi spawn Gateway; runtime lock được thực thi bởi WebSocket bind.