Release channels

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. It receives read-only update hints when update.checkOnStart is enabled, including direct final extended-stable package installs, but never applies automatically.
• beta: the newest version by semantic version order from the npm beta and latest dist-tags. An older beta tag never replaces a newer stable release.
• dev: moving head of main (git), including when switching from a package install. 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

openclaw update --channel stableopenclaw update --channel extended-stableopenclaw update --channel betaopenclaw update --channel dev

--channel drives the update and persists the choice to update.channel in config after core update success. A refused or failed core update keeps the previous channel. The selected channel drives both install paths:

An explicit --channel stable or --channel beta switches a Git installation to a package installation. A bare openclaw update in a Git checkout with a previously stored stable or beta channel instead selects the corresponding Git tag. For these Git tag updates, OpenClaw refreshes branches without adding force to their configured refspecs, then force-refreshes tags only from the release remote. The retained branch.main.remote setting takes precedence, followed by origin or the only configured remote. With multiple remotes and neither choice, set branch.main.remote to the remote that publishes releases before retrying. Recreated release tags replace their old copies; local-only tags are preserved. Tag pruning is disabled even when Git's fetch.pruneTags setting is enabled. These guarantees assume standard branch fetch mappings; custom remote.*.fetch mappings that explicitly include tags still follow Git's configured behavior. The normal CLI inspects these refs in a private repository before admitting an update, so a refused update leaves the installed checkout's refs unchanged.

For managed Gateways, successful switches refresh the service to the verified installation before checking readiness. A refused switch or verified rollback recovers the previous service; unverified recovery leaves it stopped for inspection.

For dev git installs, the default checkout is ~/openclaw (or $OPENCLAW_HOME/openclaw when OPENCLAW_HOME is set); override with OPENCLAW_GIT_DIR. Automatic update campaigns pin the upstream commit they announce, so the displayed list previews up to five commits from the exact target installed even if main advances during the countdown. A manual openclaw update --channel dev still targets the current upstream main.

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:

# Install a specific versionopenclaw 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 specopenclaw update --tag [email protected] 

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.
• A package install with stored update.channel: "dev" still honors a one-off --tag without switching to Git. An explicit --channel dev takes precedence over --tag and selects the Git checkout flow.
• The --tag main shorthand is rejected for package installs because the workspace checkout is not a self-contained package artifact. 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.
• 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:

openclaw update --dry-runopenclaw update --channel beta --dry-runopenclaw update --tag 2026.4.1-beta.1 --dry-runopenclaw update --dry-run --json

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. Version-bound runtime plugins use the base release cohort for correction versions (for example, YYYY.M.P-2 uses plugin YYYY.M.P).
• npm-installed plugins are updated after the core update completes.
• beta uses the same newest-of-beta/latest rule for managed npm plugins, including official plugins such as @openclaw/codex. Exact version and range pins retain their selector. Startup repair keeps an already-current plugin instead of reinstalling it and requiring another restart.

Checking current status

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. It also shows the last recorded update run, including a failed fetch. Plain openclaw status uses cached Git refs without fetching. If the latest recorded update fetch in the current state directory failed, it shows update check stale: last update fetch failed with the failure's age and a short reason instead of up to date. Ahead/behind counts are labeled cached. A later update run with a completed fetch clears the warning, even if the rest of the update is skipped, fails, or rolls back. A manual git fetch does not clear the recorded warning. Use openclaw update status for a fresh availability check or run openclaw update again. openclaw status --deep also fetches for that check, without changing the ledger.

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.

Related

• Updating
• Installer internals
• Release policy - how releases are cut and published into these channels