Gateway Lock

Zuletzt aktualisiert: 11.12.2025

Warum

Es soll nur eine Gateway-Instanz pro Basis-Port auf demselben Host laufen. Weitere Gateways müssen isolierte Profile und eigene Ports verwenden.
Bei Abstürzen oder SIGKILL bleiben keine verwaisten Lock-Dateien zurück.
Bei bereits belegtem Control-Port gibt es sofort eine klare Fehlermeldung.

Das Gateway bindet den WebSocket-Listener (Standard: ws://127.0.0.1:18789) direkt beim Start mit einem exklusiven TCP-Listener.
Schlägt die Bindung mit EADDRINUSE fehl, wirft der Start einen GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>").
Das Betriebssystem gibt den Listener automatisch frei, wenn der Prozess beendet wird — auch bei Abstürzen und SIGKILL. Eine separate Lock-Datei oder Aufräumschritte sind nicht nötig.
Beim Herunterfahren schließt das Gateway den WebSocket-Server und den darunterliegenden HTTP-Server, um den Port schnell freizugeben.

Wenn ein anderer Prozess den Port belegt, wirft der Start einen GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>").
Andere Bindungsfehler erscheinen als GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …").

Wenn der Port von einem anderen Prozess belegt ist, erscheint dieselbe Fehlermeldung. Gib den Port frei oder wähle einen anderen mit openclaw gateway --port <port>.
Die macOS-App verwendet zusätzlich einen eigenen leichtgewichtigen PID-Guard, bevor sie das Gateway startet. Die eigentliche Laufzeitsperre wird durch die WebSocket-Bindung durchgesetzt.