Playbook 2026: OpenClaw-Gateway-LaunchAgent-Wiederherstellung auf macOS nach Updates

Das OpenClaw-macOS-Gateway soll über launchd Neustarts überleben, doch schnelle 2026.x-Kanal-Updates hinterlassen Teams mit einem stillen Fehler: das Binary aktualisiert sich, der LaunchAgent lädt nie neu, und jede Messaging-Brücke antwortet nicht mehr. Dieses Playbook ordnet Symptome Fixes zu, vergleicht Wiederherstellungsoptionen in einer Matrix und listet neun reproduzierbare Schritte, die Sie per SSH auf einem NodeMac Mac mini M4 ausführen können—ohne Pfad zu raten.

Ergänzen Sie den Leitfaden mit dem OpenClaw-Operations-Runbook zu Log-Pfaden und Upgrade-Richtlinie sowie mit Erstinstallation unter macOS, falls Sie neu aufsetzen.

Signale für LaunchAgent-Drift—nicht „KI ist down“

• Prozess fehlt, kein Crash-Dialog: ps zeigt keinen Gateway-Worker bei leerer CPU—klassisch entladener Agent.
• HTTP 401 von jedem Provider nach Reboot: Schlüssel liegen in einer dotenv, doch der Daemon erbt eine leere Umgebung, weil die Plist keine nötigen Variablen enthält.
• Manueller CLI-Start klappt, Autostart nicht: Operatoren starten das Gateway in einer Terminal-Session; nach Logout stoppt der Dienst, weil der LaunchAgent auf ein veraltetes Arbeitsverzeichnis oder einen alten Einstiegspfad zeigt.

Matrix der Wiederherstellungsoptionen

Umgebungsvariablen: wo sie für Daemons leben müssen

Interaktive Shells lesen .zshrc; LaunchAgents nicht. Liegen Provider-Schlüssel nur in einer von der Plist ignorierten Datei, startet das Gateway unauthentifiziert und loggt verwirrende 401-Stürme.

1. Erforderliche Keys auflisten (API-Tokens, optionale Proxy-URLs) in einem Runbook-Snippet für Ops nach Rotation.
2. In EnvironmentVariables der Plist spiegeln oder vendor-unterstützten Wrapper nutzen, der dotenv beim Start lädt—eine Strategie pro Maschine, nicht beides halb.
3. Reboot-Test: vierteljährlich planen; fehlende Env-Vars innerhalb von 24 Stunden nach Credential-Rotation erkennen.
4. Plist-Berechtigungen auf den Service-User beschränken; world-readable Plists leaken Geheimnisse.
5. Aktive Domain dokumentieren (gui/$(id -u) vs. Hintergrund), damit Responder nicht den falschen Job entladen.

Warum Updates Autostart brechen, obwohl das Binary stimmt

Paket-Updates können drei fragile Punkte gleichzeitig ändern: den Executable-Pfad in ProgramArguments, das Arbeitsverzeichnis für relative Configs und die erwartete Node.js-Major-Version des Gateway-Bundles. Drift an einem Punkt genügt: launchd hält den Job weiter für „konfiguriert“, obwohl er sofort endet—grüne Häkchen in einer UI, die nie wirklich lief.

Behandeln Sie jedes Upgrade als Mini-Migration: Plist-Snapshot, Checksummen für das Gateway-Einstiegsskript, vorheriges Tarball mindestens sieben Tage aufbewahren. Auf Cloud-Macs zahlen Sie für Laufzeit unabhängig davon, ob der Bot antwortet; diese Disziplin im Change-Kalender amortisiert sich beim ersten Freitag-Deploy, das Kunden-Automation strandet.

• Automatische Upgrades drosseln auf Produktions-Gateways; Canary in Staging zuerst.
• Node-Major-Versionen an Vendor-Doku ausrichten—falsche Majors zeigen sich oft als obskure Modulauflösung in der ersten Logzeile.
• Secrets-Rotation zentralisieren, damit Plist-Änderungen einmal pro Flotte statt pro Panikfall passieren.

Neun-Schritte-Runbook (SSH auf Mac mini M4)

