Gateway 鎖定機制

最後更新：2025-12-11

為什麼需要

• 確保同一台主機上每個基底埠只有一個 gateway 實例在運行；額外的 gateway 必須使用獨立的 profile 和專屬埠。
• 即使程序崩潰或被 SIGKILL 強制終止，也不會留下過期的鎖定檔。
• 當控制埠已被佔用時立即失敗，並給出清楚的錯誤訊息。

機制

• Gateway 在啟動時會立即透過獨佔式 TCP 監聽器繫結 WebSocket 監聽器（預設 ws://127.0.0.1:18789）。
• 如果繫結因 EADDRINUSE 失敗，啟動時會拋出 GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")。
• 作業系統會在程序結束時自動釋放監聽器（包括崩潰和 SIGKILL），不需要另外的鎖定檔或清理步驟。
• 關閉時，gateway 會關閉 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>: …")。

操作注意事項

• 如果埠被_其他_程序佔用，錯誤訊息是一樣的；釋放該埠或用 openclaw gateway --port <port> 選擇其他埠。
• macOS 程式在啟動 gateway 前仍會維護自己的輕量 PID 守護機制；執行期鎖定則是由 WebSocket 繫結來強制執行。