{"id":602,"date":"2026-03-21T22:52:56","date_gmt":"2026-03-21T14:52:56","guid":{"rendered":"https:\/\/pa.yingzhi8.cn\/index.php\/2026\/03\/21\/cli-backup\/"},"modified":"2026-03-21T23:08:55","modified_gmt":"2026-03-21T15:08:55","slug":"cli-backup","status":"publish","type":"post","link":"https:\/\/pa.yingzhi8.cn\/index.php\/2026\/03\/21\/cli-backup\/","title":{"rendered":"backup"},"content":{"rendered":"

backup<\/h1>\n

openclaw backup<\/code><\/h1>\n

Create a local backup archive for OpenClaw state, config, credentials, sessions, and optionally workspaces.<\/p>\n

“`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\nopenclaw backup create
\nopenclaw backup create –output ~\/Backups
\nopenclaw backup create –dry-run –json
\nopenclaw backup create –verify
\nopenclaw backup create –no-include-workspace
\nopenclaw backup create –only-config
\nopenclaw backup verify .\/2026-03-09T00-00-00.000Z-openclaw-backup.tar.gz<\/p>\n

\n## Notes\n\n* The archive includes a `manifest.json` file with the resolved source paths and archive layout.\n* Default output is a timestamped `.tar.gz` archive in the current working directory.\n* If the current working directory is inside a backed-up source tree, OpenClaw falls back to your home directory for the default archive location.\n* Existing archive files are never overwritten.\n* Output paths inside the source state\/workspace trees are rejected to avoid self-inclusion.\n* `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.\n* `openclaw backup create --verify` runs that validation immediately after writing the archive.\n* `openclaw backup create --only-config` backs up just the active JSON config file.\n\n## What gets backed up\n\n`openclaw backup create` plans backup sources from your local OpenClaw install:\n\n* The state directory returned by OpenClaw's local state resolver, usually `~\/.openclaw`\n* The active config file path\n* The OAuth \/ credentials directory\n* Workspace directories discovered from the current config, unless you pass `--no-include-workspace`\n\nIf you use `--only-config`, OpenClaw skips state, credentials, and workspace discovery and archives only the active config file path.\n\nOpenClaw 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.\n\nThe 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.\n\n## Invalid config behavior\n\n`openclaw backup` intentionally bypasses the normal config preflight so it can still help during recovery. Because workspace discovery depends on a valid config, `openclaw backup create` now fails fast when the config file exists but is invalid and workspace backup is still enabled.\n\nIf you still want a partial backup in that situation, rerun:\n\n```bash  theme={"theme":{"light":"min-light","dark":"min-dark"}}\nopenclaw backup create --no-include-workspace\n<\/code><\/pre>\n
That keeps state, config, and credentials in scope while skipping workspace discovery entirely.<\/p>\n
If you only need a copy of the config file itself, --only-config<\/code> also works when the config is malformed because it does not rely on parsing the config for workspace discovery.<\/p>\n
Size and performance<\/h2>\n
OpenClaw does not enforce a built-in maximum backup size or per-file size limit.<\/p>\n
Practical limits come from the local machine and destination filesystem:<\/p>\n
    \n
  • Available space for the temporary archive write plus the final archive<\/li>\n
  • Time to walk large workspace trees and compress them into a .tar.gz<\/code><\/li>\n
  • Time to rescan the archive if you use openclaw backup create --verify<\/code> or run openclaw backup verify<\/code><\/li>\n
  • 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<\/li>\n<\/ul>\n
    Large workspaces are usually the main driver of archive size. If you want a smaller or faster backup, use --no-include-workspace<\/code>.<\/p>\n
    For the smallest archive, use --only-config<\/code>.<\/p>\n","protected":false},"excerpt":{"rendered":"
    backup openclaw backup Create a local backup archive fo […]<\/p>\n","protected":false},"author":0,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-602","post","type-post","status-publish","format-standard","hentry","category-docs"],"_links":{"self":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/602","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/comments?post=602"}],"version-history":[{"count":2,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/602\/revisions"}],"predecessor-version":[{"id":721,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/602\/revisions\/721"}],"wp:attachment":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/media?parent=602"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/categories?post=602"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/tags?post=602"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}