Openclaw shipped 13 point releases in March 2026 alone. Three of those introduced breaking changes. If you run Openclaw for anything beyond casual experimentation, updating without a plan is how you end up spending a weekend restoring configs instead of building workflows.
The update process below goes beyond the two-line quickstart from the docs. It covers version checks, backup, the update itself (npm and Docker Compose), post-update verification, and rollback when things go sideways.
Check Your Current Version
Before touching anything, record what you are running:
openclaw --version
For Docker deployments, the version lives in the image tag:
docker inspect openclaw-gateway --format '{{.Config.Image}}'
Write this down or pipe it to a file. You will need it if the update fails and you need to pin back to the working version.
Read the Changelog First
This step gets skipped more than any other, and it is the single biggest predictor of whether an update goes smoothly.
Check the Openclaw releases page for every version between your current version and the target. Look specifically for:
- Breaking changes tagged in the release notes
- Config schema changes that require manual migration
- Tool permission changes (v2026.3.2 switched tool profiles from opt-out to opt-in, silently disabling agent tools for thousands of users)
- Deprecated plugin APIs that affect custom skills
If the release notes mention a config migration and do not include a migration script, treat that as a red flag. Budget extra time for manual config adjustments.
Decide Whether to Update Now
Not every release warrants immediate action. Here is a practical framework:
Update immediately when:
- The release patches a CVE or security vulnerability (9 CVEs were patched in March 2026 alone)
- The release fixes a bug you are actively experiencing
- A dependency you rely on requires the newer version
Wait 3-5 days when:
- The release is feature-only with no security patches
- You run custom skills that could be affected by API changes
- The community trackers (r/openclaw, PatchBot, Releasebot) have not yet reported issues
Skip entirely when:
- The release adds features you do not use and includes no security fixes
- You are mid-project and cannot afford debugging time
- Community reports indicate regressions that have not been resolved
Delayed adoption (waiting 3-5 days after a release) catches most of the problems other people find first. The only exception worth making is for security patches.
Back Up Before You Touch Anything
This takes 30 seconds and saves hours. Your entire Openclaw state lives in ~/.openclaw/:
tar -czf openclaw-backup-$(date +%Y%m%d-%H%M).tar.gz ~/.openclaw/
For Docker Compose deployments with bind mounts, back up both directories:
tar -czf openclaw-full-backup-$(date +%Y%m%d-%H%M).tar.gz \
~/.openclaw/ \
~/openclaw/workspace/
Verify the archive is not empty:
tar -tzf openclaw-full-backup-*.tar.gz | head -5
If you see file listings, you are good. If the archive is 0 bytes or tar reports an error, do not proceed until the backup is valid.
For production deployments, encrypting the archive before storing it adds a layer of protection:
gpg --symmetric --cipher-algo AES256 openclaw-full-backup-*.tar.gz
Store the backup somewhere outside the machine you are updating. A local backup on the same disk you are about to modify is not a backup.
Update Openclaw
npm (Global Install)
The built-in update command is the simplest path:
openclaw update
This detects your install type, fetches the latest stable version, runs openclaw doctor, and restarts the gateway. To preview what will change without applying it:
openclaw update --dry-run
To update to a specific channel:
openclaw update --channel stable
openclaw update --channel beta
If you prefer direct npm control (useful for pinning exact versions):
npm install -g openclaw@latest
openclaw doctor --fix
openclaw gateway restart
Pin to a specific version when you need reproducibility:
npm install -g openclaw@2026.3.23
Docker Compose
For Docker deployments, the update is a pull-and-recreate cycle. Your data persists in bind-mounted volumes, so the container replacement is safe:
docker compose pull
docker compose up -d --force-recreate
docker image prune -f
To test the new image before committing to it, pull it first and check the version:
docker compose pull
docker compose run --rm openclaw-gateway openclaw --version
If the version looks correct and the release notes check out, proceed with the recreate. If not, your running container is still on the old image.
For production Docker deployments, pin the image tag in your docker-compose.yml instead of using latest:
image: ghcr.io/openclaw/openclaw:2026.3.23
This prevents accidental upgrades when someone runs docker compose pull without checking the changelog first. Our Docker deployment guide covers the full production Compose configuration.
Source Install
If you built Openclaw from source:
cd ~/openclaw
git fetch --all
git checkout tags/v2026.3.23
npm install
npm run build
openclaw doctor --fix
openclaw gateway restart
Verify the Update Worked
Do not assume the update succeeded because the command exited cleanly. Run these checks:
Version confirmation:
openclaw --version
Health diagnostics:
openclaw doctor
openclaw health
openclaw doctor checks for config migrations, missing dependencies, and security issues. If it reports problems, run openclaw doctor --fix and review what it changed.
Channel connectivity:
openclaw channels status --probe
This confirms your Telegram, Slack, Discord, or WhatsApp connections are still active. Channel connections occasionally drop during updates, especially WhatsApp which requires re-authentication after certain version jumps.
Tool execution:
Send your agent a test message that requires tool use. After v2026.3.2, tool permissions changed to opt-in. If your agent responds but refuses to execute tools, check:
openclaw config get tools.profile
If it returns messaging-only, switch back to full tool access:
openclaw config set tools.profile full
openclaw gateway restart
Custom skills:
If you have custom skills installed, test each one. Skill APIs occasionally change between versions, and a skill that worked on the previous version can silently fail after an update. Our skills development guide covers testing practices.
Scheduled tasks:
openclaw cron list
Verify your heartbeat schedules and cron jobs are intact and running on their expected cadence.
Roll Back if Something Breaks
If the update causes problems you cannot resolve within 30 minutes, roll back first and debug later. Continuing to troubleshoot on a broken version wastes time and risks further state corruption.
npm Rollback
npm install -g openclaw@PREVIOUS_VERSION
openclaw doctor --fix
openclaw gateway restart
Replace PREVIOUS_VERSION with the version number you recorded before updating.
Docker Compose Rollback
Change the image tag in docker-compose.yml back to the previous version:
image: ghcr.io/openclaw/openclaw:PREVIOUS_VERSION
Then recreate:
docker compose up -d --force-recreate
Restore from Backup
If the rollback alone does not fix things (config corruption, memory state issues), restore from your pre-update backup:
openclaw gateway stop
rm -rf ~/.openclaw
tar -xzf openclaw-backup-YYYYMMDD-HHMM.tar.gz -C /
openclaw gateway restart
For encrypted backups:
gpg --decrypt openclaw-full-backup-*.tar.gz.gpg > openclaw-full-backup.tar.gz
tar -xzf openclaw-full-backup.tar.gz -C /
Handling Breaking Changes
When a breaking change hits your deployment, the fix usually falls into one of three categories:
Config schema changes: Compare your config against the new defaults:
diff <(openclaw config dump) <(openclaw config defaults)
Look for new required fields or changed default values. The Openclaw changelog documents these, but sometimes incompletely.
Tool permission changes: Check tools.profile and the tool allowlist. The v2026.3.2 incident is the canonical example: tools went from enabled-by-default to disabled-by-default, and thousands of agents suddenly stopped working.
Plugin API deprecations: If a custom skill stops working after an update, check whether the skill uses deprecated API methods. Run openclaw doctor first; it flags known deprecations. For skills you built yourself, check the skills development guide for migration paths.
Frequently Asked Questions
How do I check which Openclaw version I’m running?
Run openclaw --version in your terminal. For Docker deployments, use docker inspect openclaw-gateway --format '{{.Config.Image}}' to see the image tag, which includes the version number.
Will updating Openclaw delete my memory or sessions?
No. Memory, sessions, and configuration live in ~/.openclaw/, which is separate from the Openclaw binary. Updates replace the application code, not your data. The most common cause of perceived “memory loss” after updates is a config migration that changes how memory files are read, not actual deletion. Back up ~/.openclaw/ before updating and you can always restore.
What is the difference between openclaw update and npm install -g openclaw@latest?
openclaw update is a wrapper that detects your install type (npm, source, or Docker), fetches the latest version for your channel, runs openclaw doctor automatically, and restarts the gateway. npm install -g openclaw@latest only replaces the binary and skips the doctor check and gateway restart. If you use the npm method, run openclaw doctor --fix and openclaw gateway restart manually afterward.
Can I skip multiple versions and jump straight to the latest?
You can, but read every changelog entry between your current version and the target. Breaking changes compound. If v2026.3.5 changed the config schema and v2026.3.12 deprecated a plugin API, jumping from v2026.3.4 to v2026.3.15 means you hit both changes at once. For jumps spanning more than 5 releases, update incrementally or at minimum read every release note in the range.
My agent stopped using tools after an update. What happened?
This is almost certainly the v2026.3.2 tool profile change. Check openclaw config get tools.profile. If it returns messaging-only, your agent can respond to messages but cannot execute tools. Set it to full with openclaw config set tools.profile full and restart the gateway.
How do I roll back if an update breaks something?
For npm: npm install -g openclaw@PREVIOUS_VERSION followed by openclaw doctor --fix and openclaw gateway restart. For Docker: change the image tag in your docker-compose.yml to the previous version and run docker compose up -d --force-recreate. If config or memory state is corrupted, restore from your pre-update backup archive.
Should I update Openclaw immediately when a new version drops?
Only for security patches. For feature releases, wait 3-5 days and check community reports on r/openclaw and the GitHub issues tracker. Most breaking changes surface within 48 hours of a release. Delayed adoption is the lowest-effort way to avoid being the person who discovers the regression.
How do I update Openclaw in Docker Compose?
Run docker compose pull to fetch the latest image, then docker compose up -d --force-recreate to replace the container. Your data persists in bind-mounted volumes. For production, pin the image tag in your docker-compose.yml rather than using latest, and update the tag manually after reviewing the changelog.
Key Takeaways
- Back up
~/.openclaw/before every update. It takes 30 seconds and prevents the worst-case scenario. - Read the changelog between your current version and the target. Breaking changes are documented, but only if you look.
- Use
openclaw update --dry-runto preview changes before applying them. - After updating, verify with
openclaw doctor, test your channel connections, and confirm tool execution still works. - If something breaks and you cannot fix it in 30 minutes, roll back first. Debug on a known-good version, not a broken one.
- For production Docker deployments, pin image tags. The minor inconvenience of manual version bumps is worth avoiding surprise breakage.
SFAI Labs
