OpenClaw sicher updaten: Backup, Verify und Recovery ohne Blindflug

Wer OpenClaw dauerhaft betreibt, braucht vor einem Update einen nachvollziehbaren Ausgangspunkt: ein geprüftes Backup, den aktuellen Versionsstand und einen Rollback-Pfad. Sonst bemerkst du womöglich nach dem Versionswechsel, dass wichtige Workspace-Dateien nicht im Archiv liegen oder eine ältere OpenClaw-Version den bereits migrierten State nicht mehr lesen kann.

Dieses Tutorial gilt für lokale Installationen, die OpenClaw über npm, pnpm, Bun oder einen Git-Checkout betreiben. Für Docker, Podman und Kubernetes beschreibt die OpenClaw-Dokumentation einen separaten Image-Upgrade-Pfad. Plane außerdem ein Wartungsfenster ein: openclaw update führt openclaw doctor aus und startet den Gateway nach einem erfolgreichen Update standardmäßig neu.

1. Ausgangslage und Backup-Ziel festhalten

Lege zu Beginn ein nur für deinen Benutzer zugängliches Backup-Verzeichnis an und notiere die aktuell installierte Version:

mkdir -p ~/Backups/openclaw
chmod 700 ~/Backups/openclaw
openclaw --version

Die Versionsnummer brauchst du für die Wahl des Update-Pfads und für einen möglichen Rollback. Prüfe zusätzlich, ob auf dem Zielvolume genug Platz für das Archiv und seine anschließende Verifikation vorhanden ist. OpenClaw warnt vor knappem Speicher, kann Quotas und entfernte Volumes aber nicht zuverlässig vorhersagen.

Versionsweiche festlegen

Stammt die angezeigte OpenClaw-Version aus Juni 2026 oder früher, darfst du nicht direkt auf latest, einen aktuellen Kanal oder eine andere aktuelle Zielversion wechseln. Laut der offiziellen Anleitung zum Aktualisieren sehr alter OpenClaw-Versionen benötigen Installationen von vor Juli 2026 zwingend OpenClaw 2026.9.5 als Migrationsbrücke.

Notiere für diesen Fall folgenden zweistufigen Pfad:

1. Backup erstellen und verifizieren.
2. Auf 2026.9.5 aktualisieren.
3. Die Doctor-Migrationen vollständig ausführen und die Runtime prüfen.
4. Nur nach erfolgreichen Prüfungen das gewünschte aktuelle Ziel installieren.

Versionen aus Juli 2026 oder später benötigen diese Brücke nicht. Die verbindliche Prüfung und die zugehörigen Befehle folgen unmittelbar vor dem eigentlichen Update in Schritt 5.

Backups können Auth-Profile, Channel- und Provider-Credentials, Sessions sowie Workspace-Inhalte enthalten. Bewahre sie deshalb nicht in einem öffentlichen Git-Repository oder ungeschützt in einem gemeinsam genutzten Sync-Ordner auf. Wie du Zugangsdaten außerhalb des Klartexts referenzierst und rotierst, erklärt der Praxisartikel zu OpenClaw SecretRef.

2. Backup-Plan prüfen

Lass dir anzeigen, welche Quellen OpenClaw einplanen würde:

openclaw backup create --output ~/Backups/openclaw --dry-run --json

Der Dry-Run schreibt kein Archiv. Die JSON-Ausgabe sollte unter anderem die aufgelösten Quellen und ausgelassene Pfade erkennen lassen. Kontrolliere besonders, ob die erwarteten Workspaces auftauchen.

Ein normales Archiv berücksichtigt:

• das OpenClaw-State-Verzeichnis, üblicherweise ~/.openclaw
• die aktive JSON-Konfigurationsdatei
• das aufgelöste credentials/-Verzeichnis, wenn es außerhalb des State-Verzeichnisses liegt
• die aus der Konfiguration ermittelten Workspaces

Liegt eine Quelle bereits innerhalb des State-Verzeichnisses, wird sie nicht doppelt als eigene Archivquelle aufgenommen. Fehlende Pfade überspringt OpenClaw.

Ist die Konfigurationsdatei vorhanden, aber ungültig, kann OpenClaw die Workspaces nicht zuverlässig ermitteln. Der Backup-Lauf bricht dann ab, solange die Workspace-Sicherung aktiviert ist. Hilfe beim Aufbau und bei der Prüfung der Datei bietet die Anleitung zur Gateway-Konfiguration mit openclaw.json.

Zwei dokumentierte Teil-Backups bleiben möglich:

