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
• INLINECODE1 — session metadata
• INLINECODE2 — recent restart delivery state
• INLINECODE3 — vector index / memory DBs
• INLINECODE4 — per-agent runtime/session state
• INLINECODE5
• INLINECODE6
• INLINECODE7
• INLINECODE8
• INLINECODE9
• INLINECODE10 — 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:

• - INLINECODE11
• INLINECODE12
• INLINECODE13
• INLINECODE14
• INLINECODE15 (if still present)

Backup strategy

Use the bundled scripts for deterministic behavior.

Create backup

Run scripts/backup_state.py with:

• - INLINECODE17
• INLINECODE18 (usually ~/.openclaw)
• INLINECODE20 for generated snapshots
• optional INLINECODE21
• optional --mode mutable|full (default: mutable)
• optional repeated INLINECODE24
• optional repeated INLINECODE25

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

The script writes:

• - a timestamped INLINECODE28
• a INLINECODE29
• 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:

• - INLINECODE32
• INLINECODE33
• INLINECODE34
• optional INLINECODE35
• optional INLINECODE36
• optional INLINECODE37
• optional INLINECODE38
• optional repeated INLINECODE39
• optional repeated INLINECODE40

Restore behavior:

1. 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
• INLINECODE49 — mostly-stable workspace identity/configuration files
• INLINECODE50 — 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.