OpenClaw State Backup

Create and restore versioned, restorable snapshots of mutable OpenClaw state.

What changes over time

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 state
• workspace/MEMORY.md
• workspace/memory/
• workspace/SESSION-STATE.md
• workspace/HEARTBEAT.md
• workspace/TOOLS.md
• workspace/skills/ — user-authored skills and local skill state

Treat 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.md
• workspace/USER.md
• workspace/IDENTITY.md
• workspace/AGENTS.md
• workspace/BOOTSTRAP.md (if still present)

Backup strategy

Use the bundled scripts for deterministic behavior.

Create backup

Run scripts/backup_state.py with:

• --workspace <path>
• --state-dir <path> (usually ~/.openclaw)
• --output-dir <path> for generated snapshots
• optional --label <name>
• optional --mode mutable|full (default: mutable)
• optional repeated --include-prefix <relative-path-prefix>
• optional repeated --exclude-prefix <relative-path-prefix>

mutable captures changing state only. full adds mostly-static workspace identity/bootstrap files too.

The script writes:

• a timestamped .tar.gz
• a manifest.json
• checksums for every stored file
• compatibility metadata (formatVersion, OpenClaw version, host/platform)
• applied include/exclude filter metadata

Restore backup

Run scripts/restore_state.py with:

• --archive <path-to-tar.gz>
• --workspace <path>
• --state-dir <path>
• optional --verify-only
• optional --dry-run
• optional --allow-version-mismatch
• optional --report-dir <path>
• optional repeated --include-prefix <relative-path-prefix>
• optional repeated --exclude-prefix <relative-path-prefix>

Restore behavior:

1. verify archive structure + checksums
2. compare compatibility metadata
3. optionally narrow restore scope with include/exclude prefixes
4. build a restore plan (create / update / unchanged / missingFromArchive)
5. always write a JSON restore/dry-run report to disk
6. if --dry-run, stop after writing the diff-style report
7. otherwise create a pre-restore rollback backup automatically
8. restore files into place
9. write a final restore report showing what changed and where rollback lives

Safety rules

• Always prefer --verify-only first when archive provenance is uncertain.
• Never overwrite from an archive that fails checksum verification.
• Never delete unrelated files outside the managed backup manifest.
• If compatibility check fails, stop unless the user explicitly wants --allow-version-mismatch.
• Before reporting restore success, mention the generated rollback archive path.

File model

The scripts split backup contents into:

• mutable/ — runtime-changing state
• static/ — mostly-stable workspace identity/configuration files
• meta/manifest.json — archive manifest

Read the manifest if you need to inspect contents without restoring.

When to use which mode

• Use mutable for routine safety snapshots and frequent backups.
• Use full before machine migration, risky reconfiguration, or major cleanup.

Recovery guidance

If a restore causes problems, immediately restore the auto-generated pre-restore rollback archive created by restore_state.py.