Updating

Keep OpenClaw up to date.

For Docker, Podman, and Kubernetes image replacements, see Upgrading container images. The gateway runs startup-safe upgrade work before readiness and exits if mounted state needs manual repair.

Before a significant update, create a verified backup. Automatic config copies and migration recovery originals are not a full-state backup.

Recommended: openclaw update

Detects your install type (npm, pnpm, Bun, or git), validates the candidate while the old Gateway serves, then activates and verifies the update.

openclaw update

An already-installed registry package version or Git target SHA still runs plugin convergence, preserves exact pins with retained-pin advisories, and restarts a running managed Gateway only when plugins change and --no-restart is not set; unchanged runs finish as skipped / already-current. An explicit package artifact (for example, a tarball path or URL) is validated and installed even when its version matches; matching versions do not prove that two artifacts contain the same code. An explicit --channel choice still becomes the saved update channel. For targets that support candidate validation, Doctor lint, config and plugin planning, and a canary boot on copied state finish before the service stops. The stopped interval contains the swap, required migrations, plugin downloads and convergence, and service start. Plugin work uses the installed target without requiring a serving Gateway. A changed plugin snapshot runs fresh Doctor migrations before restart; unchanged plugins do not run another full Doctor pass. The final report records downtime through convergence and final verification, plus verification results. See Validation and activation for the checks.

Package updates also check npm availability for enabled configured plugins before stopping the serving Gateway or replacing the installed core. Registry targets are checked early; explicit package artifacts are checked using the privately staged package version before rehearsal, live-state preparation, or activation. The check uses the same plugin version rules as post-update synchronization, including release-cohort tracking, beta selection, and extended-stable targets. A missing version or registry error refuses the update with plugin-target-unavailable; registry-target --dry-run reports the same refusal. For explicit artifacts, --dry-run does not stage the package and reports that plugin availability checking remains pending. Retry when the registry or mirror is ready, select an older available core with openclaw update --tag <version>, or disable the affected plugin before retrying. Extended-stable does not accept --tag; retry later or explicitly switch channels. Bundled and path-installed plugins do not require registry requests. This metadata check does not reserve downloads, so later download failures can still require recovery.

Switch channels or target a specific version:

openclaw update --channel betaopenclaw update --channel extended-stableopenclaw update --channel devopenclaw update --dry-run   # preview without applying

openclaw update has no --verbose flag (the installer does). For diagnostics use --dry-run to preview planned actions, --json for structured results, or openclaw update status --json to inspect channel and availability state.

--channel beta selects the newest version by semantic version order from the beta and latest npm dist-tags. Use --tag beta for a one-off package update pinned to the raw npm beta dist-tag instead.

A saved update.channel remains the channel for future updates, automatic checks, and update status. For example, a one-off beta package on a saved stable channel keeps checking stable afterward. Use --channel beta to subscribe to beta updates. Plugins still follow the installed core version where required for compatibility.

--channel extended-stable is package-only, and installation remains foreground-only. OpenClaw reads the public npm extended-stable selector, verifies the selected exact package, and installs that exact version. Missing or inconsistent registry data fails closed; it never falls back to latest. If the selected version is older than the installed version, the normal downgrade confirmation still applies. The CLI persists the channel after a successful core update; a direct npm install -g openclaw@extended-stable --allow-scripts=openclaw does not update update.channel, but a final extended-stable package version still checks only the verified extended-stable selector for update availability. That direct command is for npm 12 or npm 11.16+. On npm 11.15 and earlier, omit --allow-scripts=openclaw. After the core swap, eligible official npm and trusted official ClawHub plugins with bare/default or latest intent converge to that exact core version. Exact pins and explicit non-latest tags, third-party plugins, custom registries, and other sources remain unchanged. Version-bound runtime plugins converge to the base release cohort when the core is a correction release (for example, YYYY.M.P-2 uses plugin YYYY.M.P). Catalog installs created by current OpenClaw versions retain that default intent. Older records that contain only an exact version remain pinned because OpenClaw cannot safely distinguish an old automatic pin from a user pin. For npm installs, run openclaw plugins update @openclaw/name once on the extended-stable channel to opt that plugin back into exact-core tracking.

--channel dev gives a persistent moving GitHub main checkout for npm-owned package installs and existing Git checkouts. Package installs reject the --tag main shorthand because the workspace checkout is not a self-contained package artifact. Use openclaw update --channel dev to switch to the supported checkout and build flow. Other explicit package specs keep their package-manager behavior.

Managed npm plugins on the beta channel use the same newest-of-beta/latest selection, including official plugins such as @openclaw/codex. An older beta tag cannot hold a plugin behind the current stable release. Startup repair leaves already-current packages in place so a no-op refresh does not require another restart.

See Release channels for channel semantics.

Updating from 2026.9.2 across a schema bump

Updates driven by OpenClaw 2026.9.2 can cross a shared-state schema bump normally. The target applies the migration content while retaining the old published schema version, so the old updater can finish its ledger writes and final report. Doctor explains that schema content is applied and version publication is deferred. The new Gateway runs on the migrated content during this interval.

Publication waits until every affected update run has been terminal for at least five minutes. A running row that has not changed for more than 30 minutes counts as abandoned for publication purposes only; this does not terminalize an identityless update-history row. The Gateway watcher publishes after the deadline; a later database open can also publish it. See the precise timing and residual old-CLI limitation in Database schemas.

