2026 OpenClaw openclaw update nach Upgrade: Gateway startet nicht, Kanäle leer, Modell 401 — update status, Update restart und plugin load failed Entscheidungsmatrix

openclaw update meldet Erfolg, doch das Gateway bleibt gestoppt, die Kanalliste ist leer oder Provider liefern 401. Die offizielle Sektion After an update verlangt update status, Beobachtung von Update restart, dann gateway status --deep, doctor --fix und gateway restart. Dieser Leitfaden übersetzt die Leiter in eine auditierbare Entscheidungsmatrix für die erste Stunde — inklusive plugin load failed: dependency tree corrupted, OAuth-Shadow-Credentials und dem v2026.5.20-Fix gegen stilles Umschalten der Gateway-Node bei mehreren Node-Installationen.

1. Vier-Schichten-Triage: Post-Upgrade-Fehler sind nicht alle gleich

In produktionsnahen Umgebungen mit wöchentlichen OpenClaw-Patches verschwenden Teams Stunden mit launchd- oder systemd-Neustarts, obwohl die Ursache eine Schicht höher oder tiefer liegt. Schichten der Reihe nach bearbeiten — sonst entstehen widersprüchliche Logs und parallele Config-Edits ohne Change-Kontrolle.

1. L0 Paket und Handoff: Installer erfolgreich, aber openclaw status --all zeigt Update restart als pending oder failed. Problem liegt im Update-Handoff, nicht in der Telegram-Firewall.
2. L1 Gateway-Prozess: Runtime: stopped, Portkonflikt oder CLI-/Service-Versionsdrift. Zuerst macOS gateway restart oder Linux systemd HOME-Drift.
3. L2 Kanal-Plugins: Prozess läuft, aber channels status --probe leer oder plugin load failed. Abschnitt 6. Bei grünem Probe ohne Antwort: Kanal-Probe grün, keine Antwort.
4. L3 Modell-Credentials: Kanäle gesund, Chat liefert 401/403. doctor --fix plus Onboard-Credentials-Schichten. Alte Binary, die Service-Config nicht schreibt: Split Brain.

Für Alltags-Störungen außerhalb von Upgrade-Fenstern bleibt die offizielle Diagnoseleiter Referenz. Dieser Artikel fokussiert die sechzig Minuten unmittelbar nach openclaw update — relevant für Betriebsstabilität und nachvollziehbare Incident-Dokumentation (DSGVO-konforme Protokollierung vorausgesetzt).

Upgrade-Skripte lösen die Semver-Installation; Produktionsfähigkeit erfordert Handoff: Service-Recycle, Plugin-Registry, Credential-Shadow-Bereinigung und Node-Pfad-Alignment. Wer beides vermischt, sieht leere Kanäle und intermittierende 401 als unzusammenhängende Tickets — typisch in geteilten Entwickler-Laptops ohne dedizierten Gateway-Host.

In regulierten Umgebungen lohnt sich die Disziplin, jede Schicht mit einem einzigen Beleg-Befehl zu schließen, bevor die nächste geöffnet wird. Das reduziert nicht nur Mean Time To Recovery, sondern erleichtert auch revisionssichere Incident-Berichte: welcher semver stand zum Zeitpunkt des Fehlers, welcher Handoff-Status war rot, welche doctor-Ausgabe bestätigte Plugin-Baum-Reparatur. Teams, die diese Reihenfolge in Runbooks verankern, berichten selten über doppelte Key-Rotationen oder widersprüchliche launchd-Plists nach demselben Upgrade-Fenster.

Vergleichen Sie post-upgrade-Symptome nicht pauschal mit Split Brain. Split Brain erfordert Binary-Alignment; Handoff-Fehler erfordern oft nur den in status vorgeschlagenen Recycle. Die Abgrenzung spart Stunden, wenn beide Zustände nacheinander auftreten — zuerst Binary, dann diese Leiter.

2. Drei häufige Schmerzpunkte (nummeriert)

Schmerz eins: leere Kanäle als Netzwerkausfall. Nach dem Upgrade stehen Messenger-Einträge noch in der Config, instanziieren sich aber nicht, weil plugin load failed: dependency tree corrupted; run openclaw doctor --fix vor Channel-Konstruktoren fehlschlug. nginx- oder Tailscale-Anpassungen reparieren keinen korrupten Plugin-Abhängigkeitsbaum.

