Unter macOS wird das OpenClaw-Gateway häufig von launchd überwacht. Betreiber—und gelegentlich Agenten—versuchen, das Gateway „einfach neu zu starten“ aus derselben Session, die davon abhängt. Das kann den LaunchAgent entladen, während der auslösende RPC noch hängt—passend zu realen Meldungen, dass Gateways erst nach Login mit separater Shell zurückkehren. Dieses Runbook erklärt warum, liefert eine Entscheidungstabelle für sichere vs. riskante Aktionen, sechs narrative Schritte passend zum JSON-LD-HowTo mit sieben Schritten, und verlinkt Recovery sowie Parallelität.
Vor Änderungen lesen Sie LaunchAgent-Gateway-Recovery und interaktiver Chat vs. lange Workspace-Jobs, damit Neustarts nicht mit schweren Tasks kollidieren. Erstinstallation: Installation und Deployment. Kontofragen: Hilfe; Gateway und CI auf zwei NodeMac-Hosts splitten: Preise. Token-Auth und Plist-Drift: Konfigurationsdrift.
Fehlermodus: Selbst-Enthauptung unter launchd
Das Gateway ist sowohl Server als auch Abhängigkeit des laufenden Befehls. Sendet ein Agent openclaw gateway restart über denselben RPC-Kanal, den der Gateway-Prozess besitzt, kann launchd den Job bootout, bevor ein sauberer Handoff fertig ist. Die CLI-Session endet mit Transportfehler, und kein verbleibender Supervisor garantiert einen gesunden bootstrap—besonders headless ohne Displaybeobachtung.
- Symptom A:
gateway statusflippt in derselben Sekunde von laufend zu fehlend, in der der Agent den Neustart auslöste. - Symptom B: Logs zeigen launchd-unload-Zeilen direkt neben RPC-Disconnect-Fehlern.
- Symptom C: Externe Health-Checks (HTTP oder TCP) laufen mehrere Minuten ins Leere, während keine Benutzersession gestartet wurde—typisch für reines SSH.
Matrix: wer das Gateway neu starten darf
| Akteur | Typischer Kontext | Urteil | Sicherere Alternative |
|---|---|---|---|
| Mensch via zweitem SSH | Screen oder ssh user@host | Bevorzugt | Dokumentierte bootout/bootstrap-Sequenz; Logs sichern |
| Automationsagent in OpenClaw | Tool-Call während Chat | Neustart vermeiden | Ticket erzeugen; externer Orchestrator nach Mutex |
| Geplanter LaunchAgent | Nächtliche Drift-Reparatur | Erlaubt bei isoliertem Plist | Von Chat-Peaks versetzen; siehe Scheduled-Task-Ausrichtung |
| CI-Job auf demselben Mac | Pipeline-Schritt „Gateway bounce“ | Abgeraten | Dedizierte Admin-Job-Warteschlange mit separaten Credentials |
Zweite Matrix: Pre-Restart-Checkliste
| Check | Pass-Kriterium |
|---|---|
| Listener-Besitz | Genau ein PID zur konfigurierten Gateway-Portfamilie; PID für Rollback-Notizen notieren |
| Plattenplatz für Logs | Mindestens 8 GB frei auf dem Volume mit State und Logs, damit der Neustart nicht mitten im Schreiben scheitert |
| Mutex mit Langjobs | Kein Workspace-Job hält die Compile-Mutex-Stufe, die Sie für Gateway-Wartung definiert haben |
| Auth-Token-Kontinuität | Clients können Token von der Platte neu laden ohne interaktives GUI-Prompt |
Betriebszahlen für jedes Incident-Log
- Cold-Start-Budget: bis zu 90 Sekunden nach bootstrap, bevor Sie Failure deklarieren—länger bei Antivirus- oder Full-Disk-Access-Prompts.
- RPC-Sondenintervall: alle 5 Sekunden in der ersten Minute, danach exponentieller Backoff.
- Parallele Admin-Aktionen: maximal eine gateway-verändernde Operation pro Host.
Headless-Tipp: Bei Verdacht auf GUI-Berechtigungen kurz VNC anbinden, einmal durchklicken, dann wieder nur SSH.
Sechs On-Host-Schritte (narrative Erweiterung des 7-Schritte-HowTo)
- Keine Befehle mehr über das kranke Gateway. Zweite SSH zum selben Mac mini M4; diese Session darf nicht vom zu recyclenden RPC abhängen.
- Beweise sammeln: Status, Logs, vermuteter Plist-Pfad—abgleichen mit Config-Drift.
- Listener prüfen mit
lsof, damit Sie bei geteiltem Lab nicht den falschen PIDbootouten. - Entladen mit passender launchd-Semantik, dann bootstrap von der Platte, damit EnvironmentVariables und WorkingDirectory greifen.
- Gesundheit sondieren bis RPC aus der externen Shell grün ist; erst dann Chat-Clients reconnecten.
- Einzeiler-Incident-Notiz mit Zeitstempel, Grund, Chat/CI-Impact—Korrelation mit Rate-Limits 429 wird trivial.
FAQ
Kann ich Neustarts mit Ansible automatisieren?
Ja, wenn das Playbook immer eine Steuerungsverbindung nutzt, die nicht durch den Gateway-Prozess läuft, den Sie neu starten. Gateway wie Datenbank behandeln: vom Orchestration-Layer bouncen, nicht vom Client-Query.
Mehrere Gateways für Dev und Prod?
Getrennte Plists, Ports und State-Verzeichnisse. Dokumentieren Sie, welches LaunchAgent-Label zu welcher Umgebung gehört, damit bootout nie das falsche Label trifft.
Wann Hosts komplett trennen?
Wenn Chat-SLO und CI-Präemption trotz Mutex-Stufen kämpfen—zweiten dedizierten Mac mini M4 von NodeMac hinzufügen statt inkompatible Lebenszyklen auf einem launchd-Graphen zu stapeln.
Zuverlässiger OpenClaw-Betrieb profitiert von derselben Hardware-Geschichte wie Ihre Builds: ein dedizierter Mac mini M4 liefert Apple Silicon-Leistung mit nativem macOS, SSH für headless Wartung und VNC bei GUI-Berechtigungsdialogen, plus Standortwahl zwischen Hongkong, Japan, Korea, Singapur und den USA, damit Operatoren näher an den Maschinen sitzen, die sie um 03:00 wecken. Mieten statt kaufen macht einen zweiten „nur Gateway“-Host wirtschaftlich, sobald dieses Runbook zeigt, dass experimentelle und Produktions-Chat-Agenten nie denselben launchd-Graphen teilen sollten. Pläne nach Region vergleichen, bevor Sie weiteres Risiko auf einen einzelnen Plist stapeln.