Gateway Lock

Warum

• Sicherstellen, dass pro Basis-Port auf demselben Host nur eine Gateway-Instanz läuft; weitere Gateways müssen isolierte Profile und eigene Ports nutzen.
• Bei Abstürzen/SIGKILL keine verwaisten Lock-Dateien hinterlassen.
• Schnell mit klarem Fehler abbrechen, wenn der Kontroll-Port bereits belegt ist.

Mechanismus

• Der Gateway bindet den WebSocket-Listener (Standard ws://127.0.0.1:18789) beim Start sofort über einen exklusiven TCP-Listener.
• Schlägt das Binden mit EADDRINUSE fehl, wirft der Start GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>").
• Das Betriebssystem gibt den Listener bei jedem Prozessende automatisch frei (inkl. Absturz und SIGKILL)—keine separate Lock-Datei oder Aufräum-Schritt nötig.
• Beim Herunterfahren schließt der Gateway den WebSocket- und den zugrundeliegenden HTTP-Server, um den Port zügig freizugeben.

Fehleroberfläche

• Hält ein anderer Prozess den Port belegt, wirft der Start GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>").
• Andere Bind-Fehler erscheinen als GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …").

Betriebshinweise

• Ist der Port von einem anderen Prozess belegt, ist die Fehlermeldung dieselbe; Port freigeben oder mit openclaw gateway --port <port> einen anderen wählen.
• Die macOS-App behält weiterhin ihre eigene leichte PID-Guard bei, bevor sie den Gateway startet; die Laufzeit-Sperre wird durch das WebSocket-Bind durchgesetzt.