Create, inspect, and restore versioned OpenClaw state backups with rollback safety. Use when backing up or migrating OpenClaw memory, workspace state, gatewa...
Create and restore versioned, restorable snapshots of mutable OpenClaw state.
Treat these as mutable state and include them in backups when they exist:
~/.openclaw/openclaw.json — runtime config~/.openclaw/sessions.json — session metadata~/.openclaw/restart-sentinel.json — recent restart delivery state~/.openclaw/memory/ — vector index / memory DBs~/.openclaw/agents/ — per-agent runtime/session stateworkspace/MEMORY.mdworkspace/memory/workspace/SESSION-STATE.mdworkspace/HEARTBEAT.mdworkspace/TOOLS.mdworkspace/skills/ — user-authored skills and local skill stateTreat these as mostly static/user-maintained bootstrap files and back them up when you want a full environment restore, but do not rely on them as fast-changing runtime state:
workspace/SOUL.mdworkspace/USER.mdworkspace/IDENTITY.mdworkspace/AGENTS.mdworkspace/BOOTSTRAP.md (if still present)Use the bundled scripts for deterministic behavior.
Run scripts/backup_state.py with:
--workspace <path>--state-dir <path> (usually ~/.openclaw)--output-dir <path> for generated snapshots--label <name>--mode mutable|full (default: mutable)--include-prefix <relative-path-prefix>--exclude-prefix <relative-path-prefix>mutable captures changing state only.
full adds mostly-static workspace identity/bootstrap files too.
The script writes:
.tar.gzmanifest.jsonformatVersion, OpenClaw version, host/platform)Run scripts/restore_state.py with:
--archive <path-to-tar.gz>--workspace <path>--state-dir <path>--verify-only--dry-run--allow-version-mismatch--report-dir <path>--include-prefix <relative-path-prefix>--exclude-prefix <relative-path-prefix>Restore behavior:
create / update / unchanged / missingFromArchive)--dry-run, stop after writing the diff-style report--verify-only first when archive provenance is uncertain.--allow-version-mismatch.The scripts split backup contents into:
mutable/ — runtime-changing statestatic/ — mostly-stable workspace identity/configuration filesmeta/manifest.json — archive manifestRead the manifest if you need to inspect contents without restoring.
If a restore causes problems, immediately restore the auto-generated pre-restore rollback archive created by restore_state.py.
ZIP package — ready to use