A pre-flight list, the update commands for every install type, and the rollback that takes two minutes.
I updated OpenClaw on a Tuesday afternoon. By Tuesday evening, my customer support agent had stopped responding on Telegram, three cron jobs had silently deactivated, and my gateway was binding to a different port than before.
The update itself took 30 seconds. The debugging took four hours. A 5-minute backup before the update would have prevented all of it.
OpenClaw ships several releases a week. As of 10 November 2026 the current stable release is 2026.11.2 (8 November), the extended-stable line is 2026.9.36, and a 2026.11.5 beta is out. Most releases are small. Some migrate your config or databases in ways you cannot simply undo. Our OpenClaw latest version page tracks what each release changed.
Here's how to update safely every time, whatever your install type.
Before you update: a 5-minute pre-flight
Record your current version
openclaw --version
openclaw status
openclaw gateway status --deep
openclaw --version reports the CLI. openclaw status reports the Gateway service, which can point at a different installation than your shell. If the two disagree, fix that first, because you would be updating one install while another one keeps running. Write the version down. It is the version you roll back to.
Back up the right files, the right way
OpenClaw keeps its state in ~/.openclaw unless you moved it with OPENCLAW_STATE_DIR:
~/.openclaw/openclaw.json: your config (model providers, channels, gateway settings)~/.openclaw/state/openclaw.sqlite: the shared database~/.openclaw/agents/<id>/agent/openclaw-agent.sqlite: one database per agent, holding sessions and memory~/.openclaw/workspace: your agent's workspace files
Do not copy the live .sqlite files by hand. The OpenClaw docs warn that committed data can still sit in the -wal file, so a plain copy can be incomplete. Use the built-in backup instead:
openclaw backup create --output ~/Backups/openclaw --verify
That creates a verified, WAL-aware archive of state and workspace. Also note the size of each agent database. A session database near 1 GB is a warning sign on current releases (see the "admission is closed" failure below).

