OpenClaw-Update fehlgeschlagen: Wie Codex den Gateway wiederherstellte

Ein Update kann installiert sein und den Betrieb trotzdem brechen. Nach dem Wechsel von OpenClaw 2026.7.1-2 auf 2026.8.1 startete ein verwalteter Gateway auf einem Mac mini nicht mehr zuverlässig. openclaw update endete mit ERROR, obwohl die neue Version bereits auf dem Rechner lag.

Die Recovery übernahm eine separate Codex-Session in der ChatGPT Desktop-App. Sie lief unabhängig vom ausgefallenen Gateway und erhielt nur Zugriff auf das lokale OpenClaw-Verzeichnis. Nach knapp einer Stunde funktionierten CLI und Gateway wieder mit der neuen Version, die Konfiguration validierte und die notwendigen Zustandsmigrationen waren abgeschlossen.

Die praktische Konsequenz: Wer OpenClaw produktiv betreibt, sollte vor einem Update einen zweiten, unabhängigen Werkzeugkasten bereithalten. Das kann ein lokal arbeitender Coding-Agent sein, der Dateien lesen, Befehle ausführen und kleine Änderungen kontrolliert anwenden kann. Die OpenClaw-Release-Notes bezeichnen diese Werkzeugschicht allgemein als „Coding-Harness“, ohne ein Produkt festzulegen. Codex oder Claude Code sind konkrete Beispiele für diese Gattung. Getestet wurde hier ausschließlich Codex in der ChatGPT Desktop-App, nicht die Codex CLI und nicht Claude Code.

Das Paket war aktualisiert, das System nicht

openclaw update erledigt laut OpenClaw-Dokumentation mehr als einen Paketwechsel. Der Ablauf installiert die Zielversion, führt Doctor-Prüfungen aus und startet den Gateway neu. Erst wenn die neue Binary auch mit der vorhandenen Konfiguration und dem lokalen Zustand funktioniert, ist das Update betrieblich abgeschlossen.

Im konkreten Lauf schloss nur der Paketwechsel erfolgreich ab:

✓ Updating via package manager
✗ Running doctor checks

Update Result: ERROR
Reason: openclaw doctor

Das ist kein kosmetischer Fehler. Die neue Binary traf nun auf Altzustände, die nicht vollständig mit dem Schema und den Speichern dieser Version zusammenpassten. Ein weiterer Aufruf von openclaw update konnte diese Widersprüche nicht auflösen.

Der anfängliche harte Blocker war ein alter TTS-Schlüssel, den das 8.1-Schema nicht mehr akzeptierte. Derselbe Wert steckte in der automatisch vorgehaltenen Last-known-good-Konfiguration. Ein Rückfall auf den vermeintlich guten Stand half deshalb nicht: Die Sicherung enthielt bereits den ungültigen Eintrag.

Nach dessen Korrektur erschienen nacheinander weitere Blocker. Ältere Konfigurationsfelder benötigten eine Migration, offizielle Plugins lagen noch auf dem vorherigen Versionsstand und der Session-Store musste von JSON nach SQLite wechseln. Auch die bisherige Exec-Freigabepolicy gehörte in den neuen Speicher. Erst ein Neustart nach einer behobenen Ursache machte jeweils die nächste sichtbar.

Warum Doctor nicht einfach alles reparierte

Ein Updater kann eindeutig veraltete Felder verschieben. Er sollte jedoch nicht raten, wenn die Ausgangskonfiguration ungültig ist oder ein alter Wert keine klare Entsprechung mehr hat. An dieser Grenze stoppte Doctor.

Das verlängerte die Recovery, war aber richtig. Eine frei erfundene TTS-, Routing- oder Agentenkonfiguration wäre schwerer zu erkennen gewesen als ein harter Abbruch.

Auch neue Plugin-Capabilities durften nicht still akzeptiert werden. Sobald ein Plugin nach dem Update zusätzliche Werkzeuge oder Zugriffe verlangte, blieb die Versionsangleichung stehen, bis diese Fähigkeiten einzeln geprüft und freigegeben waren.

Noch sensibler waren die Zustandsmigrationen. Der Session-Import überführte bestehende Verläufe in den neuen kanonischen SQLite-Zustand. Die Migration der Exec-Freigaben beeinflusste dagegen, welche Befehle künftig ausgeführt werden dürfen. Beides brauchte eine bewusste Bestätigung und eine überprüfbare Sicherung.

