OpenClaw Update Command: Refresh and Switch Release Tracks

openclaw update

Refresh OpenClaw and move between the stable, extended-stable, beta, and dev release tracks.

When OpenClaw was set up through npm/pnpm/bun (a global install without git metadata), the package-manager routine described in Updating handles the update process.

Usage

openclaw update
openclaw update status
openclaw update repair
openclaw update wizard
openclaw update --channel extended-stable
openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag beta
openclaw update --dry-run
openclaw update --no-restart
openclaw update --yes
openclaw update --acknowledge-clawhub-risk
openclaw update --json
openclaw --update

openclaw --update replaces openclaw update (handy for shells and launcher scripts).

Options

No --verbose flag exists. Use --dry-run to preview planned actions, --json for machine-readable results, and openclaw update status --json for channel/availability only. Gateway console verbosity (--verbose) and file log level (logging.level: "debug"/"trace") are separate controls; see Gateway logging.

Note

In Nix mode (OPENCLAW_NIX_MODE=1), mutating openclaw update runs are disabled. Update the Nix source or flake input for this install instead; for nix-openclaw, use the agent-first Quick Start. openclaw update status and openclaw update --dry-run remain read-only.

Warning

Downgrades need confirmation because older versions can break configuration. If the install has already migrated sessions to SQLite, restore archived legacy transcript artifacts before starting an older file-backed version. See Doctor: Downgrading after session SQLite migration.

update status

Display the active update channel, git tag/branch/SHA (source checkouts only), and update availability.

openclaw update status
openclaw update status --json
openclaw update status --timeout 10

For extended-stable package installs, status performs the same public selector and exact-package verification as foreground update. It can report ahead of extended-stable when the installed version is newer. JSON failures include registry.reason (selector_missing, selector_query_failed, exact_package_mismatch, or unsupported_git_channel).

update repair

Rerun update finalization after the core package already changed but later repair work did not finish cleanly. This is the supported recovery path when openclaw update installed the new core package but post-core plugin sync, managed npm plugin metadata, registry refresh, or doctor repair did not converge.

openclaw update repair
openclaw update repair --channel beta
openclaw update repair --acknowledge-clawhub-risk
openclaw update repair --json

update repair executes openclaw doctor --fix, then reloads the corrected config along with install records, synchronizes tracked plugins for the active update channel, handles managed npm plugin installs, repairs any missing configured plugin payloads, refreshes the plugin registry, and writes out converged install-record metadata. No new core package gets installed, and the Gateway is not restarted.

update wizard

An interactive flow lets you choose an update channel and decide whether to restart the Gateway afterward, with restart as the default. Picking dev when no git checkout exists offers to create one.

What it does

Explicitly switching channels with --channel ... also keeps the install method in sync:

• dev -> guarantees a git checkout (defaulting to ~/openclaw, or $OPENCLAW_HOME/openclaw when OPENCLAW_HOME is set; OPENCLAW_GIT_DIR overrides it), updates that checkout, and installs the global CLI from it.
• stable -> pulls from npm using latest.
• extended-stable -> resolves the public npm extended-stable selector, confirms the exact chosen package, and installs that precise version. No fallback to another selector occurs, and Git checkouts reject this option.
• beta -> favors npm dist-tag beta, then falls back to latest if beta is absent or older than the current stable release.

Restart handoff

When enabled through config, the Gateway core auto-updater triggers the CLI update path outside the live Gateway request handler. Control-plane update.run package-manager updates and supervised git-checkout updates rely on the same managed-service handoff rather than swapping the package tree or rebuilding dist/ inside the running Gateway process: the Gateway starts a detached helper and exits, and that helper runs openclaw update --yes --json outside the Gateway process tree. If the handoff is unavailable, update.run returns a structured response containing the safe shell command for manual execution.

Stored extended-stable selections get read-only startup and 24-hour update hints when update.checkOnStart is enabled. These checks never apply an update, initiate a handoff, restart the Gateway, use stable delay/jitter, or adopt beta polling cadence. Explicit foreground updates, bare foreground updates with stored update.channel: "extended-stable", on-demand status, and their managed Gateway handoff continue to work.

