OpenClaw-Gateway launchd-Start auf Mac mini: absoluter Node-Pfad, ProcessType & Exit-78-Fix (2026-05-21)

Nach einem Neustart bindet Ihr OpenClaw-Gateway-LaunchAgent auf einer gemieteten Mac mini M4 in Hongkong, Japan, Korea, Singapur oder den USA möglicherweise nie den Admin-Port, beendet sich mit Code 78 in launchctl list oder braucht etwa drei Minuten, bis WebSocket-Clients keine abnormalen Schließungen mit 1006 mehr sehen. Dieses Runbook vom 21. Mai 2026 zielt auf launchd-plist-Fehler—ein nacktes node in ProgramArguments und ein fehlendes ProcessType mit Wert Interactive—nicht auf MCP-Waisenprozess-Bäume. Es ergänzt Gateway-Neustart-Wiederherstellung, Headless-SSH-Erststart und Node-Runtime-/nvm-Abgleich.

Exit 78, langsames Listen und WebSocket 1006 nach Kaltstart

Community-Berichte auf Apple-Silicon-Hosts beschreiben zwei unterschiedliche launchd-Fehlerformen. Sofortiger Exit 78 bedeutet, launchd hat Ihre Gateway-Binary nie erfolgreich ausgeführt—oft weil ProgramArguments mit dem String node beginnt, während launchds Umgebung einen leeren oder minimalen PATH hat. Verzögerte Bereitschaft zeigt den Job als „running“ in launchctl list, aber lsof findet minutenlang keinen Listener; Dashboards loggen dann WebSocket-Schließcode 1006, bis der Prozess endlich eingeplant wird. Beides unterscheidet sich von ThrottleInterval-Absturzschleifen, die die CPU mit schnellen Respawns belasten.

