TL;DR

openclaw update --dry-run to preview, then openclaw update to do it: one command that detects your install type, pulls the new version, runs openclaw doctor, and restarts the gateway. The three traps: skipping the dry-run, trusting the success message without checking openclaw --version afterward, and updating with no way back. Every bad update story I've got starts with one of these.

Search this topic and you get the same page ten times: here's openclaw update, here are the flags, good luck. The command is the easy part. I run OpenClaw (with Hermes next to it) on servers I'm responsible for, and every update I've regretted was one I ran out of habit instead of for a reason. On a production box you want to know what can break and how you get back before you type anything. The fast path first. Then the caveats.

The fast path

For a working npm install, updating is three steps.

Preview first:

openclaw update --dry-run

It shows the effective channel, the target version, the actions it plans to take, and whether it will ask you to confirm a downgrade. It changes nothing. I run it every time, including when I'm sure what it'll say. Once in a while it catches something I didn't expect.

Then the update:

openclaw update

This does more than npm install. It detects how OpenClaw was installed (npm or git), pulls the new version, runs openclaw doctor, and restarts the gateway. Under the hood it installs the new version into a temporary npm prefix, verifies the dist inventory, then atomically swaps in a clean tree rather than layering new files over old ones. If the install fails, it retries once with --omit=optional.

Then verify. Everyone skips this one, and it's saved me more than once:

openclaw --version
openclaw doctor
openclaw health

openclaw --version confirms the live binary is the version you think you installed. doctor migrates config, repairs state, and audits policy. health confirms the gateway is up and answering. If you need the gateway to keep running through the swap, openclaw update --no-restart defers the restart, and the pending migrations with it, until you run openclaw doctor --fix and restart yourself.

Prefer the package manager directly? npm i -g openclaw@latest works, as do pnpm add -g and bun add -g. On a supervised install, openclaw update is still the better tool: it coordinates the package swap with the live gateway. If you go manual, stop the gateway first (openclaw gateway stop), update, then openclaw gateway restart. Skip the stop and the gateway ends up reading a half-swapped package tree.

Two small notes. --verbose on openclaw update does nothing; --dry-run and --json are the diagnostic tools. And openclaw update status --json reports your channel and whether an update is waiting, handy in scripts and tickets.

Channels, and whether to let it update itself

There are three release channels.

  • stable is the npm latest dist-tag. For most installs, this is the one.
  • beta is the beta dist-tag. If no beta exists, or it's older than latest, it falls back to latest.
  • dev tracks the moving main branch in git. The docs are blunt: "Do not use it for production gateways." Believe them; it can carry unfinished or breaking work.

openclaw update --channel stable|beta|dev switches, and the choice persists in update.channel. Note the difference between --channel beta and --tag beta: the channel knows how to fall back to latest when beta is stale, while --tag beta hits the raw dist-tag for one run, no safety net.

The auto-updater is off by default, and on production machines I leave it off. If you enable it (update.auto.enabled in ~/.openclaw/openclaw.json): stable waits out a stableDelayHours window and rolls out with jitter, beta checks hourly and applies as soon as it sees something new, dev never auto-applies. Read the beta line again. Auto-update on beta means someone else's release can restart your runtime overnight. I update on my own schedule, with the dry-run output in front of me and a known-good version written down.

Two switches worth knowing. update.checkOnStart: false silences the update nag at startup. OPENCLAW_NO_AUTO_UPDATE=1 in the gateway's environment blocks auto-applies even when update.auto.enabled is set, which is what you want mid-incident or while deliberately holding a downgrade.

Why I don't chase latest

Unpinned latest works until an upstream release lands with a regression and takes down something that worked yesterday, with no change on your side to explain it. I learned this the standard way: installs that pulled whatever was newest started breaking whenever upstream shipped, and the fix was to pin and stop pulling blind.

People will tell you to always run the newest version. The newest version also carries bugs nobody has hit yet. Chase whatever shipped last and you're rolling upstream's regressions, and sometimes their CVEs, straight onto your box. Update when you can say why: a CVE, a feature, a build that passed your checks.

So before a version goes near prod, run it somewhere you can afford to break. A staging box, a spare VM, anything. At minimum a --dry-run on prod, so you know what the updater is about to do.

What actually breaks on update

The failure tail, from my own machines and from what keeps filling the forums.

The config that didn't land. You update, you fix a config value, nothing changes. Config edits are picked up by a service restart, not by saving the file. After an update, confirm the config you think is live is the config the gateway loaded; a gateway will run on stale settings and look healthy doing it.

The silent version mismatch. "Update completed" does not mean the system is on the new version. Updates move forward: a new build can choke on old state, and it fails quietly. Upstream's own docs describe the case where logs show an openclaw binary older than the version that last wrote openclaw.json, and the prescription is openclaw doctor --fix. This is the whole argument for the verify step: openclaw --version, doctor, health, every time, no exceptions for updates that "went fine."

The neighbor that fell over. More than one agent runtime on the machine? I run OpenClaw and Hermes side by side, and I've watched an update to one leave the other down. Same host, same ports. Check the neighbor after every update; it costs a minute.

Tokens that drift. Restarts can leave tokens out of sync between a control layer and the gateway. If auth gets weird right after an update, look there before you reinstall anything.

The classics. EACCES on a root-owned global install: openclaw gateway stop, the global install again with sudo npm i -g, then openclaw gateway install --force, then restart. A Node runtime too old for the new build. And the manual-update-while-the-gateway-runs mistake from earlier, which leaves that half-swapped tree.

When something is off and you don't know where: openclaw doctor --fix first. Then openclaw channels status --probe for live per-account transport status, including 401s and auth failures. Then openclaw gateway status --deep --json for the full picture. If openclaw update itself died after the npm phase, re-run the installer; it knows how to finish a half-updated install:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm

Pinning and rollback

OpenClaw has no persistent version lock. openclaw update --tag <version> installs that specific version (npm installs only; git ignores --tag) and holds for a single run. The next openclaw update follows your configured channel straight back to whatever is newest there. There's no way to make the pin stick, so you hold it yourself: the auto-updater stays off, nobody runs openclaw update casually, and the known-good version number is written down where you'll find it mid-incident.

Before an update on any box that matters:

openclaw backup create

It takes a restorable snapshot of state, config, and workspace. --output <dir> picks the destination; --dry-run --json shows what it would capture. Do it before the update, while everything works. Take it after something breaks and all you've saved is a clean copy of the broken state.

Rollback on an npm install:

npm i -g openclaw@<version>
openclaw doctor
openclaw gateway restart

npm view openclaw version tells you what's published upstream right now, so you know how far behind you are.

Rollback on a source install: git checkout <sha>, then pnpm install && pnpm build, then restart the gateway.

One guardrail: downgrade protection. When the target is older than what's running, OpenClaw asks for confirmation; --yes skips the prompt, and --dry-run warns you it's coming. Either way, pick the version you'd roll back to before you update, not during the outage.

When not to update

  • Stable production system, narrow job, nobody complaining. An update adds regression risk and buys nothing. Leave it alone.
  • No reason you can name out loud. "A new version exists" is not a reason on its own.
  • No rollback on hand. If you have no backup and no known-good version to fall back to, fix that before you update.
  • You're considering `dev` on a production gateway. Upstream already said no.

On a machine that makes money, or one people depend on, my default answer to "should I update?" is "not yet." Schedule it, make it reversible, or you're gambling with a working box.

If you'd rather hand this off

Everything above is a routine you can run yourself, and plenty of operators should. It's also most of what Cain is: OpenClaw and Hermes on a dedicated server provisioned for you, one client per server, with this update policy baked in, so nobody has to remember it. We watch upstream OpenClaw releases, run every new version through our upgrade matrix, and roll it out only after it passes. We don't pull latest blind; we ship a pinned build we've already validated, so security fixes reach you without someone else's regression riding along. Your prompts go straight to the model provider you already pay for, not through anyone's shared cloud. That's one way to run it. If you'd rather hold the pin yourself, this page is most of the checklist.

FAQ

`openclaw update` failed, or things broke right after an update. Where do I start? openclaw doctor --fix, then check what's live: openclaw --version, openclaw health, openclaw channels status --probe for per-account transport and auth, openclaw gateway status --deep --json for the deep view. If the updater died after the npm phase, re-run the installer (curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm); it finishes a half-updated install. And if you changed config, a restart applies it, not the file save.

How do I roll back or downgrade OpenClaw? On npm: npm i -g openclaw@<version>, then openclaw doctor, then openclaw gateway restart. From source: git checkout <sha>, pnpm install && pnpm build, restart. Downgrade protection asks for confirmation when the target is older than what's running; --yes skips it. That assumes you know your known-good version; decide it while everything still works, not once things are down.

Should I turn on OpenClaw auto-update? It ships off, and on production I keep it off. Stable at least waits out a delay window; beta checks hourly and applies as soon as it sees a new release, which means upstream can restart your runtime before you know there's anything to apply. If you enable it anyway, remember OPENCLAW_NO_AUTO_UPDATE=1 blocks auto-applies when you need to hold a version steady.

Which update channel should I pick? stable, unless you have a reason not to. beta if you track what's coming and can absorb surprises; it falls back to latest when no newer beta exists. dev is the moving git main, and the docs say not to run it on production gateways.

How do I check which OpenClaw version I'm running? openclaw --version for what's installed and live. npm view openclaw version for what's published upstream. openclaw update status --json for your channel and whether an update is waiting. Run the first one after every update, even when you're sure.

Can I have the agent update itself? Possible, not recommended. The update restarts the gateway, which drops the agent's own session mid-flight, and it can require a clean git checkout or an interactive confirmation. Do it from a shell, as the operator. If you script it anyway: openclaw update --yes --no-restart, then openclaw gateway restart.

Ilya Prudnikov runs private OpenClaw and Hermes instances. These are an operator's notes on updating in place, not project documentation; commands and defaults drift, so check OpenClaw's current docs for the authoritative version.