OpenClaw kann auf macOS zwei Gateway-Dienste gegeneinander starten lassen

Ein Gateway läuft auf einem Headless-Mac bereits als Systemdienst. Nach einem Installationslauf brechen Webchat-Verbindungen ab, Prozesse wechseln sich ab und der Host startet denselben Dienst immer wieder neu. Das Fehlerbild sieht zunächst nach Netzwerkproblemen aus. Im beschriebenen Fall beginnt es beim Service-Management.

Ein OpenClaw-Issue vom 27. Juni dokumentiert einen Konflikt zwischen einem systemweiten LaunchDaemon und einem zusätzlich angelegten GUI-LaunchAgent. Der Bericht betrifft eine konkrete ältere OpenClaw- und macOS-Umgebung. Für Headless-Macs bleibt er ein sinnvoller Prüftest, weil der Fehlpfad klar beschrieben ist.

Zwei Manager, ein Gateway

Im gemeldeten Ablauf läuft das Gateway bereits als Systemdienst unter /Library/LaunchDaemons/ai.openclaw.gateway.plist. Der Installationspfad legt zusätzlich ~/Library/LaunchAgents/ai.openclaw.gateway.plist an.

Beide Einträge verwenden dasselbe Label und denselben Port. Dadurch können zwei launchd-Manager versuchen, das gleiche Gateway am Leben zu halten. Beim Binden auf den Port räumt eine Instanz den jeweils anderen Prozess als vermeintlichen Rest weg. Die Folge sind wiederholte Neustarts und getrennte Clients.

Das erwartete Verhalten wäre ein einziger aktiver Gateway-Dienst. Beobachtet wurde ein Systemdienst plus ein zweiter GUI-Dienst, der denselben Startauftrag übernimmt.

Das Log-Symptom erkennen

Im Issue erscheint vor dem Binden auf Port 18789 die Meldung service-mode: cleared 1 stale gateway pid before bind on port 18789. Gleichzeitig werden Webchat-Clients mit code=1012 reason=service restart getrennt. Der Zähler von launchctl print system/ai.openclaw.gateway steigt weiter, weil beide KeepAlive-Manager ihren Dienst erneut starten.

Wer nur wechselnde PIDs und Verbindungsabbrüche sieht, prüft leicht Firewall oder Portbindung. Auf einem Headless-Host lohnt zuerst eine andere Frage: Gibt es für dasselbe Gateway-Label gleichzeitig einen Systemdienst und einen GUI-Dienst?

Die Statusmeldung kann in die falsche Richtung führen

Der Repro-Bericht beschreibt einen per SSH verwalteten Mac ohne GUI-Login. Das Gateway läuft bereits als Systemdienst unter launchd. Die Statusabfrage meldet in diesem Szenario dennoch LaunchAgent (not loaded) und empfiehlt eine Installation.

Diese Empfehlung passt zum GUI-Pfad, kann auf einem Headless-Host aber den zweiten Manager erzeugen. Vor jedem erneuten Installationslauf sollte daher geprüft werden, ob das Gateway schon systemweit aktiv ist, ob der erwartete Port lauscht und welcher launchd-Bereich den Prozess verwaltet.

Recovery und Gegenprüfung

Der Issue beschreibt, dass das Entfernen des doppelten GUI-Dienstes den Host wieder stabilisiert. Solche Änderungen gehören in einen kontrollierten Wartungsschritt: aktiven Dienst identifizieren, vorhandene Konfiguration sichern, genau einen Manager behalten und anschließend Client-Verbindungen sowie Neustartzähler beobachten.

Für sensible oder dauerhaft verbundene Gateways würde ich den Installationslauf nicht als Diagnosewerkzeug verwenden. Ein Blick auf Dienstlabel, Prozessbaum und Portbelegung liefert vorher mehr Sicherheit. Nach jeder Änderung sollte ein kontrollierter Neustart folgen, bevor Clients wieder dauerhaft auf das Gateway vertrauen.

Die Betriebsregel für Headless-Macs

Dieser Fall zeigt keine allgemeine Aussage über jede macOS-Installation. Er zeigt aber einen klaren Prüfpunkt nach Updates oder Reparaturversuchen: Ein Gateway darf nur einen aktiven Startmanager haben.

Wenn ein Headless-Mac einen laufenden Systemdienst meldet, während eine Oberfläche nach einer GUI-Installation verlangt, ist Gegenprüfung angesagt. Erst Dienstbereich, Port und Prozessbaum abgleichen. Für die weitere Absicherung helfen Sandboxing & Exec-Approvals und Dashboard, Monitoring und Agenten-Sichtbarkeit.