2026-07-20

OpenClaw Update Guide: Upgrade, Verify, and Roll Back Safely

Update OpenClaw safely with channel-aware dry runs, verified backups, supervised Gateway restarts, production checks, repair steps, and rollback procedures.

The safest OpenClaw update on the host examined for this guide was the one that did not install anything. The installed CLI and Gateway both reported 2026.7.1-2; the stable registry target was the same version; and openclaw update --dry-run --json showed the complete handoff without touching config, packages, plugins, or the running service. That result is more useful than a ritual upgrade command: it proves which installation would change, which channel would supply it, whether a downgrade is involved, and whether the Gateway will restart.

An OpenClaw update is not just a package-manager transaction. On a managed installation it crosses three boundaries: the CLI that starts the operation, the package tree that is replaced, and the Gateway process that must leave its own process tree before the replacement can happen safely. Treating those as one opaque command is how operators end up with a new CLI in one shell and an old service still running elsewhere.

A fresh read-only pass on 23 July 2026 reached the same no-op decision: stable still resolved to 2026.7.1-2, the CLI and Gateway agreed on that version, the Gateway RPC probe was healthy, and the update preview retained a supervised restart in its plan. None of that proves a future package download or restart will succeed. It does establish the exact before-state, the handoff that would occur, and the evidence an operator must demand afterward.

Do not update merely because an update command exists. First identify the installation used by the managed service, record the current and target versions, create a verified recovery point when state changes matter, and decide what observation would cause you to stop. An unplanned channel switch or install-root switch is a change of operating model, not routine patching.

The preflight result that should cancel an update

Start with openclaw update status --json. On the reviewed host, it reported a pnpm package installation under the global pnpm tree, the default stable channel, registry tag latest, and no available registry or Git update. The current and latest versions were both 2026.7.1-2.

openclaw --version
openclaw update status --json
openclaw update --dry-run --json

The dry run then resolved the effective target as openclaw@latest, kept the install kind as package, selected pnpm, and set restart: true. Its planned actions were still explicit: refresh the package install, synchronize managed plugins, refresh completion data if needed, restart the Gateway, and run Doctor checks. Because the target already matched the installed version, executing that plan would have created risk without gaining a newer core.

That is the first operator decision: no available update means stop, unless the goal is an intentional repair or reinstall. “The command would run” is not a reason to run it. A stable production procedure needs an expected state transition, not just a syntactically valid command.

No delta, no maintenance event.

Preflight field	What it answers	Stop condition
`installKind` and package manager	Which update engine owns the active installation	The result points at an unexpected package or Git root
Current and target version	Whether any core change will occur	They match, or the target is an unexplained downgrade
Effective channel and tag	Which release policy selects the target	The channel changed without an explicit decision
`restart`	Whether the managed Gateway should be handed off	The maintenance plan assumes no interruption but restart is enabled
Planned actions and notes	What happens beyond the core package swap	Plugin, service, or migration work is outside the approved scope

Find the service's installation, not the shell's favorite binary

A shell can resolve one openclaw binary while a managed Gateway service launches another package root or Node runtime. The updater accounts for this: on a package install with a managed service, it targets the package root used by that service and checks the service Node version against the target release. That behavior prevents a common false success where the interactive CLI changes but the daemon keeps running old code.

The reviewed host made the boundary visible. openclaw gateway status --json reported a systemd user service whose command launches OpenClaw from the global pnpm installation. The CLI entrypoint, Gateway version, and RPC server version all agreed on 2026.7.1-2. The service was active, the configuration audit was clean, and the local RPC probe succeeded.

command -v openclaw
openclaw gateway status --json
openclaw plugins list --json

Do not reduce that check to “the process is running.” Record the resolved CLI, the service command, the service manager, the reported Gateway version, and the plugin state. Those values form the before-state. After an update, they reveal whether the package changed in the right place and whether the restarted service actually loaded it.

A protected system core secured beside a sealed backup capsule while a separate preview path waits ahead — Separate evidence collection and recovery preparation from the update path. A preview is valuable precisely because it leaves the live installation untouched.

A backup is useful only when its restore boundary is understood

OpenClaw's backup command covers state, configuration, credentials, agent databases, and—unless excluded—discovered workspaces. It snapshots SQLite databases safely rather than copying active WAL files, excludes volatile session and queue artifacts that have no restoration value, and writes a manifest describing the archive layout.

For a normal update, the recovery plan usually needs two separate anchors:

Code anchor: the exact package version, dist-tag, or Git commit known to work with the current deployment.
State anchor: a verified OpenClaw archive or platform snapshot created before a migration-sensitive change.

openclaw backup create --dry-run --json
openclaw backup create --verify --output /approved/backup/location
openclaw backup verify /approved/backup/location/<archive>.tar.gz

Keep the archive outside every source tree that it contains; the backup command rejects self-inclusion paths for that reason. Also budget for both the temporary archive write and the final file. Large workspaces often dominate size, so --no-include-workspace can be appropriate when repositories are already protected elsewhere and the recovery objective is OpenClaw state.

