2026-01-10 20:32:19 +01:00
|
|
|
---
|
2026-01-30 03:15:10 +01:00
|
|
|
summary: "CLI reference for `openclaw update` (safe-ish source update + gateway auto-restart)"
|
2026-01-10 20:32:19 +01:00
|
|
|
read_when:
|
|
|
|
|
- You want to update a source checkout safely
|
|
|
|
|
- You need to understand `--update` shorthand behavior
|
2026-01-31 16:04:03 -05:00
|
|
|
title: "update"
|
2026-01-10 20:32:19 +01:00
|
|
|
---
|
|
|
|
|
|
2026-01-30 03:15:10 +01:00
|
|
|
# `openclaw update`
|
2026-01-10 20:32:19 +01:00
|
|
|
|
2026-01-30 03:15:10 +01:00
|
|
|
Safely update OpenClaw and switch between stable/beta/dev channels.
|
2026-01-10 20:32:19 +01:00
|
|
|
|
2026-01-21 06:00:50 +00:00
|
|
|
If you installed via **npm/pnpm** (global install, no git metadata), updates happen via the package manager flow in [Updating](/install/updating).
|
2026-01-10 20:32:19 +01:00
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-01-30 03:15:10 +01:00
|
|
|
openclaw update
|
|
|
|
|
openclaw update status
|
|
|
|
|
openclaw update wizard
|
|
|
|
|
openclaw update --channel beta
|
|
|
|
|
openclaw update --channel dev
|
|
|
|
|
openclaw update --tag beta
|
|
|
|
|
openclaw update --no-restart
|
|
|
|
|
openclaw update --json
|
|
|
|
|
openclaw --update
|
2026-01-10 20:32:19 +01:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Options
|
|
|
|
|
|
2026-01-23 11:49:59 +00:00
|
|
|
- `--no-restart`: skip restarting the Gateway service after a successful update.
|
2026-01-20 13:33:31 +00:00
|
|
|
- `--channel <stable|beta|dev>`: set the update channel (git + npm; persisted in config).
|
2026-01-17 11:40:02 +00:00
|
|
|
- `--tag <dist-tag|version>`: override the npm dist-tag or version for this update only.
|
2026-01-10 20:32:19 +01:00
|
|
|
- `--json`: print machine-readable `UpdateRunResult` JSON.
|
|
|
|
|
- `--timeout <seconds>`: per-step timeout (default is 1200s).
|
|
|
|
|
|
2026-01-17 11:40:02 +00:00
|
|
|
Note: downgrades require confirmation because older versions can break configuration.
|
|
|
|
|
|
2026-01-20 14:05:55 +00:00
|
|
|
## `update status`
|
|
|
|
|
|
|
|
|
|
Show the active update channel + git tag/branch/SHA (for source checkouts), plus update availability.
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-01-30 03:15:10 +01:00
|
|
|
openclaw update status
|
|
|
|
|
openclaw update status --json
|
|
|
|
|
openclaw update status --timeout 10
|
2026-01-20 14:05:55 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Options:
|
2026-01-31 21:13:13 +09:00
|
|
|
|
2026-01-20 14:05:55 +00:00
|
|
|
- `--json`: print machine-readable status JSON.
|
|
|
|
|
- `--timeout <seconds>`: timeout for checks (default is 3s).
|
|
|
|
|
|
2026-01-22 07:05:00 +00:00
|
|
|
## `update wizard`
|
|
|
|
|
|
|
|
|
|
Interactive flow to pick an update channel and confirm whether to restart the Gateway
|
2026-01-23 11:49:59 +00:00
|
|
|
after updating (default is to restart). If you select `dev` without a git checkout, it
|
|
|
|
|
offers to create one.
|
2026-01-22 07:05:00 +00:00
|
|
|
|
2026-01-21 06:00:50 +00:00
|
|
|
## What it does
|
|
|
|
|
|
2026-01-30 03:15:10 +01:00
|
|
|
When you switch channels explicitly (`--channel ...`), OpenClaw also keeps the
|
2026-01-21 06:00:50 +00:00
|
|
|
install method aligned:
|
|
|
|
|
|
2026-01-30 03:15:10 +01:00
|
|
|
- `dev` → ensures a git checkout (default: `~/openclaw`, override with `OPENCLAW_GIT_DIR`),
|
2026-01-21 06:00:50 +00:00
|
|
|
updates it, and installs the global CLI from that checkout.
|
|
|
|
|
- `stable`/`beta` → installs from npm using the matching dist-tag.
|
|
|
|
|
|
|
|
|
|
## Git checkout flow
|
2026-01-10 20:32:19 +01:00
|
|
|
|
2026-01-20 13:33:31 +00:00
|
|
|
Channels:
|
|
|
|
|
|
|
|
|
|
- `stable`: checkout the latest non-beta tag, then build + doctor.
|
|
|
|
|
- `beta`: checkout the latest `-beta` tag, then build + doctor.
|
|
|
|
|
- `dev`: checkout `main`, then fetch + rebase.
|
|
|
|
|
|
2026-01-10 20:32:19 +01:00
|
|
|
High-level:
|
|
|
|
|
|
|
|
|
|
1. Requires a clean worktree (no uncommitted changes).
|
2026-01-20 13:33:31 +00:00
|
|
|
2. Switches to the selected channel (tag or branch).
|
2026-01-22 04:19:29 +00:00
|
|
|
3. Fetches upstream (dev only).
|
|
|
|
|
4. Dev only: preflight lint + TypeScript build in a temp worktree; if the tip fails, walks back up to 10 commits to find the newest clean build.
|
|
|
|
|
5. Rebases onto the selected commit (dev only).
|
|
|
|
|
6. Installs deps (pnpm preferred; npm fallback).
|
|
|
|
|
7. Builds + builds the Control UI.
|
2026-01-30 03:15:10 +01:00
|
|
|
8. Runs `openclaw doctor` as the final “safe update” check.
|
2026-01-22 04:19:29 +00:00
|
|
|
9. Syncs plugins to the active channel (dev uses bundled extensions; stable/beta uses npm) and updates npm-installed plugins.
|
2026-01-10 20:32:19 +01:00
|
|
|
|
|
|
|
|
## `--update` shorthand
|
|
|
|
|
|
2026-01-30 03:15:10 +01:00
|
|
|
`openclaw --update` rewrites to `openclaw update` (useful for shells and launcher scripts).
|
2026-01-10 20:32:19 +01:00
|
|
|
|
|
|
|
|
## See also
|
|
|
|
|
|
2026-01-30 03:15:10 +01:00
|
|
|
- `openclaw doctor` (offers to run update first on git checkouts)
|
2026-01-20 13:33:31 +00:00
|
|
|
- [Development channels](/install/development-channels)
|
2026-01-10 20:32:19 +01:00
|
|
|
- [Updating](/install/updating)
|
|
|
|
|
- [CLI reference](/cli)
|
