Run an OpenClaw agent for more than a month and you will eventually have a bad day. Mine arrived when a careless config edit left the Gateway refusing to start. Months of trained workflows, channel tokens, and session history were suddenly sitting behind a broken file, and the only thing standing between me and a full rebuild was one archive I had created two days earlier.
That is the whole point of a backup. It turns a disaster into a chore. This guide is the routine I actually run on my own installation, plus the restore steps I verified end to end on OpenClaw 2026.7.1-2. You will see the real command output, the parts of your install the archive quietly skips, and the exact way to bring an agent back when the normal command is not there at all.
Why copying the .openclaw folder by hand will bite you
Almost everyone’s first instinct is to drag the folder onto an external drive. It feels safe because all the files are right there. But OpenClaw keeps its authoritative state in SQLite, not in flat files, and SQLite does not behave like a document.
Two databases matter most. The shared control plane lives at ~/.openclaw/state/openclaw.sqlite, and every configured agent keeps its own database at <agentDir>/openclaw-agent.sqlite. Both are written continuously while the Gateway runs, and both use a write-ahead log, which is why you will see openclaw.sqlite-wal and openclaw.sqlite-shm sitting next to them.
Here is the trap. Recent committed writes can live in the -wal file and may not be merged into the main database yet. Copy the .sqlite file on its own and your newest sessions simply vanish. Copy the pieces mid-write and you can hand yourself a database that refuses to open. Never copy live .sqlite, -wal, or -shm files and call it a backup.
The one command that gets it right
OpenClaw ships a backup command that handles all of this for you. It pins the config, snapshots each database through SQLite’s online backup API, and writes the result into a single timestamped archive with a manifest that proves what is inside.
Before you trust any backup routine, prove it works on something small. This config-only run finishes in about a second and gives you the confirmation line you are looking for:
That last line is the one that counts. Archive verification: passed means the manifest and the payload agree with each other. Now the full archive, which is the command you will actually schedule:
openclaw backup create --output ~/Backups/openclaw --verify
Two behaviors are worth knowing before you run it. The default output is a timestamped tar.gz in your current directory, but if you run it from inside a backed-up source tree, OpenClaw falls back to your home directory so it cannot archive itself. Existing archives are also never overwritten, so repeated runs stack new files instead of destroying old ones. Great for retention, less great if disk space is tight.
If you want to see the plan before writing a single byte, add --dry-run --json. It prints the archive path, every asset it will capture, and every path it skipped along with the reason.
What is actually inside the archive
An OpenClaw archive is not a mystery blob. It is a tar.gz with a predictable shape: one manifest.json at the root, then a payload/ tree that mirrors the original absolute paths. A file that lived at /Users/you/.openclaw/openclaw.json comes back under payload/posix/Users/you/.openclaw/openclaw.json.
Open the manifest and you get a full record of the run. On my machine the state directory appeared as a single root asset, and each agent workspace showed up in a skipped list marked "reason": "covered", because they already sit inside ~/.openclaw. One workspace was flagged "reason": "missing", the quiet diagnostic that tells you a configured agent never got its workspace created. Reading that list is the difference between a backup that succeeded and a backup you actually trust.
Restoring when the restore command does not exist
Here is the part the documentation glosses over, and it cost me twenty minutes of confused typing. The published docs show a tidy openclaw backup restore <archive> --target <dir> command. On a 2026.7.1 build, that subcommand is not there:
So on this version, restore means extracting the archive yourself. That is less scary than it sounds, because the payload already mirrors the paths you need.
Activation steps that actually work
Extraction is only half the job. The other half is putting the bytes back in front of the Gateway while it is stopped.
- Stop the Gateway. Use
openclaw gateway stopor the daemon command for your platform, and confirm nothing is still holding the state directory. - Extract into a staging directory that lives outside your live state directory, never on top of it.
- Verify before you swap anything. Compare the restored config against the original with
diff, and confirm the manifest’s assets are all present inpayload/. - Move the payload into place or point
OPENCLAW_STATE_DIRat the restored asset. Pointing an environment variable at the staged copy is the safer choice if you are not sure yet. - Run
openclaw doctorbefore you restart, so config and channel problems surface while nothing is live.
One warning worth repeating: restoring is time travel. Messaging credentials that rely on ratchet state, WhatsApp especially, can desynchronize after a rollback and need to be relinked. Approvals and delivery dedupe state roll back too, so review anything pending before you bring the Gateway back up.
Put it on a schedule you will not forget
A backup you remember to run is not a backup. Newer builds add openclaw backup enable --repository ~/Backups/openclaw-git --every 24h --push to schedule this for you, but that subcommand is missing on 2026.7.1 too, so I schedule it myself. On the macOS machine that runs this site’s agent that means a launchd job; on Linux, cron does the same work:
0 3 * * * /opt/homebrew/bin/openclaw backup create --output ~/Backups/openclaw --no-include-workspace --verify >> ~/Backups/openclaw/backup.log 2>&1
Two flags earn their place in a nightly run. --no-include-workspace keeps the archive focused on state, config, and credentials, which keeps it small enough to run every night without chewing through disk. --verify re-validates the manifest each time, so a corrupt archive fails loudly on the night it happens instead of on the day you need it.
For how OpenClaw’s own cron and heartbeat scheduling interact with system jobs, see our guide to OpenClaw scheduling. Getting the timing wrong is how two jobs end up fighting over the same state directory.
If your hosting is the bottleneck: Kinsta keeps your site safe with automatic daily backups and one-click restore, so a bad update or a hack is a rollback, not a rebuild. Their support is top tier, and 24/7 live chat is staffed by WordPress engineers who will help fix the actual problem with you, so you are not stuck waiting on your developer to reply. Plans start at $35 per month.
Common mistakes that create false confidence
- Backing up into the state directory. OpenClaw rejects output paths inside the source trees to avoid self-inclusion. If your archive path lives under
~/.openclaw, the run fails or lands somewhere unexpected. - Treating
--only-configas your whole strategy. It is a root-file export only. It skips$includedependencies, so a modular config comes back broken. Use it to test the pipeline, not to protect it. - Never testing a restore. An archive you have not extracted is a hypothesis. Extract one into a scratch directory once a quarter and prove the bytes are readable.
- Storing the archive unencrypted. It contains auth profiles, channel tokens, and session history. Treat it exactly like the live state directory, restrict who can read it, and rotate credentials if you think it leaked.
- Forgetting plugins. Plugin
node_modulestrees are not archived. After activating a restored state, runopenclaw plugins update <id>or reinstall, then start a session so the skills index rebuilds.
If you have been living through a broken config already rather than planning ahead, our walkthrough on fixing a redacted-secrets gateway failure covers the other half of this problem, and it pairs well with the safe rollback guide if an update is what broke you.
Check out our Complete OpenClaw Guide. Setup, channels, skills, and automation in one place, so you can get your agent running before you worry about protecting it.
Read the GuideFor a small install, a nightly archive with --no-include-workspace is plenty, and it stays small because it captures state, config, and credentials rather than every workspace file. If your agent writes a lot of data each day, run the full archive before any update, reset, uninstall, or machine move, since those are the moments that actually put your state at risk.
No. OpenClaw keeps its authoritative state in SQLite databases that are written continuously while the Gateway runs, so a raw copy can capture a torn or partially checkpointed file. Recent committed writes can also still live in the -wal file and be missing from the main database. Use openclaw backup create, which snapshots each database safely through SQLite’s online backup API.
Because not every build ships the restore subcommand. OpenClaw 2026.7.1-2 only includes create and verify, even though the published docs show backup restore, backup sqlite, and backup git. On those builds you restore by extracting the tar.gz into a staging directory and moving the payload into place while the Gateway is stopped.
Three things matter most. Plugin node_modules trees are not archived, so reinstall or update plugins after activation. The generated plugin-skills symlink index is omitted and rebuilds on the next session. Live .sqlite, -wal, and -shm files are replaced by consistent database snapshots rather than copied as-is.
It works, but restoring is time travel. Credentials that use ratchet state, WhatsApp in particular, can desynchronize after a rollback and need relinking. Approvals and delivery dedupe state also roll back, so review anything pending before you restart the Gateway. Backing up also captures sensitive credentials, so store the archive encrypted.
Final Thoughts
Backing up an OpenClaw setup is a ten minute job you do once and then schedule, and it is the cheapest insurance you will ever buy for an agent that has grown into a real part of your workflow. The command handles the hard part, the SQLite snapshots, for you. Your job is to read the skipped list, keep the archive encrypted, and extract it once in a while so you know it works.
If you are still at the beginning of the journey and have not installed OpenClaw yet, start with our 30 minute OpenClaw setup guide. Set the backup schedule on day one, while your agent is still small and the archive is still fast.
About The Author
