openclaw update

Safely update OpenClaw and switch between stable/beta/dev channels.

If you installed via npm/pnpm/bun (global install, no git metadata), updates happen via the package-manager flow in Updating.

Usage

openclaw updateopenclaw update statusopenclaw update repairopenclaw update wizardopenclaw update --channel betaopenclaw update --channel devopenclaw update --tag betaopenclaw update --tag mainopenclaw update --dry-runopenclaw update --no-restartopenclaw update --yesopenclaw update --jsonopenclaw --update

Options

• --no-restart: skip restarting the Gateway service after a successful update. Package-manager updates that do restart the Gateway verify the restarted service reports the expected updated version before the command succeeds.
• --channel <stable|beta|dev>: set the update channel (git + npm; persisted in config).
• --tag <dist-tag|version|spec>: override the package target for this update only. For package installs, main maps to github:openclaw/openclaw#main; GitHub/git source specs are packed into a temporary tarball before the staged global npm install.
• --dry-run: preview planned update actions (channel/tag/target/restart flow) without writing config, installing, syncing plugins, or restarting.
• --json: print machine-readable UpdateRunResult JSON, including postUpdate.plugins.warnings when corrupt or unloadable managed plugins need repair after the core update succeeds, beta-channel plugin fallback details when a plugin has no beta release, and postUpdate.plugins.integrityDrifts when npm plugin artifact drift is detected during post-update plugin sync.
• --timeout <seconds>: per-step timeout (default is 1800s).
• --yes: skip confirmation prompts (for example downgrade confirmation).

openclaw update does not have a --verbose flag. Use --dry-run to preview the planned channel/tag/install/restart actions, --json for machine-readable results, and openclaw update status --json when you only need channel and availability details. If you are debugging Gateway logs around an update, console verbosity and file log level are separate: Gateway --verbose affects terminal/WebSocket output, while file logs require logging.level: "debug" or "trace" in config. See Gateway logging.

update status

Show the active update channel + git tag/branch/SHA (for source checkouts), plus update availability.

openclaw update statusopenclaw update status --jsonopenclaw update status --timeout 10

Options:

• --json: print machine-readable status JSON.
• --timeout <seconds>: timeout for checks (default is 3s).

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 still needs to converge.

openclaw update repairopenclaw update repair --channel betaopenclaw update repair --json

Options:

• --channel <stable|beta|dev>: persist the update channel before repair and run plugin convergence against that channel.
• --json: print machine-readable finalization JSON.
• --timeout <seconds>: timeout for repair steps (default 1800).
• --yes: skip confirmation prompts.
• --no-restart: accepted for update command parity; repair never restarts the Gateway.

openclaw update repair runs openclaw doctor --fix, reloads the repaired config and install records, syncs tracked plugins for the active update channel, updates managed npm plugin installs, repairs missing configured plugin payloads, refreshes the plugin registry, and writes the converged install-record metadata. It does not install a new core package and does not restart the Gateway.

update wizard

Interactive flow to pick an update channel and confirm whether to restart the Gateway after updating (default is to restart). If you select dev without a git checkout, it offers to create one.

Options:

• --timeout <seconds>: timeout for each update step (default 1800)

What it does

When you switch channels explicitly (--channel ...), OpenClaw also keeps the install method aligned:

• dev → ensures a git checkout (default: ~/openclaw, or $OPENCLAW_HOME/openclaw when OPENCLAW_HOME is set; override with OPENCLAW_GIT_DIR), updates it, and installs the global CLI from that checkout.
• stable → installs from npm using latest.
• beta → prefers npm dist-tag beta, but falls back to latest when beta is missing or older than the current stable release.

The Gateway core auto-updater (when enabled via config) launches the CLI update path outside the live Gateway request handler. Control-plane update.run package-manager updates and supervised git-checkout updates also use a managed-service handoff instead of replacing the package tree or rebuilding dist/ inside the live Gateway process. The Gateway starts a detached helper, exits, and the helper runs the normal openclaw update --yes --json CLI path from outside the Gateway process tree. If that handoff is unavailable, update.run returns a structured response with the safe shell command to run manually.

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, verifies the packaged dist inventory there, then swaps that 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.

When a local managed Gateway service is installed and restart is enabled, package-manager and git-checkout updates stop the running service before replacing the package tree or mutating the checkout/build output. The updater then refreshes the service metadata from the updated install, restarts the service, and verifies the restarted Gateway before reporting Gateway: restarted and verified.. Package-manager updates additionally verify the restarted Gateway reports the expected package version; git-checkout updates verify gateway health and service readiness after the rebuild. On macOS, the post-update check also verifies 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, then reruns the health/version/channel readiness checks. A fresh bootstrap loads the RunAtLoad job directly, so update recovery does not immediately kickstart -k the newly spawned Gateway. If the Gateway still does not become healthy, the command exits non-zero and prints the restart log path plus explicit 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 runs but the managed service is not stopped or restarted, so the running Gateway may keep old code until you restart it manually.

Control-plane response shape

When update.run is invoked through the Gateway control plane on a package-manager install or supervised git checkout, the handler reports the 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" mean 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" mean OpenClaw could not find a supervising service boundary and durable service identity for a safe handoff. For example, systemd handoff requires the OpenClaw unit identity (OPENCLAW_SYSTEMD_UNIT), not only 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" means the Gateway tried to create the handoff but could not spawn the detached helper.

The sentinel payload is still written before the Gateway exits, and the CLI handoff updates the 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 keeps polling it and only fires the continuation 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: checkout the latest non-beta tag, then build and doctor.
• beta: prefer the latest -beta tag, but fall back to the latest stable tag when beta is missing or older.
• dev: checkout main, then fetch and rebase.

Update steps

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

--update shorthand

openclaw --update rewrites to openclaw update (useful for shells and launcher scripts).

Related

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