Backup & Migration

OpenClaw ist eher Werkstatt als einzelne App. Deine Config ist wichtig, aber genauso wichtig sind Credentials, Sessions, Channel-State, Plugin-State und die Dateien in deinem Workspace.

Genau deshalb verdienen Backup und Migration eine eigene Routine. Stell es dir wie einen Küchenumzug vor. Das Rezeptbuch mitzunehmen hilft, aber ohne Messer, Pfannen und die eine chaotische Schublade mit allem Wichtigen wird es trotzdem unerquicklich.

Die offizielle Backup-CLI-Referenz und der Migrations-Guide sind die zwei Seiten, die du dafür griffbereit haben solltest.

Was ein echtes OpenClaw-Backup enthält

Der Backup-Befehl kopiert nicht nur eine einzelne JSON-Datei. Er kann das lokale State-Verzeichnis, die aktive Config-Datei, externe Credential-Speicher und die aus deiner Config erkannten Workspace-Verzeichnisse archivieren.

• State-Verzeichnis: Sessions, Agenten-State, Auth-Profile, Plugin-State, Logs und interne Laufzeitdaten
• Aktive Config: Gateway-Einstellungen und Model-Routing-Entscheidungen
• Credentials-Verzeichnis: wenn es außerhalb des eigentlichen State-Pfads liegt
• Workspace-Dateien: Prompts, Memory-Dateien, Skills und Betriebsnotizen

Praktisch ist auch, dass OpenClaw flüchtigen Kram ohne Wiederherstellungswert bewusst auslässt. Das macht das Archiv kleiner und brauchbarer.

Der Backup-Workflow, der am wenigsten Zeit verbrennt

Ein verifiziertes Backup schlägt jede heroische Recovery-Geschichte. Der gute Ablauf ist klein, langweilig und wiederholbar.

openclaw backup create --verify
openclaw backup verify ./2026-03-09T00-00-00.000Z-openclaw-backup.tar.gz

Der erste Befehl erstellt das Archiv und prüft es direkt. Der zweite lässt dich ein vorhandenes Archiv später erneut validieren. Das lohnt sich vor Upgrades, Host-Wechseln oder riskanter Config-Arbeit.

Es gibt auch einen sauberen Notausgang für kaputte Configs. Wenn die Workspace-Erkennung wegen einer ungültigen Config scheitern würde, kannst du trotzdem ein teilweises Backup ohne Workspace erstellen, statt mit leeren Händen dazustehen.

Wenn Migration einen Maschinenwechsel meint

OpenClaw auf eine andere Maschine umzuziehen ist meistens einfacher als gedacht, aber nur wenn du die richtigen Dinge mitnimmst. State-Verzeichnis und Workspace sind die Hauptlast. Nur openclaw.json zu kopieren endet oft mit ausgeloggten Channels und verschwundenen Sessions.

Der offizielle Ablauf ist klar: altes Gateway stoppen, damit sich Dateien nicht mehr bewegen, alten State sichern, rüberkopieren, auf der neuen Maschine entpacken, danach doctor laufen lassen und die neue Instanz prüfen.

openclaw gateway stop
openclaw backup create --verify
openclaw doctor
openclaw gateway restart
openclaw status

Die Reihenfolge ist wichtig. Sie trennt einen sauberen Snapshot von einem Umzug mit beweglichem Ziel.

Wenn Migration einen Import aus einem anderen Agent-System meint

OpenClaw unterstützt auch Import-Migrationen aus anderen Agent-Systemen über Migration-Provider. Dieser Weg ist bewusst preview-first. Genau das willst du, wenn Settings, Skills, MCP-Server oder Credentials an neue Orte wandern könnten.

openclaw migrate list
openclaw migrate codex --dry-run
openclaw migrate apply codex --yes

Starte mit einem Dry Run. Immer. Die Vorschau ist keine Bürokratie, sondern deine Chance, Konflikte, ausgelassene Elemente und sensible Importe zu sehen, bevor daraus Aufräumarbeit wird.

Wenn du Secrets übernehmen willst, dann bewusst. Dass OpenClaw das optional hält, ist kein Zufall. Zugangsdaten sollen keine versteckte Überraschung innerhalb einer Migration sein.

Vier Migrationsfehler, die ständig wiederkommen

So tun, als wäre die Config-Datei schon das ganze System

Ist sie nicht. Ein großer Teil des operativen Zustands lebt außerhalb der Haupt-Config. Wer das State-Verzeichnis vergisst, vergisst Verlauf, Auth und einen guten Teil der Setup-Identität.

Verifikation auslassen, weil der Archiv-Befehl schon fertig war

Fertig heißt nicht geprüft. Verifikation existiert, weil Archive trotzdem unvollständig, fehlerhaft oder am falschen Ort liegen können.

In das falsche Profil zurückspielen

Wenn die alte Maschine ein eigenes State-Dir oder Profil genutzt hat und die neue nicht, wirkt die Wiederherstellung schnell seltsam leer. Die Daten sind dann oft da. Du schaust nur in die falsche Garage.

Env-Fallback-Credentials vergessen

Manche Channel-Setups hängen noch an Umgebungsvariablen als Fallback. Fehlen diese Keys auf der neuen Maschine, sieht alles migriert aus, während ein kritischer Kanal leise scheitert.

Eine praktische Routine, die du ruhig kopieren darfst

• Erstelle vor Upgrades, Migrationen oder Plugin-Experimenten immer ein verifiziertes Backup
• Lege Backups außerhalb der Quellbäume ab, damit sie sich nicht selbst mitschleppen
• Teste genau eine Wiederherstellung auf einer Ersatzmaschine, bevor du sie ernsthaft brauchst
• Nutze Dry-Run-Migrationspläne vor jedem Apply-Schritt
• Lass nach jedem Umzug doctor laufen und prüfe mindestens einen echten Channel

Langweilige Prozesse sind hier der ganze Witz. Backups und Migrationen sollten unspektakulär sein. Wenn sie dramatisch werden, hat etwas zu spät begonnen.