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. (On an Everpod pod: backups every day, restores tested, and cancelling deletes the machine, its memory, and its backups together.)