docs/install/updating.md
Keep OpenClaw up to date.
openclaw updateThe fastest way to update. It detects your install type (npm or git), fetches the latest version, runs openclaw doctor, and restarts the gateway.
openclaw update
To switch channels or target a specific version:
openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag main
openclaw update --dry-run # preview without applying
openclaw update does not accept --verbose. For update diagnostics, use
--dry-run to preview the planned actions, --json for structured results, or
openclaw update status --json to inspect channel and availability state. The
installer has its own --verbose flag, but that flag is not part of
openclaw update.
--channel beta prefers beta, but the runtime falls back to stable/latest when
the beta tag is missing or older than the latest stable release. Use --tag beta
if you want the raw npm beta dist-tag for a one-off package update.
For managed plugins, beta-channel fallback is a warning: the core update can still succeed while a plugin uses its recorded default/latest release because no plugin beta is available.
See Development channels for channel semantics.
Use channels when you want to change the install type. The updater keeps your
state, config, credentials, and workspace in ~/.openclaw; it only changes
which OpenClaw code install the CLI and gateway use.
# npm package install -> editable git checkout
openclaw update --channel dev
# git checkout -> npm package install
openclaw update --channel stable
Run with --dry-run first to preview the exact install-mode switch:
openclaw update --channel dev --dry-run
openclaw update --channel stable --dry-run
The dev channel ensures a git checkout, builds it, and installs the global CLI
from that checkout. The stable and beta channels use package installs. If the
gateway is already installed, openclaw update refreshes the service metadata
and restarts it unless you pass --no-restart.
For package installs with a managed Gateway service, openclaw update targets
the package root used by that service. If the shell openclaw command comes
from a different install, the updater prints both roots and the managed service
Node path. The package update uses the package manager that owns the service
root and checks the managed service Node against the target release engine
before replacing the package.
curl -fsSL https://openclaw.ai/install.sh | bash
Add --no-onboard to skip onboarding. To force a specific install type through
the installer, pass --install-method git --no-onboard or
--install-method npm --no-onboard.
If openclaw update fails after the npm package install phase, re-run the
installer. The installer does not call the old updater; it runs the global
package install directly and can recover a partially updated npm install.
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
To pin the recovery to a specific version or dist-tag, add --version:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>
npm i -g openclaw@latest
Prefer openclaw update for supervised installs because it can coordinate the
package swap with the running Gateway service. If you update manually on a
supervised install, stop the managed Gateway before the package manager starts.
Package managers replace files in place, and a running Gateway can otherwise try
to load core or plugin files while the package tree is temporarily half-swapped.
Restart the Gateway after the package manager finishes so the service picks up
the new install.
For a root-owned Linux system-global install, if openclaw update fails with
EACCES and you recover with system npm, keep the Gateway stopped through the
manual package replacement. Use the same openclaw profile flags or environment
you normally use for that Gateway. Replace /usr/bin/npm with the system npm
that owns the root-owned global prefix on your host:
openclaw gateway stop
sudo /usr/bin/npm i -g openclaw@latest
openclaw gateway install --force
openclaw gateway restart
Then verify the service:
openclaw --version
curl -fsS http://127.0.0.1:18789/readyz
openclaw plugins list --json
openclaw gateway status --deep --json
openclaw doctor --lint --json
When openclaw update manages a global npm install, it installs the target into
a temporary npm prefix first, verifies the packaged dist inventory, then swaps
the clean package tree into the real global prefix. That avoids npm overlaying a
new package onto stale files from the old package. If the install command fails,
OpenClaw retries once with --omit=optional. That retry helps hosts where native
optional dependencies cannot compile, while keeping the original failure visible
if the fallback also fails.
OpenClaw-managed npm update and plugin-update commands also clear npm
min-release-age quarantine for the child npm process. npm may report that
policy as a derived before cutoff; both are useful for general supply-chain
quarantine policies, but an explicit OpenClaw update means "install the selected
OpenClaw release now."
pnpm add -g openclaw@latest
bun add -g openclaw@latest
Some Linux npm setups install global packages under root-owned directories such as `/usr/lib/node_modules/openclaw`. OpenClaw supports that layout because plugin install/update commands write outside that global package directory.
```ini
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
```
The auto-updater is off by default. Enable it in ~/.openclaw/openclaw.json:
{
update: {
channel: "stable",
auto: {
enabled: true,
stableDelayHours: 6,
stableJitterHours: 12,
betaCheckIntervalHours: 1,
},
},
}
| Channel | Behavior |
|---|---|
stable | Waits stableDelayHours, then applies with deterministic jitter across stableJitterHours (spread rollout). |
beta | Checks every betaCheckIntervalHours (default: hourly) and applies immediately. |
dev | No automatic apply. Use openclaw update manually. |
The gateway also logs an update hint on startup (disable with update.checkOnStart: false).
For downgrade or incident recovery, set OPENCLAW_NO_AUTO_UPDATE=1 in the gateway environment to block automatic applies even when update.auto.enabled is configured. Startup update hints can still run unless update.checkOnStart is also disabled.
Package-manager updates requested through the live Gateway control-plane handler
do not replace the package tree inside the running Gateway process. On managed
service installs, the Gateway starts a detached handoff, exits, and lets the
normal openclaw update --yes --json CLI path stop the service, replace the
package, refresh service metadata, restart, verify the Gateway version and
reachability, and recover an installed-but-unloaded macOS LaunchAgent when
possible. If the Gateway cannot make that handoff safely, update.run reports a
safe shell command instead of running the package manager in-process.
openclaw doctor
Migrates config, audits DM policies, and checks gateway health. Details: Doctor
openclaw gateway restart
openclaw health
npm i -g openclaw@<version>
openclaw doctor
openclaw gateway restart
git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
pnpm install && pnpm build
openclaw gateway restart
To return to latest: git checkout main && git pull.
openclaw doctor again and read the output carefully.openclaw update --channel dev on source checkouts, the updater auto-bootstraps pnpm when needed. If you see a pnpm/corepack bootstrap error, install pnpm manually (or re-enable corepack) and rerun the update.