Nach einem OpenClaw-Upgrade — welche «Art von kaputt» sehen Sie? gateway startet nicht, RPC-Sonden scheitern oder die CLI meldet ein Upgrade, aber der systemd-Userdienst zeigt noch auf einen alten Pfad? Für Betrieb: sieben versteckte Annahmen zu Split-brain (alte vs. neue Binary), eine Symptomtabelle (Konfig-Stempel vs. Token/Remote-URL), ein sechsstufiges sicheres Runbook (PATH → gateway install --force → gateway restart → doctor) und wann destruktive Umgebungsvariablen Sinn ergeben. Links: Cron und Upgrade-Regression, Remote-Modus, Observability.
Die offizielle Troubleshooting-Hilfe: Schreibt eine neuere OpenClaw-Version openclaw.json und Aktualisierungen wie meta.lastTouchedVersion, bleibt aber der alte openclaw-Binary auf dem PATH, sind Lesezugriffe noch möglich — doch bei Installation/Neustart/Deinstallation des Gateways lehnt die CLI schreibende Aktionen ab, um keine halb gemischten Metadaten zu erzeugen — umgangssprachlich Split-brain in Produktion.
«npm war erfolgreich» = «der Dienst nutzt die neue Binary»: npm install -g aktualisiert nur Binaries im globalen Präfix; in launchd/systemd --user kann noch ein alter absoluter Pfad stehen — beim nächsten Neustart wieder dasselbe.
Login-Shell-PATH und PATH im Dienst-Kontext vermischen: Wenn which openclaw in der interaktiven Session stimmt, gilt das nicht automatisch für die Daemon-Umgebung.
Mehrere Installationsquellen ignorieren: Homebrew, offizielles Script und npm-global können parallel mehrere Binaries liefern; die Reihenfolge bestimmt nur der PATH-Präfix.
Nach dem Upgrade gateway install --force überspringen: Dokumentation empfiehlt Dienst-Metadaten neu zu schreiben, wenn Service und Binary drift sind; nur Gateway manuell starten hinterlässt eine Sprengfalle für den nächsten Reboot.
Jeden doctor-Fehler als korrupte Konfig deuten: Oft ist es Wächter-Binary-Mismatch — zuerst Versionen angleichen, erst dann Einzelfelder.
Zwischen Remote und lokal ohne Config-Screenshots pendeln: Wie im Remote-Modus-Artikel: zuerst openclaw config get gateway.mode, dann entscheiden, welche Host die Sonden treffen.
Nach Upgrade nur Kanäle checken, Scheduling ignorieren: Cron und Gateway teilen die Prozessfamilie — Regression lesen Sie in der Cron-Checkliste.
Die gemeinsame Wurzel: «Konfig lässt sich lesen» mit «Ausführungsseite ist konsistent» verwechseln. Richtig: der Stempel zeigt nur, wer zuletzt schrieb — das laufende Binary muss separat verifiziert werden.
Tabelle, um Einsatzzentrale von «Upgrade fühlt sich kaputt an» zu signierbaren Zweigen zu führen:
| Signal | eher Split-brain | eher Auth / Session | eher Remote-URL / Topologie |
|---|---|---|---|
| Schlüsselwörter in doctor | Hinweis auf alte/neue Binary, blockiert zerstörerische Gateway-Aktionen | Token-/Gerätecodes, unabhängig von der Binary-Version | RPC-Sonden scheitern und gateway status --deep zeigt unerwarteten Host |
| gateway status | Runtime widerspricht --version der CLI deutlich | Runtime läuft, bleibt aber unauthorized | Lokal gestoppt, entfernt tatsächlich aktiv |
| Erste Maßnahme | PATH angleichen → gateway install --force → restart | Token rotieren / Gerätehandshake angleichen | gateway.remote.url und Env mit Remote-Modus vergleichen |
Die goldene Frage in der Upgrade-Nacht: (A) Welches Binary läuft? (B) Welcher Stempel wurde zuletzt geschrieben? Erst wenn beides passt, Kanäle und cron.
Setzen Sie Tailscale / private Tunnels ein, verwechseln Sie «Tunnel steht» nicht mit «RPC gesund» — prüfen Sie beide Enden wie im Tailscale-Privatfreigabe-Artikel.
Reihenfolge-kritisch — bei alter/neu-Diskrepanz einen Schritt zurück, nicht parallel Konfig und Binaries frisieren.
Szene einfrieren: openclaw --version, sichtbarer Binary-Pfad in der Unit, doctor-Ausgabe dokumentieren.
PATH und Aliase bereinigen: In nicht-interaktiver Session muss which openclaw zur gewollten Release zeigen; Shell-Aliase entfernen.
Eine Installationsquelle wählen: Ein wartbarer Kanal (empfohlenes npm/Script) — kein Dauer-Mix «altes brew, neues npm».
Dienst-Install neu ausführen: Für denselben Nutzer nach verifiziertem PATH openclaw gateway install --force — launchd/systemd-Metadaten erneuern.
Gateway kalt starten: openclaw gateway restart, dann gateway status und RPC-Sonden.
Regression: openclaw doctor → channels status --probe → wie in cron list registriert?
openclaw --version command -v openclaw openclaw gateway status openclaw doctor openclaw gateway install --force openclaw gateway restart openclaw channels status --probe
Hinweis: Bei Portkollision, Speicher-Spikes oder Compose-Reihenfolge parallel Gateway not ready und closed(1000) RPC lesen — Ressourcenfehler nicht als Split-brain interpretieren.
Offizielles Troubleshooting: «neuere Konfig + altes Binary» ist riskant — könnte Plattenzustände unbrauchbar mischen. Neuere OpenClaw-Versionen können harte Sperren für zerstörerische Gateway-Operationen haben — OPENCLAW_*-Variablen nur setzen, wenn ein Notfall mit dem alten Binary einmalig nötig ist (Namen laut aktueller Dokumentation).
Achtung: Das ist kein «alles überspringen»-Schalter — nur die enge Klasse «Risiko akzeptiert, möglicherweise Dienst-Metadaten beschädigt». Standard: unset, außer dokumentierter Rollback-Eintrag.
Ingenieurpraxis: PATH reparieren → Dienst neu → vollständiges Upgrade mit neuer Binary — Downgrade nur als separater Change mit Audit, z. B. wenn Lieferanten alte Pakete sperren.
Interne Messpunkte für Plattform-Alignment:
openclaw --version in der interaktiven Shell und in der systemd-/launchd-Unit — nach Recovery identisch.doctor nachher.Reine Notebooks oder geteilte Dev-Maschinen leiden oft unter Schlafmodus und Multi-User-. OpenClaw auf einem dedizierten 24/7-Remote-Mac mit SSH und vertraglich fixierter Platte/Netz amortisiert sich gegen wiederholtes «Upgrade dann wieder Split». NodeMini Cloud Mac Mini liefert feste SSH und exklusive CPU — Referenz Mac-Mini-Mietpreise und Onboarding im Hilfezentrum. Filter OpenClaw : Observability → cron → Remote → dieser Upgrade-Fork.
Versionsstempel «welche OpenClaw-Generation hat die Konfig zuletzt geschrieben» — findet PATH noch ältere Binaries, blockieren Guards schreibende Dienstaktionen. PATH und Runbook, dann erst JSON-Zeilen editieren.
Solange Split-brain nicht ausgeschlossen ist, wirkt cron-Liste oft normal, die Ausführungsseite blockt — erst Abschnitt drei, dann Cron-Guide für Periodizität. Mehr im OpenClaw-Filter.
gateway.mode, gateway.remote.url und gateway status gegenüberstellen — Details Remote-Troubleshooting; Kapazitätsentscheid Mietpreise.