openclaw backup create --output ~/Backups/openclaw --no-include-workspace --verify
openclaw backup create --output ~/Backups/openclaw --only-config --verify

--no-include-workspace lässt State, Konfiguration und ein externes Credentials-Verzeichnis im Sicherungsumfang. --only-config archiviert ausschließlich die aktive Konfigurationsdatei und funktioniert auch bei einer fehlerhaften Konfiguration.

3. Archiv erstellen und verifizieren

Wenn der Plan stimmt, erstellst du das Backup mit unmittelbarer Prüfung:

openclaw backup create --output ~/Backups/openclaw --verify

Der Befehl schreibt ein zeitgestempeltes .tar.gz-Archiv und prüft es anschließend. Ein vorhandenes Archiv wird nicht überschrieben. Ziele innerhalb der zu sichernden State- oder Workspace-Bäume weist OpenClaw zurück, damit sich das Archiv nicht selbst einschließt.

Falls du ein vorhandenes Archiv später erneut prüfen willst:

openclaw backup verify ~/Backups/openclaw/<dein-archiv>.tar.gz

Verify kontrolliert unter anderem das Root-Manifest, unzulässige Traversal-Pfade, die im Manifest referenzierten Payloads und kanonische OpenClaw-SQLite-Datenbanken. Ein erfolgreicher Lauf bestätigt die Struktur und Integrität des Archivs. Er sagt nicht aus, dass nach einer späteren Aktivierung sofort jeder Channel und jedes Plugin betriebsbereit ist.

Was das portable Archiv bewusst auslässt

Während der Archivierung schließt OpenClaw bekannte, laufend veränderte Dateien aus. Dazu gehören passende .jsonl- und .log-Dateien unter Session-, Cron-Run- und Log-Verzeichnissen, Dateien aus Delivery-Queues sowie Socket-, PID- und Temp-Dateien. Die JSON-Ausgabe meldet diese Auslassungen über skippedVolatileCount.

Auch installerverwaltete oder wiederaufbaubare Runtime-Verzeichnisse wie dev/, git/, npm/, tmp/ und tools/ werden unter dem State-Verzeichnis normalerweise nicht archiviert. Lokale Änderungen in einem verwalteten dev/-Checkout musst du deshalb separat committen, pushen oder kopieren.

Bei Plugins enthält das Archiv Quell- und Manifestdateien unter extensions/, aber keine verschachtelten node_modules/-Verzeichnisse. Meldet ein wiederhergestelltes Plugin fehlende Abhängigkeiten, nutze den dokumentierten Reparaturpfad:

openclaw plugins update <id>

Alternativ kannst du das Plugin mit seiner bekannten Paketspezifikation neu installieren:

openclaw plugins install <spec> --force

Benötigst du einen bytegenauen Wiederherstellungspunkt einschließlich volatiler Dateien, stoppe den Gateway und erstelle zusätzlich einen Snapshot des Dateisystems, Volumes oder der VM. Das portable OpenClaw-Archiv ist dafür nicht gedacht.

4. Update-Ziel trocken prüfen

Prüfe vor dem Wechsel den gespeicherten Kanal und die verfügbaren Versionen:

openclaw update status --json
openclaw update --dry-run

Der Dry-Run zeigt die geplanten Aktionen, ohne das Update anzuwenden. Bei einer Installation aus Juni 2026 oder früher darf dieser allgemeine Dry-Run nicht als Freigabe für den direkten Sprung auf das aktuelle Ziel dienen. Prüfe stattdessen zunächst die in der offiziellen Update-Dokumentation vorgeschriebene Brückenversion 2026.9.5:

openclaw update --tag 2026.9.5 --dry-run

Für einen dauerhaften Kanalwechsel stehen folgende Varianten bereit:

openclaw update --channel beta
openclaw update --channel extended-stable
openclaw update --channel dev

--channel beta bevorzugt das Beta-Tag, fällt aber auf stable beziehungsweise latest zurück, wenn keine neuere Beta-Version verfügbar ist. Wenn du einmalig exakt das rohe npm-Beta-Tag ansteuern willst, verwendest du stattdessen:

openclaw update --tag beta

--channel dev richtet einen dauerhaften, beweglichen GitHub-main-Checkout ein. Bei einer Paketinstallation bildet der einmalige Aufruf --tag main den Paketstand aus github:openclaw/openclaw#main ab:

openclaw update --tag main

Das ist ein Entwicklungsstand und kein normaler Produktionskanal. openclaw update besitzt kein --verbose-Flag; für Diagnosen sind --dry-run, --json und openclaw update status --json vorgesehen.

