How to roll back OpenClaw after a bad update

Step 1 — Back up first

openclaw backup create --verify        # archive of your OpenClaw state, then check it
openclaw --version                     # note what you're on

Since 2026.9.7, a verified backup checks that every agent database recorded at capture is present, including custom and moved ones. A config-only export is not a recovery backup, and archives made by older versions may have unknown completeness. These protections can't add missing backups to an update that an older updater already ran.

Restore later with openclaw backup restore <archive> --target <fresh-directory>. Your persona and memory are plain files in the workspace (default ~/.openclaw/workspace/: SOUL.md, AGENTS.md, USER.md, MEMORY.md, skills/), so copying that folder is a good extra safety net. Config lives in ~/.openclaw/openclaw.json.

Step 2 — Let the updater help

• Rehearse: openclaw update --dry-run reports what an update would change without applying it.
• Automatic rollback: a failed update tries to roll back. When the rollback verifies, the previous version keeps running, and OpenClaw offers to diagnose or report the failure. Since 2026.9.7 this includes database rollback, but only for eligible updates that fail before the new version is allowed to start: restoring databases needs a snapshot captured while OpenClaw was stopped, with the new version never started and no unaccounted later writes. Changed or incompletely captured config files may still need manual recovery.
• Snapshots: the updater deletes its database snapshots after a verified successful update. A failed or unverified update keeps them and may leave OpenClaw stopped, so read the update report before deleting older snapshots (Doctor only reports them). Capturing them needs substantial free disk space and can block an update that would otherwise work.
• Interrupted repair: openclaw update repair finishes it; openclaw update cleanup --dry-run shows leftover recovery files.

Step 3 — Move to the slower channel

openclaw update --channel extended-stable

Extended-stable is OpenClaw's long-term-support line: older code plus security and reliability fixes. It's the supported way to wait out a rough patch without freezing on an unpatched version. (Release channels)

Step 4 — Or pin an exact version with npm

npm view openclaw versions --json      # available versions
npm install -g openclaw@<version>       # e.g. the last one that worked for you
openclaw --version
openclaw doctor

npm has no per-package "pin" setting for global installs. Stay on a version by not running npm update -g or openclaw update until you're ready. If you manage OpenClaw from a project's package.json, use an exact version (no ^ or ~).

Check Node first. Since 2026.9.3 OpenClaw has needed Node 24.16+ or 26.1+, and since 2026.10.6 the patched 24.22.1+ or 26.12.1+; going back across either line may also mean going back on Node. See troubleshooting.

Before you upgrade again

• Read the release notes (GitHub releases) and our "broke after an update" list.
• Installed before June 2026? Upgrade through 2026.9.5 first (the docs' very old versions steps), running openclaw doctor --fix there; the latest version requires that 2026.9.5 step. If a newer version has already changed your databases, follow the compatible-backup recovery steps in the rollback and recovery guide before downgrading.
• Run openclaw update --dry-run, then openclaw doctor --fix after updating. Doctor migrates retired settings (for example HEARTBEAT.md and old memory backends).

Correction 2026-09-27: an earlier version of this page backed up ~/.openclaw/soul.md (the file is SOUL.md in the workspace) and suggested npm config set openclaw <version>, which does not pin anything.