mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-15 10:46:14 +00:00
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
72 lines
5.2 KiB
Markdown
72 lines
5.2 KiB
Markdown
---
|
|
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, auth profiles, channel/provider 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-09T08-00-00.000+08-00-openclaw-backup.tar.gz
|
|
```
|
|
|
|
## Notes
|
|
|
|
- The archive embeds a `manifest.json` with the resolved source paths and archive layout.
|
|
- Default output is a timestamped `.tar.gz` archive 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 --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 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 `--verify` or `openclaw 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.
|
|
|
|
## Related
|
|
|
|
- [CLI reference](/cli)
|