Backing up an OpenClaw agent (and actually restoring it)
One directory holds everything your agent is. How to back it up, what a real restore test looks like, and why backups carry secrets.
Everything your agent is lives in one place — ~/.openclaw (plus auth secrets under ~/.config/openclaw in some setups) — so a backup is an archive of a directory, and a restore is putting it back on a machine with the same OpenClaw version. The two rules that make it real: test one restore before you trust the scheme, and treat every backup as the sensitive object it is — it contains your agent’s memory and credentials.
What to back up
The state directory holds config, sessions, workspace, memory, installed skills, and channel credentials. Archive it and you’ve archived the agent:
tar -czf openclaw-backup-$(date +%F).tar.gz \
~/.openclaw ~/.config/openclaw 2>/dev/nullQuiesce first when you can (openclaw gateway stop, archive, start again) — archiving a live directory usually works, but a stopped one can’t be mid-write. On a VPS, provider machine backups (typically ~20% of the instance price) or snapshots do this at the disk level and are worth having as well — they protect against the machine dying, while the tarball protects against everything else: fat-fingered deletion, a bad update, migrating homes.
The restore (and the test that makes it true)
Restoring is the mirror: same OpenClaw version installed, unpack the archive to the same paths, start the Gateway. The agent comes back as itself — identity, memory, config, channels; we’ve watched restored agents resume Telegram conversations as if nothing happened. Which is exactly why the untested backup is the industry’s oldest sad story: a backup you’ve never restored is a hope. The test costs twenty minutes, once: spin up any scratch machine (or container), restore into it, start the Gateway, confirm the agent knows who it is. Now you have a scheme, not a wish.
- Match versions when restoring — restore into the version the backup came from, then update deliberately if you want newer. Restoring old state into much newer software asks it to migrate under the worst conditions.
- Automate the schedule — a cron’d tarball to somewhere off the machine beats twelve good intentions. Daily is right for an agent you use daily.
Backups are secrets with a timestamp
The archive contains your agent’s memory of your life, its model key, and its channel credentials. Three consequences worth writing down: store backups somewhere with the same care as the machine itself (not a world-readable bucket); rotate or encrypt them if they leave your control; and when you delete an agent for good, the backups are part of the deletion — an agent isn’t gone while a copy of its mind sits in an old snapshot. (This is the standard we hold pods to: automatic backups, restore actually rehearsed, and cancellation deletes machine, memory, and backups together.)