• Exit-Status 78 direkt nach launchctl bootstrap oder Login—~/Library/LaunchAgents/*.plist auf nacktes node prüfen.
• 180+ Sekunden vom Boot bis zum ersten erfolgreichen Health-Check auf einer sonst idle mini.
• 1006 am Control-WebSocket, während SSH funktioniert und die Platte gesund ist—Listener noch nicht oben, keine TLS-Fehlkonfiguration.
• Manuelles node gateway.js per SSH funktioniert, der LaunchAgent-Pfad aber nicht—klassische PATH-vs.-absoluter-Binary-Trennung.

Warum launchd Ihren Shell-PATH ignoriert und Hintergrund-Agenten zurückstuft

LaunchAgents erben eine abgespeckte Umgebung gegenüber interaktiven Terminal.app-Sitzungen. Dokumentation und Feldthreads betonen, dass EnvironmentVariables in der plist den Interpreter-Namen in ProgramArguments nicht auflösen—launchd löst die ausführbare Datei auf, bevor diese Keys greifen. Deshalb scheitert eine vom Laptop kopierte plist mit node als argv[0] auf headless ProxyMac-Minis, selbst wenn Sie PATH im selben XML exportieren.

Fehlt ProcessType, kann macOS das Gateway als Hintergrundlast behandeln, die nach Neustart Energie- und Planungsheuristiken unterliegt. Operatoren berichten, die Kaltstart-Zeit bis zum Listen schrumpfe von der Größenordnung drei Minuten auf wenige Sekunden nach <key>ProcessType</key><string>Interactive</string> neben Label. Das ist Planungshygiene, kein Freibrief für unbeaufsichtigte GUI-Sitzungen—einmalige Keychain-Arbeit per VNC laut Erststart-Checkliste, danach SSH.

Operator-Matrix (Signal → erster Fix)

Primäres Signal	Erste Reaktion (Reihenfolge zählt)	Belege sichern	Rollback bei Irrtum	Verantwortlich
Letzter Exit-Code 78 am OpenClaw-Label	argv[0] durch absoluten Pfad $(command -v node) ersetzen; bootout → bootstrap	launchctl print gui/$UID/<label> + plist-XML	Vorherige plist aus Git wiederherstellen	Plattform-SRE
Job läuft, kein Listener >60 s nach Neustart	ProcessType Interactive ergänzen; ein plist-Label bestätigen	Zeitgestempeltes lsof -nP -iTCP:<port> -sTCP:LISTEN	ProcessType entfernen, wenn Desktop-Sitzungsrichtlinie es verbietet	Leitung Automatisierung
Doppelte Listener am Admin-Port	Einzel-Listener-Wiederherstellung folgen	Zwei PIDs in lsof-Ausgabe	Doppeltes Label bootout	Bereitschaft
Absturzschleife <30 s Takt, hohe CPU	ThrottleInterval / KeepAlive tunen—nicht dieser Artikel	log show --predicate 'process == "launchd"' --last 5m	Throttle-Keys zurücksetzen	SRE

Neun-Schritte-plist-Fix (SSH auf ProxyMac-mini)

1. Label identifizieren: launchctl list | grep -i openclaw und den vollen Reverse-DNS-Namen notieren.
2. Live-Zustand ausgeben: launchctl print gui/$(id -u)/<label> und letzten Exit-Code festhalten.
3. Node auflösen: im gleichen Benutzerkontext command -v node (oder which node) und absoluten Pfad notieren—typisch unter /opt/homebrew oder ~/.nvm.
4. plist bearbeiten: argv[0] in ProgramArguments auf diesen Pfad setzen; auch Gateway-Skriptpfad absolut halten.
5. ProcessType ergänzen: Interactive ins Root-dict einfügen, wenn Kaltstart-Verzögerung zu Feldmeldungen passt.
6. XML validieren: plutil -lint ~/Library/LaunchAgents/<file>.plist vor Reload.
7. Recyceln: launchctl bootout gui/$(id -u) <label>, dann bootstrap mit demselben Pfad (oder Vendor-kickstart).
8. Zeit bis Listen: lsof alle 5 Sekunden für 120 Sekunden; Ziel <15 s auf M4.
9. Dokumentieren: plist ins Infra-Repo committen; diesen Artikel im Runbook für den nächsten Kollegen verlinken.

Listener, Health-Endpoint und WebSocket-Stabilität prüfen

Nach dem Bootstrap genau eine PID auf Ihrem konfigurierten Admin-Port bestätigen (in der Operator-Dokumentation oft um 18999—an Ihre config.json anpassen). HTTP-Health-Route per curl, falls aktiv; dann Desktop-Client anbinden und innerhalb der ersten 30 Sekunden nach Neustart kein 1006. Health-Check erfolgreich, scheitern aber MCP-Tools, zu MCP-Waisen-Hygiene wechseln statt die Gateway-plist erneut zu bearbeiten.

Einmal pro Quartal Reboot-Test auf Automations-Hosts: launchd-Regressionen zeigen sich oft erst nach macOS-Sicherheitsupdates, nicht bei SSH-Änderungen am selben Tag. uname -r neben Zeit-bis-Listen im Ticketsystem loggen.

Prävention: Plists als Code und Staging-Labels

• Plists in Git mit absolutem Node-Pfad aus Ihrem Image-Build (Homebrew-Prefix oder nvm-Default).
• Getrennte LaunchAgent-Labels für Entwicklung/Staging/Produktion auf derselben mini—Neustart-Wiederherstellungs-Leitfaden bei Port-Kollisionen.
• CI-Smoke: nach Deploy per SSH-Skript Listener <20 s prüfen, bevor der Host als betriebsbereit gilt.
• Wegwerf-Lab-mini in HK/JP/KR/SG/US für plist-Experimente—günstiger als Debug am Produktions-Orchestrator.

FAQ

Warum beendet sich mein OpenClaw-LaunchAgent sofort mit Code 78? launchd löst ProgramArguments auf, bevor EnvironmentVariables angewendet werden. Ein nackter node-String schlägt fehl, wenn PATH unter launchd leer ist. Ersetzen Sie ihn durch den absoluten Pfad von command -v node, dann bootout und bootstrap der plist erneut.

Warum braucht das Gateway nach einem Neustart Minuten, bis es lauscht? Standard-LaunchAgent-plists lassen ProcessType Interactive oft weg; macOS kann den Hintergrundstart dann minutenlang zurückstufen. ProcessType Interactive im Haupt-dict senkt die Zeit bis zum Listen auf Apple-Silicon-Minis oft von etwa drei Minuten auf wenige Sekunden.

Worin unterscheidet sich das von ThrottleInterval-Absturzschleifen? ThrottleInterval-Probleme zeigen schnelle Respawn-Stürme mit hoher CPU. Exit 78 ist ein einmaliger Konfigurationsfehler, bevor das Gateway läuft. Langsames Listen ohne Absturzschleifen deutet auf ProcessType oder Ressourcenplanung hin—nicht auf KeepAlive, das gegen eine falsche Binary kämpft.

Warum gemietete Mac mini der richtige Ort für harte OpenClaw-launchd-Plists sind

Gateway-plists sind Infrastruktur: Sie müssen Neustart, OS-Updates und Ingenieure überstehen, die nur Laptop-Homebrew-Pfade kennen. Apple Silicon M4-Minis liefern vorhersagbare Kaltstart-Zeiten, macOS launchd passt zum dokumentierten OpenClaw-LaunchAgent-Flow, und Platzierung in HK / JP / KR / SG / US hält die Latenz der Steuerungsebene nah an den APIs, die Sie automatisieren. ProxyMac erlaubt, eine bekannte plist auf einer Staging-mini zu klonen, Sub-Minuten-Listen per SSH zu beweisen und dasselbe XML in Produktion zu übernehmen—Preise für die Region, Hilfe-Center für Zugangsmuster.