Bei der Approval-Migration kam ein Reihenfolgeproblem hinzu: Die neue Verwaltung blockierte Änderungen, solange die alte Datei noch am Legacy-Pfad lag. Dadurch erreichte der vorgesehene Doctor-Ablauf seinen eigenen Importschritt nicht sauber. Für die Recovery wurde das Original gesichert, unter einem inaktiven Namen abgelegt und anschließend über die offizielle Approval-Schnittstelle importiert.

Es gab also nicht den einen kaputten Befehl. Mehrere Schutz- und Migrationsgrenzen lagen hintereinander. Eine vollautomatische Reparatur hätte entweder zusätzliche Rechte stillschweigend akzeptieren oder aus mehrdeutigen Altwerten neue Konfiguration erzeugen müssen. Eine grüne Erfolgsmeldung wäre diesen Preis nicht wert gewesen.

Der Recovery-Agent muss außerhalb des Ausfalls laufen

Eine gewöhnliche OpenClaw-Session war hier kein verlässlicher Helfer, weil ihr eigener Gateway nicht erreichbar war. Die Codex-Session lief dagegen in der ChatGPT Desktop-App und blieb vom Ausfall unberührt.

Ihr genügte ein klar begrenzter Arbeitsbereich: .openclaw, die installierte OpenClaw-Version und die lokal verfügbaren Diagnosebefehle. Laut OpenAI-Dokumentation kann die Desktop-App Dateien und Computerwerkzeuge innerhalb eines solchen Arbeitsbereichs bereitstellen. Der gesamte Benutzerordner musste dafür nicht freigegeben werden.

Entscheidend war nicht ein spezieller Reparaturmodus, sondern die Arbeitsweise: Codex las zunächst den Befund, isolierte die kleinste plausible Ursache, legte vor einer Änderung eine Sicherung an und prüfte anschließend denselben Zustand erneut.

Als doctor --fix eine erkannte Migration nicht schrieb, untersuchte Codex die lokal installierten Migrationsregeln der neuen Version. Als der Gateway nach der Konfigurationskorrektur weiterhin ausfiel, wechselte die Diagnose zu den Plugins und danach zum Session-Store.

Kein Schritt war spektakulär. Die Reihenfolge war es.

.openclaw in einer separaten Codex-Session öffnen

Vor einem Update bleibt ein verifiziertes OpenClaw-Backup der bessere Schutz. Ist der Fehler bereits eingetreten, startest du auf dem Gateway-Rechner eine neue Codex-Session in der ChatGPT Desktop-App und gibst ihr gezielt das lokale OpenClaw-Verzeichnis als Arbeitsbereich.

Die Bezeichnung dieser Auswahl kann sich mit der App-Version ändern. Prüfe deshalb direkt in der Session, welcher Workspace geöffnet ist und welche Pfade tatsächlich beschrieben werden dürfen. Im getesteten Lauf reichte ~/.openclaw; andere Projekte und persönliche Dateien blieben außerhalb des Arbeitsbereichs.

Pauschale Vollzugriffsrechte sind dafür nicht nötig. Der folgende Auftrag setzt eine engere Grenze:

Ich habe dieser Codex-Session mein lokales OpenClaw-Verzeichnis
~/.openclaw als Arbeitsbereich freigegeben.

Mein OpenClaw-Update ist fehlgeschlagen und der Gateway ist nicht zuverlässig
erreichbar. Untersuche den Zustand schrittweise.

Beginne ausschließlich lesend: Version, Update-Status, Config-Validierung,
Gateway-Status, Plugin-Versionen und relevante redigierte Logs. Gib keine
Secrets oder vollständigen Config-Dateien aus.

Bevor du etwas änderst:
- Ursache und geplante kleinste Änderung erklären,
- betroffene Datei sichern,
- keine Dateien löschen, sondern bei Bedarf umbenennen oder archivieren,
- vor Gateway-Stopp/-Neustart, Zustandsmigrationen, Plugin-Capabilities und
  Änderungen an Exec-Freigaben meine Bestätigung abwarten.

Nach jeder Änderung denselben Check erneut ausführen. Stoppe nach drei
erfolglosen Versuchen am selben Problem und fasse den Befund zusammen.

