Updates break things. A backup that takes thirty seconds to make can save hours of rebuilding. Here's the one command that does it properly, what it captures, and how to get back if the update goes wrong.
The most upvoted comment in every "update broke my agent" thread this year says the same thing: I stop OpenClaw and back up first now. Learned the hard way, every time.
The good news is that OpenClaw ships a backup command that does this correctly, and most people don't know it exists. The bad news is that the way most people back up by hand (copying the folder while the Gateway is running) can produce an archive that doesn't restore. Here's the right way, short.
What actually needs backing up
Everything lives under the state directory, ~/.openclaw by default, plus your agent workspace. The pieces that matter:
| What | Where | Why it matters |
|---|---|---|
| Config | openclaw.json | Gateway settings, channels, model choices |
| Shared auth and control state | state/openclaw.sqlite | API keys, OAuth, and the record of everything |
| Per-agent state | agents/<id>/agent/openclaw-agent.sqlite | That agent's auth profiles, sessions, runtime state |
| Channel and provider credentials | credentials/ | Telegram session, WhatsApp login, Discord pairing |
| Workspace | AGENTS.md, SOUL.md, MEMORY.md, USER.md, skills/ | Who your agent is and what it remembers |
| Scheduled work | cron jobs, stored in the databases above | Everything that runs unattended |
Here's the part that catches people. The config file alone is not enough, and the docs say so directly: shared model auth lives in the SQLite database, agent auth lives in a second one, and channel state lives under credentials/. Copy only openclaw.json and you'll restore an agent that has forgotten every login it ever had.
Never copy live
.sqlite,-wal,-shm, or-journalfiles as a backup. The Gateway writes to them continuously. A raw copy of a live database can be torn or corrupt, and you won't find out until the restore fails.
That's from OpenClaw's own backup guide, and it's why the "just cp -r the folder" advice in most forum threads is only half right. It works if the Gateway is stopped. It's a coin flip if it isn't.
The backup command
One line. Run it before every update.
openclaw backup create --output ~/Backups/openclaw --verify
That writes a timestamped .tar.gz covering the state directory, the config, credentials/, every configured agent directory, and your workspace, then verifies the archive's manifest and payload. It captures the SQLite databases with SQLite's online backup API, so it's safe to run while the Gateway is up. Stopping first is still the safer habit before an update, but the archive itself won't be torn either way.
A few flags worth knowing. --dry-run --json shows what would be captured without writing anything. --no-include-workspace skips workspaces if yours are huge or already in Git. --only-config is a quick config-only snapshot. And openclaw backup verify <archive> rechecks an old archive before you rely on it.
Two things the archive deliberately leaves out: plugin node_modules/ trees (rebuildable; reinstall the plugin after a restore) and live session transcripts, cron run logs, and delivery queues (no restoration value). The JSON output reports how many volatile files it skipped so you can see it wasn't an error.
Then note your version, because you'll want it for the rollback section:
openclaw --version
How to restore after a broken update
Restore is deliberately two steps: stage, then activate. Nothing overwrites live state in place, and there is no force or in-place mode. That design is what makes it safe, and it's also the source of the disk-space requirement people trip over.
Stage the archive into a fresh directory
openclaw backup restore ~/Backups/openclaw/<archive>.tar.gz --target ./restored-openclaw
The target must be new or empty, and it must not be inside the live state directory. OpenClaw verifies the archive structure, manifest, symlink containment, and every SQLite database before writing. A failed extraction cleans up its own partial output.
This is the disk-space catch: a restore needs enough free space for a full second copy of your state, because it never extracts over the live one. If the staging copy can't be prepared, the restore fails before touching anything. Check free space before you start, and if you're on a small VPS, stage to a mounted volume or clear old archives first.
Activate it, offline
- Stop the Gateway and any node hosts using the files.
- Back up or move aside the current (broken) state directory.
- Move the restored state asset into place, or point
OPENCLAW_STATE_DIRat it. Use the archive'smanifest.jsonfor the original paths; don't guess from the default layout. - Run
openclaw doctor. - Start the Gateway and check
openclaw health.
Restoring an archive is time travel. WhatsApp and other channels with ratchet state may need relinking after a rollback, and pending approvals and delivery state roll back too. Review approvals before you let the agent resume.
After activation, reinstall any plugin that reports missing dependencies with openclaw plugins install <spec> --force, and run openclaw skills list to regenerate the skills index.
How to roll back the version itself
Sometimes the state is fine and the release is the problem. For that, use the updater's own rollback rather than a raw npm i -g, because the updater retains the previous package, runs the required Doctor migrations, and verifies the Gateway comes back:
openclaw update --tag <known-good-version> --dry-run
openclaw update --tag <known-good-version>
It asks for downgrade confirmation. If your channel is extended-stable, add --channel stable for a one-off exact tag. If the auto-updater is enabled, set OPENCLAW_NO_AUTO_UPDATE=1 in the Gateway's environment during recovery so it doesn't immediately reapply the newer release.
One rule the docs are firm on: if the older version refuses to start because the schema or config was migrated forward, do not edit version markers to force it. That's what the pre-update archive is for. Restore it as above, then roll the package back. The full sequence, and the nine specific ways a Gateway fails after an update, is in OpenClaw Gateway won't start after updating.
The habit, in four lines
openclaw backup create --output ~/Backups/openclaw --verify
openclaw --version # write it down
openclaw update
openclaw doctor # and check the defaults that changed
That last comment matters this month. The 2026.9.2 release flipped two defaults (swarm on, cross-agent session visibility on) that a clean backup won't protect you from; the 2026.9.2 update breakdown covers what to review after you're back up. And openclaw doctor will now nag you if your newest successful backup is more than 14 days old, which is the project's way of saying the same thing this post is.
What BetterClaw does differently
There's no backup step on BetterClaw because you never run the update. We stage releases, snapshot each agent's state before applying, migrate config before restart, and roll the agent back automatically if the release breaks it. Your SOUL.md, memory, credentials, and cron jobs are isolated per agent in their own container and never depend on you remembering a command at 11pm. If you'd rather spend the thirty seconds on your agent than on its infrastructure, that's the whole idea. Free plan, bring your own keys.
If any of this resonated, give BetterClaw a try. Free plan with 1 agent and 100 credits a month, bring your own API keys, no inference markup. Pro is $49 a month for 5 agents. Updates, backups, and rollbacks are ours to worry about. Start free or see full pricing.
Frequently Asked Questions
What is the correct way to back up an OpenClaw agent?
Run openclaw backup create --output <dir> --verify. It writes a timestamped, verified .tar.gz of the state directory (~/.openclaw by default), openclaw.json, credentials/, every agent directory, and your workspace, capturing the SQLite databases safely with the online backup API. Copying the folder by hand only works if the Gateway is stopped, because raw copies of live databases can be corrupt.
How does openclaw backup compare to copying ~/.openclaw manually?
The command is safe with the Gateway running, verifies the archive, skips volatile files that have no restoration value, and records a manifest so restore knows the original paths. A manual copy is fine only if the Gateway is stopped first, and it's easy to miss the workspace if it lives outside the state directory. Either way, copying just openclaw.json is not a backup: auth and channel state live in SQLite and credentials/.
How do I restore an OpenClaw backup after an update breaks my setup?
Stage it first with openclaw backup restore <archive> --target <new-empty-dir>, which verifies and extracts without touching live state. Then stop the Gateway, move the broken state directory aside, move the restored one into place (or point OPENCLAW_STATE_DIR at it), run openclaw doctor, and start. Expect to relink WhatsApp and review pending approvals, since restore rolls those back too.
How much disk space does an OpenClaw restore need?
Enough for a full second copy of your state directory and workspace, because restore extracts to a fresh target and never overwrites in place. If the staging copy can't be created, the restore fails before changing anything. On a small VPS, clear old archives or stage to a mounted volume first, and consider --no-include-workspace if your workspace is large and already in Git.
Is it safe to keep OpenClaw backups on the same server?
It's better than nothing and worse than offsite. Archives contain auth profiles, channel credentials, and full session history, so store them encrypted with permissions as tight as the live state directory, and copy them off the machine (the docs show rclone to an S3-compatible bucket). If you suspect an archive leaked, rotate the credentials in it. For continuous protection, the docs also cover Litestream replication of the databases.
