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 erst 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 zuerst 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, falls du später gezielt zum vorherigen Paketstand zurückkehren musst. 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.

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 zunächst 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 ist keine Garantie dafür, 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 eigentlichen 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. 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

Wenn Backup und Dry-Run plausibel sind, startest du den Wechsel:

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 danach die CLI-Version, den Gateway und die 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 zunächst 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 zunächst 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 zunächst mit --no-include-workspace oder --only-config und repariere danach die Konfiguration.

Ist das Archiv gültig, aber ein Plugin startet nach dem Restore nicht, prüfe zuerst 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 zuerst die Ausgangsversion und prüfe anschließend den Backup-Plan. Erstelle das Archiv mit --verify und kontrolliere das Update mit --dry-run, bevor du den Versionswechsel ausführst. Danach liefern Version, Health, Gateway-Status und Plugin-Liste die entscheidenden Laufzeitsignale.

Scheitert der Wechsel, stellst du zuerst 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.