Gateway 鎖定

# 原因

• 確保同一主機上的每個基準連接埠只執行一個 Gateway 執行個體；額外的 Gateway 必須使用隔離的設定檔與唯一連接埠。
• 在當機/SIGKILL 後仍能恢復，且不留下過時的鎖定檔。
• 當控制連接埠已被佔用時，快速失敗並顯示清楚的錯誤。

# 機制

• Gateway 會先在狀態鎖定目錄下取得每個設定專屬的鎖定檔，並探測已設定連接埠是否已有既有監聽器。
• 如果記錄的鎖定擁有者已不存在、連接埠可用，或鎖定已過時，啟動程序會收回鎖定並繼續。
• 接著 Gateway 會使用獨占 TCP 監聽器綁定 HTTP/WebSocket 監聽器（預設 ws://127.0.0.1:18789）。
• 如果綁定因 EADDRINUSE 失敗，啟動程序會拋出 GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")。
• 關閉時，Gateway 會關閉 HTTP/WebSocket 伺服器並移除鎖定檔。

# 錯誤介面

• 如果另一個程序持有該連接埠，啟動程序會拋出 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> 選擇另一個連接埠。
• 在服務監督程式下，若新的 Gateway 程序看到現有健康的 /healthz 回應者，會讓該程序維持控制權。在 systemd 上，重複啟動者會以代碼 78 結束，因此預設的 RestartPreventExitStatus=78 會阻止 Restart=always 因鎖定或 EADDRINUSE 衝突而不斷迴圈。如果現有程序始終無法變為健康狀態，重試次數會受限，且啟動會以清楚的鎖定錯誤失敗，而不是永遠迴圈。
• macOS App 在產生 Gateway 前仍會維護自己的輕量 PID 防護；執行階段鎖定則由鎖定檔加上 HTTP/WebSocket 綁定強制執行。

# 相關

• 多個 Gateway — 使用唯一連接埠執行多個執行個體
• 疑難排解 — 診斷 EADDRINUSE 與連接埠衝突