Darunter gehört die ursprüngliche Update-Ausgabe. Kopierbarer Text ist hilfreicher als ein Screenshot, weil der Agent Fehlermeldungen und Befehle direkt untersuchen kann. Zugangsdaten, Tokens und vollständige Konfigurationsdateien gehören nicht in den Prompt.

Die Diagnose beginnt lesend:

openclaw --version
openclaw update status --json
openclaw config validate
openclaw gateway status --deep
openclaw plugins list --json
openclaw doctor --lint --json

Der Agent muss jeden Befehl und jede Option gegen die tatsächlich installierte OpenClaw-Version prüfen. Online-Dokumentation kann dem lokalen CLI voraus- oder hinterherlaufen. Erst nach einem eindeutigen Befund folgen schreibende Schritte wie doctor --fix, Plugin-Updates oder Migrationen. Für Neustarts und Änderungen an Freigaben ist weiterhin eine ausdrückliche Bestätigung nötig.

Weitere Diagnosepfade und Eingriffsgrenzen beschreibt der Guide zu OpenClaw Doctor.

Andere Coding-Agenten sind möglich, aber nicht getestet

Das Recovery-Muster ist technisch nicht an Codex gebunden. Ein anderer lokal arbeitender Coding-Agent könnte dieselbe Rolle übernehmen, wenn er unabhängig vom OpenClaw-Gateway läuft und nur kontrollierten Zugriff auf die betroffenen Dateien und Werkzeuge erhält.

Für diesen Versionswechsel gibt es jedoch nur einen belegten Praxislauf: Codex in der ChatGPT Desktop-App. Claude Code wurde weder getestet noch für diesen Fall eingerichtet. Die Übertragbarkeit ist deshalb eine technische Einschätzung, keine zweite Erfolgsgeschichte und keine konkrete Startanleitung.

Wo der Agent stoppen muss

.openclaw enthält produktiven Zustand. Dazu können Konfiguration, Sitzungsverläufe, Plugin-Daten und Verweise auf Zugangsdaten gehören. Der Recovery-Agent darf deshalb viel lesen, aber nur wenig auf einmal verändern.

Rohe Configs, Logs oder Sessiondateien gehören nicht in öffentliche Chats oder Issues. Shell-Kommandos und neue Plugin-Rechte sollten nicht pauschal freigegeben werden. Alte Zustände bleiben erhalten, bis Import und Gateway-Start nachweislich funktionieren.

Falls die neue OpenClaw-Version mit dem vorhandenen Zustand grundsätzlich nicht zurechtkommt, gilt die in der OpenClaw-Dokumentation beschriebene Rollback-Grenze: Zuerst wird bekannter Code wiederhergestellt, während der aktuelle Zustand erhalten bleibt. Ein vollständiger State-Restore folgt erst, wenn die ältere Version Konfiguration oder Datenbank nicht mehr lesen kann.

Reality Check

• Getestet mit: dem beschriebenen OpenClaw-Versionswechsel, macOS, verwaltetem lokalem Gateway und einer separaten Codex-Session
• Geeignet für: lokale Update-Fehler, bei denen Host, Dateien und OpenClaw-CLI noch erreichbar sind
• Wahrscheinliche Grenze: defekter Host, fehlender Dateizugriff, beschädigtes Backup oder ein Recovery-Agent, der selbst vom ausgefallenen Gateway abhängt
• Nicht getestet: Claude Code, Linux mit systemd, Docker oder ein entfernter Gateway
• Sicherheitsrisiko: hoch, weil produktive Konfiguration, Freigaben und Sitzungszustand betroffen sind
• Betriebsaufwand: mittel bis hoch, abhängig von Zahl und Art der Blocker
• Recovery: im beschriebenen Lauf vollständig verifiziert

Der zweite Werkzeugkasten gehört vor den Ausfall

Der Praxisfall ergänzt die Einordnung des aktuellen OpenClaw-Releases um eine Betriebsregel: Ein Agentensystem sollte nicht sein einziges eigenes Reparaturwerkzeug sein. Wer OpenClaw produktiv betreibt, hält zusätzlich einen lokalen Coding-Agenten bereit, der ohne Gateway auf den relevanten Zustand und die CLI zugreifen kann.

Codex löste den Ausfall nicht mit einem genialen Einzeiler. Es arbeitete kontrolliert weiter, während OpenClaw selbst nicht verfügbar war. Für Update-Recovery ist Ausdauer mit klaren Grenzen nützlicher als Vollautomatik.