OpenClaw update broke your agent? How to roll back or downgrade

Check whether it already went back

A current openclaw update verifies the new version after switching to it: the Gateway has to start, own its port, load its plugins and channels, and report ready. If that check fails and nothing about your agent’s data changed in a way the old version cannot read, the updater stops the new version and restores the previous one, with its configuration exactly as it was. The update then ends with a line beginning ↩️ OpenClaw update rolled back to and the reason, and the command exits with an error even though your agent is running again. The rollback and recovery reference lists the conditions. The updater already installed is the one that runs this, so an older install may not have it.

openclaw update status
openclaw --version
openclaw gateway status --deep

If the status shows a rollback and the agent answers on its usual channel, you are back where you were. The failed version is recorded with its reason; read it before trying that update again.

Repair before you downgrade

Most breakage after an update is a migration or a repair that did not finish, and the fix runs forward, on the new version, against the same data. Stop the Gateway, run Doctor, start it again:

openclaw gateway stop
openclaw doctor --fix --non-interactive
openclaw gateway start

A restart loop with a run openclaw doctor --fix message in the log is this case, and repeating the restart does not complete the repair; the update guide walks through one such loop and its fix. If Doctor reports something else, openclaw triage hands the update’s recorded failure and fresh diagnostics to a coding agent installed on the same machine (Claude Code, Codex, OpenCode or Pi, in that order) to repair. In the Control UI, Settings → Updates → Diagnose update asks OpenClaw itself to investigate. Diagnosis does not retry the update.

Go back to the version that worked

Take a backup of the agent as it is now, so the downgrade itself can be undone:

openclaw gateway stop
openclaw backup create --output ~/Backups/openclaw --verify

Then ask the updater for the older version by its number. The latest-version guide explains where to find release numbers; openclaw update status shows the version you came from.

openclaw update --tag 2026.9.6 --dry-run
openclaw update --tag 2026.9.6

The dry run previews the change. The real run checks that the older version can read your agent’s current data, asks you to confirm the downgrade, restarts the Gateway and verifies it. If your install follows the extended-stable channel, add --channel stable for the one-off version. If automatic updates are switched on, set OPENCLAW_NO_AUTO_UPDATE=1 in the Gateway’s environment until the problem is fixed, or the newer release comes straight back.

Docker installs go back the same way they go forward: select the previous image tag for the Gateway and any CLI service, keep the same mounted volumes, and recreate the container. The image runs Doctor before it starts and exits if it cannot use the data safely; an older image that exits on a newer database means the data has already moved on.

When the old version can’t read your agent anymore

An update can migrate the agent’s databases and configuration to a newer format, and that is one-way. Installing the older program afterwards does not convert them back, and the updater refuses a downgrade that would leave an older version reading data it does not understand. Do not edit version numbers in the database or the config to get past that refusal; OpenClaw’s database recovery notes are explicit that the markers describe the format, and changing them does not restore it.

The way back is the backup taken before the update, restored together with the OpenClaw version that made it. With the Gateway stopped, install that version, unpack the backup into an empty folder, and move it into place:

openclaw backup restore ~/Backups/openclaw/<archive>.tar.gz --target ~/openclaw-restored

The restore never overwrites your live agent; you move the restored state into place yourself, using the manifest.json it writes, then run openclaw doctor and start the Gateway. The backup and restore guide covers each step. Everything the agent did after the backup is lost, a WhatsApp connection may need linking again, and plugins need reinstalling, so copy out anything new from the current state first.

Without a backup from before the update, read the update report first: it names any database copies the updater kept, which the project’s recovery steps can sometimes use. Otherwise, repair forward on the new version, and report the failure to the project through openclaw triage or on GitHub.

Before the next update

The updater’s own safety copies are not a backup of your agent: in OpenClaw’s documentation, a full recovery point is openclaw backup create --verify, run before the update and kept until you have checked that the new version works. Read the release notes for the versions in between, and if your agent does work you depend on, give a new release a few days and read the issues filed against it first.

If running updates is the part you would rather not own, managed OpenClaw hosting moves it off your plate. On an Everpod pod, updates aren’t your job: new OpenClaw releases are applied for you after testing, and your agent’s computer is backed up every day.