Skip to main content
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. Detects your install type (npm, pnpm, Bun, or git), checks the new version while the old Gateway serves, then activates and verifies the update.
Managed-service inspection is best effort. If the service manager is unavailable, including Linux hosts without systemd, the update continues and records a warning. It leaves unverified service definitions unchanged and skips their automatic restart. Restart the Gateway you launched manually after the update, or use its actual supervisor. Doctor still checks for active state writers before migrations. After package replacement, compatibility config reads from older updaters run in a fresh process using the updated package and its dependencies. This also applies to updates driven by 2026.9.4. If an optional read fails, the updater prints candidate-config-read-failed and leaves the service definition unchanged. Reads follow the restored package after a rollback. Inspect the reported problem with the updated CLI after the update. When a writable managed Gateway service points at another global installation, the update keeps the active CLI’s installation as its target and refreshes the service through gateway install --force before verifying the restarted Gateway. The old service command remains the recovery identity until that handoff succeeds. Reconciliation failures are recorded as warnings with a manual repair command. Deployment-owned definitions retain their existing installation owner. Pending package-publication recovery in either the CLI or selected service installation blocks writable preparation. Follow the package recovery command reported by the update before retrying; Doctor does not clear those artifacts. The installed 2026.9.4 updater can refuse with managed-service-preflight before the target code runs. To reach a release containing this repair, use the manual package-manager procedure with the same owning package manager, prefix, and state/configuration. Back up first, stop the Gateway through its actual supervisor or foreground process owner, replace the package, run Doctor, and restart through that same owner. --no-restart cannot repair the old admission check.
On macOS, the 2026.9.4 Gateway’s update.run action or /update can hand off successfully, then fail at activation with managed-service-preflight and “This command is running inside the gateway process tree.” The installed updater refuses its own managed helper before swapping packages, so a newer candidate cannot repair that first update.For this ancestry refusal, the owner should run openclaw update once from an independent Terminal outside the Gateway process tree, using the same owning account, installation, and state/configuration. After installing a release containing the managed-helper authority fix, subsequent updates started through update.run or /update use the corrected updater. The fix applies to updates from the fixed version; it does not repair the 2026.9.4 macOS handoff in place.
Registry updates inspect the exact candidate’s Node requirement before staging. An incompatible runtime produces node-runtime-preflight, with the target version, required engine range, selected Node version, and an upgrade command. npm directory permission failures produce global-install-permission-denied, naming the directory, its owner when available, and the next action. Dry-run JSON includes these outcomes in failures; the update report and Doctor’s update history retain recorded failures. The serving Gateway stays in place during these preflight checks. These checks run in the installed updater. Older updaters cannot gain new preflight behavior from the candidate they have not installed yet. If upgrading from an older release, check Node requirements and the npm prefix’s permissions first; see update troubleshooting.
On FreeBSD, OpenClaw 2026.9.4 can stop before staging an update with managed handoff process start identity is unavailable. Changing the target or adding --no-restart cannot repair the installed updater.For a pkg or Ports installation, update through pkg or Ports; do not overwrite its files with npm. For an npm-owned installation, use the manual package-manager procedure from a separate shell, with the same owning npm, installation prefix, and Gateway state/configuration. Select a published version whose release notes include the FreeBSD fixes; changes on main are not a published release.Stop and start the Gateway through its actual supervisor or foreground process owner around the manual replacement. This recovery does not add CLI-managed FreeBSD rc.d service updates.
An already-installed registry package version or Git target SHA still runs plugin maintenance, repairs eligible old OpenClaw release pins, and restarts a running managed Gateway when plugins change or its service points at another installation, unless --no-restart is set. Unchanged runs finish as skipped / already-current. Plugin maintenance does not fail an otherwise successful core update. If a plugin cannot be updated, OpenClaw continues with the remaining plugins, keeps the previous installation where possible, and prints a short next action. A running updated Gateway can also report a plugin that did not load without turning the core update into a failure. Individual plugin outcomes remain available in --json output. Failures to install core, repair required configuration or state, or start the updated Gateway remain update failures. Local copies selected through plugins.load.paths are operator-managed. Updates and openclaw update repair retain the selected copy and any npm install it shadows, and record a plugin-operator-managed warning in the outcome and update history. Verify that copy against the updated OpenClaw version, or remove its path from plugins.load.paths to use the managed installation again. This does not grant the local copy trusted plugin privileges. 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 versions that support checks before installation, health checks, config and plugin planning, and a test Gateway 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. The canary uses a temporary loopback Gateway port and suppresses background listeners, including the MCP Apps sandbox, browser control, and channel services. This lets validation run while the serving Gateway keeps its configured ports. It preserves non-secret Gateway auth settings such as gateway.auth.rateLimit for policy checks, while using a temporary token and disabling Tailscale identity authentication. The activated Gateway retains your normal listener settings. The canary verifies the copied plugin payloads without downloading replacements. It warns when plugin refresh is deferred; live update finalization owns that refresh, so a slow registry cannot consume the canary’s startup budget. This candidate-side behavior also applies when the installed updater is 2026.9.3. That older updater still caps the entire validation sequence at five minutes; its --timeout option cannot increase this cap. 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 private validation, 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 plugin version or registry error produces a warning naming the affected plugin; the core update can continue. Registry-target --dry-run includes those warnings. For explicit artifacts, --dry-run does not stage the package and reports that plugin availability checking remains pending. Extended-stable does not accept --tag. Bundled and path-installed plugins do not require registry requests. This metadata check does not reserve downloads. Plugin-only download, install, or load failures remain actionable warnings after an otherwise successful core update. The updater preserves recorded choices and retains the previous plugin payload where possible. Follow the reported openclaw plugins update <id> command for a failed install or update, or openclaw doctor --fix for a load problem. Invalid configuration or state, ownership errors, and failed core startup or readiness checks still prevent completion. Switch channels or target a specific version:
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. Eligible older OpenClaw release pins resume that default update policy. Explicit non-latest tags, independently versioned pins, third-party plugins, custom ClawHub registries, and other sources retain their existing behavior. 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. Verified OpenClaw-owned packages recorded at an exact OpenClaw release no newer than core resume their catalog’s default selector after a successful update. This includes old automatic and manual pins. Their recorded registry and plugin settings are preserved, and subsequent updates continue following the selected channel. A version explicitly supplied to a plugin update command still applies to that operation. --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. On source installs, Doctor and plugin updates keep plugins built with the host. A registry plugin with the same version string can target a different SDK, so it does not replace the source build without matching SDK build evidence. Existing registry generations remain on disk; convergence reports the bundled selection and skips their refresh. OPENCLAW_DEV_SOURCE_ROOT is not required. 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. When agent databases also need migration, the candidate first rehearses Doctor on private copies while the published updater can still roll back its package. After package commit, the fresh post-core process acquires current executor authority and delegates Doctor. Doctor verifies a retained recovery archive covering each agent database before migrating live state. The updater then restarts the Gateway. Missing state metadata or unverified backup coverage can still produce update-schema-bump-unfenced with database versions and recovery instructions. Before package commit, let the failed update finish restoring the previous package. OpenClaw 2026.9.2 leaves the Gateway service stopped after failed post-install verification. After package commit, the old package backup is gone: finish openclaw doctor --fix with the installed compatible build, then run openclaw gateway start. Package rollback cannot undo migrated state. If the compatible package still needs installation, run the manual update from a shell outside the Gateway, replacing <target> with the exact target version from the refusal:
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. For a Git checkout updated by 2026.9.2, a Doctor refusal before state writes prints source recovery commands when the checkout’s reflog identifies the previous commit unambiguously. Wait for the updater to exit, then follow the printed checkout, pnpm install, pnpm build, and service-start guidance from an independent shell. If the previous commit cannot be verified, Doctor points you to the reflog instead. A refusal after state repairs keeps the migration owner’s instructions: restoring source alone does not restore state. These diagnostics also enter the warning log, subject to normal logging settings and rotation. After resolving the refusal cause, retry the update. Once the upgrade succeeds, subsequent updates check the new version before activation.

