OpenClaw Backup: The Archive Passed, the Restore Was Still Unproven

The archive passed twice. OpenClaw verified it while writing, then verified the exact tarball again as a standalone command. The receipt was clean: one asset, two archive entries, runtime version 2026.7.1-2. It was also a 3,998-byte config-only backup. Nothing in that green result claimed that sessions, credentials, workspaces, plugins, or a working agent could return.

That is the uncomfortable but useful fact behind an OpenClaw backup: verification can be completely correct and still answer a much narrower question than the operator has in mind. A defensible recovery point needs four receipts—selected scope, archive integrity, independent storage, and an isolated start—not one optimistic badge.

Validation is deliberately narrow

The batch-98 probe began with the smallest write-path test on the installed OpenClaw 2026.7.1-2 binary:

openclaw backup create \
  --only-config \
  --output /private/openclaw-backup-smoke \
  --verify \
  --json

openclaw backup verify \
  /private/openclaw-backup-smoke/<timestamp>-openclaw-backup.tar.gz \
  --json

Both checks passed. The creation receipt named one config asset. Standalone verification reported assetCount: 1 and entryCount: 2. The archive SHA-256 was retained with the probe, so a transferred copy can be matched to the tested bytes rather than to a similar filename.

This is a good smoke test, not a recovery point. It exercises destination permissions, archive publication, the embedded manifest, and the verifier without copying live session or credential state. The same result that proves the mechanism works also proves why the artifact is insufficient: its declared scope contains only the active JSON config.

Four lines in the plan decide what can return

The most valuable command in the workflow writes nothing:

openclaw backup create \
  --dry-run \
  --json \
  --no-include-workspace \
  --output /private/openclaw-backups

In the live probe, the result returned dryRun: true, includeWorkspace: false, and one resolved state source at ~/.openclaw. No archive appeared in the fresh destination. That receipt answers a different question: which profile and source tree would the real command select?

Run the preview as the operating-system user and environment that own the Gateway. A second shell can point at a different state root and produce a valid backup of the wrong installation. Review the resolved state, active config, external credentials path, and discovered workspaces before permitting the write.

Workspace scope is where a simple command becomes an operational decision. Repositories, generated media, model artifacts, and dependency trees can dominate time and storage. Excluding them is reasonable only when Git, object storage, or another durable system owns those bytes and its restore path has been exercised. “Too large for tonight’s job” is not a recovery policy.

Read the archive as an evidence packet

A broad state archive is not a raw copy of a running home directory. The matching v2026.7.1 documentation says OpenClaw records resolved sources in manifest.json, refuses to overwrite an existing archive, and rejects output paths inside source state or workspace trees so the backup cannot ingest itself.

It also leaves some material behind on purpose. Active transcript and log streams, cron run logs, delivery queues, sockets, PID files, temporary files, managed runtime roots, and nested plugin dependency trees are volatile or rebuildable. The JSON receipt exposes skippedVolatileCount; completed transcripts that match those rules may still be absent. If a transcript is an audit record, retain it through a log policy rather than quietly assigning that duty to the backup command.

OpenClaw-owned SQLite files under the state directory receive SQLite-safe capture instead of a naive copy of a live database plus -wal and -shm sidecars. That boundary matters during active writes. A plugin-owned database that needs unavailable schema capabilities fails closed rather than being copied as an unverified page set. Workspace databases, by contrast, are workspace files and do not inherit the same compaction guarantee.

A release boundary can change recovery semantics

Current upstream documentation now describes openclaw backup sqlite commands for portable global or per-agent database snapshots. It adds manifest hashes, integrity and role checks, private content-pinned verification, and a restore command that writes only to a fresh target. The installed 2026.7.1-2 help in this probe exposed only create and verify; its matching v2026.7.1 documentation also lacked the SQLite subcommand.

Both documents can be accurate. They describe different command surfaces. The operator error is copying a current example into an older binary’s incident runbook and discovering the mismatch during recovery.

openclaw --version
openclaw backup --help
openclaw backup create --help

Keep those three outputs beside the archive receipt. When the installed help exposes dedicated SQLite snapshots, use their verified repository and fresh-target restore contract. Until then, use the archive path supported by that release and do not invent a live-database copy procedure from newer documentation.

Move the copy before you praise it

A timestamped tarball beside ~/.openclaw is convenient for rollback and weak against disk loss, host compromise, or a destructive command with broad reach. After verification, move or replicate the exact hashed bytes to storage outside the production failure domain. Recalculate the checksum there.

Treat the archive like live secret material. It may hold auth profiles, channel credentials, session state, and configuration values. Owner-only access, encryption, retention limits, deletion controls, and restore authorization belong in the design before the first upload. An encrypted disk snapshot is not independent if the only decryption key disappears with the same host.

A dead address is the only honest rehearsal

The safest restore target is disposable and incapable of reaching production channels. Prepare a clean host, VM, or isolated user profile. Transfer the verified artifact, match its hash, and extract only into that target. Never rehearse by laying recovered state over a running ~/.openclaw.

Before a Gateway starts, compare the restored inventory with the dry-run receipt. The active config should parse. Intended agents and authentication profiles should exist. Workspaces should be present or fetchable from their assigned source of truth. Omitted plugin dependencies should reinstall cleanly. Channel and provider credentials should resolve through the planned secret path.

Then test from read-only to consequential: configuration validation, agent inventory, expected session counts, plugin loading, Gateway health, and one inert end-to-end task. Use disabled or test channel routes. A clean archive that starts the wrong profile—or sends a real message during the drill—is not a successful recovery.

The retained record can be compact: OpenClaw version, archive filename and SHA-256, scope flags, verifier result, remote storage receipt, restore target, rebuilt components, functional checks, failures, and the time to reach a usable agent. NIST contingency-planning guidance places testing and plan maintenance inside recovery planning. The same discipline keeps an OpenClaw runbook from becoming a promise nobody has exercised.

Five verdicts are clearer than “backup succeeded”

• Scope PASS: the dry-run receipt names the intended state, config, credentials, and workspace ownership.
• Archive PASS: creation and standalone verification agree on the exact hashed artifact.
• Storage PASS: a separately controlled destination holds matching bytes and a usable recovery key.
• Restore PASS: an isolated target rebuilds omissions and reaches named functional checks without production effects.
• Freshness PASS: the runbook, binary version, retention window, and last rehearsal date remain current.

The first two verdicts can be automated. The last three require an operator to define what loss means and what “usable” means. Keeping them separate is not bureaucracy; it prevents one well-formed tarball from being promoted into evidence it never contained.

For adjacent boundaries, the OpenClaw update guide covers the code and rollback anchor around binary changes, while the sessions guide explains which conversation records are authoritative. If owning storage, restore rehearsals, Gateway recovery, and runtime portability is the wrong operational tradeoff, GolemWorkers runs persistent hosted agents without handing that maintenance burden to each team.

Primary material and retained evidence

• OpenClaw v2026.7.1 backup documentation — the archive behavior matched to the tested binary.
• Current OpenClaw backup documentation source — the newer dedicated SQLite snapshot and fresh-target restore contract.
• OpenClaw backup CLI reference — the current operator-facing documentation endpoint.
• NIST SP 800-34 Rev. 1 — contingency planning, testing, and maintenance context.