5. Update ausführen und Runtime prüfen

Prüfe unmittelbar vor dem Update erneut die installierte Version:

openclaw --version

Pfad für Versionen vor Juli 2026

Zeigt der Befehl eine Version aus Juni 2026 oder früher, installierst du entsprechend der offiziellen Update-Anleitung für sehr alte Versionen zuerst die Brückenversion 2026.9.5:

openclaw update --tag 2026.9.5

Führe danach die Migrationen der Brückenversion vollständig aus:

openclaw doctor --fix

Brich den Ablauf ab, wenn der Update- oder Doctor-Lauf fehlschlägt. Installiere das aktuelle Ziel erst, wenn openclaw --version die dokumentierte Brückenversion 2026.9.5 meldet und die folgenden Runtime-Prüfungen ohne ungeklärte Fehler abgeschlossen sind:

openclaw --version
openclaw health
openclaw plugins list --json
openclaw gateway status --deep --json
openclaw doctor --lint --json

Die Brücke gilt als erfolgreich durchlaufen, wenn die CLI die dokumentierte Version 2026.9.5 meldet, der Gateway erreichbar und gesund ist, Doctor keine noch ausstehende Migration oder blockierende Reparatur ausweist und benötigte Plugins weder fehlen noch inkompatibel sind. Behebe gemeldete Migrations- oder Runtime-Probleme auf der dokumentierten Brückenversion; überspringe diese Prüfung nicht.

Erst danach installierst du das zuvor gewählte aktuelle Ziel. Für den gespeicherten Kanal verwendest du:

openclaw update

Für eine ausdrücklich gewählte Version oder ein Tag verwendest du stattdessen:

openclaw update --tag <zielversion-oder-tag>

Pfad für Versionen ab Juli 2026

Stammt die Ausgangsversion aus Juli 2026 oder später, kannst du nach geprüftem Backup und plausiblem Dry-Run direkt zum gewählten Ziel wechseln:

openclaw update

OpenClaw erkennt npm-, pnpm-, Bun- und Git-Installationen, führt den passenden Update-Pfad aus, startet openclaw doctor und startet den Gateway anschließend neu.

Prüfe nach dem Zielupdate erneut CLI-Version, Gateway und Plugins:

openclaw --version
openclaw health
openclaw plugins list --json
openclaw gateway status --deep --json
openclaw doctor --lint --json

Die neue Versionsnummer sollte dem geplanten Ziel entsprechen. openclaw health und der tiefe Gateway-Status dürfen keine ungeklärten Laufzeitfehler melden. Prüfe außerdem die Plugin-Liste auf deaktivierte, inkompatible oder fehlende Erweiterungen.

6. Zuerst den Code zurückrollen

Wenn die neue Version fehlschlägt, ist ein Code-Rollback meist der kleinere Eingriff. Dabei bleibt der aktuelle State vorerst erhalten.

Für Paketinstallationen listest du verfügbare Versionen, prüfst den bekannten guten Stand trocken und installierst ihn anschließend über den OpenClaw-Updater:

npm view openclaw versions --json
openclaw update --tag <known-good-version> --dry-run
openclaw update --tag <known-good-version>

Ersetze <known-good-version> durch die vor dem Update notierte Version. Der Updater erkennt das Downgrade, verlangt eine Bestätigung, prüft verwaltete Plugins, aktualisiert die Service-Metadaten und startet den Gateway neu. Ist extended-stable gespeichert, kombiniere den exakten Versionsstand mit dem stabilen Kanal:

openclaw update --channel stable --tag <known-good-version>

Falls der CLI-Updater selbst nicht mehr funktioniert, stoppe den Gateway und verwende denselben Paketmanager und Installationsumfang wie bei der ursprünglichen Installation. Für eine globale npm-Installation lautet der dokumentierte Notfallpfad:

openclaw gateway stop
npm i -g openclaw@<known-good-version>
openclaw gateway install --force
openclaw gateway restart

Bei pnpm- oder Bun-Installationen ersetzt du npm durch den tatsächlich verwendeten Paketmanager.

Für einen Git-Checkout wählst du einen bekannten Tag oder Commit:

git fetch --all --tags
git checkout --detach <known-good-tag-or-commit>
pnpm install && pnpm build
openclaw gateway restart

Führe danach erneut die Runtime-Prüfungen aus. Wenn die ältere Version mit dem aktuellen State funktioniert, ist kein State-Restore nötig.

