2026-04-25 OpenClaw doctor, CLI-Konfiguration & Modell-Allowlist-Triage nach Upgrades auf headless gemietetem Cloud-Mac

Auf einem gemieteten Mac mini M4 in HK / JP / KR / SG / US arbeiten Sie in der Praxis zuerst per SSH; VNC nur, wenn eine GUI unvermeidbar ist. Genau diesen Modus adressiert OpenClaw: ein langlebiger Gateway-Prozess, JSON-förmige Konfiguration und ein schneller npm-Release-Takt, bei dem „in meinem git diff stand nichts“ trotzdem die Produktion bricht, weil eine Abhängigkeit Validierungsregeln verschärft, Defaults verschiebt oder eine Modell-Allowlist enger setzt. Dieses 2026-04-25-Runbook ist ein Triage-Pfad—kein Ersatz für den Egress- und DNS-Leitfaden oder die Onboarding-Schritte. Es führt zusammen: openclaw doctor (und optional --fix), die Grenze zwischen CLI-verwalteten Keys und per Hand editierten Dateien, den Nachweis, welches ~/.openclaw ein LaunchAgent tatsächlich liest, und die Vermeidung der klassischen Falle „im interaktiven ssh -t ok, unter launchd nicht“. Behalten Sie npm + doppelter Neustart in Ihrer Rollback-Story, wenn doctor veraltete native Module oder doppelte Gateways meldet.

Warum Upgrades auf Headless-Macs „Geister“-Probleme sichtbar machen

Es gibt drei Zeitgeber: Ihr Laptop (reicher PATH, zshrc, vergessenes HTTPS_PROXY), die SSH-Session im CI-Stil Ihrer Automatisierung und die launchd-Umgebung—die einzige, die für den Daemon zählen sollte. Nach npm -g oder einer getaggten OpenClaw-Version kann die Schema-Validierung plötzlich einen seit April mitgeschleppten Key ablehnen, der Gateway schreibt eine zweite PID-Datei, oder ein zuvor impliziter Tool-Call braucht eine explizite Freigabe / Capability, die nur in ausführlichen Logs auftaucht. Nutzen Sie Readiness als schnellen Filter auf den Listener 127.0.0.1:18789, nicht als Beweis, dass die gesamte Persönlichkeitskonfiguration stimmig ist—Readiness ist nötig, für „Chat überall ok“ aber nicht hinreichend.

openclaw doctor (und --fix) in den ersten 90 Sekunden

Starten Sie mit einem nicht destruktiven Durchlauf, dann mit einem fixbaren, den Sie zurückrollen können: openclaw status --all druckt Versionen, PIDs, Ports und eine kompakte Matrix; openclaw doctor prüft Schema, erkennt veraltete oder kollidierende Keys; openclaw doctor --fix, wenn die CLI offensichtlichen Ballast (z. B. altes ~/.openclaw/gateway.pid nach einem Crash) sicher entfernt. Dokumentieren Sie im internen Wiki die exakte Reihenfolge—Teams, die doctor nach kill -9 mischen, sehen anderes als Teams, die zuerst openclaw gateway stop fahren. Wenn doctor ein Plugin-Load-Problem meldet, korrelieren Sie mit WebSocket-Fehlern der 1006-Klasse; stoppen Sie nicht beim ersten „anderer Gateway hört“ ohne Prüfung auf ältere clawdbot-Prozesse.

Eine Quelle der Wahrheit: CLI-config vs. JSON auf der Platte

Bevorzugen Sie openclaw config set <key> <value> und openclaw config get <key> (Oberfläche je Version)—viele Teams erzeugen Schema-Drift, indem sie ~/.openclaw/openclaw.json manuell mit Kommafehler oder einem Key bearbeiten, den die UI einst schrieb, die CLI aber nicht mehr serialisiert. Nach jeder manuellen Änderung erneut doctor. Hot-Reload deckt viele Agent / Modell / Prompt-Felder ab, gateway.port und gateway.bind brauchen aber einen vollen openclaw gateway restart—vergleichbar mit nginx + Webhook, wenn nur eine Hälfte eines geteilten Stacks wechselt. Geheimnisse in ~/.openclaw/.env und dieselbe EnvironmentVariables-Sektion wie bei API-Keys in launchd, nicht aus einem einmaligen cat >> ~/.zshrc.

