Backup OpenClaw State and Configs in Seconds

Setting up your development environment takes time and effort. Losing your configuration, credentials, or session state because of a hardware failure or a bad update can set you back hours. You need a way to grab everything important and keep it safe without manual hunting.

The openclaw backup command helps you create a local archive of your setup. You can run it with different flags depending on how much data you want to save or if you just want to check an existing backup.

openclaw backup create
openclaw backup create --output ~/Backups
openclaw backup create --dry-run --json
openclaw backup create --verify
openclaw backup create --no-include-workspace
openclaw backup create --only-config
openclaw backup verify ./2026-03-09T00-00-00.000Z-openclaw-backup.tar.gz

Notes

Here are a few things to keep in mind when you use this tool:

• The archive includes a manifest.json file with the resolved source paths and archive layout.
• Default output is a timestamped .tar.gz archive in the current working directory.
• If the current working directory is inside a backed-up source tree, OpenClaw falls back to your home directory for the default archive location.
• Existing archive files are never overwritten.
• Output paths inside the source state/workspace trees are rejected to avoid self-inclusion.
• openclaw backup verify <archive> validates that the archive contains exactly one root manifest, rejects traversal-style archive paths, and checks that every manifest-declared payload exists in the tarball.
• openclaw backup create --verify runs that validation immediately after writing the archive.
• openclaw backup create --only-config backs up just the active JSON config file.

What gets backed up

When you run openclaw backup create, the tool looks for specific parts of your local OpenClaw install:

• The state directory returned by OpenClaw’s local state resolver, usually ~/.openclaw
• The active config file path
• The OAuth / credentials directory
• Workspace directories discovered from the current config, unless you pass --no-include-workspace

If you use --only-config, OpenClaw skips state, credentials, workspaces, and config discovery and archives only the active config file path.

OpenClaw canonicalizes paths before building the archive. If config, credentials, or a workspace already live inside the state directory, they are not duplicated as separate top-level backup sources. Missing paths are skipped.

The archive payload stores file contents from those source trees, and the embedded manifest.json records the resolved absolute source paths plus the archive layout used for each asset.

Invalid config behavior

Sometimes you need a backup because things are already broken. openclaw backup skips the usual config checks so it can help you recover. However, since finding workspaces requires a working config, the command will fail if your config is invalid while workspace backup is turned on.

If you need a partial backup while your config is broken, run this:

openclaw backup create --no-include-workspace

This command keeps your state, config, credentials, and sessions in scope while skipping the workspace search. If you only need the config file itself, --only-config works even if the file is malformed because it does not try to parse the config for workspace discovery.

Size and performance

There are no hard limits on backup size within the tool itself. Instead, the speed and success of your backup depend on your hardware and destination:

• Available space for the temporary archive write plus the final archive
• Time to walk large workspace trees and compress them into a .tar.gz
• Time to rescan the archive if you use openclaw backup create --verify or run openclaw backup verify
• Filesystem behavior at the destination path. OpenClaw prefers a no-overwrite hard-link publish step and falls back to exclusive copy when hard links are unsupported

Large workspaces usually make archives much bigger. If you want a smaller or faster backup, use --no-include-workspace. For the smallest possible file, use --only-config.

Next Steps

• Restore Documentation
• Config Guide

AI Setup Assistant