OpenClaw doctor Diagnose-Runbook 2026: rote Checks in launchd-Fixes übersetzen, bevor Kanäle verstummen

Teams, die OpenClaw-Gateways auf gemieteten Mac mini betreiben, pendeln zwischen „CLI funktioniert in SSH“ und „Slack antwortet um 03:00 nicht mehr“. Dieses Runbook behandelt openclaw doctor als primäre Datenquelle und korreliert jede Warnzeile sofort mit launchd-Pfaden, Node-Binaries, Listener-Ports und ausgehendem DNS desselben Benutzers, der ai.openclaw.gateway besitzt. Sie erhalten Symptommatrix, acht nummerierte Checks, eine launchd-Korrelationstabelle, Nachweisfelder und FAQ für MacLogin-Regionen.

Umgebungsvariablen und LaunchAgent-Schichten in Umgebungsvariablen + launchd, Daemon-Wiederherstellung in Gateway-Fehlerbehebung, SSH-Sitzungen in Keepalive bei Abbruch, Statusverzeichnis in Backup und Übergabe. Lease-Basics in der Hilfe, Staging-Knoten unter Preisen, VNC wenn macOS-Dialoge headless blockieren.

Lokale Healthchecks, die nur Loopback sehen, lassen doctor grün während TLS an der Kante bricht. Behandeln Sie ausgehende TLS-Fehler als P1, selbst wenn doctor schweigt.

Warum doctor auf headless Cloud-Macs zuerst kommt

• Lease-Hopping: LaunchAgents zwischen Tokio und Singapur kopieren ohne doctor ⇒ veralteter Node-Pfad bis zum ersten Reboot verborgen.
• Token-Rotation: doctor kann „Konfiguration lesbar“ melden, obwohl Tokens ungültig sind.
• Audit: zeitgestempelte doctor-Ausgabe belegt Gesundheit vor Vorfällen besser als Slack-Screenshots.

Symptommatrix vor dem Log-Tail

Sichtbares Symptom	Zuerst lesender doctor-Abschnitt	Sekundärbeweis	Häufige Ursache MacLogin
launchd Exit 127	Runtime / Node	which node vs ProgramArguments	Homebrew-Präfix nach OS-Update verschoben
Edge-Webhook 502	Ports / listeners	lsof auf Loopback	Drift des localhost-Ports
LLM-Timeouts	Network / DNS	dig gleicher User	Egress-Policy auf geteiltem Lease
Tool-Ausführungen verweigert	Permissions / workspace	TCC einmal per GUI	Erststart nie außerhalb SSH abgeschlossen

Acht Schritte für Tickets

1. Shell-Parität: SSH als LaunchAgent-Besitzer; OPENCLAW_STATE_DIR nicht auf iCloud (Statusdir).
2. Capture: openclaw doctor > ~/tmp/doctor-$(date +%Y%m%d-%H%M).txt.
3. Version lock: openclaw --version + Node semver in dieselbe Datei.
4. launchctl print: launchctl print gui/$(id -u)/ai.openclaw.gateway.
5. Port cross-check: Abweichung > ±1 ⇒ alte Konfiguration.
6. Kanalprobe: synthetischer Ping auf günstigstem Kanal vor Prod.
7. Timebox: ohne Fortschritt in 25 Minuten Eskalation mit doctor + launchctl.
8. Nachfix: doctor erneut; null rote Zeilen oder dokumentierte Risikoannahme.

launchd-Korrelation

Doctor-Hinweis	launchd-Feld	Gesundes Muster
Cannot find node	ProgramArguments[0]	Absoluter Pfad wie interaktive Shell
State dir not writable	WorkingDirectory	Repo-Root 700
Port in use	keines—Prozess	Duplikat-Gateway stoppen, +1 nur im Lab

Falsche Grüntöne und rote Flaggen

Doctor kann grün bleiben, während TLS-Proxys brechen. Ausgehende TLS-Fehler bleiben P1.

• Rot: doctor grün, aber CPU > 85 % für 20 Minuten ohne Traffic ⇒ Tool-Schleife.
• Rot: freier Speicher < 12 GB auf APFS-Systemvolume ⇒ Cache-Risiko.

Auditfreundliches Paket

Artefakt	Mindestinhalt	Aufbewahrung
doctor.txt	vollständiges stdout, Hostname, Regionscode	90 Tage
launchctl print	Exitcode, Zeitstempel, uid	90 Tage
openclaw.json diff	maskierte Secrets	180 Tage

FAQ

Ersetzt doctor Integrationstests? Nein—schneller Preflight, Kanal-Smokes behalten.

CI ruft doctor auf? Ja, mindestens Staging-Leases mit non-zero bei roten Zeilen.

Führt MacLogin doctor aus? Nein—Kundenbetrieb; Artikel beschreibt Ihre Ausführung.

Warum Mac mini M4 passt

arm64 und launchd entsprechen der OpenClaw-Dokumentation; genug Leistung für doctor plus lokale Ollama-Sonde. Neural Engine hält optionalen On-Device-Check offen. Regionen näher an Nutzern reduzieren WAN-Falschnegativ.

Bei CPU-/Disk-Druck Preise erweitern, Hilfe für SSH/VNC-Muster nutzen.