Schmerz zwei: Config-Edit bei pending Update restart. Unvollständiger Handoff führt zu übersprungenem Hot Reload, Invalid config oder Service-Unit mit halb geschriebenem State. Erst den in status --all vorgeschlagenen Befehl ausführen.

Schmerz drei: alle API-Keys rotieren beim ersten 401. Re-OAuth am Shared Profile invalidiert nicht automatisch veraltete per-agent OAuth auth shadows. Einzelne Agents lesen weiter alte Kopien. doctor --fix ist gezielter als pauschale Key-Rotation — und reduziert Risiko für Staging- und CI-Klone mit gleichen Profilen.

Zusätzlich: zweites openclaw update bei rotem Handoff stapelt partielle Installationen. Paralleländerungen einfrieren — keine nginx-Edits, keine Plugin-Reinstalls, keine Credential-Experimente — bis die Leiter in Abschnitt 4 grün ist.

Ein vierter, weniger dokumentierter Schmerz: Ops mischt Beta-Kanal mit Produktion, weil Release Notes ein Feature versprechen, das stable noch nicht trägt. Nach dem Upgrade erscheinen leere Kanäle oder stille Respawns — kein Netzwerkbug, sondern Kanal-Drift. Pin stable, dokumentieren Sie Rollback-semver, und testen Sie Beta auf isoliertem Remote-Mac-Klon, nicht auf dem produktiven launchd-Job.

Dokumentieren Sie für jedes Upgrade-Fenster drei Screenshots: Update restart-Zeile, Auszug aus update status --json, Gateway-Version aus gateway status --deep. Diese Triade reicht in neun von zehn Postmortems, um L0 von L2 zu trennen, ohne vollständige Log-Archive an externe Auditoren weiterzugeben.

3. Symptom → erste Evidenz Entscheidungsmatrix (zitierfähig)

Die aktive Tabellenzeile ins Ticket übernehmen, bevor parallele Responder divergieren. Die Matrix bevorzugt einen Beweis-Befehl gegen spekulative Deinstallationen, die Rollback-Artefakte löschen.

4. Offizielle Befehlsleiter nach Update (How-to, Ziel 15 Minuten)

1. Paralleländerungen stoppen: während des Upgrade-Fensters kein nginx, keine Telegram-Token-Rotation, keine optionalen Plugin-Reinstalls.
2. Vollstatus: openclaw status --all; Zeile Update restart für das Change-Record screenshoten.
3. Update-JSON: openclaw update status --json; pending/failed, Kanal stable/beta und Folgebefehl speichern.
4. Tiefen-Gateway: openclaw gateway status --deep; Runtime, Config (cli) vs. Config (service), Port, Gateway-Version.
5. Automatische Reparatur: openclaw doctor --fix für Plugin-Bäume, OAuth-Shadows, veraltete Service-Ports.
6. Kontrollierter Neustart: openclaw gateway restart; bei Fehler openclaw gateway install --force, erneut restart.
7. Kanal-Abnahme: openclaw channels status --probe bis works / audit ok.

openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart
openclaw channels status --probe

Für Live-Beobachtung zweites Terminal: openclaw logs --follow. Tokens vor Ticket-Upload redigieren — siehe Produktions-Protokoll-Redaktion.

Start- und Endzeit je Schritt dokumentieren. Dedizierte 24/7-Hosts clearen Handoff oft unter fünf Minuten; schlafende Laptops überschreiten zwanzig Minuten und erzeugen falsche Split-Brain-Diagnosen — ein häufiger Grund für instabile SLA in kleinen Teams ohne dedizierten Server.

Wenn gateway install --force nötig wird, notieren Sie den Grund im Change-Ticket: fehlender bootout, falscher Node-Pfad oder abgelehnte Config durch meta.lastTouchedVersion. Diese Metadaten verhindern, dass das nächste Upgrade-Team dieselbe Force-Install blind wiederholt und dabei gültige Rollback-Pfade überschreibt.

