mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-07 08:23:33 +00:00
d214622320
* feat(update): add extended-stable channel contract * feat(update): implement extended-stable package flow * docs(update): document extended-stable behavior * fix(update): preserve extended-stable preflight guarantees * fix(update): reject extended-stable Git repair * fix(update): support loopback extended-stable canaries * fix(update): preserve scoped package roots
165 lines
6.5 KiB
Markdown
165 lines
6.5 KiB
Markdown
---
|
|
summary: "Stable, extended-stable, beta, and dev channels: semantics, switching, pinning, and tagging"
|
|
read_when:
|
|
- You want to switch between stable/extended-stable/beta/dev
|
|
- You want to pin a specific version, tag, or SHA
|
|
- You are tagging or publishing prereleases
|
|
title: "Release channels"
|
|
sidebarTitle: "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 foreground-only in this release.
|
|
- **beta**: npm dist-tag `beta` when it is current; if beta is missing or older than
|
|
the latest stable release, the update flow falls back to `latest`.
|
|
- **dev**: moving head of `main` (git). npm dist-tag: `dev` (when published).
|
|
The `main` 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 `latest` without
|
|
changing the version number. Maintainers can also publish a stable release
|
|
directly to `latest` when needed. Dist-tags are the source of truth for npm
|
|
installs.
|
|
|
|
## Switching channels
|
|
|
|
```bash
|
|
openclaw update --channel stable
|
|
openclaw update --channel extended-stable
|
|
openclaw update --channel beta
|
|
openclaw update --channel dev
|
|
```
|
|
|
|
`--channel` persists your choice in config (`update.channel`) and aligns the
|
|
install method:
|
|
|
|
- **`stable`** (package installs): updates via npm dist-tag `latest`.
|
|
- **`extended-stable`** (package installs only): resolves the public npm
|
|
`extended-stable` selector, verifies the exact selected package version, and
|
|
installs that exact version. Resolution fails closed with no fallback to
|
|
`latest`, `beta`, or `dev`.
|
|
- **`beta`** (package installs): prefers npm dist-tag `beta`, but falls back to
|
|
`latest` when `beta` is missing or older than the current stable tag.
|
|
- **`stable`** (git installs): checks out the latest stable git tag, excluding
|
|
semver prerelease tags such as `-alpha.N`, `-beta.N`, `-rc.N`, `-dev.N`,
|
|
`-next.N`, `-preview.N`, `-canary.N`, `-nightly.N`, and other prerelease
|
|
suffixes.
|
|
- **`beta`** (git installs): prefers the latest beta git tag, but falls back to
|
|
the latest stable git tag when beta is missing or older.
|
|
- **`extended-stable`** (git installs): unsupported. OpenClaw leaves the
|
|
checkout unchanged and asks you to use a package installation.
|
|
- **`dev`**: ensures a git checkout (default `~/openclaw`, or
|
|
`$OPENCLAW_HOME/openclaw` when `OPENCLAW_HOME` is set; override with
|
|
`OPENCLAW_GIT_DIR`), switches to `main`, 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.
|
|
</Tip>
|
|
|
|
## One-off version or tag targeting
|
|
|
|
Use `--tag` to target a specific dist-tag, version, or package spec for a single
|
|
update **without** changing your persisted channel:
|
|
|
|
```bash
|
|
# 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
|
|
openclaw update --channel dev
|
|
|
|
# Install a specific npm package spec
|
|
openclaw update --tag openclaw@2026.4.1-beta.1
|
|
|
|
# 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.
|
|
- The tag is not persisted. Your next `openclaw update` uses your configured
|
|
channel as usual.
|
|
- For package installs, OpenClaw pre-packs GitHub/git source specs into a
|
|
temporary tarball before the staged npm install. Use `--channel dev` or
|
|
`--install-method git --version main` when you want the moving `main`
|
|
checkout as your persistent install.
|
|
- Downgrade protection: if the target version is older than your 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` is different from `--tag beta`: the channel flow can fall back
|
|
to stable/latest when beta is missing or older, while `--tag beta` targets the
|
|
raw `beta` dist-tag for that one run.
|
|
|
|
## Dry run
|
|
|
|
Preview what `openclaw update` would do without making changes:
|
|
|
|
```bash
|
|
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 update`, OpenClaw also syncs plugin
|
|
sources:
|
|
|
|
- `dev` prefers bundled plugins from the git checkout.
|
|
- `stable` and `beta` restore npm-installed plugin packages.
|
|
- `extended-stable` currently uses the existing stable/latest plugin line after
|
|
the core package succeeds. Official plugin `@extended-stable` selectors are
|
|
not queried yet.
|
|
- npm-installed plugins are updated after the core update completes.
|
|
|
|
## Checking current status
|
|
|
|
```bash
|
|
openclaw update 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 (`vYYYY.M.PATCH` for stable,
|
|
`vYYYY.M.PATCH-beta.N` for beta; named semver prerelease suffixes such as
|
|
`-alpha.N`, `-rc.N`, and `-next.N` are not stable 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` is also recognized for compatibility, but 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 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
|
|
|
|
- [Updating](/install/updating)
|
|
- [Installer internals](/install/installer)
|