Backup

text

Copy

openclaw backup

Create a local backup archive for OpenClaw state, config, auth profiles, channel/provider credentials, sessions, and optionally workspaces.

bash
Copy
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

• The archive includes a
  text

  Copy

  manifest.json
  file with the resolved source paths and archive layout.
• Default output is a timestamped
  text

  Copy

  .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.
• text

  Copy

  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.
• text

  Copy

  openclaw backup create --verify
  runs that validation immediately after writing the archive.
• text

  Copy

  openclaw backup create --only-config
  backs up just the active JSON config file.

What gets backed up

plans backup sources from your local OpenClaw install:

• The state directory returned by OpenClaw's local state resolver, usually
  text

  Copy

  ~/.openclaw
• The active config file path
• The resolved
  text

  Copy

  credentials/
  directory when it exists outside the state directory
• Workspace directories discovered from the current config, unless you pass
  text

  Copy

  --no-include-workspace

Model auth profiles are already part of the state directory under

, so they are normally covered by the state backup entry.

If you use

, OpenClaw skips state, credentials-directory, and workspace discovery and archives only the active config file path.

OpenClaw canonicalizes paths before building the archive. If config, the credentials directory, 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

records the resolved absolute source paths plus the archive layout used for each asset.

Installed plugin source and manifest files under the state directory's

tree are included, but their nested dependency trees are skipped. Those dependencies are rebuildable install artifacts; after restoring an archive, use or reinstall the plugin with when a restored plugin reports missing dependencies.

Invalid config behavior

intentionally bypasses the normal config preflight so it can still help during recovery. Because workspace discovery depends on a valid config, now fails fast when the config file exists but is invalid and workspace backup is still enabled.

If you still want a partial backup in that situation, rerun:

bash
Copy
openclaw backup create --no-include-workspace

That keeps state, config, and the external credentials directory in scope while skipping workspace discovery entirely.

If you only need a copy of the config file itself,

also works when the config is malformed because it does not rely on parsing the config for workspace discovery.

Size and performance

OpenClaw does not enforce a built-in maximum backup size or per-file size limit.

Practical limits come from the local machine and destination filesystem:

• Available space for the temporary archive write plus the final archive
• Time to walk large workspace trees and compress them into a
  text

  Copy

  .tar.gz
• Time to rescan the archive if you use
  text

  Copy

  openclaw backup create --verify
  or run
  text

  Copy

  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 are usually the main driver of archive size. If you want a smaller or faster backup, use

.

For the smallest archive, use

.

Related

• CLI reference