channels status --probe sollte erst nach stabilem Runtime laufen. Probe auf gestopptem Gateway erzeugt grüne Scheinbeweise in Dashboards, die nur HTTP-Erreichbarkeit prüfen, nicht Plugin-Registrierung. Kombinieren Sie probe mit einem kurzen Test-DM oder Tool-Aufruf auf dem erwarteten Agent.

5. Update restart pending und fehlgeschlagener Handoff

Update restart steht in openclaw status und status --all. Pending bedeutet: der Handoff hat den überwachten Gateway-Prozess noch nicht recycled. Failed enthält den nächsten empfohlenen Befehl — oft fehlender gateway restart, Service-Unit mit altem Node-Pfad oder unvollständiges launchd-bootout.

Bei Handoff-Fehler nicht sofort erneut openclaw update. update status --json für Kanal, Ziel-Tag und Blocker lesen. Produktion sollte stable pinnen und Rollback-Semver im Ticket führen. Beta um v2026.5.19-beta meldete stille Respawn-Schleifen; stable plus dokumentierter Rollback schlägt Nightly-Jagd.

Zeigt gateway status --deep WebSocket-Health länger als zehn Sekunden stabil, Kanäle bleiben aber leer, Session-Dateigröße prüfen — v2026.4.26 chat.history kann Neustarts imitieren.

Unter Linux journalctl-Zeitstempel mit update status --json korrelieren. Typisch: Upgrade unter Admin-User, systemd startet Gateway unter Service-Account mit HOME-Drift — leere Merge-Config nach unit-Rewrite.

Auf macOS prüfen Sie nach failed handoff, ob ein Benutzer-Upgrade (npm global) und ein root-gebundener launchd-Job unterschiedliche Prefixe lesen. gateway status --deep zeigt Config(cli) und Config(service) nebeneinander — jede Abweichung ist ein handoff-Blocker, kein Messenger-Problem.

Halten Sie für Produktion ein Rollback-Skript bereit, das den vorherigen stable-Tag installiert und unmittelbar status --all ausführt. Ziel: unter zehn Minuten von Entscheidung bis cleared oder bewusstem Rollback — messbar in Ihrem Change-Prozess.

6. plugin load failed: dependency tree corrupted

Config-Einträge existieren, Plugin-Registrierung scheitert vor Channel-Instanziierung. Unterstützter Fix: openclaw doctor --fix, nicht blind node_modules löschen.

Minimal-Repro: nicht kritische plugins.entries auskommentieren, einen Messenger plus Kern-Provider behalten, restart, probe. Plugins einzeln reaktivieren — isoliertes Paket vs. globaler Modulbaum-Drift.

Startup-Load-Fehler von MCP-Laufzeit-Leaks unterscheiden. Dependency-Tree-Fehler in den ersten Sekunden; Speicheranstieg nach Stunden → andere Runbooks. Bleibt es rot nach doctor: Gateway-Version und Node-Absolutpfad aus gateway status --deep — Multi-Node-Drift trotz v2026.5.20.

Speichern Sie doctor-Ausgabe und Plugin-Liste vor und nach --fix. Auditoren und zukünftige Sie selbst brauchen den Nachweis, dass der Baum repariert wurde, nicht manuell gelöscht. Blindes Löschen von extensions-Verzeichnissen ohne doctor erhöht das Risiko, dass credentials-Profile und plugin-metadata auseinanderlaufen.

7. Provider 401 und OAuth-Shadows nach Upgrade

Teilmenge der Agents mit 401, Primary ok → OAuth-Shadows. Re-Auth am Shared Profile invalidiert nicht garantiert per-agent Shadows. doctor --fix entfernt veraltete Kopien.

Alle Modelle 401: ~/.openclaw/credentials/ leer? systemd EnvironmentFile oder launchd-Env injiziert Secrets vor Start? Upgrade-Rewrites von Service-Units legen Reihenfolge-Bugs offen, die interaktiv zufällig funktionierten.

Cloudflare AI Gateway + Anthropic (2026.5.6–5.7): Regression bei Dual-Auth-Headern. Nach Upgrade Header-Weiterleitung prüfen statt pauschaler Key-Rotation.

