Switch OpenClaw Development Channels in Seconds

We’ve all been there—trying to test a new feature without wrecking a stable environment. It’s a balancing act between staying current and staying safe. Managing different versions of a CLI tool can be a headache, especially when you need to jump between stable releases and experimental features.

OpenClaw makes this easier by giving you clear paths for how you receive updates.

Development channels

OpenClaw ships three update channels:

• stable: npm dist-tag latest. Recommended for most users.
• beta: npm dist-tag beta (builds under test).
• 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 ship builds to beta, test them, then promote a vetted build to latest without changing the version number — dist-tags are the source of truth for npm installs.

Switching channels

openclaw update --channel stable
openclaw update --channel beta
openclaw update --channel dev

--channel persists your choice in config (update.channel) and aligns the install method:

• stable/beta (package installs): updates via the matching npm dist-tag.
• stable/beta (git installs): checks out the latest matching git tag.
• dev: ensures a git checkout (default ~/openclaw, 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 + dev in parallel, keep two clones and point your gateway at the stable one.

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:

# 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:

• --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.
• Downgrade protection: if the target version is older than your current version, OpenClaw prompts for confirmation (skip with --yes).

Dry 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 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.
• npm-installed plugins are updated after the core update completes.

Checking current status

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.D for stable, vYYYY.M.D-beta.N for beta).
• vYYYY.M.D.beta.N is also recognized for compatibility, but prefer -beta.N.
• Legacy vYYYY.M.D-<patch> 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:
  • latest -> stable
  • beta -> candidate 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.

Next steps

• Update Command Reference
• Configuration Guide

Need help getting your environment set up? Check out the AI Setup Assistant.