Note your installed skills and anything running on a schedule too. A missing cron job fails silently: nothing errors, the agent simply stops doing something, and you notice a week later.
What changed about backups in 2026.9.2
Backup integrity got stricter in 2026.9.2: corrupt archive headers are now rejected outright rather than accepted as a partial backup, and Skill Workshop backups refuse incomplete directory snapshots. A backup that used to appear to work may now fail loudly instead. Better to find that out before you need it.
Restoring also needs free temporary disk space, because the restore prepares a safe copy first. The restore steps are in how to back up and restore an OpenClaw agent.
Read the release notes and do a dry run
Read the notes for every version between yours and the target. Then preview the update without changing anything:
openclaw update --dry-run
If you are on a VM, take a snapshot as well. It is the fastest rollback there is.
The update command for each install type
npm, pnpm or Bun installs: openclaw update
openclaw update
Per the OpenClaw docs, openclaw update detects your install type (npm, pnpm, Bun or git), checks the new version while the old Gateway keeps serving, then activates and verifies it. It runs the required Doctor migrations and keeps the previous package during activation, so it is the safer path than reinstalling by hand.
Useful flags:
--dry-runpreviews the update.--tag <version>installs one exact version for this run, for exampleopenclaw update --tag 2026.11.2. It applies to package installs only; git installs ignore it.--channel stable|extended-stable|beta|devswitches channel and remembers it.--no-restartskips the automatic Gateway restart. Use it only if you stopped the Gateway yourself, then restart it manually.openclaw update statusreports where your install sits without changing anything.
You can also update from chat with /update.
Manual npm global install
If openclaw update cannot run (for example, an older updater refuses the first hop), the documented manual sequence is:
openclaw gateway stop
npm i -g openclaw@latest --allow-scripts=openclaw
openclaw doctor --fix
openclaw gateway install --force
openclaw gateway start
openclaw gateway status --deep
Leave out --allow-scripts=openclaw on npm 11.15 and earlier. Replace latest with an exact version to install that version. A raw npm i -g does not keep the previous package or run OpenClaw's recovery workflow, so back up first.
Installer script
Re-running the installer updates in place:
curl -fsSL https://openclaw.ai/install.sh | bash
To install a specific version:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version>
Docker and Docker Compose
docker compose pull openclaw-gateway openclaw-cli
docker compose stop openclaw-gateway
docker compose up -d openclaw-gateway
The image runs openclaw doctor --fix --non-interactive before it starts the Gateway, so a routine image upgrade does not need a separate Doctor run. Keep one Gateway container per state volume and stop the old one before starting the new one. Set the image with OPENCLAW_IMAGE.
To update to a specific version, pin the tag. Plain version tags (for example 2026.11.2) and dated -rYYYYMMDD tags never change. latest, main and extended-stable are rebuilt weekly, so pinning one of those does not pin anything.
Ubuntu or other Linux VPS with systemd
The Gateway runs as a user service called openclaw-gateway.service. openclaw update restarts it for you. After a manual install, restart and check it:
openclaw gateway restart
openclaw health
systemctl --user status openclaw-gateway.service
On image-based systems (bootc, rpm-ostree), do not run openclaw update. Swap the image, then run openclaw doctor --fix --non-interactive. A Gateway that needs a migration exits with status 78, and the service stays failed until Doctor runs.
For "How do I update OpenClaw and back up its memory on a VPS?": run openclaw backup create --output ~/Backups/openclaw --verify on the VPS, copy the archive off the machine, then run openclaw update. The archive includes every agent database, which is where sessions and memory live.
Run Doctor and read what it says
openclaw doctor checks config, databases and services after an update. The flags you will use:
--fix(or--repair) applies the repairs it finds.--non-interactivesuppresses prompts. It does not stop writes.--deepruns deeper checks.--lint --jsongives a machine-readable report that exits nonzero on problems, for scripts and CI.
One change to know if you script it. The 2026.11.1 release notes say Doctor used to report success when inspection was blocked, the final config was invalid or required migrations were deferred. It now exits nonzero in those cases, and "scripts using doctor --json should handle the new exit status." Unattended Doctor also reports missing plugins without installing them unless you pass --fix, --repair or --yes.
The 2026.9 line also made updates safer: a failed post-update Doctor check rolls the npm candidate back, config and secret references survive a failed upgrade, and the updater waits for plugin readiness before restarting. If an update still fails with "global-install-failed", see the global install verify decoder.
What to check right after updating
Spend 5 minutes on this before you trust the update:
- Gateway and version. Run
openclaw --version,openclaw healthandopenclaw gateway status --deep. Each should show the new version. - One message on each channel. Telegram, Discord, WhatsApp, whatever you use. A channel that stops replying is the most common sign of a bad update.
- Cron jobs. Check that your schedules are still listed and enabled. Missing jobs fail silently.
- Model list. Confirm the primary model and fallbacks are what you set.
- Memory. Ask the agent about something from last week. If it cannot answer, check the agent database before you go further.
- Skills. Run a task that needs a specific skill. Reinstall any that went inactive.
When the update breaks: the common failures
Every turn in one session fails: "admission is closed"
Symptom: after updating to 2026.10.10 or later, every turn in one session fails with Agent database execution admission is closed, and the Gateway log shows ERR_WORKER_OUT_OF_MEMORY.
Cause: the SQLite worker that loads session history has a 512 MB memory cap with no setting to raise it, and a very large session (the report had a 1.06 GB database) pushes past it. Issue #191847 is still open on 2026.11.2.
Fix: start a new, separate session for the same agent, archive the oversized one, or roll back from your pre-update backup. Full steps are in the admission is closed decoder.
The Gateway will not start
Symptom: the Gateway exits right after the update, or logs Refusing to run automatic gateway startup migrations.
Fix: run openclaw doctor --fix, then start the Gateway again. The startup migrations decoder covers the guard, and Gateway won't start after updating matches ten failures to the log line each one prints.
Telegram or Discord stops replying
Symptom: the Gateway runs but a channel goes quiet.
Fix: check openclaw gateway status --deep for the channel, then work through OpenClaw Telegram bot not working. If memory climbs until the Gateway dies, see the Gateway memory leak decoder.
The update itself failed or stopped halfway
Symptom: Update failure: reconcile:abandoned or gateway-recovery-verification.
Fix: run openclaw update status, then follow the reconcile abandoned decoder.
Config keys renamed, settings ignored
Symptom: a setting you rely on stops working, or the Gateway throws a validation error.
Fix: compare your backed-up openclaw.json with the new release notes, rename the keys and restart. openclaw doctor --fix handles many of these migrations for you.
Cron jobs gone or a different port
Symptom: scheduled tasks stop, or channels cannot reach the Gateway. Fix: check your schedules and the Gateway bind address and port against your backup, and restore what changed.
For everything else, start with OpenClaw not working.
How to roll back to the previous version
This is the section you'll bookmark.
Step 1: preview the rollback.
openclaw update --tag <previous-version> --dry-run
openclaw update --tag <previous-version>
The updater checks compatibility and asks you to confirm the downgrade (--yes skips that). If you are on the extended-stable channel, add --channel stable for a one-off exact version. For Docker, set the image back to the previous version tag and recreate the container. For the installer, re-run it with --version <previous-version>.
Step 2: restore the backup if a migration ran. This is the step people miss. Per the OpenClaw docs, downgrading the package does not reverse config or database migrations. Once your state has migrated past what the older release can read, the supported recovery is to restore the verified pre-update backup together with its matching OpenClaw version. Restore config, the shared database and every agent database from the same backup. Mixing a pre-update config with a post-update agent database breaks things in new ways.
Step 3: stop auto-update from undoing your rollback. Set OPENCLAW_NO_AUTO_UPDATE=1 in the Gateway environment while you recover.
Step 4: verify.
openclaw --version
openclaw health
openclaw gateway status --deep --json
openclaw doctor --lint --json

