feat: add local backup CLI (#40163)

Merged via squash.

Prepared head SHA: ed46625ae2
Co-authored-by: shichangs <46870204+shichangs@users.noreply.github.com>
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Reviewed-by: @gumadeiras

docs/cli/backup.md

@@ -0,0 +1,76 @@
+---
+summary: "CLI reference for `openclaw backup` (create local backup archives)"
+read_when:
+  - You want a first-class backup archive for local OpenClaw state
+  - You want to preview which paths would be included before reset or uninstall
+title: "backup"
+---
+
+# `openclaw backup`
+
+Create a local backup archive for OpenClaw state, config, credentials, sessions, and optionally workspaces.
+
+```bash
+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 `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
+
+`openclaw backup create` plans backup sources from 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, and workspace 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
+
+`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.
+
+If you still want a partial backup in that situation, rerun:
+
+```bash
+openclaw backup create --no-include-workspace
+```
+
+That keeps state, config, and credentials in scope while skipping workspace discovery entirely.
+
+If you only need a copy of the config file itself, `--only-config` 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 `.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 are usually the main driver of archive size. If you want a smaller or faster backup, use `--no-include-workspace`.
+
+For the smallest archive, use `--only-config`.

docs/cli/index.md

@@ -19,6 +19,7 @@ This page describes the current CLI behavior. If commands change, update this do
 - [`completion`](/cli/completion)
 - [`doctor`](/cli/doctor)
 - [`dashboard`](/cli/dashboard)
+- [`backup`](/cli/backup)
 - [`reset`](/cli/reset)
 - [`uninstall`](/cli/uninstall)
 - [`update`](/cli/update)
@@ -103,6 +104,9 @@ openclaw [--dev] [--profile <name>] <command>
   completion
   doctor
   dashboard
+  backup
+    create
+    verify
   security
     audit
   secrets

docs/cli/reset.md

@@ -11,7 +11,10 @@ title: "reset"
 Reset local config/state (keeps the CLI installed).
 
 ```bash
+openclaw backup create
 openclaw reset
 openclaw reset --dry-run
 openclaw reset --scope config+creds+sessions --yes --non-interactive
 ```
+
+Run `openclaw backup create` first if you want a restorable snapshot before removing local state.

docs/cli/uninstall.md

@@ -11,7 +11,10 @@ title: "uninstall"
 Uninstall the gateway service + local data (CLI remains).
 
 ```bash
+openclaw backup create
 openclaw uninstall
 openclaw uninstall --all --yes
 openclaw uninstall --dry-run
 ```
+
+Run `openclaw backup create` first if you want a restorable snapshot before removing state or workspaces.