Backup & Migration

OpenClaw is more like a workshop than a single app. Your config matters, but so do credentials, sessions, channel state, plugin state, and the files inside your workspace.

That is why backup and migration deserve their own routine. Think of it like moving a kitchen. Carrying the recipe book is useful, but you still need the knives, the pans, and the one stubborn drawer full of essentials.

The official backup CLI reference and migration guide are the two pages worth keeping close.

What a real OpenClaw backup includes

The backup command is not just copying one JSON file. It can archive the local state directory, the active config file, external credentials storage, and workspace directories discovered from your config.

• State directory: sessions, agent state, auth profiles, plugin state, logs, and internal runtime data
• Active config: your gateway settings and model routing choices
• Credentials directory: when it lives outside the main state path
• Workspace files: prompts, memory files, skills, and operating notes

The useful detail here is that OpenClaw also skips volatile junk that has no restoration value. That keeps the archive cleaner and more practical.

The backup workflow that wastes the least time

A verified backup beats a heroic recovery story every time. The smart move is small, boring, and repeatable.

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

The first command creates the archive and validates it immediately. The second lets you re-check an existing archive later. That is worth doing before upgrades, host moves, or risky config surgery.

There is also a neat escape hatch for broken configs. If workspace discovery would fail because the config is invalid, you can still create a partial backup without workspace inclusion instead of walking away empty-handed.

When migration means a new machine

Moving OpenClaw to another machine is usually simpler than people expect, but only if you copy the right things. The state directory and the workspace are the main payload. Copy only openclaw.json and you will wonder why channels look logged out and sessions vanished.

The official flow is straightforward: stop the old gateway so files stop moving, archive the old state, copy it over, extract it on the new machine, then run doctor and verify the new instance.

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

That sequence matters. It is the difference between migrating a snapshot and chasing a moving target.

When migration means importing from another agent system

OpenClaw also supports import-style migration from other agent systems through migration providers. That path is preview-first, which is exactly what you want when settings, skills, MCP servers, or credentials may land in new places.

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

Start with a dry run. Always. Previewing the plan before apply is not ceremony. It is your chance to catch conflicts, skipped items, and sensitive imports before they become cleanup work.

If you choose to import secrets, do it on purpose. OpenClaw keeps that opt-in because credentials are not the kind of surprise you want hidden inside a migration.

Four migration mistakes that keep showing up

Assuming the config file is the whole system

It is not. OpenClaw keeps real operational state outside the main config. Forget the state directory and you forget the history, auth, and a good chunk of your setup identity.

Skipping verification because the archive command already finished

Completion is not proof. Verification exists because archives can still be incomplete, malformed, or pointed at the wrong output path.

Restoring into the wrong profile

If the old machine used a custom state dir or profile and the new one does not, the restored install can look strangely empty. The data is there. You are just looking in the wrong garage.

Forgetting env fallback credentials

Some channel setups still rely on environment variables as fallbacks. If those keys are not present on the new machine, everything can look migrated while one critical channel quietly fails.

A practical routine worth stealing

• Create a verified backup before upgrades, migrations, or plugin experiments
• Keep backups outside the source trees so they do not accidentally include themselves
• Test one restore on a spare machine before you need it for real
• Use dry-run migration plans before any apply step
• Run doctor and a live channel check after every move

Boring process is the point here. Backups and migrations should feel uneventful. If they feel dramatic, something started too late.