Use this file to discover all available pages before exploring further.
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 update
openclaw update status
openclaw update wizard
openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag beta
openclaw update --tag main
openclaw update --dry-run
openclaw update --no-restart
openclaw update --yes
openclaw update --json
openclaw --update
Options
- : 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>
--tag <dist-tag|version|spec>
github:openclaw/openclaw#main
- : preview planned update actions (channel/tag/target/restart flow) without writing config, installing, syncing plugins, or restarting.
- : print machine-readable JSON, including
postUpdate.plugins.integrityDrifts
- : per-step timeout (default is 1800s).
- : skip confirmation prompts (for example downgrade confirmation).
warning
Downgrades require confirmation because older versions can break configuration.
Show the active update channel + git tag/branch/SHA (for source checkouts), plus update availability.
openclaw update status
openclaw update status --json
openclaw update status --timeout 10
Options:
- : print machine-readable status JSON.
- : timeout for checks (default is 3s).
Interactive flow to pick an update channel and confirm whether to restart the Gateway
after updating (default is to restart). If you select
without a git checkout, it
offers to create one.
Options:
- : timeout for each update step (default )
What it does
When you switch channels explicitly (
), OpenClaw also keeps the
install method aligned:
- → ensures a git checkout (default: , override with ),
updates it, and installs the global CLI from that checkout.
- → installs from npm using .
- → prefers npm dist-tag , but falls back to when beta is
missing or older than the current stable release.
The Gateway core auto-updater (when enabled via config) reuses this same update path.
For package-manager installs,
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
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 updates stop the running service before replacing the package
tree, then refresh the service metadata from the updated install, restart the
service, and verify the restarted Gateway reports the expected version. With
, package replacement still runs but the managed service is not
stopped or restarted, so the running Gateway may keep old code until you restart
it manually.
Git checkout flow
Channel selection
- : checkout the latest non-beta tag, then build and doctor.
- : prefer the latest tag, but fall back to the latest stable tag when beta is missing or older.
- : checkout , then fetch and rebase.
Update steps
Verify clean worktree
Requires no uncommitted changes.
Switch channel
Switches to the selected channel (tag or branch).
Preflight build (dev only)
Runs lint and TypeScript build in a temp worktree. If the tip fails, walks back up to 10 commits to find the newest clean build.
Rebase
Rebases onto the selected commit (dev only).
Install dependencies
Uses the repo package manager. For pnpm checkouts, the updater bootstraps `pnpm` on demand (via `corepack` first, then a temporary `npm install pnpm@10` fallback) instead of running `npm run build` inside a pnpm workspace.
Build Control UI
Builds the gateway and the Control UI.
Run doctor
`openclaw doctor` runs as the final safe-update check.
Sync plugins
Syncs plugins to the active channel. Dev uses bundled plugins; stable and beta use npm. Updates npm-installed plugins.
warning
If an exact pinned npm plugin update resolves to an artifact whose integrity differs from the stored install record, `openclaw update` aborts that plugin artifact update instead of installing it. Reinstall or update the plugin explicitly only after verifying that you trust the new artifact.
note
Post-update plugin sync failures fail the update result and stop restart follow-up work. Fix the plugin install or update error, then rerun `openclaw update`.
When the updated Gateway starts, enabled bundled plugin runtime dependencies are staged before plugin activation. Update-triggered restarts drain any active runtime-dependency staging before closing the Gateway, so service-manager restarts do not interrupt an in-flight npm install.
If pnpm bootstrap still fails, the updater stops early with a package-manager-specific error instead of trying
inside the checkout.
shorthand
rewrites to
(useful for shells and launcher scripts).
Related