The 5-step safe update routine
Follow these every time you update. Tick them off as you go.
openclaw update detects how you installed OpenClaw (npm, pnpm, Bun or git), prepares the new version while your gateway keeps running, then switches over and verifies it.
Older installs should update to v2026.9.5 first and run openclaw doctor so its migrations can finish. Then update to the latest version.
How to update OpenClaw on each platform
| How you installed | How to update |
|---|---|
| Installer script, npm, pnpm, Bun | openclaw update |
| From source (git) | openclaw update |
| Docker | docker compose pull openclaw-gateway && docker compose up -d openclaw-gateway |
| Mac app | Dashboard › Settings › Updates › This Mac |
| Windows Hub | Install the newest release from GitHub over the old one |
| Linux AppImage | Updates itself with its signed in-app updater |
| Linux .deb | Download and install the newer .deb (no APT repository) |
Stable, beta or dev?
Tested releases. The right choice for anyone who relies on their assistant.
New features a little early, with a higher chance of bugs.
The latest code. For contributors and testing only.
openclaw update --channel stableWhat's in your OpenClaw setup
Everything lives in your state folder, ~/.openclaw by default. Back up the whole folder, not just the config file.
openclaw.json and its includes.envOpenClaw keeps some config copies during updates, but the docs are clear that these "are not a full-state backup." Make a real backup before every update.
Create a backup with openclaw backup
The built-in command creates a timestamped .tar.gz archive of your whole setup, with a manifest that can be verified later. For the most consistent backup, stop the gateway first.
openclaw gateway stop
mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify
openclaw gateway start| Option | What it does |
|---|---|
--output <path> | Where to save the archive |
--verify | Checks the archive straight after creating it |
--no-include-workspace | Leaves out workspace folders for a smaller file |
--only-config | Backs up just the configuration |
--dry-run | Shows what would be included without writing anything |
--json | Machine-readable output for scripts |
Check any archive later with:
openclaw backup verify <archive.tar.gz>Backup command builder
Choose what to include and where to save it.
Automatic and versioned backups
Let OpenClaw back itself up on a timer.
openclaw backup enable --every 24h
openclaw backup disableKeep a versioned history you can browse and roll back.
openclaw backup git init
openclaw backup git create
openclaw backup git logQuick snapshots of OpenClaw's SQLite stores.
openclaw backup sqlite create
openclaw backup sqlite listRun openclaw backup --help to see the exact duration format and options for your version.
Backups contain your secrets
A full backup includes API keys, chat tokens and your assistant's memory. Treat it like a password vault.
On a VPS, copy backups to your own computer:
scp user@your-server:~/Backups/openclaw/*.tar.gz .Restore an OpenClaw backup
Restoring is designed to be safe. It extracts into a new, empty folder and never overwrites your live setup. If anything fails, the partial extraction is removed.
openclaw backup verify <archive.tar.gz>
openclaw backup restore <archive.tar.gz> --target ~/openclaw-restoredThe restore stages your files without activating them. Review the restored folder, check any symbolic links point to the right places, then follow the instructions the restore command prints to put it into use. Afterwards:
openclaw doctor
openclaw gateway restart
openclaw statusMove OpenClaw to a new computer or server
- On the old machine, stop the gateway and create a verified backup:
Old machine
openclaw gateway stop mkdir -p ~/Backups/openclaw openclaw backup create --output ~/Backups/openclaw --verify - On the new machine, install OpenClaw. It's fine if onboarding creates a fresh setup, because you'll replace it.
- Copy the archive across securely and restore it:
New machine
openclaw backup restore <archive.tar.gz> --target ~/openclaw-restored - Verify and restart:
New machine
openclaw doctor openclaw gateway restart openclaw status
- Copying only
openclaw.json. Move the whole state folder. - Profile mismatch. Use the same
--profileorOPENCLAW_STATE_DIRas the old machine. - Wrong owner. The user running the gateway must own the state folder.
- WhatsApp and similar channels use changing credentials and may need re-linking after a move.
- Don't run both machines at once with the same channel connections.
If an update breaks something
- Run the repair tool first. Many problems after an update are fixed by
openclaw doctor --fix. - Check the logs with
openclaw gateway status --deep, orjournalctl --user -u openclaw-gateway.service -fon Linux. - Restore your pre-update backup using the steps above.
- For npm installs, you can reinstall a previous version with
npm install -g openclaw@<version> --allow-scripts=openclaw. For Docker, pin the image tag to the previous version. - Still stuck? See troubleshooting or report the problem on GitHub.
Update and backup questions
How do I update OpenClaw?
Run openclaw update. It detects how OpenClaw was installed, prepares the new version while your gateway keeps running, then switches over. Afterwards run openclaw doctor --fix and openclaw gateway status --deep. Docker users pull the new image instead.
How do I back up OpenClaw?
Run openclaw backup create --verify. It saves a timestamped .tar.gz archive of your configuration, credentials, sessions, memory and workspace, and checks it straight away. Stop the gateway first for the most consistent backup.
Where does OpenClaw store its data?
In the state folder, ~/.openclaw by default. It holds openclaw.json, credentials and .env, memory, sessions, the workspace and SQLite databases.
Can OpenClaw back up automatically?
Yes. openclaw backup enable with the --every option schedules regular backups, and openclaw backup git keeps a versioned history. Copy backups off the machine as well.
How do I move OpenClaw to a new computer?
Stop the gateway, run openclaw backup create --verify, install OpenClaw on the new machine, restore the archive with openclaw backup restore to a new folder, then run openclaw doctor and restart the gateway. Some channels like WhatsApp may need re-linking.
Are OpenClaw backups safe to share?
No. Full backups contain API keys, chat tokens and your assistant's memory. Encrypt them, store them privately and never send them by email.