With a local managed Gateway service installed and restart enabled, package-manager and git-checkout updates halt the running service before replacing the package tree or altering the checkout/build output. After that, the updater refreshes service metadata, restarts the service, and confirms the restarted Gateway before reporting Gateway: restarted and verified.. Package-manager updates also confirm the restarted Gateway reports the expected package version; git-checkout updates verify gateway health and service readiness after the rebuild.

Package-manager updates generally keep using the Node binary recorded in the managed service. If that Node cannot run the target release, but the current CLI Node can and the service is proven to belong to the package being updated, a restart-enabled update uses the current Node for finalization and rewrites the service metadata to that runtime. --no-restart cannot repair service metadata, so the same runtime mismatch halts before package mutation.

On macOS, the post-update check also confirms the LaunchAgent is loaded/running for the active profile and the configured loopback port is healthy. If the plist is installed but launchd is not supervising it, OpenClaw re-bootstraps the LaunchAgent automatically and reruns the health/version/channel readiness checks (a fresh bootstrap loads the RunAtLoad job directly, so recovery does not immediately kickstart -k the newly spawned Gateway). If the Gateway still fails to become healthy, the command exits non-zero and prints the restart log path plus restart, reinstall, and package rollback instructions.

If restart cannot run, the command prints Gateway: restart skipped (...) or Gateway: restart failed: ... with a manual openclaw gateway restart hint. With --no-restart, package replacement or git rebuild still happens, but the managed service is neither stopped nor restarted, so the running Gateway keeps old code until you restart it manually.

Control-plane response shape

When update.run runs through the Gateway control plane on a package-manager install or supervised git checkout, the handler reports handoff initiation separately from the CLI update that continues after the Gateway exits:

• ok: true, result.status: "skipped", result.reason: "managed-service-handoff-started", and handoff.status: "started": the Gateway created the managed-service handoff and scheduled its own restart so the detached helper can run openclaw update --yes --json outside the live service process.
• ok: false, result.reason: "managed-service-handoff-unavailable", and handoff.status: "unavailable": OpenClaw could not locate a supervising service boundary and durable service identity for a safe handoff (for example, systemd handoff requires the OPENCLAW_SYSTEMD_UNIT unit identity, not just ambient systemd process markers). The response includes handoff.command, the shell command to run from outside the Gateway.
• ok: false, result.reason: "managed-service-handoff-failed": the Gateway attempted to create the handoff but could not spawn the detached helper.

The sentinel payload is written before the Gateway exits, and the CLI handoff updates that same restart sentinel after the managed-service restart health checks complete. During the handoff, the sentinel can carry stats.reason: "restart-health-pending" with no success continuation; the restarted Gateway polls it and fires the continuation only after the CLI has verified service health and rewritten the sentinel with the final ok result. openclaw status and openclaw status --all show an Update restart row while that sentinel is pending or failed, and update.status refreshes and returns the latest sentinel.

Git checkout flow

Channel selection

• stable: select the most recent non-beta tag, then execute build and doctor.
• beta: opt for the newest -beta tag when available, otherwise use the latest stable tag if beta is absent or outdated.
• dev: switch to main, then perform fetch and rebase.
• extended-stable: not supported for Git checkouts; no changes are made to the checkout.

Update steps

Verify clean worktree

Uncommitted changes are not permitted.

Switch channel

Moves to the designated channel, whether tag or branch.

Fetch upstream

Development only.

Preflight build (dev only)

Compiles the TypeScript code within a temporary worktree. Should the tip fail, it backtracks up to 10 commits to locate the most recent buildable commit. Declaration outputs, addressed by content, from the successful candidate are reused for the final checkout build; rebased source changes automatically invalidate the relevant cache groups. To also run lint during this preflight, set OPENCLAW_UPDATE_PREFLIGHT_LINT=1; lint operates in constrained serial mode since user update hosts are often less powerful than CI runners.

Rebase

Rebases onto the specified commit, limited to dev.

Install dependencies

Employs the repository's package manager. For pnpm checkouts, the updater initializes pnpm as needed (using corepack first, then a temporary npm install pnpm@11 fallback) instead of executing npm run build within a pnpm workspace. If pnpm bootstrap fails, the updater halts early with a package-manager-specific error, avoiding any attempt at npm run build in the checkout.