7. State nur bei echter Inkompatibilität wiederherstellen

Kann die ältere Version eine migrierte Konfiguration oder Datenbank nicht lesen, stellst du den vor dem Update gesicherten State wieder her. Dabei gehen alle Änderungen verloren, die nach dem Backup entstanden sind. Sichere den aktuellen Zustand deshalb separat, bevor du ihn ersetzt.

Extrahiere das Archiv in ein neues oder leeres Staging-Verzeichnis:

openclaw backup restore ~/Backups/openclaw/<dein-archiv>.tar.gz --target <frisches-staging-verzeichnis>

Restore verifiziert Archiv und SQLite-Datenbanken vor der Extraktion. Das Ziel darf nicht existieren oder muss leer sein. Der Befehl überschreibt keinen laufenden State und besitzt bewusst keinen --force-Modus.

Öffne anschließend die wiederhergestellte manifest.json. Sie ist die Referenz dafür, welche Payloads im Archiv zum ursprünglichen State-, Config-, Credentials- oder Workspace-Pfad gehören. Die Aktivierung erfolgt offline:

1. Stoppe den Gateway.
2. Bewahre den aktuellen State separat auf.
3. Verschiebe die laut Manifest wiederhergestellten Assets an ihre vorgesehenen Pfade oder richte OPENCLAW_STATE_DIR auf das wiederhergestellte State-Asset aus.
4. Führe openclaw doctor gegen den aktivierten State aus.
5. Starte den Gateway neu und wiederhole die Runtime-Prüfungen.

Ein State-Restore ist eine Zeitreise. Ratchet-basierte Channel-Credentials, besonders bei WhatsApp, können danach nicht mehr zum Stand des externen Dienstes passen und eine erneute Verknüpfung benötigen. Auch Freigaben sowie Delivery- und Dedupe-Zustände springen auf den Sicherungszeitpunkt zurück. Prüfe deshalb offene Freigaben und mögliche doppelte Zustellungen, bevor du den normalen Betrieb wieder aufnimmst.

Wenn ein Schritt scheitert

Bricht das Backup wegen einer ungültigen Konfiguration ab, sichere mit --no-include-workspace oder --only-config und repariere danach die Konfiguration.

Scheitert bei einer Version vor Juli 2026 das Update auf die vorgeschriebene Brückenversion 2026.9.5, führe keinen direkten Sprung zum aktuellen Ziel aus. Prüfe den Update-Status, den Dry-Run für 2026.9.5 und die ausgegebene Fehlermeldung. Bleibt Doctor auf der Brückenversion bei einer Migration stehen, behebe diesen Befund dort und wiederhole openclaw doctor --fix sowie die Runtime-Prüfungen.

Ist das Archiv gültig, aber ein Plugin startet nach dem Restore nicht, prüfe dessen Abhängigkeiten. node_modules/ wird absichtlich nicht archiviert; ein Plugin-Update oder eine Neuinstallation ist dann der passende nächste Schritt.

Weicht das Update-Ziel vom erwarteten Beta-Stand ab, kontrolliere die Kanal-Semantik. --channel beta darf auf stable/latest zurückfallen. Für das unveränderte npm-Beta-Tag ist --tag beta vorgesehen.

Meldet der Gateway nach dem Versionswechsel Fehler, rolle zunächst nur den Code zurück. Aktiviere den alten State erst, wenn die bekannte gute OpenClaw-Version den aktuellen State tatsächlich nicht lesen kann.

Kernpunkte

Notiere die Ausgangsversion und prüfe anschließend den Backup-Plan. Installationen aus Juni 2026 oder früher müssen gemäß der offiziellen OpenClaw-Update-Dokumentation über 2026.9.5 migriert werden. Doctor-Migrationen und Runtime-Prüfungen müssen auf dieser Brückenversion erfolgreich abgeschlossen sein, bevor das aktuelle Ziel installiert wird.

Erstelle das Archiv mit --verify und kontrolliere den passenden Update-Pfad mit --dry-run. Nach jedem Versionswechsel liefern Version, Health, Gateway-Status, Doctor und Plugin-Liste die entscheidenden Laufzeitsignale.

Scheitert der Wechsel, stellst du den bekannten guten Code wieder her. Den gesicherten State aktivierst du nur bei einer tatsächlichen Inkompatibilität und in einem getrennten Offline-Schritt. Damit verhinderst du, dass ein Paketproblem unnötig Credentials, Freigaben oder Zustellzustände auf einen älteren Stand zurücksetzt.