How Do I Back Up and Restore OpenClaw? Create, Verify and Stage

Published 2026-11-15 · Updated 2026-11-15 · By The Is My Agent Safe team

Short answer

To back up OpenClaw, run openclaw backup create --output ~/Backups/openclaw --verify. That writes a timestamped archive covering state, config, credentials, agent directories and, by default, workspaces. To restore, use openclaw backup restore with a fresh, empty target. Restore never writes into live state. Then stop the Gateway, move the restored files into place or point OPENCLAW_STATE_DIR at them, and run openclaw doctor.

  • openclaw backup create --verify writes a full archive and checks its manifest and payload.
  • Copying only openclaw.json is not enough. Auth, credentials and sessions live in other files.
  • openclaw update keeps a pre-update config copy, not a full-state recovery point.
  • Restore stages into an empty directory and has no in-place or force mode.
  • After activation, run openclaw doctor before restarting the Gateway.

Paste your audit: run openclaw security audit --deep and paste the output into our free check for a red/amber/green result with the most important finding first (Limits of the check).

Who this is for

OpenClaw owners who want a recovery point before an update, a reset, an uninstall or a move to a new machine.

How do I back up OpenClaw?

OpenClaw's backup docs give this command for a one-off state and workspace archive:

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

That writes a timestamped .tar.gz and then validates the archive manifest and payload. For a move to a new machine, OpenClaw's migration docs say to stop the Gateway first:

openclaw gateway stop
mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify

They warn that a raw copy of a changing SQLite database can capture mismatched database and WAL files. Quiescing the Gateway keeps the state tree stable.

If a full archive fails because the configuration is malformed, first save the active config with openclaw backup create --only-config --output ~/Backups/openclaw --verify. Repair the config, then rerun the full archive command.

What does a full archive include?

A verified full archive covers state, config, credentials, every configured agent directory, and (by default) workspaces (backup docs). Agent directories stay included even if you pass --no-include-workspace.

Copying only openclaw.json is a common miss. The migration docs say shared model auth lives in state/openclaw.sqlite, agent-local profiles live in agents/<agentId>/agent/openclaw-agent.sqlite, and channel and provider state lives under credentials/.

The archive can contain credentials, auth profiles and channel state. OpenClaw's rollback docs say to store it with owner-only permissions and the same care as the live state directory. The migration docs add: store backups encrypted, avoid insecure transfer channels, and rotate keys if you think the archive was exposed.

--only-config is a root-file export, not a complete recovery point.

When should I make a verified backup?

The backup docs call a full archive the right tool before an update, a reset, an uninstall or a machine move, and a reasonable daily routine for small installs.

openclaw update is not a substitute. The rollback docs say it preserves an automatic pre-update config copy, not a full-state recovery point. Create an independent verified backup before a significant update. See our guide to updating OpenClaw without breaking it.

How do I restore without overwriting live state?

Restore is deliberate. Nothing overwrites live state in place (restore docs):

openclaw backup restore <archive.tar.gz> --target ~/openclaw-restored

The target must not exist, or must be empty, and it cannot sit inside the live state directory or any configured live agent directory. A non-empty target is refused. A failed extraction is cleaned up. There is no --force and no in-place mode.

Start only from an archive you created or otherwise trust. openclaw backup verify checks archive structure and payload layout. OpenClaw's docs say it does not authenticate the archive.

Treat the restored directory as sensitive: it can contain credentials, auth profiles, sessions and workspace data.

To activate, stop the Gateway and any node hosts that use the restored files. Make a fresh backup of current state, or move it aside. Then move the extracted state asset into place, or point OPENCLAW_STATE_DIR at that asset. Restore every custom agent root using its recorded agent id and original source path: keep its configured agentDir, or update that setting to the new location. Use the restored manifest.json to map config, credentials and workspaces, especially on a new machine or under a different home directory. Review absolute symbolic links; they keep their original target locations. Then:

openclaw doctor
openclaw gateway restart
openclaw status

What should I watch after a restore?

OpenClaw's restore docs warn that restoring an archive is time travel:

If the old Gateway used --profile or OPENCLAW_STATE_DIR, launch the new one with the same profile or state directory, then rerun openclaw doctor.

Run a small business in the UK? We can name 3 admin jobs we could take off you, free and in writing. Get your free 3-job list

What our free check covers

We built a free paste check. Paste your openclaw security audit --deep output and openclaw --version. It puts the most important finding first, in plain English, with how to fix that one when we have steps for it. It also looks for risky settings, such as API keys handed to skills, and checks the version against published OpenClaw security advisories. Nothing is installed into the agent you're checking.

We check the text you paste. Your browser hides many common key and token formats before sending, but not all of them, so remove any other secrets first. Green means no issues found in the checks we ran. See Limits of the check.

The check is free, and a full report is $29. One-off $29, not a subscription. Refunded automatically if the check can't finish, or in full if you ask within 14 days. The full report explains every finding and lists the fixes in order. We don't review the code inside skills or MCP servers ourselves, beyond what OpenClaw's own audit reports.

Is My Agent Safe is independent and isn't affiliated with or endorsed by OpenClaw or its maintainers.

Written with AI assistance by the Is My Agent Safe team at Your Evenings Ltd.

Where next

Frequently asked questions

Is copying openclaw.json enough for a backup?

No. OpenClaw's migration docs say the config file alone is not enough. Shared model auth lives in state/openclaw.sqlite, agent-local profiles live in agents/<agentId>/agent/openclaw-agent.sqlite, and channel and provider state lives under credentials/. Use the backup and restore flow for the entire state directory.

Does openclaw update create a full backup?

No. OpenClaw's rollback docs say openclaw update preserves an automatic pre-update config copy, not a full-state recovery point. Before a significant update, create an independent verified backup with openclaw backup create --output ~/Backups/openclaw --verify.

Can I restore a backup over my live OpenClaw directory?

No. OpenClaw's backup docs say restore never writes into live state or agent roots and has no force or in-place mode. The target must be empty, or must not exist, and it cannot sit inside the live state directory.

Can Is My Agent Safe check this for me?

We built a free paste check. Paste your openclaw security audit --deep output and openclaw --version, and it puts the most important finding first, in plain English, with how to fix that one when we have steps for it. We don't review the code inside skills or MCP servers ourselves, beyond what OpenClaw's own audit reports.

Sources

  1. OpenClaw docs: backups (checked 15 Nov 2026)
  2. OpenClaw docs: backup CLI (checked 15 Nov 2026)
  3. OpenClaw docs: migrating to a new machine (checked 15 Nov 2026)
  4. OpenClaw docs: rollback and recovery (checked 15 Nov 2026)