Backing up an OpenClaw agent (and actually restoring it)

What an OpenClaw backup holds

Your agent is more than its workspace files. Current OpenClaw keeps its working state in SQLite databases: one shared database in the state directory (usually ~/.openclaw) and one per agent, which between them hold its conversations, its model sign-ins and its running state. Beside them sit the configuration file, the channel credentials such as a WhatsApp login, and the workspace with MEMORY.md, SOUL.md, skills and the rest of what makes the agent itself. The backup command finds all of these from your configuration, including agent folders kept somewhere other than the default:

mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify

The result is a timestamped .tar.gz with a manifest.json recording where every part came from and which OpenClaw version made it. --verify checks the archive and its databases straight after writing it. The command copies the databases safely while the agent is running; stop the Gateway first (openclaw gateway stop) when the backup is for a move or an update, so nothing changes between the databases and the files.

Two things are left out on purpose, and the backup reference lists the rest: the installed code of plugins, which you reinstall after a restore, and running logs. Do not make your own backup by copying the .sqlite files of a running agent: recent changes can still be sitting in the files beside them, and the copy can come out torn.

Restore, and the test that makes a backup real

A restore never writes over your live agent. It checks the archive and unpacks it into a folder that must be empty:

openclaw backup restore ~/Backups/openclaw/<archive>.tar.gz --target ~/openclaw-restored

Putting it into use is a separate step you do with the Gateway stopped: move the restored state folder into place, or point OPENCLAW_STATE_DIR at it, using manifest.json to see where the configuration, credentials and workspace belong; then run openclaw doctor and start the Gateway. The backups guide in OpenClaw’s documentation covers custom agent folders and restoring single databases.

Restore into the same OpenClaw version the backup came from or a newer one, never an older one, and update deliberately from there. Newer versions migrate older data, but an older version cannot read data a newer one has migrated, which is why the backup taken before an update is the way back from a bad one (the rollback guide walks through it). A restore is also time travel: everything after the backup is gone, a WhatsApp connection may need linking again, and pending approvals roll back with it.

Restored properly, the agent comes back as itself, with its identity, memory, settings and channels, and it picks up its Telegram conversations where they left off. Which is why a backup you have never restored is a hope. The test takes twenty minutes, once: restore into a scratch machine or a spare folder, start the Gateway against it, and ask the agent what it remembers about you.

Make it a routine

From OpenClaw 2026.10.1 the Gateway can send the full archive, workspace included, to a named storage location on a schedule: a folder on an external disk or a mounted network share, or a Cloudflare R2 bucket through OpenClaw’s Cloudflare plugin. Each run is checked after the upload and encrypted with your passphrase before it leaves the machine. Add the location to your configuration; the folder must already exist, and OPENCLAW_STORAGE_PASSPHRASE must be set both where you run the commands below and in the Gateway’s environment:

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

Then prepare and test the location, and hand the schedule to the Gateway:

openclaw storage init offsite
openclaw storage test offsite
openclaw backup enable --to offsite --every 24h --keep-daily 7 --keep-weekly 4 --keep-monthly 12

That runs it daily, which suits an agent you use daily. After each successful upload the --keep flags delete all but the newest backup of each of the last seven days, four weeks and twelve months; without them nothing is ever deleted. Keep the passphrase somewhere other than the machine it protects: without it, or without the openclaw-storage.json file that storage init writes in the location, the archives cannot be read. The schedule runs inside the Gateway, so it runs only while the Gateway does. openclaw status shows when the last backup succeeded, and openclaw doctor warns when one failed or is overdue. Restoring from the location starts with openclaw backup restore --from offsite latest --target <empty folder>, then goes on as above; each machine’s backups are filed under its hostname, so on a new machine add --namespace <old hostname>.

The Gateway can also commit the databases to a Git repository you own, one commit per run and none when nothing changed, and the two schedules can run side by side:

openclaw backup git init --repository ~/Backups/openclaw-git --remote <private-git-url>
openclaw backup enable --repository ~/Backups/openclaw-git --every 24h --push

A pushed Git schedule leaves the credential-bearing tables out unless you add --include-secrets, so restoring from it means signing in to your model providers and pairing devices again, and it does not cover the workspace files. On 2026.9.9 and earlier it is the only schedule there is, so keep the archive above in the routine too: a daily openclaw backup create --verify from your scheduler, copied off the machine.

Backups are secrets with a timestamp

The archive holds your agent’s memory of your life, its model sign-ins and its channel credentials. Keep it where only you can read it, encrypt it if it leaves your machine (an archive made with --output is a plain .tar.gz; one sent to a storage location is encrypted unless you set its encryption to "none"), and rotate the keys inside if one ever leaks. When you delete an agent for good, its backups are part of the deletion: an agent isn’t gone while a copy of its mind sits in an old archive. (On Everpod’s OpenClaw pod, backups run every day with restores tested, and cancelling deletes the machine, its memory and its backups together.)

Moving your agent to another computer is the same backup and restore with a transfer in between; moving OpenClaw to a new computer covers what else changes on the way.