A verified archive is not permission to restore it after every failed update. Restoring older state can erase newer sessions, credentials, pairing data, cron changes, and configuration created after the backup. Prefer a code-only rollback when the current state remains readable. Preserve the newer state before any offline restore.

Verify the handoff, not just the package transaction

Replacing package files underneath a running Gateway is unsafe because the process may load core or plugin files while the package manager is changing them. For managed services, OpenClaw avoids that race with a detached handoff: the Gateway exits, a helper runs the CLI update outside the Gateway process tree, service metadata is refreshed, the service restarts, and the CLI verifies the restarted Gateway before reporting success.

This is why --no-restart is not a harmless speed option. It can replace the package while leaving the managed service on the old in-memory code. That may be useful in a tightly controlled staged window, but the system is then intentionally split until a later restart. Record that state and do not claim the update complete.

When the control-plane route cannot construct a safe handoff, it returns a structured failure and a shell command to run outside the Gateway. That is a stop signal. It is not an invitation to make the live Gateway replace its own package tree.

What success should mean: the expected package version is installed; the managed service restarted; readiness and RPC probes succeed; the Gateway reports the expected version; configuration and Doctor checks are clean; and required plugins load without unexplained drift. A zero exit from a package manager covers only the first item.

A newly installed green system core connected to three inspection instruments while the prior core remains protected in a recovery cradle — Keep the previous code anchor available while the new Gateway is checked at the service, runtime, plugin, and workflow layers.

Failure modes: repair finalization or roll back the core

Repair is not rollback.

openclaw update repair is for a core package that changed successfully while finalization did not converge. It reruns Doctor repair, reloads config and install records, synchronizes tracked plugins, repairs managed plugin metadata and missing configured payloads, and refreshes the plugin registry. It does not install a new core and does not restart the Gateway.

That makes repair the right tool for post-core plugin or metadata drift, not for a core version that fails to boot. Conversely, repeating a full update after finalization failed adds another package transaction without addressing the incomplete phase.

Observed failure	First response	Avoid
Core unchanged; preflight or install failed	Fix the reported package, permission, disk, or registry condition and rerun the preview	Restoring application state
Core changed; plugin sync or Doctor finalization failed	Run `openclaw update repair --json` after reviewing the failure	Installing the core again blindly
New core installed but Gateway cannot become healthy	Inspect restart log, service metadata, config validation, and target version; use the known-good code anchor if necessary	Repeated restarts with no changed condition
Current code cannot read or safely migrate state	Stop writes, preserve current state, then use the documented offline recovery plan	Overwriting the only copy of newer state
Shell CLI and service report different versions	Resolve the service-owned package root and Node runtime	Assuming PATH proves the daemon's install

For package installations that become partially unusable after the npm phase, the official installer can recover the global package directly without invoking the updater. Pin it to a known version when recovering; an unqualified reinstall of latest may simply reproduce the failing target. On root-owned system-global installs, stop the Gateway before a manual package replacement, then force-refresh service metadata, restart, and verify.

Write the maintenance record before applying

The following record is deliberately shorter than a generic checklist. Each line produces evidence that can be compared after the handoff.

Resolve: capture CLI path, service command, install kind, package manager, Node runtime, current Gateway version, channel, and plugin inventory.
Preview: save update status --json and update --dry-run --json; stop on an unexpected root, channel, downgrade, or no-op.
Protect: record a known-good code version and create a verified state archive when the change can affect state compatibility.
Apply: use the supervised updater from outside overlapping package operations; let the managed-service handoff own the restart.
Prove: compare CLI, Gateway, RPC, readiness, config audit, Doctor, and plugin results with the captured before-state.
Canary: run one harmless real channel action and one bounded agent workflow that exercises the plugins and tools the deployment actually depends on.
Recover: choose repair for incomplete finalization, a code anchor for a bad core, and state restoration only for a demonstrated state problem.

The 23 July read-only pass again reached step two and stopped: stable had no newer target. openclaw update --dry-run --json planned the package refresh, plugin synchronization, completion refresh, Gateway restart, and Doctor checks, while openclaw backup create --dry-run --json described the recovery scope without writing an archive. No package files changed and no service restarted. That is the honest boundary between a reproduced preflight and an unearned claim that the upgrade path ran end to end.

For teams that do not want package channels, service handoffs, plugin convergence, backups, and rollback ownership on every agent host, deploy a managed AI agent on GolemWorkers. For related operating procedures, see OpenClaw backup and recovery, OpenClaw Doctor, and OpenClaw Gateway setup.

Primary documents retained for this maintenance decision

OpenClaw updating guide — install detection, release channels, package/Git switching, supervised service replacement, auto-update behavior, verification, and recovery.
OpenClaw update CLI — status, dry-run, repair, channel and tag semantics, managed-service handoff, and structured results.
OpenClaw backup CLI — archive scope, manifest and verification behavior, safe SQLite snapshots, volatile-file exclusions, and restore-boundary considerations.
OpenClaw Doctor — configuration migration, health diagnosis, and bounded repair after updates.