docs/install/development-channels.md
OpenClaw ships four update channels:
latest. Recommended for most users.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. Falls back to latest when beta is missing
or older than the current stable release.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.
openclaw update --channel stable
openclaw update --channel extended-stable
openclaw update --channel beta
openclaw update --channel dev
--channel persists the choice to update.channel in config and drives both
install paths:
| Channel | npm/package installs | git installs |
|---|---|---|
stable | dist-tag latest | latest stable git tag (excludes -alpha.N, -beta.N, -rc.N, -dev.N, -next.N, -preview.N, -canary.N, -nightly.N, and other named prerelease suffixes) |
extended-stable | resolves the public npm extended-stable selector, verifies the exact selected package, and installs that exact version. Fails closed with no fallback to latest, beta, or dev. | unsupported: OpenClaw leaves the checkout unchanged and asks you to use a package installation |
beta | dist-tag beta, falling back to latest when beta is missing or older | latest beta git tag, falling back to the latest stable git tag when beta is missing or older |
dev | dist-tag dev (rare; most dev users run git installs) | fetches, rebases the checkout on the upstream main branch, builds, and reinstalls the global CLI |
For dev git installs, the default checkout is ~/openclaw (or
$OPENCLAW_HOME/openclaw when OPENCLAW_HOME is set); override with
OPENCLAW_GIT_DIR.
Use --tag to target a specific dist-tag, version, or package spec for a
single update without changing the persisted channel:
# Install a specific version
openclaw update --tag 2026.4.1-beta.1
# Install from the beta dist-tag (one-off, does not persist)
openclaw update --tag beta
# Switch to the moving GitHub main checkout (persistent)
openclaw update --channel dev
# Install a specific npm package spec
openclaw update --tag [email protected]
# Install from GitHub main once without persisting the channel
openclaw update --tag main
Notes:
--tag applies to package (npm) installs only; git installs ignore it.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.--yes).--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.Preview what openclaw update would do without making changes:
openclaw update --dry-run
openclaw update --channel beta --dry-run
openclaw update --tag 2026.4.1-beta.1 --dry-run
openclaw update --dry-run --json
The dry run reports the effective channel, target version, planned actions, and whether a downgrade confirmation would be required.
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.openclaw update 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.
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.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.latest -> stableextended-stable -> trailing supported-month package releasebeta -> candidate build or beta-first stable builddev -> main snapshot (optional)Beta and dev builds may not include a macOS app release. That is fine: