openclaw update · pinned backups · doctor · rollback
Teams already running OpenClaw in production rarely struggle with whether they can run openclaw update; the pain shows up after the command returns, when the Gateway fails to start, an old process still holds the listener, PATH resolves to a stale binary, or configuration migration silently rewrites tool settings. This article unpacks five recurring upgrade risks, then provides a matrix comparing official update, global npm, and source builds, a six-step Runbook with backup and channel policy, post-upgrade doctor and health ordering, and a port conflict and dual-install evidence table. It cross-links multi-platform install and daemons, install and doctor triage, and runtime troubleshooting so upgrades, observability, and rollback stay on one page.
Official guidance recommends openclaw update followed by openclaw doctor, yet production stacks add daemons that do not follow package-manager switches, old Gateway processes that never release their listeners, and multiple CLI installs on one host. If you have been reading the production hardening checklist, you already know channel allowlists and listen-surface reduction interact tightly with upgrade order; skipping a clean Gateway stop before swapping packages often leaves 18789 held by a stale PID.
When teams treat upgrades as isolated CLI events, they lose the thread that ties version numbers to listening surfaces and identity material. Sustainable programs therefore document the failure modes first: process drift, silent configuration migration, channel cadence collisions, weak rollback evidence, and incomplete health telemetry. Each item below maps to an artifact you can attach to a change ticket, which is how you graduate from “we ran update” to “we can explain any failure with a version string and a backup path.”
Process and package version drift: Global npm already points at a new build, but launchd or systemd still launches a binary that was built under an old working directory, so openclaw --version and gateway status disagree.
Configuration migration and silent rewrites: Major releases may change semantics inside openclaw.json; doctor attempts migration, but if merge rules diverge from your GitOps review flow you get “the file changed on disk without a matching pull request.”
Automatic channel cadence versus change windows: Stable-channel delay and jitter exist so the whole fleet does not explode at once, but misalignment with business releases can trigger unplanned Friday-night restarts; when combined with channel probes, confirm the Gateway actually restarted before you trust callbacks.
Insufficient rollback evidence: Without backups or pinned versions you can only “install latest again” instead of returning to a known-good state; paired with persistent cloud deployments, nodes often run cron jobs and external webhooks, so the wrong rollback order amplifies downtime.
Missing observability fields: Saving a screenshot that says “upgrade succeeded” without archiving gateway status --deep and bind addresses prevents you from proving the exposure surface matched the security baseline afterward.
Turn the five bullets into a preflight checklist before you compare install paths in the next section; that is how “we can update” becomes “we can audit and roll back an update.” Sleep and OS maintenance windows on personal laptops also transiently skew daemon state, whereas cloud Mac nodes with contractual SLAs let you write upgrade windows and availability into acceptance criteria.
Operational leads should also record which machine role each host plays: developer laptop, shared build agent, or dedicated Gateway. The same CLI version can behave differently when launchd loads a plist that references an old WorkingDirectory versus when systemd runs inside a pinned container image. Naming those roles in the ticket prevents “works on my machine” from becoming “mysterious production drift after a patch Tuesday.”
None of the three paths is universally best; fit depends on team size, whether you pin commits for audit, and whether automatic Gateway restarts are acceptable. The official update subcommand suits most teams; global package managers fit CI images; source builds suit groups that ship patches or must lock a dev channel.
When you document the matrix below inside your operations handbook, you also eliminate ambiguous ownership: build engineers know when to rebuild images, platform engineers know when to touch systemd units, and application teams know when doctor output must be archived for compliance. That clarity pays off the first time a release introduces a breaking field in openclaw.json and you need to prove which environment applied which migration.
| Dimension | openclaw update | Global npm / brew | Git source build |
|---|---|---|---|
| Learning curve | Low; one command chains fetch, doctor, and restart hints | Medium; you wire doctor and Gateway restarts yourself | High; pnpm builds and PATH hygiene |
| Traceable versions | Medium; relies on release metadata | Strong; pin package semver | Strong; pin commit SHA |
| Rollback path | Medium; needs pinned releases plus backups | Strong; npm i -g openclaw@x | Strong; git checkout then rebuild |
| Automation fit | Strong; natural for runbooks | Strong; natural for image layers | Weak; long builds and cache complexity |
| Interaction with daemons | Requires explicit stop-then-start ordering | Same | Highest risk of dual-path installs |
Sustainable upgrades hinge on whether failure can be explained with a version number and a backup path, not on whether the Gateway occasionally starts.
If you already follow install-daemon guidance, copy the conclusions from this section into your handbook to avoid the “docs say brew, the host uses npm, cron points at a third path” triangle.
The following six steps are written so an on-call playbook can be checked line by line: regardless of install style, consistent ordering lets a new teammate rehearse an upgrade within an hour. When combined with the three-way runtime split, keep a snippet of gateway status after the upgrade so channel issues stay separate from model-layer problems.
Before you freeze the window, notify downstream owners who depend on outbound webhooks or shared API keys; rotating credentials during the same night as a Gateway upgrade multiplies blast radius. Likewise, if you rely on external secret stores, verify their availability before you stop the Gateway, otherwise you may boot into a half-configured state where doctor passes but runtime calls fail.
Freeze the change window: Record the target semver and acceptable downtime minutes on the ticket; do not pair the work with a large model-key rotation on the same evening.
Back up configuration and identity paths: Use the official backup command or at least archive directories under ~/.openclaw that hold config and identity material; verify checksums on the archive.
Stop the Gateway gracefully: Run openclaw gateway stop, confirm the listener is free, then run the updater; avoid half-upgraded states that keep ports busy.
Apply the update and log the channel: If you use openclaw update, paste the reported version and channel metadata into the ticket’s index fields.
Run doctor and health in order: Capture migration hints and warnings; if unexpected fields change, pause automatic restarts and review a manual diff.
Probe channels with a minimal message: In an allowed environment send a probe or run channels status to ensure callbacks still reach your stack.
openclaw gateway stop openclaw update openclaw doctor openclaw gateway start openclaw health openclaw gateway status --deep
Note: If the built-in restart inside update races your manual scripts you can briefly see duplicate listeners; serialize stop-install-start instead of parallelizing.
Community threads often mention “port still busy after upgrade” or “CLI shows a new version but the process is an old build.” Triage should converge on a single source of truth for bind addresses, process binary paths, and package locations before you blame configuration. When you read alongside the install and doctor checklist, paste the table below into the ticket as an appendix.
Documenting the output of lsof or platform equivalents alongside which openclaw gives reviewers enough signal to decide whether you are fighting a zombie process or a mis-linked service unit. On shared hosts, also capture the effective user ID under which the Gateway runs, because profile scripts for one account do not apply to another.
Port already in use: Evidence from lsof -i :18789 or equivalent showing an old PID; action is gateway stop first, then escalate to a controlled kill only if stop fails, and finally re-check for leftovers.
Dual install paths: Evidence when which openclaw and npm root -g disagree on prefixes; action is to normalize PATH, remove redundant globals, or pin aliases.
Daemon unit not refreshed: Evidence when plist or unit files still reference an old WorkingDirectory; action is to reinstall the daemon or follow documented force-install steps before kickstart.
Configuration validation failures: Evidence when doctor reports migration conflicts; action is restore from backup, upgrade in stages, or merge JSON manually and rerun doctor.
False-green health: Evidence when health passes but channels never call back; action is to follow the runtime triage article and avoid closing the incident early.
Still broken after rollback: Evidence that environment variables or shell startup scripts still inject an old NODE_PATH; action is to clean login sessions and CI image layers.
Warning: On shared nodes, temporary export paths that land in a colleague’s profile turn personal experiments into fleet-wide incidents; use separate Unix users or container boundaries for pools.
The three bullets below summarize what many small teams observe when rolling out OpenClaw; use them for pre-project review, not as vendor guarantees, and replace them with measurements from your own tickets.
Thresholds work best when paired with owners: someone must watch the probe dashboards during the window, someone must approve extending downtime beyond the P95 budget, and someone must keep the backup retention policy aligned with compliance. Without those names, the numbers become aspirational wallpaper.
| Team size | Change cadence | Risk appetite | Steadier default |
|---|---|---|---|
| Solo | Ad hoc | High | Official update plus manual stop/start; keep a zip backup |
| Small team | Weekly | Medium | Pinned npm semver, change tickets, archived doctor output |
| Platform | Daily | Low | Image builds, canary nodes, automated probes |
| Outsourced collaboration | Irregular | Medium | Read-only runbooks and dedicated nodes; no shared HOME |
Sleep, disk space, and OS patching on personal hardware constantly interrupt daemons; even perfect CLI discipline cannot manufacture an auditable upgrade SLA on a laptop. By contrast, contractable cloud Mac Mini nodes let you write process uptime, ingress, and maintenance windows into the agreement.
Common mistake: Treating a passing health check as proof that channels and models are healthy—health covers a subset; full acceptance still follows the runtime triage order.
If you need rollback-friendly OpenClaw upgrades with observable Gateway lifecycles and want nodes online without laptop sleep breaking agents—especially when production automation and iOS-related build environments matter—VpsMesh Mac Mini cloud rental is often the better fit: predictable billing, selectable regions, and dedicated hardware you can audit, so upgrade conversations rest on real availability data.
Strongly recommended; at least back up configuration and identity-related paths before running update. Cross-read install and doctor triage. When you need to order a node, see the order page.
Include rollback rehearsal time, on-call effort, and probe-script maintenance in the cost of each release, then compare against the pricing page and the three-year TCO article when deciding.
Start with the help center; if only channels misbehave after upgrading, follow runtime troubleshooting first, then return here to re-check ports and PATH.