350bac4e0e
* fix(sqlite): enable bounded vacuum and hot indexes * fix(sqlite): serialize shared schema upgrades * fix(sessions): reject stale transcript rewrites * fix(sqlite): surface busy checkpoints and refresh registry * fix(backup): verify sqlite snapshots * feat(doctor): compact shared sqlite state * test(sqlite): align hardening helpers * fix(backup): respect plugin sqlite ownership * fix(backup): snapshot plugin sqlite opaquely * fix(doctor): reject mixed sqlite actions * fix(backup): reject unsafe sqlite snapshots * fix(sessions): track unconditional transcript replacements * fix(backup): reject page-aligned sqlite truncation * fix(backup): reject state-root case aliases * docs: refresh sqlite maintenance map * fix(sqlite): register doctor compaction boundary * fix(sqlite): serialize fresh database initialization * fix(sqlite): prove main v5 agent upgrade * perf(sqlite): seek latest transcript messages * test(sessions): align terminal freshness fixtures with SQLite * docs: refresh generated map
5.2 KiB
summary, read_when, title
| summary | read_when | title | ||
|---|---|---|---|---|
| CLI reference for `openclaw backup` (create local backup archives) |
|
Backup |
openclaw backup
Create a local backup archive for OpenClaw state, config, auth profiles, channel/provider credentials, sessions, and optionally workspaces.
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-09T08-00-00.000+08-00-openclaw-backup.tar.gz
Notes
- The archive embeds a
manifest.jsonwith the resolved source paths and archive layout. - Default output is a timestamped
.tar.gzarchive in the current working directory. Timestamped filenames use your machine's local timezone and include the UTC offset. 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>checks that the archive contains exactly one root manifest, rejects traversal-style archive paths and SQLite sidecars, confirms every manifest-declared payload exists, validates every SQLite snapshot's file shape, and runs full integrity and role checks on canonical OpenClaw databases. Dedicated plugin schemas remain opaque because they may require owner-defined SQLite capabilities.openclaw backup create --verifyruns that validation immediately after writing the archive.openclaw backup create --only-configbacks up just the active JSON config file.
What gets backed up
openclaw backup create plans sources from your local OpenClaw install:
- The state directory (usually
~/.openclaw) - The active config file path
- The resolved
credentials/directory when it exists outside the state directory - Workspace directories discovered from the current config, unless you pass
--no-include-workspace
Auth profiles and other per-agent runtime state live in SQLite under the state directory (agents/<agentId>/agent/openclaw-agent.sqlite), so they are covered by the state backup entry automatically.
--only-config 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.
During archive creation, OpenClaw skips known live-mutation files with no restoration value: active agent session transcripts, cron run logs, rolling logs, delivery queues, socket/pid/temp files under the state directory, and related durable-queue temp files. The JSON result's skippedVolatileCount reports how many files were intentionally omitted. SQLite databases under the state directory are compacted with VACUUM INTO so deleted-page remnants do not enter the archive, and live WAL/SHM files are not copied. A plugin-owned database that requires unavailable owner-defined SQLite capabilities fails closed rather than falling back to a raw page copy. SQLite files included through workspace backups are copied as workspace files and are not covered by the compaction guarantee.
Installed plugin source and manifest files under the state directory's extensions/ tree are included, but their nested node_modules/ dependency trees are skipped as rebuildable install artifacts. After restoring an archive, use openclaw plugins update <id> or reinstall with openclaw plugins install <spec> --force if a restored plugin reports missing dependencies.
Invalid config behavior
openclaw backup bypasses the normal config preflight so it can still help during recovery. Workspace discovery depends on a valid config, so openclaw backup create fails fast when the config file exists but is invalid and workspace backup is still enabled.
For a partial backup in that situation, rerun with --no-include-workspace: it keeps state, config, and the external credentials directory in scope while skipping workspace discovery entirely.
--only-config also works when the config is malformed, since it does not parse 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:
- 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 with
--verifyoropenclaw backup verify - Destination filesystem behavior: 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. Use --no-include-workspace for a smaller/faster backup, or --only-config for the smallest archive.