OpenClaw Off-Machine Backups: A Restore-First Guide for Personal Agents

A backup on the same disk as your personal AI agent is useful for a bad edit. It is not a recovery plan for losing that machine.

OpenClaw's 2026.10.1-beta.1 release notes highlight off-machine backups to external disks, NAS storage, and Cloudflare R2, with visible backup health. The official Backup CLI and storage-location documentation describe the operational details: explicitly initialized destinations, client-side encryption, verified uploads, retention, and staged restores.

That makes this a useful moment to test something more important than whether a backup command exits successfully: can you recover your agent's state without trusting the original host?

This guide is an operator runbook, not a Clawly feature announcement. The release cited is a pre-release, and the documentation can move ahead of installed versions. Confirm that your installed CLI supports these commands before using them; do not switch a production agent to a beta just to follow this article.

1. Define what you need to recover

For a personal agent, recovery involves more than its workspace. OpenClaw's full archives cover state, configuration, credentials, sessions, and optionally workspaces. Decide which of those your recovery plan requires.

Two flags deserve particular care:

--no-include-workspace omits workspace files, not credentials or agent databases.
--only-config exports the active configuration file, not its $include dependencies. It is not a complete recovery point for a modular configuration.

Preview the scope before creating an archive:

openclaw backup create --dry-run --json

Treat the resulting inventory as sensitive. Review the actual paths and ensure custom agent roots and configuration dependencies are accounted for. The documentation also notes that a full archive is not one atomic snapshot across configuration and all databases; avoid concurrent configuration changes during capture.

2. Put the destination in a different failure domain

The built-in filesystem provider accepts an existing directory on an external disk or mounted network filesystem. Cloudflare R2 is supplied by the Cloudflare plugin, with its own setup and credential requirements.

An external disk protects against some host failures, but a disk permanently attached to that host is not equivalent to a geographically separate copy. Choose the destination based on the failure you need to survive.

For a filesystem destination, mount the intended device and create the directory first. Merge a named storage location into your existing configuration rather than replacing the configuration file. For example, the official documentation uses this shape:

{
  storage: {
    locations: {
      archive: {
        provider: "filesystem",
        settings: { path: "/mnt/archive/openclaw" },
        encryption: {
          passphrase: {
            source: "env",
            provider: "default",
            id: "OPENCLAW_STORAGE_PASSPHRASE",
          },
        },
      },
    },
  },
}

Supply the passphrase through your supported secret configuration and make sure both the CLI and the Gateway process can resolve it. Do not paste the passphrase into a chat, commit it to Git, or assume a variable in your interactive shell is also available to a service.

Keep a recoverable copy of the passphrase in a separate secret manager. Preserve the destination's openclaw-storage.json marker too: the storage documentation warns that losing either can make encrypted objects unreadable.

Only after verifying that the intended destination is mounted, initialize and test it:

openclaw storage init archive
openclaw storage test archive

The test performs a temporary write/read/delete cycle. Initialization is explicit for a reason: an unexpectedly empty mountpoint must not silently turn into a backup directory on the host's system disk. If a previously working destination becomes unavailable, fix the mount or credentials rather than reflexively initializing it again.

3. Create one remote recovery point before scheduling anything

Use a stable namespace so recovery does not depend on remembering an old hostname:

openclaw backup create --to archive --namespace personal-agent
openclaw backup list --from archive --namespace personal-agent
openclaw backup verify --from archive --namespace personal-agent latest

According to the Backup CLI reference, offsite creation verifies the archive locally, uploads it, and confirms its stored size. The separate remote verification step downloads and decrypts the stored object, then applies archive verification. That is a stronger check than observing a successful upload alone.

Two easy mistakes to avoid:

Adding --output retains a local copy that is an ordinary plaintext .tar.gz, even when destination encryption is enabled. Secure that copy separately.
Reusing a namespace across active installations can create ownership or retention conflicts. Use a separate namespace for each concurrent installation, including a running clone. Do not make --claim-namespace a routine workaround for an ownership error.

4. Practice restoration without activating a second agent

Restore to a fresh staging directory outside the live state and agent directories:

openclaw backup restore --from archive --namespace personal-agent latest --target ./restore-drill

The target must be absent or empty. This command stages an extraction; it does not switch the running Gateway to the restored state.

Inspect the archive's manifest.json and its recorded paths. Confirm that the expected configuration, agent state, credentials, and workspace assets are present. Preserve this directory as sensitive recovery material, not as a shareable debugging bundle.

For a stronger drill, perform read-only recovery on a separate controlled machine that has the necessary CLI, storage configuration, and recovery secrets. Do not start a cloned Gateway with live channels or automations enabled. A restore rolls back approvals and delivery/deduplication state, and messaging credentials with ratchet state may require relinking. Activation needs a separate, reviewed recovery procedure.

Archive verification is evidence of structural and database integrity—not proof that every plugin, external account, or workflow will work after activation. Include those dependencies in your recovery checklist.

5. Add retention and monitor freshness, not just the last exit code

Once remote verification and staged restoration work, decide how much history to retain. A documented example is:

openclaw backup create --to archive --namespace personal-agent --keep-daily 7 --keep-weekly 4 --keep-monthly 12

These options can delete older backups in the selected namespace after a successful upload. Review that consequence before enabling them. Retention is a union of UTC calendar buckets, not a promise to retain exactly 23 archives; without retention flags, the command deletes nothing.

Then configure a schedule using the options supported by your installed version. Keeping the destination and namespace from the tested recovery point:

openclaw backup enable --to archive --namespace personal-agent --every 24h --keep-daily 7 --keep-weekly 4 --keep-monthly 12

Inspect existing backup schedules first: re-running backup enable updates the automation for the selected mode rather than creating another independent offsite job. Use your actual destination name and confirm the scheduled command's namespace. Verify that the Gateway's service identity can reach the same mount and secrets as your successful manual test.

A useful monitoring record contains:

The time of the latest successful off-machine backup.
The result of the latest attempt, even when an older success exists.
The destination and namespace used.
The date and outcome of the last remote verification and restore drill.

For a daily schedule, an alert after roughly 36 hours without success is a reasonable starting policy—not an OpenClaw default. Adjust it to the amount of work you can afford to lose.

The practical acceptance test

Your backup plan is ready when you can identify a remote archive, retrieve and verify it, stage its contents safely, and explain how you would reactivate the agent without duplicate actions or missing credentials.

Hosting keeps an agent available. A tested recovery path protects the state that makes it yours.

Sources

Checked October 9, 2026. Release status and capability claims were cross-checked against the project's release notes, implementation record, and official documentation.