Principle:Openclaw Openclaw Version Update
Version Update
Version Update is the principle of self-updating CLI applications: enabling the OpenClaw gateway to detect available updates, manage multiple release channels, and orchestrate the complete update-restart cycle from a single command.
Motivation
OpenClaw is an actively developed system where new features, bug fixes, and security patches ship frequently. Operators running the gateway need a reliable, automated path to update their installation without manual package management. The update system must handle the complexity of multiple installation methods (git checkout vs. npm global install), multiple release channels (stable, beta, dev), and the need to restart the running gateway after updates.
Core Concepts
Installation Kinds
OpenClaw detects how it was installed and adapts its update strategy accordingly:
| Kind | Detection | Update Strategy |
|---|---|---|
| git | A .git directory exists at the package root. |
Fetch upstream changes, preflight-test candidate commits, rebase, install deps, build, and run doctor. |
| package | No .git directory; installed via a package manager (npm, pnpm, or bun). |
Detect the package manager, run the appropriate global install/update command. |
| unknown | Neither git nor a detectable package manager. | Report the situation and suggest manual update steps. |
Release Channels
The update system supports three release channels:
| Channel | Description | npm Tag | Git Strategy |
|---|---|---|---|
| stable | Tagged releases only (e.g., v2025.1.15). |
latest |
Checkout the latest stable git tag. |
| beta | Prerelease tags (e.g., v2025.1.15-beta.1). |
beta |
Checkout the latest beta or stable git tag (whichever is newer). |
| dev | Moving head on main. |
n/a | Fetch, preflight-test commits, rebase onto the best candidate. |
The active channel can be set persistently in configuration (update.channel) or overridden per-invocation with --channel. Channel switching can trigger a change in installation kind (e.g., switching from stable/npm to dev/git creates a git checkout at ~/.openclaw).
Preflight Testing (Dev Channel)
When updating on the dev channel, the system does not blindly rebase onto the latest upstream commit. Instead, it:
- Enumerates the most recent upstream commits (up to 10).
- Creates a temporary git worktree for each candidate.
- Runs the full build and lint gate in the worktree.
- Selects the first commit that passes all checks.
- Rebases the working tree onto that verified commit.
This "preflight" approach prevents broken upstream commits from landing on the operator's machine.
Post-Update Steps
After the core update completes, the system runs several follow-up steps:
- Plugin sync -- Synchronizes extension plugins to match the new version and channel.
- Shell completion -- Regenerates the cached shell completion data and optionally installs completion for the first time.
- Gateway restart -- Restarts the running gateway daemon so it picks up the new code.
- Doctor checks -- Runs a non-interactive doctor pass to validate the updated installation.
Downgrade Protection
When the target version is older than the currently installed version, the update system requires explicit confirmation (or the --yes flag) because downgrading can break configuration that was migrated by newer versions.
Design Principles
- Detect, do not assume -- The update system auto-detects the installation method, package manager, and current channel rather than requiring the operator to specify them.
- Fail safely -- If any step fails (git fetch, build, lint), the update reports the failure with step-by-step diagnostics and does not leave the installation in a broken state. For git updates, a failed rebase is automatically aborted.
- Atomic channel switching -- Switching channels persists the choice in configuration immediately, so subsequent updates use the correct channel.
- Transparent progress -- Each update step is reported with a spinner, success/failure icon, and timing information.
Relationship to Other Concepts
Version Update invokes Diagnostic Repair after applying updates to verify the system is healthy. It relies on Gateway Restart to restart the daemon after a successful update. The update system also checks Health Monitoring indirectly through the doctor flow.