An OpenClaw agent that's been running for months is not a config file. It's accumulated memory, conversation history across every channel, a workspace of skills, and a SQLite database tying it together — all in one directory on one machine, usually a laptop. Lose the directory, lose the agent.
The good news: backing it up properly is a two-minute job, and the official docs are unambiguous about what "properly" means. The bad news: most of the backups people actually make fail one of three quiet ways, and they find out during the restore. Here's the by-hand method in full — every path, the exact tar command, the failure modes — and then the one-command version that restores into a cloud VM instead of another fragile laptop.
Where OpenClaw keeps everything
One root: ~/.openclaw (or wherever OPENCLAW_STATE_DIR points). The
official migration doc says to
copy the entire state directory, and the layout explains why — the pieces
reference each other:
| Path | What it is | Belongs in a backup? |
|---|---|---|
~/.openclaw/openclaw.json | Gateway, channel, and model config | Yes — but it embeds API keys and bot tokens, so a raw copy is also a secret leak |
~/.openclaw/sessions/ | Conversation sessions — the agent's memory of every chat | Yes |
~/.openclaw/state/ | openclaw.sqlite (plus -wal/-shm sidecars) — the durable brain | Yes, and only when the gateway is stopped |
~/.openclaw/workspace/ | Agent workspace: skills, files, working memory | Yes |
~/.openclaw/credentials/ | Channel pairing secrets (WhatsApp, Discord, Signal, Telegram) | No — re-link on the destination |
~/.openclaw/.env, secrets.json, agents/*/agent/auth-profiles.json | Provider keys and per-agent auth | No — re-enter on the destination |
The split in that last column is the design decision that makes a backup safe to store: state travels, secrets never do.
How to back up OpenClaw by hand
Three steps, in this order.
1. Stop the gateway. openclaw.sqlite is a live database. Archive it
mid-write and the -wal sidecar can hold committed data the main file
doesn't have yet — a torn snapshot that restores into subtle corruption.
Stop the process (Ctrl-C, or stop its service unit), then archive.
2. Tar the state dir, excluding secrets:
tar -C ~ \
--exclude='.openclaw/credentials' \
--exclude='.openclaw/.env' \
--exclude='.openclaw/secrets.json' \
-czf openclaw-backup-$(date +%F).tar.gz .openclaw
3. Move the archive off the machine. A backup on the same disk insures you against nothing that matters. Object storage, another box, anywhere — just not the laptop whose failure you're planning for.
Restore is the mirror image: extract into the destination home directory, fix ownership if you extracted with sudo, start the gateway, then re-enter keys and re-pair channels:
tar -C ~ -xzf openclaw-backup-2026-08-13.tar.gz
sudo chown -R youruser: /home/youruser/.openclaw # only if extracted as root
That's the complete honest method. It works. The failure modes live in the gaps between those steps.
The three ways an OpenClaw restore breaks
Ownership after a root copy. Extract or scp as root and the whole tree
lands owned by root; the gateway, running as your user, can't read its own
state and fails in ways that don't say "permission denied" anywhere helpful.
The migration doc calls this out for a reason — it's the top restore bug. One
chown -R fixes it; knowing to run it is the hard part.
The partial copy. Someone backs up openclaw.json and calls it done, or
grabs sessions/ but not state/. The pieces are interdependent: config
without state is an agent with settings and no memory; state without the
workspace is memory referencing skills that aren't there. Whole directory or
it isn't a backup.
The mid-write database. The cron job that tars a running gateway produces archives that extract cleanly, list cleanly, and restore a database missing its last writes. Nothing errors until the restore, weeks later, when the original is already gone.
There's also the quieter failure baked into the destination: a perfect archive restored onto another laptop is an always-on agent on a sometimes-off machine. You've moved the fragility, not fixed it.
Restoring an OpenClaw backup into a cloud VM
jurniti transfer is the backup-and-restore above, implemented as one
command, with a destination that stays on. It reads your local state dir into
a temp copy, drops everything in the never-travels column, redacts the secret
fields inside openclaw.json, and shows you the manifest before anything
uploads. The dry run is free and needs no account:
$ jurniti transfer --harness openclaw --dry-run
Found local OpenClaw state (1876 files, 216.4 MiB).
Transfer manifest — OpenClaw
keep .openclaw/ 1874 file(s) 216.1 MiB
total 1874 file(s), 216.1 MiB
never uploaded (credentials — you'll re-enter keys in the VM):
.openclaw/.env
.openclaw/secrets.json
redacted 4 secret-bearing field(s) in: .openclaw/openclaw.json
sessions: 97 session file(s) travel with you
Dry run — nothing was uploaded. Re-run without --dry-run to transfer.
On a machine with paired channels, everything under credentials/ and any
per-agent auth-profiles.json joins the never-uploaded list automatically.
Re-run without --dry-run and the archive streams straight into a dedicated
Firecracker microVM where OpenClaw is already installed — extracted with the
right ownership, gateway restarted, no 2 a.m. checklist. Your laptop's copy
is never touched, so it doubles as your rollback.
What must never be in the archive
Worth stating as its own rule, because every DIY recipe has to re-derive it:
a backup that contains credentials/, .env, or secrets.json is a
complete impersonation kit for your agent — bot tokens, provider keys,
channel pairings — sitting in cold storage wherever copies of it end up.
The transfer enforces the rule client-side: credential files are dropped and config key-fields redacted on your machine, before upload, and the manifest prints exactly what was dropped so you can verify rather than trust. On the VM you re-enter model keys (BYOK — your key lives in your VM, and model traffic never routes through jurniti) and re-pair channels fresh, which also prevents your laptop and the VM from fighting over the same WhatsApp or Discord identity.
From backup ritual to one command
If you run OpenClaw on a machine you control and enjoy operating, do the manual method above — it's complete, and it's the same mechanism the official docs describe for migration. Set a calendar reminder for the tar, another for testing a restore, and one before every upgrade.
If what you actually want is the agent — its memory intact, on hardware that doesn't sleep, with the backup problem dissolved rather than scheduled — the OpenClaw backup-and-restore page covers plans, pricing, and the full manifest walkthrough:
jurniti transfer --harness openclaw
For the broader case for running the gateway on a dedicated microVM in the first place — isolation, channels, BYOK — see the self-hosting OpenClaw guide.