​
From chat

Ask the agent to update OpenClaw, or send /update from Discord or another connected chat. Natural-language requests use the existing gateway tool’s update.run action. The minimal, coding, and messaging profiles expose that update action without granting configuration reads or other Gateway controls. Explicit tool restrictions still apply. /update is the model-independent fallback: it works without a functioning model or access to the gateway tool. The tool, slash command, and Control UI all use the same Gateway update handler and current authorization checks. The new version is checked while the old Gateway serves. An already-current update restarts a running Gateway when plugins change or its service points at a different installation. 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.
External update and restart notices go only to destinations listed in commands.ownerAllowFrom. Selecting a non-owner chat in the Control UI does not authorize notices to that contact. If no owner destination resolves, OpenClaw logs the skipped notice and keeps the update outcome in the run record and Control UI; it does not redirect the notice to another chat or wake the rejected session with diagnostics. Update lifecycle notices also honor the destination account’s actions.sendMessage policy. An explicit account setting overrides the channel default; when neither sets the flag, notices are allowed. Disabled sends are recorded as skipped notices without preventing the update or its Control UI report. 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. The agent relays the returned recovery instructions to the operator. Manual update commands run in a terminal outside the Gateway service; the agent must not execute them in the shell of the Gateway hosting its session. A missing owner permission requires owner setup, and an externally supervised installation uses its deployment owner’s update workflow. 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. Being allowed to chat does not grant owner permissions. If your account is not an owner, the reply explains how the Gateway operator can connect it. Channel setup and pairing distinguish owner access from chat access; existing allowed users are not automatically promoted. External-chat updates through /update or the tool require commands.restart (enabled by default), including managed installations. The slash command also follows command-access restrictions; tool calls follow tool policy. Chat updates use the hosting installation’s configured update channel and install method. Agents must never run npm install -g openclaw or stop the Gateway service from a chat shell; use /update or the update action so restart and notification stay coordinated.