1. Konnektivität bestätigen mit demselben SSH-User wie der LaunchAgent; Rechte-Mismatch erklärt oft „manuell ok, beim Boot nicht“.
2. launchctl print gui/$(id -u) erfassen und zu Incident-Notizen für Diffs ablegen.
3. Plist unter ~/Library/LaunchAgents/ finden; ProgramArguments-Pfade auf Existenz prüfen.
4. kickstart mit -k erzwingen; 30 Sekunden warten und Listening-Ports prüfen.
5. Bei anhaltendem Ausfall Plist sauber unload/load; auf doppelte Labels achten, alte Kopien unter /Library/LaunchDaemons prüfen.
6. Umgebungsvariablen angleichen; fehlende Keys setzen, erneut laden.
7. Gateway-Logs zwei Minuten tailen auf Crash-Loops—bei drei gleichen Stacktraces Rollback.
8. Integrations-Smoke-Test (Testnachricht über niedrigstes Risiko-Kanal) vor „grün“.
9. Interne Docs aktualisieren mit den exakten Kommandos; Flotten in HK, JP, KR, SG und US teilen eine kanonische Recovery-Seite.

Logs, Health-Checks und Eskalation

Nach dem Neustart sollten Sie nicht nur auf „Prozess läuft“ prüfen, sondern auf sinnvolle Logzeilen: erfolgreiche Provider-Handshakes, stabile WebSocket-Verbindungen und fehlende wiederholte Stacktraces. Ergänzen Sie die Gateway-Version in Monitoring-Labels für schnelle Korrelation. Richten Sie einen einfachen HTTP-Health-Check ein (wo vom Gateway unterstützt) und hängen Sie ihn an dasselbe Monitoring wie Ihre übrigen Produktionsdienste; so erkennen Sie den Unterschied zwischen „launchd meint, der Job sei ok“ und „Brücken beantworten wirklich Traffic“.

Für verteilte Teams empfiehlt es sich, zentrale Log-Aggregation (z. B. Weiterleitung per rsyslog oder Agent) nur nach Threat-Model und Datenschutzfreigabe zu aktivieren—API-Schlüssel dürfen nie ungefiltert in gemeinsame Indizes. Auf NodeMac-Maschinen bleiben Sie über SSH und optional VNC nah am Host; kombinieren Sie das mit wöchentlichen kurzen „Plist-Diffs“ nach jedem Vendor-Update, um Drift früh zu sehen, statt erst beim Kunden-Ticket.

Eskalationspfad: Erst kickstart, dann plist reload, dann CLI-Reinstall, dann Rollback—genau in dieser Reihenfolge dokumentieren, damit Nachtschicht nicht experimentiert. Wenn zwei aufeinanderfolgende Releases scheitern, frieren Sie die Produktionsversion ein und eröffnen Sie ein Vendor-Ticket mit Plist-Anhang und redigierten Logs.

Postmortem und Änderungskontrolle

Nach jedem Vorfall sollten Sie Plist-Hash, Gateway-Version und die funktionierenden launchctl-Befehle in Ihr Ticket-System schreiben. Verknüpfen Sie Änderungen mit einem Change-Request, damit Freitag-Experimente nicht ohne Genehmigung auf Produktions-Gateways landen. Auf dedizierten NodeMac-Maschinen können Sie solche Policies pro Host gruppieren und über dasselbe SSH-Zugangsmodell durchsetzen wie in der Hilfe-Dokumentation beschrieben.

Checkliste, bevor Sie den Modellanbieter beschuldigen

FAQ

Warum verschwindet OpenClaw nach einem Update aus der Menüleiste?

Der Gateway-Prozess kann beendet sein, während launchd die LaunchAgent-Plist nie neu lädt, oder die Plist zeigt noch auf einen alten Programmpfad nach Layout-Änderung des Pakets. Lösung: Plist prüfen, Agent neu laden und sicherstellen, dass Umgebungsvariablen einen Neustart überleben.

Ist kickstart auf einem Produktions-Gateway sicher?

Ja, wenn Sie wenige Sekunden Ausfallzeit akzeptieren; für Teams mit Messaging-Brücken Wartungsfenster bevorzugen. Logs in der ersten Minute nach dem Neustart mitverfolgen.

Immer erreichbare Gateways ohne Laptop-Babysitting? Vergleichen Sie NodeMac-Preise für dedizierte Mac mini M4 mit SSH/VNC in passenden Regionen und nutzen Sie dieses Playbook als Standard-Checkliste nach Updates.

Mac mini M4 hält Daemon-Recovery langweilig im besten Sinne: Apple Silicon-Headroom lässt Gateway, lokale Helfer und leichte Automation ohne Swapping koexistieren; unified memory reduziert OOM bei Log-Spitzen. NodeMac liefert dedizierte physische Maschinen—keine geteilten VMs—mit SSH und VNC in Hongkong, Japan, Korea, Singapur und den USA, damit Operatoren dieses Playbook remote ausführen, sobald ein Update landet. Miete vermeidet CapEx beim Iterieren an LaunchAgent-Policies und passt zu den Plattform-Hilfedokumenten für sauberen Zugriff über die Flotte.