Build checkout

Builds the gateway and Control UI once in the final checkout. The standalone Control UI build is executed by the updater only when a target build omitted those assets or doctor later removes them.

Run doctor

openclaw doctor serves as the final safe-update verification.

Sync plugins

Synchronizes plugins to the active channel. Dev relies on bundled plugins; stable and beta use npm. Updates tracked plugin installations.

Plugin sync details

On the beta channel, tracked npm and ClawHub plugin installs that follow the default/latest line first attempt a plugin @beta release. If no beta release exists, OpenClaw reverts to the recorded default/latest spec and issues a warning. For npm plugins, OpenClaw also falls back when the beta package exists but fails install validation. These fallback warnings do not cause the core update to fail. Exact versions and explicit tags remain unchanged.

Warning

Should an exact pinned npm plugin update resolve to an artifact whose integrity differs from the stored install record, openclaw update aborts that plugin artifact update rather than installing it. Reinstall or update the plugin explicitly only after confirming you trust the new artifact.

Note

Post-update plugin sync failures that are scoped to a managed plugin and that the sync path can bypass (for instance, an unreachable npm registry for a non-essential plugin) are reported as warnings after the core update succeeds. The JSON result retains top-level update status: "ok" and reports postUpdate.plugins.status: "warning" with openclaw update repair and openclaw plugins inspect <id> --runtime --json guidance. Unexpected updater or sync exceptions still fail the update result. Fix the plugin install or update error, then rerun openclaw update repair. When a failed update leaves a managed plugin unusable, OpenClaw disables its runtime entry and resets active slots without altering the operator-authored plugins.allow or plugins.deny policy.

Following the per-plugin sync step, openclaw update executes a mandatory post-core convergence pass before the gateway restarts: it repairs missing configured plugin payloads, validates each active tracked install record on disk, and statically verifies its package.json is parseable and its declared openclaw.extensions entries are loadable. When a package does not declare OpenClaw extensions, the check instead verifies any explicitly declared npm main. Failures from this pass, and an invalid config snapshot, return postUpdate.plugins.status: "error" and flip the top-level update status to "error", so openclaw update exits non-zero and the gateway is not restarted with an unverified plugin set. The error includes structured postUpdate.plugins.warnings[].guidance lines pointing at openclaw update repair and openclaw plugins inspect <id> --runtime --json. Disabled plugin entries and records that are not trusted-source-linked official sync targets are skipped here (mirroring the skipDisabledPlugins policy used by the missing-payload check), so a stale disabled plugin record cannot block an otherwise valid update.

When the updated Gateway starts, plugin loading is verify-only: startup does not run package managers or mutate dependency trees. Package-manager update.run restarts are handed to the CLI managed-service path, so the package swap happens outside the old Gateway process and the service health checks decide whether the update can be reported as complete.

After an extended-stable core update succeeds, post-core plugin integrity and convergence target eligible official npm plugins at the exact installed core version. For default/latest intent, OpenClaw does not query plugin @extended-stable or fall back to npm latest; it derives the package version from the installed core. Explicit version pins, explicit non-latest tags, third-party packages, and non-npm sources keep their existing intent.

For package-manager installs, openclaw update resolves the target package version before invoking the package manager. npm global installs use a staged install: OpenClaw installs the new package into a temporary npm prefix, lets the candidate package validate the host Node version during preinstall, and verifies the packaged dist inventory there. A packed completion guard stays outside that inventory until preinstall succeeds, so package managers that skip lifecycle scripts also stop before activation. On npm 12 and newer, the updater approves only the candidate OpenClaw lifecycle; transitive dependency scripts remain blocked. OpenClaw then swaps the clean package tree into the real global prefix. If verification fails, post-update doctor, plugin sync, and restart work do not run from the suspect tree. Even when the installed version already matches the target, the command refreshes the global package install, then runs plugin sync, a core-command completion refresh, and restart work. This keeps packaged sidecars and channel-owned plugin records aligned with the installed OpenClaw build, while leaving full plugin-command completion rebuilds to explicit openclaw completion --write-state runs.

Related

• openclaw doctor (offers to run update first on git checkouts)
• Development channels
• Updating
• CLI reference