openclaw update with global npm installs, defines stable, beta, and dev blast radius, documents smoke checks, and ends with a six-step runbook that ties maintenance windows to Singapore, Tokyo, Seoul, Hong Kong, US East, and US West placement so upgrades become measurable policy instead of heroics
Why production upgrades fail as path drift, not as loud crashes
First install assumes a clean slate. Upgrade assumes layered state: plist labels, environment exports, cached credentials, pinned skill manifests, and sometimes multiple workspaces on one host. A minor semver bump can still rewrite defaults, tighten sandbox checks, or relocate the global binary that your daemon entry point references.
The failure mode is therefore subtle: WebSocket sessions that reconnect but lose throughput, doctor output that suddenly lists new warnings, or channels that stay green while remote clients point at stale gateway URLs. Metro hopping does not fix those patterns because the root cause is configuration and supply-chain drift, not RTT alone.
Incident notes often mix three different stories: model latency, channel auth, and host upgrade side effects. Without signatures, on-call rotates through the wrong ladder. The five-item list below is meant for change-review vocabulary so leadership can decide when to freeze channels and require paired approvals.
Connected channels with slowing replies: often plugin ABI skew or workspace mismatch after the CLI moved while skills stayed pinned.
which openclaw disagrees with plist absolute paths: prefix changes from npm or brew reshuffle who launches which binary.
Doctor noise jumps after a minor bump: new defaults for security or sandbox posture need explicit adoption, not silent ignores.
Port 18789 class errors cluster after unattended upgrades: bind or multi-instance policy may require restart paths that hot reload cannot cover.
CI hosts and interactive hosts diverge silently: one fleet auto-bumped while another stayed pinned, producing two behaviors for one repo.
Once signatures exist on paper, the next move is policy: which hosts may track beta, where dry-run artifacts must be stored, and how quickly pin rollback must execute. Treat dev channel installs on shared production directories as a process defect, not a clever shortcut.
If you already split Docker versus bare-metal install flows, keep that article beside this one. Upgrade events frequently intersect reload boundaries, and mixing the two decision tables on one wiki page reduces pager thrash.
Finally, capture evidence before and after every bump: doctor output, gateway status snapshots, and a short log window. Evidence beats memory when you need to decide whether a regression came from the model vendor, the channel, or the host toolchain.
Operational maturity also means naming owners for transitive dependencies. A bump that refreshes a crypto or HTTP client library can change TLS behavior without touching OpenClaw user-facing release notes. If nobody owns that diff, on-call will oscillate between “rollback OpenClaw” and “rollback the whole Node prefix,” which are different risk profiles. A dry-run artifact attached to the ticket is the cheapest insurance.
For fleets that mix laptops and cloud builders, add a fifth column to your inventory: last successful upgrade hash per role. Interactive machines tolerate slower rollouts; builders that run unattended jobs should trail stable by a deliberate lag, not by accident. That single table prevents the classic split where engineers see new CLI flags while CI still parses old config keys.
Official openclaw update versus global npm and channel blast radius
There is no universally superior installer, only a supply chain you can explain in an audit. CLI update tends to converge paths for teams that want narratable changes. Global npm or OS packages couple OpenClaw with the rest of your Node estate, which is fine when you already run mirrors, dist-tag discipline, and lockfiles for globals.
Channel choice is a risk budget. Stable should anchor customer-facing gateways: acceptable downtime is the window where you can pin back and restore handshakes. Beta belongs on pre-prod or day-rent hosts where you accept occasional behavior shifts. Dev belongs on disposable directories with no production tokens.
| Dimension | Official CLI update | Global npm or system package |
|---|---|---|
| Binary path stability | Easier to bind launchd to explicit paths | Prefix drift needs post-upgrade plist checks |
| Channel governance | Aligns with documented release tracks | Requires your own dist-tag policy |
| Rollback clarity | Pairs cleanly with pin plus service restart | Needs scripted npm install at explicit versions |
| Multi-instance isolation | Still requires separate OPENCLAW_HOME and ports | Same, with higher blast radius from transitive bumps |
| Team fit | Ops teams that want small, reviewable steps | Teams with mature Node governance and mirrors |
Channels are not novelty switches. They are contracts about how much instability you will explain to customers.
When every host documents its channel and target version, you stop debating mystery slowdowns. When channels differ across metros without a spreadsheet, you will misread regional network issues for software drift.
Maintenance windows should avoid heavy browser automation and large builds. Upgrade IO plus Swap from heavy tools masks handshake failures and makes triage noisy. Schedule bumps when queues are empty and keep thirty-minute buffers on both sides of the window.
Document what “success” means for each metro. Singapore and Tokyo teams may prefer late local evening windows, while US East and US West splits often need two staged waves to avoid overlapping pager fatigue. Seoul and Hong Kong hosts frequently sit between artifact registries and API regions, so schedule upgrades after large registry sync jobs finish, not before.
If you rely on npm dist-tags, mirror the tags you actually use inside a private registry or cache proxy. Public tag moves that happen between your dry-run and production cutover are a real class of incidents. Pinning explicit versions in the change ticket removes that ambiguity even when tags move upstream.
Dry-run diffs and minimum smoke: what must go green
Dry-run is valuable for the diff, not only for exit codes. Production teams treat the output like a release note: new dependencies, relocated binaries, new default keys, and deprecation warnings each need an owner before go-live. Post-upgrade smoke should touch both control plane and data plane: a channel probe plus a lightweight tool call, not only a friendly chat message.
Split reload-eligible keys from restart-required keys in your checklist. If gateway.remote or bind addresses change, validate TLS endpoints explicitly. Skipping that step yields green local doctor while remote clients flap.
openclaw update --dry-run openclaw doctor openclaw channels probe openclaw gateway status
Adapt service restart commands to your supervisor. Prefer targeted service restarts over rebooting entire hosts so you retain comparable log windows. Container sidecars need the same discipline with compose pull policies.
Note: Archive dry-run and doctor output to immutable storage or ticket attachments. Postmortems without artifacts rarely converge.
Six-step runbook from change ticket to executable rollback
Freeze channel and exact version: ban verbal “move to latest”; require semver in the ticket.
Backup configs and state roots: timestamp archives for openclaw.json, plist or unit files, env exports, and skill locks.
Dry-run on a matching host: record diffs; unowned warnings block promotion.
Enter the maintenance window: pause heavy queues before bumping to avoid IO contention.
Run smoke tests and capture logs: reopen traffic only after channels and gateway status pass.
Publish rollback commands: pin version, reinstall step, and supervised restart order written for pager use.
Guardrails you can paste into an on-call primer
Channel drift alarm: if production and pre-prod semver diverge by more than one minor without a ticket, force alignment or file the missing change.
Smoke failure clock: any failed smoke inside the window triggers pin rollback within fifteen minutes or the upgrade is marked failed.
Heavy tool buffer: forbid scheduling browser automation and giant builds for thirty minutes before and after the bump.
Caution: These thresholds are engineering communication aids, not vendor SLA promises. Validate with your own traces.
Defaulting to “restart until green” creates untraceable production where channels drift and paths fork. Writing update, dry-run, pin rollback, and metro windows into one runbook lets short programs rehearse on real bare metal with day or week rentals before locking monthly cadence. MESHLAUNCH Mac mini cloud rental is usually the stronger fit because you practice upgrades and rollbacks on dedicated Apple Silicon with elastic rental terms instead of gambling on a single shared production host.
Yes for any host that serves customer channels. Pair with Gateway hot reload guidance when reload versus restart is unclear. Pricing context is on the pricing page.
Stable for production, beta for burn-in hosts, dev for disposable sandboxes. Docker versus bare-metal install tradeoffs live in the dual-path guide.
Diff gateway blocks and environment exports, then ports and supervisor units. Remote access summaries are in the help center.