Credentials-Schichten mit Onboard-Leitfaden abgleichen: Umgebungsvariablen, Dateiprofile, Provider-Switching — nach Service-Recycle kann Probe grün sein, Chat aber andere Route nutzen.

Testen Sie nach doctor --fix einen einzelnen failing Agent mit minimalem Prompt, nicht sofort den produktiven Gruppenchat. So trennen Sie Shadow-401 von Rate-Limit-429 oder Provider-Outage. Dokumentieren Sie Provider-Name, Agent-ID und Timestamp — Pflichtfelder für wiederholbare Postmortems in Enterprise-Setups.

8. Multi-Node und v2026.5.20

v2026.5.20 behebt stilles Umschalten der Gateway-Node bei mehreren Node-Installationen durch openclaw update. Betrieb sollte Node-Pfade dennoch explizit führen:

• Absoluter Node-Pfad in launchd ProgramArguments oder systemd ExecStart.
• Vor/nach Upgrade: which openclaw, openclaw --version, Gateway-Version in gateway status --deep.
• Bei CLI/Service-Drift: gateway install --force, dann restart.

Homebrew-Node-Upgrades auf macOS und nvm-Default-Wechsel auf Linux bleiben Top-Trigger für CLI-neu, Daemon-alt — auch nach dem v2026.5.20-Guardrail. Erwartete Digests im Runbook dokumentieren.

9. Metriken für Postmortems und Compliance

• Handoff-Dauer: Minuten bis Update restart cleared (Ziel < 5 auf dediziertem Host).
• Probe-Zeit: Sekunden bis channels probe grün (Ziel < 120).
• Rollback-Fenster: vorheriges stable-Tag mindestens 72 Stunden vorhalten.
• Config-Churn: nicht-generierte Diff-Zeilen pro Fenster (Ziel < 50).
• 401-Recovery: Minuten bis erfolgreicher Chat nach doctor --fix bei Shadow-Ursache (Ziel < 10).

Fünf Zahlen ins Change-Ticket-Template. Steigt Handoff-Dauer quartalsweise, Schlafrichtlinien auf Laptops prüfen und Produktion auf always-on Remote-Mac verlagern — messbar stabilere Betriebsführung für regulierte Umgebungen.

10. FAQ

F: update status überspringen und sofort restart? Nicht empfohlen. Restart bei unvollständigem Handoff looped oft; status zeigt den kürzeren Pfad.

F: Ändert doctor --fix openclaw.json? Kann Prefix, Ports, Plugin-Bäume reparieren. Snapshot vor Major-Releases. Ungültiges landet in .rejected.*.

F: Verhältnis zu Split Brain? Split Brain: alte Binary schreibt neue Config nicht. Dieser Artikel: neue Binary, Handoff/Plugins/Credentials noch nicht aligned. Kette möglich: erst Split Brain, dann diese Leiter.

11. Fazit: Update installiert Semver — Handoff stellt Produktion wieder her

openclaw update advance Semver. Verfügbarkeit hängt an abgeschlossenem Update-restart-Handoff, intakten Plugin-Bäumen, korrekt gebundener Node im Service und OAuth-Shadows am aktuellen Shared Profile. Schlafende Laptops, hibernierendes WSL, unterdimensionierte VPS und geteilte Workstations erhöhen Handoff-Fehler — leere Kanäle und intermittierende 401, während Teams Messenger-Token debuggen.

Gateway auf always-on macOS-Remote-Node mit expliziten Node-Pfaden in launchd plus SFTP/rsync-Snapshots von ~/.openclaw macht die 15-Minuten-Leiter wiederholbar und auditierbar. SFTPMAC Remote-Mac-Miete richtet sich an OpenClaw- und CI/CD-Teams mit Apple-Silicon-Hosts, die Upgrade-Fenster durchhalten — verknüpft mit Diagnoseleiter, Split Brain, Gateway-Restart und Protokoll-Redaktion. Ein dedizierter gemieteter Mac schlägt Co-Hosting auf Maschinen, die schlafen, Node casual upgraden oder keine Snapshot-Disziplin haben — besonders wenn Betriebsstabilität und nachvollziehbare Changes für Compliance zählen.