How to update OpenClaw without breaking your agent
Updates are where long-running agents get hurt. The safe ritual: know your version, read the release, back up state, update deliberately, verify after.
Mechanically, updating is easy — npm install -g openclaw@latest then openclaw gateway restart (or bump the pinned image tag in a Docker setup). The discipline around those commands is what protects a long-running agent: back up state first, read what changed, update deliberately rather than automatically, and verify the agent afterward.
Why updates deserve respect here
An OpenClaw agent is long-running, stateful software: months of memory, live channel sessions, skills, config. OpenClaw itself moves fast — frequent releases, including security fixes worth having promptly. Those two facts pull against each other, and the resolution isn’t “never update” or “always update” — it’s updating deliberately: on your schedule, with a backup behind you, having read what’s changing.
The ritual (five minutes, every time)
- 1. Know where you are and where you’re going.
openclaw --version, then skim the release notes on the official GitHub — you’re looking for breaking changes, config migrations, and security fixes (which raise the urgency). - 2. Back up state first. One directory, one archive — the cheapest insurance an update can buy. If the new version migrates something and you need to roll back, pre-update state is what makes that clean.
- 3. Update and restart:
Usenpm install -g openclaw@latest openclaw gateway restartgateway restartitself — the docs are explicit that chaining a manual stop and start isn’t the supported substitute. Docker setups update by changing the pinned tag and re-upping — which is why pinned tags beatlatest: your version changes when you say so, not when a tag moves under you overnight. - 4. Verify like an operator.
openclaw gateway status, then a real message to the agent through a real channel, thenopenclaw security audit— new versions can add checks or change defaults, and the audit-after-change habit catches both.
Two habits that prevent the classic wounds
- Don’t let anything update the agent implicitly. Unpinned Docker tags, auto-update mechanisms, or clicking a dashboard update prompt in passing all share the same flaw: a version change nobody scheduled, on a machine holding months of state. (It’s also why, on our managed pods, updates are an operator ritual with before/after checks — and why we ask customers not to press native update buttons themselves.)
- Update the machine too, separately. On a VPS the OS wants patching as well; kernel updates mean an occasional reboot, which a healthy setup survives — volume-mounted state and a service that starts on boot are what make “reboot for the kernel, agent comes back on its own” the boring non-event we’ve verified it can be. If a reboot scares your setup, that’s the finding — fix persistence, not the reboot.