# How to Back Up OpenClaw by Hand (and Restore It Anywhere)

> What an OpenClaw backup must include, a tar command that captures it all safely, the three ways restores break, and the one-command cloud restore.

- Published: 2026-08-13 · Updated: 2026-08-13 · jurniti
- Canonical: https://www.jurniti.com/blog/how-to-back-up-openclaw

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](https://docs.openclaw.ai/install/migrating) 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:**

```bash
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:

```bash
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](/move/openclaw) covers plans, pricing, and
the full manifest walkthrough:

```bash
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](/blog/openclaw-hosting).

## Frequently asked questions

### Where does OpenClaw store its data?

In one state directory: ~/.openclaw by default, or wherever OPENCLAW_STATE_DIR points. Config (openclaw.json), sessions, the SQLite state database, the agent workspace, and channel credentials all live under that single root — which is why the official migration guidance is to treat it as one unit.

### Can I back up just openclaw.json?

No — config alone is not a backup. openclaw.json references state that lives in sessions/ and state/openclaw.sqlite; restore only the config and you get an agent with settings but amnesia. The official docs say to copy the entire state directory, and they mean it.

### Should I stop OpenClaw before backing it up?

Yes. openclaw.sqlite is a live SQLite database with -wal and -shm sidecar files; archiving it mid-write can capture a torn state that looks fine until the day you restore it. Stop the gateway, tar, start it again — the whole pause is seconds.

### Do I need to back up the credentials directory?

Deliberately not. credentials/ holds channel pairing secrets and .env holds API keys — putting those in an archive turns every copy of your backup into a full credential set. Exclude them and re-link channels and re-enter keys on the machine you restore to.

### Why won't my restored OpenClaw start?

The most common cause is ownership: an archive extracted with sudo leaves ~/.openclaw owned by root, and the gateway running as your user can't read its own state. chown -R the tree back to the runtime user. The next most common causes are a partial copy and a database archived mid-write.

### Can I restore an OpenClaw backup on a different machine?

Yes — OpenClaw's state is path-agnostic, so migrating is exactly the backup-restore mechanism: move the whole state dir to the new machine, fix ownership, start the gateway, re-enter keys and re-pair channels. That's also how `jurniti transfer` restores it into a cloud VM.

### How often should I back up OpenClaw?

Every time losing the interval would hurt — for an agent accumulating memory and conversation history daily, that's daily, plus one before every upgrade (OpenClaw upgrades have broken configs before). If a manual ritual won't survive your calendar, move the state to an always-on VM once instead.