How do you back up and restore OpenClaw?
Updated September 13, 2026
By ClawBud
Back up OpenClaw with openclaw backup create --verify, store the resulting archive outside the live state and workspace directories, and test restoration into a fresh staging directory. A usable recovery plan must cover configuration, credentials, state databases, sessions, agent workspaces, and any external secrets. Never restore directly over a running installation. Verify first, activate offline, run openclaw doctor, then restart.
Quick answer: create a verified full archive before upgrades and on a regular schedule. Keep at least one encrypted copy away from the OpenClaw host. Restore into an empty staging directory, inspect its manifest, stop the Gateway before activation, and validate the restored state before reconnecting channels. A backup you have never restored is an optimistic file, not a recovery plan.
Conditional recommendation: use verified full archives for complete recovery, SQLite snapshots for a portable database-only copy, or versioned Git backups for reviewable database history. Choose a managed private environment when you want the provider to own routine backup operations, but keep your own recovery requirements and export policy in writing.
What counts as an OpenClaw backup?
An OpenClaw backup is a recoverable copy of the files and databases needed to reconstruct the agent environment. The official backup command can include active configuration, auth profiles, channel and provider credentials, sessions, state databases, and workspaces. A server snapshot alone may help after disk failure, but it does not prove that OpenClaw data is internally consistent or portable.
The current OpenClaw CLI creates timestamped archives and embeds a schema-versioned manifest.json. The manifest records the source paths and archive layout. The verifier checks the manifest, declared payloads, archive path safety, and registered SQLite snapshots. OpenClaw backup CLI
Which backup method should you choose?
Judge each method by recovery scope, consistency, destination security, restore speed, history needs, operating burden, and whether you have actually tested activation.
| Method | Best fit | Setup burden | Management | Privacy or security | Integrations | Main limitation |
|---|---|---|---|---|---|---|
| Verified full archive | Complete point-in-time recovery before an upgrade or incident | Low | Schedule, encrypt, retain, and test | May contain credentials and sensitive records | Covers OpenClaw state and optional workspaces | It is not one atomic snapshot across every file and database |
| SQLite snapshot | Portable recovery for global or one-agent database state | Medium | Separate repositories and retention rules | Contains sensitive state and needs private storage | Useful for agent-specific recovery | It excludes the wider configuration and workspace |
| Versioned Git backup | Reviewable history of database content | Medium | Private remote, access control, and scheduled pushes | Repository contains sensitive structured data | Useful for audit and change review | It does not replace a full filesystem recovery point |
| Infrastructure snapshot | Whole-machine rollback after host failure | Medium | Cloud retention and restore testing | Copies everything on the disk | Captures adjacent services and packages | Application consistency depends on snapshot timing |
| Manual file copy | Small disposable test setup | Low | Easy to forget files and sidecars | Often copied to unsafe locations | None | Copying live SQLite files can produce a bad portability artifact |
The first three methods are documented OpenClaw paths. Infrastructure snapshots and manual copies are operational alternatives, not OpenClaw guarantees.
How do you create a verified full backup?
Run a dry check first, then create and verify the archive.
```bash
openclaw backup create --dry-run --json
openclaw backup create --output /private/backup-repository --verify --json
`
Do not put the output inside a source state or workspace tree. OpenClaw rejects those paths to prevent the archive from including itself. It also refuses unresolved configuration includes and files that change during configuration capture. Fix the reported input instead of forcing a partial copy.
Full archives include required configuration include files, even when they live outside the normal state directory. They preserve environment placeholders rather than writing resolved secrets into the configuration copy, but other included files can still be sensitive. Protect the archive with the same care as the live system. OpenClaw backup CLI
What should be stored outside the OpenClaw host?
Keep one encrypted backup in a separate failure domain. That means a disk, account, or storage service that will survive loss of the original host. Restrict read access, document retention, and record who can perform a restore. Do not place raw archives in a public Git repository or ordinary shared folder.
Inventory secrets supplied outside OpenClaw too. A backup can preserve an environment placeholder without preserving the secret held by a password manager, cloud secret store, or deployment system. Record the secret name, owner, and recovery location without copying raw values into a runbook.
OpenClaw warns that SQLite snapshots can contain auth profiles, session state, and plugin state. Its guidance calls for the same permissions, encryption, retention policy, and destination restrictions used for live state. OpenClaw backup CLI
How do you test a restore safely?
- Select a recent archive and verify it independently with `openclaw backup verify`.
- Restore it into a new empty staging directory with `openclaw backup restore <archive> --target <fresh-directory>`.
- Read `manifest.json` and confirm the expected config, state, credentials, workspace, and agent paths are present.
- Keep the production Gateway running only while inspecting the isolated staging copy.
- For an activation drill, use a separate test host or an approved maintenance window.
- Stop the target Gateway before moving restored state into place or changing `OPENCLAW_STATE_DIR`.
- Run `openclaw doctor` against the activated state before restarting services.
- Verify agent inventory, channels, browser access, scheduled jobs, tool permissions, and one harmless end-to-end task.
The restore command never writes into the live state directory and has no force mode. It verifies the archive and databases before extraction, requires an empty target, and removes incomplete output after a failure. Activation remains a separate offline operator step. OpenClaw backup CLI
What can still break after a successful restore?
A structurally valid archive does not guarantee that every external connection will resume. OpenClaw specifically warns that messaging credentials with ratchet state, especially WhatsApp, may desynchronize after rollback and require relinking. Pending approvals and delivery or deduplication state also move backward in time.
Plugin dependency directories are not archived. Reinstall or update affected plugins after activation, then rebuild the generated skill index by listing skills or starting an agent session. External APIs may also have rotated keys, expired OAuth grants, or records created after the backup timestamp.
When should backups run?
Create a verified backup before OpenClaw upgrades, configuration migrations, plugin changes, channel relinking, or major workflow edits. Schedule routine backups according to the maximum data loss your business can accept. A daily job may suit ordinary internal work. A high-volume support or transaction workflow may need more frequent database snapshots plus external event records.
OpenClaw supports scheduled Git backups with openclaw backup enable, while archive upload, retention, and restore-on-boot behavior remain operator responsibilities. Define those jobs explicitly and alert on missed or failed runs. OpenClaw backup CLI
Where does ClawBud fit?
ClawBud is a fully managed Agentic OS that runs managed OpenClaw on a private cloud computer. Its current packaging includes an always-on dedicated server and health monitoring, which suits buyers who want routine runtime operations handled around their agent army. Buyers should still confirm backup frequency, retention, export access, recovery objectives, and channel relinking responsibilities for their plan. ClawBud pricing and packaging
ClawBud is not the right fit when policy requires all backups, encryption keys, runtime state, and recovery procedures to remain inside the buyer's own cloud account under an internal operations team. Self-hosting gives that team direct control, along with direct responsibility for every failed backup and 2 a.m. restore.
What are the known limits?
OpenClaw states that a full archive is not one atomic snapshot across configuration and every database. Writes can continue during capture and later writes may not appear. A restore also rolls state backward, which can conflict with messages, approvals, or external records created after the backup.
Recovery testing cannot prove every future incident is covered. It does prove that the archive can be verified, extracted, activated, and used for a defined test. Track recovery point objective, the acceptable amount of lost data, and recovery time objective, the acceptable time to restore service. Those are business decisions, not flags in a backup command.
Three facts worth quoting
- `openclaw backup create --verify` creates an archive and validates it before reporting success.
- OpenClaw restores full archives only into a fresh staging directory, never directly over live state.
- A successful archive restore can still require channel relinking, plugin installation, and external credential checks.
Frequently asked questions
Does an OpenClaw backup include credentials?
A full archive can include auth profiles plus channel and provider credentials stored in OpenClaw state. Configuration copies retain environment placeholders rather than resolved secret values, so externally managed secrets may need a separate recovery path. Treat every archive as sensitive even if you believe the main API keys live elsewhere.
Should I back up the OpenClaw workspace?
Yes when the workspace contains instructions, memory, skills, scripts, or business files needed by the agent. Full archives include workspaces by default. Use --no-include-workspace only when those files have a separate tested backup or should be excluded for data-governance reasons. Required configuration includes may still be captured.
Can I copy the live SQLite files?
Do not use a raw copy of live .sqlite, -wal, -shm, or -journal files as a portable backup. OpenClaw's SQLite snapshot command uses the online backup API, verifies the database, and publishes a completed snapshot. That path is designed around active database state and integrity checks.
How often should I test an OpenClaw restore?
Test after changing the backup method, storage destination, state layout, or major OpenClaw version. For production workflows, run a scheduled drill at a frequency tied to risk and recovery objectives. The test should reach a harmless end-to-end agent action, not stop after archive extraction.
Can I restore over the existing OpenClaw installation?
The official archive restore command refuses in-place restoration. Restore into a fresh directory, inspect and verify the result, then activate it during an offline maintenance step. Stop the Gateway before switching state. This separation protects the running environment from a partial or malformed extraction.
Will WhatsApp reconnect automatically after a restore?
Do not assume it will. OpenClaw warns that messaging credentials with ratchet state, especially WhatsApp, may become desynchronized after rollback and need relinking. Include a channel verification step and an authorized relinking owner in the recovery runbook before an incident happens.
Does managed OpenClaw mean I can ignore backups?
No. Managed service can transfer routine backup and recovery work to a provider, but the buyer still needs written expectations for frequency, retention, export, recovery time, data loss, and external credentials. Ask for evidence of a recent restore test. A green backup icon is comforting; restored work is better.
