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, with 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). For a major release, read what changed before deciding when: OpenClaw 2.0 and its one-time migration are the current example. - 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.
- 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.