​
Inspect FreeBSD service discovery

The standalone scripts/freebsd-service-inspect.mjs diagnostic reports which openclaw rc.d definitions the native configuration selects. It requires a root-owned Node installation, script, and shared discovery helper. It does not require the OpenClaw Ports service package. From an existing root shell, install the script from a trusted OpenClaw package:
Use your root-owned Node path if it differs. Clear the environment before Node starts, as shown, to exclude Node preload options. The command accepts no arguments. It reads native administrator shell configuration as root and requests no service lifecycle operation. Administrator configuration is trusted shell code, not a sandboxed data format. The result includes the exact clean environment and working directory used for discovery. It corresponds to service invoked with that same context. Configuration that depends on another environment or directory can select different services. The single JSON result reports absent, present, or unknown. Present results include executable and non-executable definitions, their native search order, and the first executable definition. Symlinks, unsafe ownership, incomplete inspection, or unexpected configuration output produce unknown and exit 1. Configuration contents and subprocess errors are not included in the result. This is a diagnostic observation. It does not establish process or package ownership, authorize an update, or enable CLI-managed rc.d service updates. Continue to use the installation owner’s update procedure above.

​
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:
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. Repair started within the owning update can continue with a matching inherited run ID and live process identity; the run records that continuation. Repair still refuses an unrelated live or stalled updater. The error identifies its run, phase, driver PID, host, start and last-activity ages, and observed liveness. Wait for that update to finish, or stop the named driver on its host and rerun repair after it exits. See Update repair for maintenance and recovery behavior. 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:
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.

​
Background exec notifications after an update

[OpenClaw exec completion] identifies an automatic follow-up for a background command, rather than a recurring heartbeat poll. These follow-ups can run with agents.defaults.heartbeat.every: "0m". To keep background exec without these extra model calls, set tools.exec.notifyOnExit: false and check per-agent overrides at agents.entries.<id>.tools.exec.notifyOnExit. Use process poll to collect results. See Background exec notifications for when the setting takes effect.

​
Detailed topics

Other update methods

Switching between npm and git installs, source servers, the installer, and manual package managers.

Automatic updates

The auto-updater, per-channel behavior, and update campaigns.

Rollback and recovery

Downgrades, automatic rollback, pre-update backups, and triage.