OpenClaw Gateway-Sperre: Port-Konflikte sicher vermeiden

Kennst du das? Du willst dein Gateway starten, aber es passiert einfach nichts oder du bekommst kryptische Fehlermeldungen, weil im Hintergrund noch eine alte Instanz feststeckt. Besonders nach einem harten Crash sind verwaiste Lock-Files oft ein echtes Hindernis, das den Workflow unterbricht.

Wir setzen hier auf eine Lösung, die direkt das Betriebssystem nutzt, um diese Probleme zu lösen. So stellen wir sicher, dass dein System sauber bleibt, ohne dass du dich um manuelles Cleanup kümmern musst.

Warum

• Sicherstellen, dass nur eine Gateway-Instanz pro Base-Port auf demselben Host läuft; zusätzliche Gateways müssen isolierte Profile und eindeutige Ports nutzen.
• Crashes oder SIGKILL ohne veraltete Lock-Files überstehen.
• Schneller Abbruch mit klarer Fehlermeldung, wenn der Control-Port bereits belegt ist.
• Vermeidung von inkonsistenten Zuständen bei Mehrfachstarts durch automatische OS-Bereinigung.

Mechanismus

• Das Gateway bindet den WebSocket-Listener (Standard ws://127.0.0.1:18789) sofort beim Start über einen exklusiven TCP-Listener.
• Falls das Binden mit EADDRINUSE fehlschlägt, bricht der Start ab und wirft GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>").
• Das OS gibt den Listener automatisch bei jedem Prozess-Exit frei, auch bei Crashes oder SIGKILL – es ist kein separates Lock-File oder ein Cleanup-Schritt nötig.
• Beim Shutdown schließt das Gateway den WebSocket-Server und den zugrunde liegenden HTTP-Server, um den Port unverzüglich freizugeben.

Fehlerquellen

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

Betriebshinweise

• Falls der Port durch einen anderen Prozess belegt ist, bleibt die Fehlermeldung gleich; du musst den Port entweder freigeben oder einen anderen wählen mit openclaw gateway --port <port>.
• Die macOS-App nutzt weiterhin einen eigenen leichtgewichtigen PID-Guard, bevor sie das Gateway startet; der Runtime-Lock wird jedoch durch das WebSocket-Binding erzwungen.

Verwandte Themen

• Multiple Gateways — Mehrere Instanzen mit eindeutigen Ports betreiben.
• Troubleshooting — Diagnose von EADDRINUSE und Port-Konflikten.

Nächste Schritte

Du hast noch Fragen zur Konfiguration oder brauchst Hilfe beim Setup? Unser AI Setup Assistant hilft dir gerne weiter.