With a backup, the whole rollback takes about 2 minutes. Without one, you may not be able to go back at all. Rolling back is not failure. Update again once the fix ships.
Pin a version and wait for the first patch
You don't need to update every time a new version drops. The practical policy:
- Pick a channel.
stablefollows npmlatest.extended-stable(2026.9.36 as of 10 November) is package-only and never auto-applies, which suits agents you cannot babysit.betaanddevare for testing. - Pin the version. On npm, install an exact version with
openclaw update --tag <version>. On Docker, use a plain version tag, neverlatest. - Wait 3 to 5 days after a release. Watch the release thread and GitHub issues. If people report problems, wait for the patch release.
- Security fixes are the exception. When a CVE is published, update the same day. The one-click RCE (CVE-2026-25253, CVSS 8.8) showed why: 30,000+ exposed instances were found without authentication.
Automating updates safely
If you run several agents, the safest automation is a second machine or agent whose only job is to update a staging copy, run Doctor and a test message, and only then update the real one. Take a snapshot before each run, and keep the last verified backup until the new version has run cleanly for a few days.
Or skip all of it. BetterClaw is a managed no-code AI agent platform: updates are applied for you, your config is preserved, your skills stay active and security patches land same-day. Plans start at $19 a month, with BYOK across 28+ providers. See the plans.
Frequently Asked Questions
How do I update OpenClaw to the latest version?
Back up with openclaw backup create --output ~/Backups/openclaw --verify, then run openclaw update. It detects your install type, checks the new version while the old Gateway keeps serving, then activates and verifies it. Afterwards, run openclaw doctor, check openclaw health and send one test message on each channel. As of 10 November 2026 the latest stable release is 2026.11.2.
How do I update OpenClaw in Docker?
Run docker compose pull openclaw-gateway openclaw-cli, then docker compose stop openclaw-gateway and docker compose up -d openclaw-gateway. The image runs openclaw doctor --fix --non-interactive before starting, so you don't need a separate Doctor run. Pin a plain version tag rather than latest, because latest is rebuilt weekly.
How do I roll back an OpenClaw update?
Run openclaw update --tag <previous-version> --dry-run, then the same command without --dry-run, and confirm the downgrade. If the update migrated your config or databases, also restore your pre-update backup with its matching version, because downgrading the package does not reverse migrations. Set OPENCLAW_NO_AUTO_UPDATE=1 so auto-update doesn't reapply the new version.
What does openclaw doctor do?
It checks your config, databases and services and reports problems. openclaw doctor --fix applies the repairs, --non-interactive suppresses prompts and --deep runs deeper checks. Since 2026.11.1, Doctor exits nonzero when inspection is blocked, the config is invalid or required migrations are deferred, so scripts that use doctor --json must handle that exit status.
Why did my OpenClaw break after an update?
The usual causes are a migration the old config did not expect, a channel that needs re-checking, or on 2026.10.10 and later, a very large session hitting the 512 MB SQLite worker cap ("Agent database execution admission is closed"). Run openclaw doctor --fix, check the Gateway log for the exact error, and look it up in our decoder pages. If you cannot fix it quickly, roll back.
How do I back up OpenClaw memory on a VPS?
Run openclaw backup create --output ~/Backups/openclaw --verify on the VPS and copy the archive off the machine. Sessions and memory live in each agent's openclaw-agent.sqlite database under ~/.openclaw/agents/, and the archive includes them. Never copy the live .sqlite files by hand, because recent writes can still be in the -wal file.
Is it safe to skip OpenClaw updates?
Skipping feature releases for a few weeks is fine, and the extended-stable channel exists for that. Skipping security updates is risky. Apply security patches the same day and delay feature updates by a few days so others find the breaking changes first.
Want a second opinion on what to automate and where an agent is worth running? Book an AI automation audit.
Related Reading
- OpenClaw Latest Version: What each release changed
- OpenClaw Gateway Won't Start After Updating: Ten post-update failures, each matched to the log line it prints
- How to Back Up and Restore an OpenClaw Agent: The backup and two-step restore in detail
- OpenClaw Not Working: The most common failures and fixes
- OpenClaw Best Practices: Seven practices for ongoing maintenance and stability
- OpenClaw Security Risks Explained: Why security patches can't be delayed




