Skip to main content
OpenClaw ships four update channels:
  • stable: npm dist-tag latest. Recommended for most users.
  • extended-stable: npm dist-tag extended-stable. A net-new, trailing supported-month package channel. It is package-only, and installation is foreground-only. A stored selection receives read-only update hints when update.checkOnStart is enabled, but never applies automatically.
  • beta: npm dist-tag beta. Falls back to latest when beta is missing or older than the current stable release.
  • dev: moving head of main (git). npm dist-tag dev when published. main is for experimentation and active development; it may contain incomplete features or breaking changes. Do not run it for production gateways.
Stable builds usually ship to beta first, get vetted there, then get promoted to latest without a version bump. Maintainers can also publish directly to latest. Dist-tags are the source of truth for npm installs.

​
Switching channels

--channel persists the choice to update.channel in config and drives both install paths: For dev git installs, the default checkout is ~/openclaw (or $OPENCLAW_HOME/openclaw when OPENCLAW_HOME is set); override with OPENCLAW_GIT_DIR.
To keep stable and dev in parallel, use two separate checkouts and point each gateway at its own.

​
One-off version or tag targeting

Use --tag to target a specific dist-tag, version, or package spec for a single update without changing the persisted channel:
Notes:
  • --tag applies to package (npm) installs only; git installs ignore it.
  • The tag is not persisted; the next openclaw update uses the configured channel.
  • --tag main maps to the npm-compatible spec github:openclaw/openclaw#main for that one run. For a persistent moving main install, use openclaw update --channel dev (package installs switch to a git checkout) or reinstall with the installer’s git method: curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --version main. The npm install path rejects GitHub/git source targets outright and points you at the git method instead.
  • Downgrade protection: if the target version is older than the current version, OpenClaw prompts for confirmation (skip with --yes).
  • Extended-stable always uses its verified exact package target. It is not a one-off alias for --tag extended-stable, and --tag cannot be combined with an effective extended-stable channel.
  • --channel beta differs from --tag beta: the channel flow can fall back to stable/latest when beta is missing or older, while --tag beta always targets the raw beta dist-tag for that one run.

​
Dry run

Preview what openclaw update would do without making changes:
The dry run reports the effective channel, target version, planned actions, and whether a downgrade confirmation would be required.

​
Plugins and channels

Switching channels with openclaw update also syncs plugin sources:
  • dev switches installed plugins that have a bundled counterpart back to their bundled (git checkout) source.
  • stable and beta restore npm-installed or ClawHub-installed plugin packages.
  • extended-stable resolves eligible official npm plugins with bare/default or latest intent to the exact installed core version. It does not query plugin @extended-stable tags at runtime.
  • npm-installed plugins are updated after the core update completes.

​
Checking current status

Shows the active channel (with the source that decided it: config, git tag, git branch, installed version, or default), install kind (git or package), current version, and update availability.

​
Tagging best practices

  • Tag releases you want git checkouts to land on: vYYYY.M.PATCH for stable, vYYYY.M.PATCH-beta.N for beta. Named prerelease suffixes such as -alpha.N, -rc.N, and -next.N are not stable or beta targets.
  • Legacy numeric stable tags such as vYYYY.M.PATCH-1 and v1.0.1-1 are still recognized as stable git tags for compatibility.
  • vYYYY.M.PATCH.beta.N (dot-separated) is also recognized for compatibility; prefer -beta.N.
  • Keep tags immutable: never move or reuse a tag.
  • npm dist-tags remain the source of truth for npm installs:
    • latest -> stable
    • extended-stable -> trailing supported-month package release
    • beta -> candidate build or beta-first stable build
    • dev -> main snapshot (optional)

​
macOS app availability

Beta and dev builds may not include a macOS app release. That is fine:
  • The git tag and npm dist-tag can still publish on their own.
  • Call out “no macOS build for this beta” in release notes or changelog.