Kein Terminal-Crash mehr: OpenClaw doctor bei inaktivem Gateway, Modell-Auth und Sechs-Schritte-Rettungs-Runbook auf dem Mac (2026)

Sie doppelklicken eine Verknüpfung — oder tippen openclaw in Terminal — und das Fenster verschwindet. Kein Stack Trace, kein freundlicher Dialog, nur Stille. Slack zeigt weiterhin „gateway not active“, Modellauswahl dreht sich endlos, und Berechtigungs-Pop-ups, die Sie gestern weggeklickt haben, kommen als roter Text zurück. Das ist nicht „Sie können nicht mit Computern umgehen“; es ist Environment Drift: falscher Node, falscher User, falsche Config-Datei, oder ein Gateway-Prozess, der launchd nie überlebt hat.

openclaw doctor ist OpenClaws offizieller Selbstdiagnose-Befehl. Er druckt eine strukturierte Checkliste — CLI im PATH, Config-Lesbarkeit, Gateway-Erreichbarkeit, Auth-Profile, Festplatten-Headroom — damit Sie Zeile für Zeile fixen statt aus einem Blog neu zu installieren. Dieses Tutorial ist die Anfänger-Rettungsspur: was doctor prüft, wie man gelbe vs rote Zeilen liest, ein Sechs-Schritte-Runbook fürs Ticket, und zwei Troubleshooting-Rezepte für die Fehler, die Anfänger wirklich sehen. Für SLA-taugliche Abnahme nach Onboarding auf einem gemieteten Mac lesen Sie die separate Post-Onboard-Doctor-Matrix; dieser Artikel ist „es ist heute wieder abgestürzt.“

Beim ersten Erwähnen kombinieren mit dem OpenClaw Hour-Zero-Installationsvertrag (Node-22+-Floor), Rate Limits und Budget-Alerts (damit Retries nicht wie Crashes wirken), und OpenClaw + Ollama, wenn lokale Modelle Cloud-Keys ersetzen. Upstream-Installationsreferenz: OpenClaw-Installationsskript und Gateway-Konfigurationsbeispiele. Hardware-Kontext: Apple Mac mini Spezifikationen.

Offenlegung: KvmZone wird nur erwähnt, wo ein gemieteter Mac Anfängern eine saubere SSH-Shell für openclaw doctor bietet. Die meisten Schritte funktionieren auf jedem Mac, den Sie bereits besitzen.

Warum doctor besser ist als Neuinstallation von Grund auf

Auf dem chinesischen Festland kann langsame oder gefilterte Ausgehend-Verbindung zu npm-Spiegeln wie „OpenClaw ist kaputt“ wirken, wenn die echte Ursache Registry-Timeout ist — doctors Netzwerk-/TLS-Zeilen sind Ihr erster Beweis. Optionale gemietete Mac-Hosts in Hongkong oder Singapur sind für doctor selbst nicht erforderlich.

Architektur: was openclaw doctor prüft

Terminal / launchd → openclaw CLI → doctor module → reads ~/.openclaw/* → probes gateway HTTP → prints PASS/WARN/FAIL lines

Dateien und Rollen

Doctor ersetzt nicht Lasttests oder Webhook-POP-Planung — das ist die Post-Onboard-Matrix. Er sagt Ihnen, ob Sie den Modellanbieter schon beschuldigen dürfen.

Entscheidungsmatrix: Crash-Typ → erster Befehl

Empfohlener Pfad: Wenn die Shell blitzschließt, doctor zuerst interaktiv — nie über GUI-Shortcut debuggen. Wenn doctor grün ist, aber der Menüleisten-Agent noch inactive sagt, launchd-User und Port fixen, nicht den LLM-API-Key.

Sechs-Schritte openclaw doctor Rettungs-Runbook

Schritt 1 — Echte Shell öffnen (kein Doppelklick-Alias)

# macOS: use Terminal.app or iTerm — note the user name
whoami
echo $SHELL

Ausgabe speichern; Shortcuts ohne Login-Shells verbergen PATH-Fixes.

Schritt 2 — Node 22+ und CLI im PATH bestätigen

node -v
which openclaw
openclaw --version

Pass: node meldet v22 oder neuer; which openclaw liefert einen einzigen Pfad unter /opt/homebrew oder Ihrem dokumentierten globalen Prefix.

Schritt 3 — doctor ausführen und Transcript speichern

openclaw doctor 2>&1 | tee ~/openclaw-doctor-$(date +%Y%m%d).log

Diese Datei an jedes Support-Ticket anhängen. Nach jedem Fix erneut — keine Vermutungen stapeln.

Schritt 4 — Erstes FAIL fixen (meist PATH oder Config-JSON)

# Example: validate JSON before restart
python3 -m json.tool < ~/.openclaw/openclaw.json > /dev/null && echo "JSON OK"

Wenn JSON scheitert, aus Backup wiederherstellen:

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d)

Schritt 5 — Daemon-User angleichen (gateway inactive Fix)

# See which user launchd uses (label varies by install)
launchctl print system/com.openclaw.gateway 2>/dev/null | head -20
# Run doctor as that user if different from Step 1
sudo -u _openclaw openclaw doctor 2>&1 | tee ~/openclaw-doctor-daemon.log

Pass: interaktive und Daemon-Transcripts stimmen überein, oder jede Abweichung ist dokumentiert.

Schritt 6 — Gateway neu starten und Status prüfen

openclaw gateway restart   # or launchctl kickstart per your install doc
sleep 5
openclaw status
openclaw doctor

Pass: status zeigt lauschenden Port; doctor hat keine unerklärten FAIL-Zeilen. Dann — und erst dann — Agent oder Shortcut erneut versuchen.

Für SSH-only gemietete Hosts den Remote-Mac-SSH-Workflow statt Pixel-Tools nutzen, außer eine dokumentierte GUI-Gate verlangt es.

Troubleshooting

Fehlermuster: zsh: command not found: openclaw (oder sofortiges Fenster-Schließen)

Symptome: Skript oder .app-Wrapper beendet vor jeder UI; doctor läuft nie.

Fix:

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile
npm install -g openclaw@latest
openclaw doctor

Dasselbe PATH in der launchd-plist EnvironmentVariables angleichen (siehe Hour-Zero-Vertrag).

Fehlermuster: gateway not active / ECONNREFUSED 127.0.0.1

Symptome: CLI existiert; UI oder openclaw status erreicht lokales Gateway nicht.

Fix:

lsof -iTCP -sTCP:LISTEN | grep -i openclaw
openclaw doctor
openclaw gateway restart

Wenn Port einem anderen User gehört, Waisen-Prozess stoppen oder gateway.port in ~/.openclaw/openclaw.json ändern, dann doctor erneut. Rate Limits konfigurieren, nachdem Gateway stabil läuft — Retry-Stürme fühlen sich wie Crashes an.

FAQ

Weiterführende Artikel

• OpenClaw Hour-Zero-Installationsvertrag — Node-22+-Disziplin
• Post-Onboard doctor + Webhook POP — Callback-Ingress
• OpenClaw Rate Limits und Budget-Alerts — Retry-Stürme vs Crashes
• OpenClaw + Ollama auf gemietetem M4 — lokale Modelle ohne Cloud-Keys
• Remote-Mac-SSH-Sicherheits-Workflow — SSH-only-Betrieb