OpenClaw update failed: what to check and how to roll back

When an OpenClaw update stops halfway, the program has usually put the old version back on its own before you even read the message. Your job is to read what it wrote down, fix the one thing it named and run the update again. This guide walks through that in order, using the official OpenClaw documentation and the project's public issue tracker, both read on the 6th of October 2026.

The situation in numbers

The update command in the current 2026.9 releases can write its own bug report, with secrets and private paths removed, according to the update troubleshooting page. Between the 1st and the 6th of October 2026 the project's public issue tracker received 15 reports titled "global-install-failed", all carrying the title that report button writes, according to a search of the tracker. Each report names the version, the platform, the phase that failed and the result of the rollback, which in the report filed on the 6th of October reads "verified safe to restart".

On the 3rd of October 2026 a user described a managed update from 2026.9.5 to 2026.9.8 that passed validation and then rolled back. The automatic recovery restored 2026.9.5 and the report measured the whole episode at 121.5 seconds of downtime, according to the issue. A project maintainer closed it on the 5th of October: both causes are fixed on the main branch and ship in 2026.9.9. Until then, a one-time manual install of 2026.9.8 works and keeps your data. The exact steps are in the error section below.

As of the 6th of October the newest stable release is 2026.9.8, published on the 3rd of October, and the newest extended-stable release is 2026.8.35, published on the 2nd of October, according to the project's releases page.

Before you touch anything

Three facts from the documentation change what you should do first.

First, when the update fails during validation, the running gateway stays untouched, according to the repair and recovery page. The gateway is the part of OpenClaw that keeps your chat apps connected.

Second, when the new version fails after it was switched on, and the database format and the config file are unchanged, OpenClaw restores the previous package, the command shortcut, the service definition and the exact bytes of your config on its own, according to the rollback and recovery page.

Third, the update troubleshooting page opens with one rule: do not restore an old backup as your first response. First put known good code back while keeping your current data. The same page says to leave lock files alone.

So your keys, your chats and your settings are most likely where they were. Run the four checks before you reinstall anything.

Check 1: which version is actually running

Ask OpenClaw for its version with the version flag. Then ask it which version last wrote the config, with the config command and the key the docs call last touched version. Then ask your shell which copy of the program it runs.

When the three answers disagree, the updates and rollbacks page calls it a split-brain install: an older program is reading a config written by a newer one, and OpenClaw blocks the change on purpose. The fix on that page has three parts. Point your shell's search path at the newer copy. Reinstall the gateway service with the force option and restart it. Remove any old system wrapper that still points at the old copy.

Check 2: read the report the update wrote

Open the Control UI, go to Settings and then Updates. The page shows the last attempt: the time, the version before and after, a reason code, the step that failed and a short diagnostic, according to the update troubleshooting page. Three buttons sit there. Check status reads the current state without starting anything. View details opens the failing step. Retry update is for after the cause is fixed.

From the terminal, the update status command with JSON output prints the same record plus any pending notes. The reason code is the key to the error section below.

Check 3: let OpenClaw examine itself

The doctor command migrates the config, audits the DM rules, checks the gateway health and compares the active plugins with the installed version, according to the updating page. With its fix option it repairs what it can.

The update repair command finishes an update that stopped in the middle. It checks that the original package is unchanged, throws away an unused prepared candidate, runs the doctor with the fix option and syncs the plugins, according to the repair and recovery page.

After a failed update in a terminal, OpenClaw offers two more options, per the same page. Diagnose update failure opens the first coding agent found on the machine, in the order Claude Code, Codex, OpenCode, then Pi, and hands it the captured failure; waiting 30 seconds skips that and prints a manual recovery command. Report update failure builds the sanitised report from the opening section and submits nothing until an administrator confirms the preview.

Check 4: is the gateway awake

Run the gateway status command with the deep option, then the health command. A managed update restarts and verifies the gateway by itself; after a manual install you restart it yourself with the gateway restart command, according to the updating page.

Two log lines matter here, according to the updates and rollbacks page. "plugin load failed: dependency tree corrupted" means a plugin stopped the chat channels from starting. "protocol mismatch" after a rollback means a newer client process is still talking to the older gateway; stop that process and restart the app that started it.

How to read the common errors