Modell-Allowlist: „nicht erlaubt“ ist oft Policy, kein Outage

Wenn ein Anbieter eine Modellzeichenkette umbenennt oder Ihre Skills anthropic/claude-3-5-sonnet-latest referenzieren, während der Gateway nur eine fixe Liste zulässt, wirkt das wie ein Credential-Problem. Prüfen Sie die effektive Allowlist: openclaw config get agents.defaults.models (oder das Äquivalent Ihrer Version) und machen Sie die Strings identisch mit dem beabsichtigten Katalog—Groß/klein, Vendor-Präfix und Slot (primär / Fallback). Kombinieren Sie mit dem Egress-Artikel: steht der Fehler hinter TLS/HTTP/2, ist es Modell-Routing; scheitert es vor dem TCP-Abschluss, sind Sie in DNS/TLS. Bei Cron oder Subagent-Lasten darf keine dünnere Allowlist in einem separaten Profil hängenbleiben. Loggen Sie das aufgelöste Modell pro geplantem Job, nicht das menschliche Label aus Slack.

Gateway, PID-Datei und „ich habe es doch schon beendet“

Zwei Lauscher entstehen, wenn ein User-LaunchAgent neu startet, während ein manuell laufender Vordergrundprozess noch den Port hält, oder ein Upgrade ein Node-Child hinterlässt, das an launchd andockt. lsof -iTCP:18789 -sTCP:LISTEN und ps -ax | grep -i openclaw im gleichen Konto wie die plist—nicht root. Bei hartem Stopp: dokumentierte Sequenz, danach doctor vor dem Neustart. Ergänzt Gateway-Upgrade/-Rollback: ein schlechtes Rollout erkennt man schneller, wenn PID, Node-Version und DEVELOPER_DIR für Sidecar-Builds im Ticket stehen.

Symptom / Schicht (Konfiguration vs. Dienst vs. Netz)

Symptom	Schicht	Stabilisieren
„Modell nicht in Allowlist“ direkt nach kleinem Bump	Konfig-Policy	Allowlist erweitern, Strings pinnen, einen Chat in Debug erneut fahren
Doctor ok, 403 am Provider trotz frischem API-Key in der Shell	launchd-Env / Egress	Env vom laufenden PID ausgeben; Egress-TLS-Checks fahren
1006 auf WebSocket nach Plugin-Add	Node-Plugin-Graph	npm install erneut, Gateway-Stderr; mit Subagent-Hinweis abgleichen

Weitere MacXCode-Runbooks

Verketten Sie die Betriebskette: ClawHub-Skills für erlaubte Automatisierung, strukturiertes Logging, damit Modell- von Routing-Fehlern zu unterscheiden ist, und Tailscale, wenn 100.64/ und öffentliche Hosts Teil des Designs sind. Im Bootstrap-Modus ist Onboard + Daemon Voraussetzung. Partner-Artikel am selben Tag: Xcode-Test + Abdeckung + Gate.

FAQ: doctor auf geteilten Buildern

Frage	Pragmatische Antwort
Soll ich vor jedem Deploy doctor laufen lassen?	Mindestens nach npm-Änderungen und Gateway-Binary-Bumps; schnell gegen ein langes Wochenende mit defekter Chat-Brücke.
Ist manuelles JSON je erlaubt?	Beim Mergen von Upstream-Beispielen—sofort doctor und Chat-Smoketest, kein blindes Restart.
Region HK hinter US—Problem?	Zeitversatz ist normal; Policy- oder Egress--Unterschiede nicht. Dashboards per Lease-Label trennen, skalieren über Preise pro Region.

Warum Bare-Metal-M4 in fünf Regionen bleibt stark

Diagnose- und Gateway-Lasten interessieren sich mehr für Jitter und reproduzierbare I/O als für Spitzen-GFLOPS. Ein Mac mini M4 bei MacXCode liefert monomandantenfähige NVMe für ausführliche JSON-Logs, dauerhaften SSH-Zugriff und die Option, bei getrennten Provider-Allowlists pro Land einen zweiten Knoten anzubinden. Wenn 2026 Ihr Jahr ist, in dem OpenClaw echte Pipelines füttert, kann dieselbe Hardwarefamilie die Xcode-Test-+-Abdeckung-Gegenseite hosten—messen Sie die Miete mit p95, statt per Reboot „grün zu würfeln“.