Use this file to discover all available pages before exploring further.
Release channels
Development channels
OpenClaw ships three update channels:
- stable: npm dist-tag . Recommended for most users.
- beta: npm dist-tag when it is current; if beta is missing or older than
the latest stable release, the update flow falls back to .
- dev: moving head of (git). npm dist-tag: (when published).
The branch is for experimentation and active development. It may contain
incomplete features or breaking changes. Do not use it for production gateways.
We usually ship stable builds to beta first, test them there, then run an
explicit promotion step that moves the vetted build to
without
changing the version number. Maintainers can also publish a stable release
directly to
when needed. Dist-tags are the source of truth for npm
installs.
Switching channels
openclaw update --channel stable
openclaw update --channel beta
openclaw update --channel dev
persists your choice in config (
) and aligns the
install method:
- (package installs): updates via npm dist-tag .
- (package installs): prefers npm dist-tag , but falls back to
when is missing or older than the current stable tag.
- (git installs): checks out the latest stable git tag.
- (git installs): prefers the latest beta git tag, but falls back to
the latest stable git tag when beta is missing or older.
- : ensures a git checkout (default , override with
), switches to , rebases on upstream, builds, and
installs the global CLI from that checkout.
tip
If you want stable and dev in parallel, keep two clones and point your gateway at the stable one.
One-off version or tag targeting
Use
to target a specific dist-tag, version, or package spec for a single
update
without changing your 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
# Install from GitHub main branch (npm tarball)
openclaw update --tag main
# Install a specific npm package spec
openclaw update --tag openclaw@2026.4.1-beta.1
Notes:
- applies to package (npm) installs only. Git installs ignore it.
- The tag is not persisted. Your next uses your configured
channel as usual.
- Downgrade protection: if the target version is older than your current version,
OpenClaw prompts for confirmation (skip with ).
- is different from : the channel flow can fall back
to stable/latest when beta is missing or older, while targets the
raw dist-tag for that one run.
Dry run
Preview what
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 shows the effective channel, target version, planned actions, and
whether a downgrade confirmation would be required.
Plugins and channels
When you switch channels with
, OpenClaw also syncs plugin
sources:
- prefers bundled plugins from the git checkout.
- and restore npm-installed plugin packages.
- npm-installed plugins are updated after the core update completes.
Checking current status
Shows the active channel, install kind (git or package), current version, and
source (config, git tag, git branch, or default).
Tagging best practices
- Tag releases you want git checkouts to land on ( for stable,
for beta).
- is also recognized for compatibility, but prefer .
- Legacy tags are still recognized as stable (non-beta).
- Keep tags immutable: never move or reuse a tag.
- npm dist-tags remain the source of truth for npm installs:
- -> stable
- -> candidate build or beta-first stable build
- -> main snapshot (optional)
macOS app availability
Beta and dev builds may not include a macOS app release. That is OK:
- The git tag and npm dist-tag can still be published.
- Call out "no macOS build for this beta" in release notes or changelog.
Related