The reason codes below come from the update troubleshooting page, with the fix the page gives for each.

• "global-install-failed". The package manager's install, staging, verification or launcher swap ended with an error. Fix: run the manual package-manager procedure for your install type, then the doctor with the fix option, then restart the gateway. The auto-filed reports with this title show only "exit 1", so the project's review bot asks reporters for the failed step from View details before it can match the report to a known fix, as it wrote on the 6th of October.
• "global-install-permission-denied". A folder in the install path refuses writes. If you own it, the message prints the permission command to run; if an administrator account owns it, that account runs the update.
• "runtime-verification-failed". The new gateway missed its check inside the 300 second limit. Fix: the manual procedure, the doctor with the fix option, restart.
• "doctor-failed". Run the doctor on the gateway machine, resolve what it lists, then retry.
• "node-runtime-preflight". Your Node version falls outside the range that the new release and the updater both need. Upgrade Node to a version inside both ranges.
• "undergoing offline maintenance; retry when it finishes". The gateway still owns the state folder. Fix: resolve the ownership problem, then run update repair, and leave lock files alone. A user on the 3rd of October found that the lock file names the process number of a gateway still running, according to a comment on the issue; check that process number directly.
• "expected schema 19, found 18" or "Package publication object has an unsafe identity" while moving to 2026.9.8. This is the situation from the opening section. The maintainer's one-time route, written on the 5th of October: stop the gateway, install 2026.9.8 by hand through npm, run the doctor with the fix option, restart the gateway. After that hop, the updater on 2026.9.8 carries what it needs for 2026.9.9.

Getting back to a working version

The documentation prefers the update command for going backwards too. Run it with the tag option naming the known good version and the dry run option first, then without dry run. The updater checks compatibility and asks you to confirm the downgrade, according to the rollback and recovery page. When it refuses because your config or database is newer than the old release understands, the page says to accept the refusal.

The reason is one sentence on the same page: downgrading the package does not reverse config or database migrations. Once your data has moved past the format an older release can read, the supported way back is a verified backup taken before the update, restored together with the matching OpenClaw release. The page lists what has to travel together: the package, the config file, every SQLite database, the workspaces and the credentials. Mixing a pre-update config with a post-update database breaks both.

For Docker, the repair and recovery page prefers rebuilding the image with the version you want, because the container's file system can refuse the package move. After any recovery, the rollback page lists the proof: the version flag, the health command, the gateway status with the deep option and the doctor with the lint option.

Staying on a version you trust

Automatic gateway updates are off by default, according to the automatic updates page. You switch them on in Settings and then Updates, or in the config file. A separate Check for updates switch controls whether OpenClaw looks for new versions at all; off means no automatic update can start, and your saved preference stays.

The channels decide how fast a new release reaches you, per the same page. Stable applies updates after a spread-out delay. Beta applies them at once. Extended-stable never applies anything automatically and only shows a hint; on the 6th of October the newest release carrying that label was 2026.8.35, according to the releases page. Administrators also get a Hold 1 h button that postpones a running update campaign.

To stay on an exact version, the updating page shows the form for npm, pnpm and Bun: the package name, an at sign, then the version number, with 2026.9.5 as its example. The update command with the tag option does the same with validation.

Before every update, the rollback and recovery page asks for a verified backup: the backup command with an output folder and the verify option. The archive records the version and includes credentials and channel state, so keep it readable by you alone. For a byte-for-byte copy the page points to a file system or virtual machine snapshot taken with the gateway stopped. Then run the update with the dry run option, read what it plans and only then run it for real.

How OneClickClaw handles versions

On OneClickClaw, OpenClaw runs on a managed server, and the update decision lives on a dashboard card with two choices: stable and latest. Before a server moves to a new version, a snapshot of the whole server is taken, so going back means restoring that snapshot. Every plan includes automatic backups and health monitoring around the clock, according to the plans page. Plans start at Starter, EUR 14.99 per month, and every plan opens with a free trial of seven days that needs only a Google account. The twin guide for Hermes Agent covers the same situation for the other agent OneClickClaw hosts.

The last check: talk to it

Send the agent one message from the chat app you normally use. A reply, on the version you expect, closes the case. Silence sends you back to check 4.