If an agent database also needs migration, required state metadata is missing, or the state-content migration fails, Doctor instead reports update-schema-bump-unfenced with database versions and manual update commands. Let the failed update finish restoring the previous package. OpenClaw 2026.9.2 leaves the Gateway service stopped after failed post-install verification. Run the manual update from a shell outside the Gateway, replacing <target> with the exact target version from the refusal:

openclaw gateway stopnpm install -g openclaw@<target> --allow-scripts=openclawopenclaw doctor --fixopenclaw gateway start

Run each command only after the previous one succeeds. On npm 11.15 and earlier, omit --allow-scripts=openclaw. For a pnpm-owned install, replace the install command with pnpm add -g --allow-build=openclaw openclaw@<target>; for Bun, use bun add -g --trust openclaw@<target>.

Same-schema updates, earlier ledger-less updaters such as 2026.9.1, and fenced transactional updaters from 2026.9.3 onward keep their existing behavior. The fallback does not undo an earlier migration; if the database is already newer than the restored package, install a compatible target and finish Doctor before starting the Gateway.

From chat

The OpenClaw owner can say "update" (the agent uses the gateway action update.run) or send /update. The candidate validates while the old Gateway serves, and an already-current update restarts it only when plugins change. Update runs can send these notices in that chat as the Gateway observes the recorded milestones:

1. An acknowledgement when the update is accepted.
2. ⏳ Restarting the gateway now (v<from> → v<to>)… when activation is recorded before the Gateway stops.
3. 🔁 Back on v<to>, verifying… when the new Gateway starts verification.
4. The final report, including successful updates.

Managed systemd or launchd updates can stop the Gateway before an intermediate notice is delivered. The complete four-message sequence is not guaranteed for those installations; the durable run report remains available after reconnect.

Runs with an internal origin session, including Control UI and webchat, receive these notices directly in that session's transcript. Passing only sessionKey is enough; the caller does not need to supply deliveryContext. Before stopping the managed service, the updater waits for the serving Gateway to finish its restart notice attempt. That wait is capped at 10 seconds so a stalled notice cannot block activation.

The report includes the outcome, recorded phase durations, failed steps, verification facts, and the next action when needed. A run sends each notice at most once; an update that stops before restart sends only the notices for phases it reached. If the update cannot start, the bot records and explains why and provides the manual command when available.

Chat, CLI, Control UI, and automatic updates share a durable run ID. Use openclaw update status to read the active or latest report, including after a restart; --json exposes the activeRun and lastRun records. See Run history and reports for Gateway history queries.

The sender must be in commands.ownerAllowFrom. /update also requires commands.restart (enabled by default). Agents must never run npm install -g openclaw or stop the Gateway service from a chat shell; use the update action so restart and notification stay coordinated.

Stale update history

Untouched, identityless legacy admissions older than 24 hours can expire automatically during Gateway startup or a status check. The row is retained as failed with reason legacy-driver-expired and retry advice; no explicit repair is needed for that shape.

If update status stays in progress while the Gateway is healthy, check that no update is still running. On the updated installation, run:

openclaw update repairopenclaw update status

For an inactive legacy row older than 30 minutes, repair verifies that the running Gateway matches the installed version and build, then clears the stale run without maintenance or a service restart. A new explicit openclaw update can also supersede a single stale identityless row. Recent rows and recorded live drivers are protected. Identityless rows outside the legacy-expiry shape require explicit recovery; the Control UI's configuration-write suspension clears after reconciliation.

OpenClaw 2026.9.2 does not reject a new CLI update because an older running row exists: its admission path creates a new run, and its ledger checks only for a duplicate run ID. Upgrade normally, then use the updated openclaw update repair if the old history remains. A package-manager escape is not required for this ledger defect. See Update run history.

Retire update recovery data

Once you have verified the update and your conversations, preview retained migration originals:

openclaw update cleanup --dry-run

Use the same profile and state/config overrides as the update, and check the state directory printed in the report. The metadata-only preview can run while the Gateway is active. To apply, stop that Gateway yourself, wait for other SQLite maintenance to finish, and stop database readers such as session-listing watchers. Keep them stopped until openclaw update cleanup exits; read-only connections can change WAL/SHM sidecars and invalidate verification. Cleanup never stops or restarts the Gateway. Confirmation defaults to No; automation must explicitly pass --yes, including when using --json.

Cleanup permanently gives up rollback to eligible originals, including repaired branches and old provider metadata. Current SQLite history, operator backups, and protected or unknown artifacts remain. It is not a substitute for a pre-update backup. See Update cleanup for eligibility, JSON output, and resuming interrupted deletion. Private package, command-shim, and Git runtime backups remain owned by the update transaction and are outside this migration cleanup. An interrupted entry in update history does not block cleanup of otherwise eligible migration archives.

After updating

Successful managed openclaw update runs already restart and verify the Gateway. Use these steps after a manual installation or when checking a reported problem.

openclaw doctor

openclaw gateway restart

openclaw health

Detailed topics

• Switch between npm and git installs
• Source-checkout servers (reference script)
• Alternative: re-run the installer
• Alternative: manual npm, pnpm, or bun
  • Package lifecycle and operator state
  • Advanced npm install topics
    • Read-only package tree
    • Hardened systemd units
    • Disk-space preflight
• Auto-updater
  • Update campaigns
• Downgrade
  • Full-state recovery requires a backup
  • Automatic schema-neutral rollback
  • Before updating: create a verified backup
• If you are stuck
  • Unattended repair on your own inference

Related

• Install overview: all installation methods.
• Doctor: health checks after updates.
• Migrating: major version migration guides.