Recommended: openclaw update
The fastest way to update. It detects your install type (npm or git), fetches the latest version, runs openclaw doctor, and restarts the gateway.
--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.
See Development channels for channel semantics.
Switch between npm and git installs
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.
--dry-run first to preview the exact install-mode switch:
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.
Alternative: re-run the installer
--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.
--version:
Alternative: manual npm, pnpm, or bun
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.
Advanced npm install topics
Read-only package tree
Read-only package tree
OpenClaw treats packaged global installs as read-only at runtime, even when the global package directory is writable by the current user. Bundled plugin runtime dependencies are staged into a writable runtime directory instead of mutating the package tree. This keeps
openclaw update from racing with a running gateway or local agent that is repairing plugin dependencies during the same install.Some Linux npm setups install global packages under root-owned directories such as /usr/lib/node_modules/openclaw. OpenClaw supports that layout through the same external staging path.Hardened systemd units
Hardened systemd units
Set a writable stage directory that is included in If
ReadWritePaths:OPENCLAW_PLUGIN_STAGE_DIR also accepts a path list. OpenClaw resolves bundled plugin runtime dependencies left-to-right across the listed roots, treats earlier roots as read-only preinstalled layers, and installs or repairs only into the final writable root:OPENCLAW_PLUGIN_STAGE_DIR is not set, OpenClaw uses $STATE_DIRECTORY when systemd provides it, then falls back to ~/.openclaw/plugin-runtime-deps. The repair step treats that stage as an OpenClaw-owned local package root and ignores user npm prefix and global settings, so global-install npm config does not redirect bundled plugin dependencies into ~/node_modules or the global package tree.Disk-space preflight
Disk-space preflight
Before package updates and bundled runtime-dependency repairs, OpenClaw tries a best-effort disk-space check for the target volume. Low space produces a warning with the checked path, but does not block the update because filesystem quotas, snapshots, and network volumes can change after the check. The actual npm install, copy, and post-install verification remain authoritative.
Bundled plugin runtime dependencies
Bundled plugin runtime dependencies
Packaged installs keep bundled plugin runtime dependencies out of the read-only package tree. On startup and during
openclaw doctor --fix, OpenClaw repairs runtime dependencies only for bundled plugins that are active in config, active through legacy channel config, or enabled by their bundled manifest default. Persisted channel auth state alone does not trigger Gateway startup runtime-dependency repair.Explicit disablement wins. A disabled plugin or channel does not get its runtime dependencies repaired just because it exists in the package. External plugins and custom load paths still use openclaw plugins install or openclaw plugins update.Auto-updater
The auto-updater is off by default. Enable it in~/.openclaw/openclaw.json:
| 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. |
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.
After updating
Migrates config, audits DM policies, and checks gateway health. Details: Doctor
Rollback
Pin a version (npm)
Pin a commit (source)
git checkout main && git pull.
If you are stuck
- Run
openclaw doctoragain and read the output carefully. - For
openclaw update --channel devon source checkouts, the updater auto-bootstrapspnpmwhen needed. If you see a pnpm/corepack bootstrap error, installpnpmmanually (or re-enablecorepack) and rerun the update. - Check: Troubleshooting
- Ask in Discord: https://discord.gg/clawd
Related
- Install overview: all installation methods.
- Doctor: health checks after updates.
- Migrating: major version migration guides.