How to Update OpenClaw: Commands, Channels, and Troubleshooting

OpenClaw shipped four builds in 48 hours during the week of May 18, 2026: the stable 2026.5.18 release, two betas on the 2026.5.19 line, and an alpha (GitHub releases). At that cadence, a single update can move your install forward by multiple versions in a day. Whether that is a feature or a problem depends on how well you understand what the update command actually does.

By default, the update command pulls the latest version for your configured release channel, installs it, and restarts the Gateway service (official docs). For npm-based stable installs, this is usually fine. The catch is that your "configured channel" may not be what you expect. A documented bug (#18702) causes git installs to default to the dev channel even when you are checked out to a stable release tag like v2026.2.15. A routine update can silently jump you from a vetted build to unreleased code on the main branch.

Most guides stop at "run the update command and you're done." That covers the happy path on npm stable and nothing else. If you need to test beta features, pin to a specific version, preview changes before applying them, or recover from a failed update, you need the full command surface.

Before running any update, confirm what you have and what is available. The status subcommand reports your active channel (stable, beta, or dev), current version, install method (npm or git), and whether a newer build exists for your channel. If the output says "Update available," a newer version is ready to pull.

For a quick version check without the full report:

openclaw --version

Compare the output against the releases page to see where you stand relative to the latest builds.

Pay attention to the channel shown in the status output. If you installed via git and see dev listed even though you are on a release tag, you have hit the #18702 bug. Fix it before updating:

openclaw update --channel stable

This sets the channel explicitly and persists the preference in your OpenClaw config file. Future updates pull from stable without needing the flag again.

The status command also accepts --json for automation. If you manage multiple OpenClaw instances or run update checks in CI, the JSON output gives you a structured payload you can parse programmatically.

The standard update workflow does everything in one step. The update subcommand pulls the latest version for your configured channel, applies it, and restarts the Gateway. The default per-step timeout is 1800 seconds (30 minutes), long enough to handle large dependency trees and slow connections.

For most users on npm stable, that single command works. But the subcommand accepts flags that give you precise control over what happens:

• --channel <stable|beta|dev> switches the release channel and persists the choice in config
• --dry-run previews all planned actions without modifying anything
• --no-restart skips the automatic Gateway restart after a successful update
• --json returns machine-readable output for scripting
• --timeout <seconds> overrides the default 1800-second per-step timeout
• --tag <version> targets a specific version or npm dist-tag for this update only, without changing your persisted channel
• --yes bypasses confirmation prompts

Flags combine naturally. Preview what a beta update would do:

openclaw update --channel beta --dry-run

Update but keep the Gateway on the old version until you restart manually:

openclaw update --no-restart

Pin to a known-good version when the latest introduces a regression:

openclaw update --tag v2026.5.14

The --tag flag is temporary. It does not change your configured channel, so the next run of the update subcommand without --tag picks up the latest for your channel again.

There is also a shorthand form:

openclaw --update

This runs the same logic as the full subcommand. Some operators prefer it for muscle memory, though the explicit form is clearer in scripts.

For first-time channel changes, the wizard subcommand walks you through the process interactively:

openclaw update wizard

It asks which channel you want, explains the differences, and confirms whether to restart the Gateway after updating.

Keep your agent's output stable across OpenClaw updates

Fastio gives your OpenClaw agents 50GB of free workspace storage with MCP access. Files persist across updates, channel switches, and version changes. No credit card, no trial expiration.

Start 14-Day Trial

Each channel serves a different purpose, and switching between them has mechanical consequences beyond which version you receive.

Stable tracks the latest npm dist-tag for package installs and the newest stable git tag for git installs. Builds here have been tested through the beta channel first. If your agents run in production or you depend on consistent behavior between updates, stable is the right default.

Beta tracks the beta npm dist-tag. It gets features days or weeks before stable, which is useful for testing new capabilities before they reach production. The update logic includes a safety net: if no beta build exists, or if the current beta is older than the latest stable release, the command falls back to stable automatically. You will not accidentally downgrade by staying on the beta channel.

Dev follows the main branch in git and the dev npm dist-tag when published. This is experimental territory. Builds may include incomplete features, breaking changes, and code that has not passed full test suites. The dev channel compensates with a preflight build check: before applying an update, it builds the project in a temporary directory. If the latest commit fails to compile, the updater walks back through up to 10 previous commits to find the newest one that builds successfully.

To switch channels permanently:

openclaw update --channel beta

This does two things at once. It updates to the latest beta build immediately, and it saves beta as your default channel in config. Every future update pulls from beta unless you change the channel again.

The install method adjusts automatically when you switch. Moving from stable (npm) to dev triggers a git checkout. Moving from dev (git) back to stable resolves through npm dist-tags. Plugin sources sync during the transition, so skills and integrations stay compatible with the new channel.

If you need to lock down updates entirely for Nix-managed installs, set the environment variable OPENCLAW_NIX_MODE=1. This restricts the subcommand to read-only operations: the status check and --dry-run still work, but the actual update step is blocked.

The --dry-run flag is your pre-flight check. It prints every action the update would take (version download, dependency changes, Gateway restart, plugin sync) without executing any of them:

openclaw update --dry-run

Use it before switching channels, after a long gap between updates, or on production gateways where unexpected behavior has real consequences. Combine it with --json for structured output you can pipe into monitoring tools:

openclaw update --dry-run --json

Downgrades get special treatment. If you target an older version through --tag or by switching from dev to stable, OpenClaw asks for explicit confirmation before proceeding. This is not just a courtesy prompt. Newer versions may introduce config changes, database migrations, or plugin API updates that older versions cannot interpret. Rolling back to a version that predates these changes can break your configuration or corrupt state.

If you are certain the downgrade is safe, --yes bypasses the confirmation:

openclaw update --tag v2026.5.3 --yes

When an agent running on OpenClaw generates files you cannot afford to lose during version transitions, consider externalizing that storage. Local directories tied to an OpenClaw install are convenient but fragile across version jumps. Services like Fastio or S3-compatible stores keep agent output intact regardless of which version or channel your install runs.

Updates fail for predictable reasons. Here are the ones that come up most often and how to resolve them.

Git installs pulling from the wrong channel. If the status check shows dev when you expected stable, you are seeing bug #18702. The update logic defaults to dev for git installs without checking your checkout state. Fix it by running the update with --channel stable, then verify by checking the status again.

Gateway won't restart after update. The automatic post-update restart can fail if you run OpenClaw behind a custom process manager, in Docker with specific health-check constraints, or on a system where the Gateway process is supervised externally. When this happens, the update command prints manual restart and rollback instructions. Follow them. If you expect restart complications, use --no-restart from the start and handle the restart through your own process management.

Plugin compatibility errors. OpenClaw validates plugins after every update. If a plugin was built for an older API version, the validation catches it and prints a structured error. Two commands help here:

openclaw doctor --fix

This repairs configuration problems, runs pending migrations, and warns about deprecated settings. It is the first command to try after any update failure.

openclaw plugins inspect

This lists installed plugins with their version compatibility status and load errors. If one plugin is blocking your update, update or remove it before retrying.

Dev channel updates stuck on the same commit. The dev channel's preflight build check walks back up to 10 commits when the latest does not compile. If you keep seeing the same version after running an update, the most recent 10 commits may all be failing to build. Run the update with --dry-run to check for build errors, and switch to beta or stable until main stabilizes.

Timeout errors on slow connections. The default 1800-second per-step timeout is generous, but large dependency trees over constrained networks can exceed it. Increase the timeout explicitly:

openclaw update --timeout 3600

This gives each step a full hour. If updates still time out, check whether your network is throttling npm registry traffic or git clone operations.