.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
OpenClaw ships updates frequently, sometimes weekly. Most of the time, upgrading is straightforward. But enough things can go wrong, especially around config schema changes and memory state, that doing it without a plan is a bad idea. The horror story that comes up regularly in the community: someone upgrades, the Gateway doesn't start cleanly, and they discover their only copy of configuration and memory was the one that's now in an inconsistent state.
This guide walks through the full upgrade process: deciding when to upgrade, backing up correctly, running the upgrade itself for npm, Docker, and source installs, verifying everything works afterward, and rolling back cleanly if it doesn't. There's also a section on ongoing maintenance routines that keep your setup healthy between upgrades.
When to upgrade (and when to wait)
OpenClaw doesn't have a formal LTS channel. Releases come from the main branch and get published to npm as latest. Whether to upgrade immediately or wait depends on what changed.
Upgrade immediately if the release includes security patches, particularly anything touching tool execution, OAuth token handling, or webhook authentication. Critical security fixes are worth a slightly rushed upgrade process. Check GitHub releases and the CHANGELOG.md for mentions of security fixes, and follow the project on X (@openclaw) or via PatchBot if you want release notifications without manually checking.
Upgrade promptly but carefully for bug fixes that affect something you're actively using: WhatsApp stability issues, memory persistence problems, cron misfires, rate limit handling. These are worth upgrading for, but take 20 minutes to do the backup properly first.
Wait a few days for pure feature releases if your current setup is working well. Let other people find the sharp edges first. The npm install history lets you see exactly what was released when, so you're not stuck on an old version forever, you're just not the first one to hit a schema change that breaks something unexpected.
To see what versions are available before committing to an upgrade:
npm view openclaw versions --jsonBacking up before you touch anything
Everything that matters about your OpenClaw setup lives in ~/.openclaw/. Config, credentials, sessions, cron jobs, agent definitions, workspace memory, skills. If you lose this directory or upgrade leaves it in a broken state without a backup, you're starting over.
The backup process has three steps: stop the Gateway so you get a consistent snapshot, create the archive, and verify it actually contains what you think it does.
Stop the Gateway first
Don't back up a running Gateway. Session files get written continuously, and a backup taken mid-write can produce a partially consistent state that's worse than useless. Stop it cleanly:
openclaw gateway stop
# or if running as systemd
sudo systemctl stop openclaw-gateway
# or for Docker
docker compose stop openclaw-gatewayCreate and encrypt the archive
tar czf openclaw-backup-$(date +%Y%m%d-%H%M).tgz ~/.openclaw/
gpg --symmetric --cipher-algo AES256 openclaw-backup-$(date +%Y%m%d-%H%M).tgzThe GPG encryption step matters because ~/.openclaw/ contains API keys, bot tokens, and channel credentials in plaintext. If your backup goes to cloud storage, an unencrypted archive is a credentials leak waiting to happen.
If you use an external workspace directory or have per-agent workspace overrides configured, back those up separately. Same for any external databases connected to memory backends like Mem0 or Cognee.
Verify the backup actually worked
Don't skip this. A backup you've never verified is not a backup.
# List contents to confirm key files are present
tar tzf openclaw-backup-*.tgz | grep -E "(openclaw.json|MEMORY.md|jobs.json|credentials)"
# Validate the config file is valid JSON
tar xzOf openclaw-backup-*.tgz .openclaw/openclaw.json | python3 -m json.tool > /dev/null && echo "Config OK"If the config validation fails, your backup contains a broken config file, which means your running config was already broken before the upgrade. Fix that first.
For a more complete backup strategy with retention policies and automated scheduling, see the backup and export guide.
Running the upgrade
The commands differ depending on how you installed OpenClaw. Use the method that matches your install, not whichever looks easiest.
npm global install (most common)
# Upgrade to latest
npm install -g openclaw@latest
# Or pin to a specific version
npm install -g [email protected]
# Run health check after install
openclaw doctor --fix
# Restart the gateway
openclaw gateway restartThe openclaw doctor --fix step is important here. Schema changes between versions are one of the most common causes of post-upgrade problems, and doctor --fix attempts to normalize your config to match the new expected structure. It won't catch everything, but it catches the common cases.
Shell installer
If you installed with the official installer script, you can re-run it to upgrade in place. It detects the existing install and updates it:
curl -fsSL https://openclaw.ai/install.sh | bashThis works fine but gives you less control over the version. If you want to pin to a specific release, use the npm method instead.
Source install
cd ~/openclaw # or wherever your source checkout lives
git pull origin main
pnpm install --frozen-lockfile
pnpm build
openclaw doctor
openclaw gateway restartIf you want to upgrade to a specific date's state of the codebase rather than the absolute latest commit:
git checkout "$(git rev-list -n 1 --before="2026-02-17" origin/main)"
pnpm install --frozen-lockfile
pnpm buildThis is useful when the latest main has a known issue and you want to stay on a stable point from a few days ago.
Docker and Docker Compose
docker compose pull
docker compose up -d --force-recreate
docker compose logs -f openclaw-gatewayYour named volumes persist across this operation, so config and memory survive the image update. Watch the logs after recreating to catch any startup errors or schema migration messages before they become problems. If you use pinned image tags rather than latest, update the tag in your docker-compose.yml before pulling:
# In docker-compose.yml
image: openclaw/openclaw:2026.2.6 # instead of :latestSystemd service
sudo systemctl stop openclaw-gateway
# Run your upgrade method (npm, source, etc.) here
sudo systemctl start openclaw-gateway
sudo systemctl status openclaw-gateway
journalctl -u openclaw-gateway -fIf you've modified your systemd unit file, reload the daemon after any changes to the unit file itself:
sudo systemctl daemon-reloadThe systemd service guide covers the unit file configuration in detail if you need to adjust anything.
Testing after the upgrade
Don't declare the upgrade successful until you've actually verified the things that matter. The Gateway starting without errors is necessary but not sufficient.
Health and schema checks
openclaw doctor --non-interactive
openclaw status --alldoctor checks config schema, dependencies, and port availability. status --all shows channel auth state, model allowlist validity, and memory index status. Both should complete cleanly. If doctor reports schema warnings and you didn't run --fix during the upgrade, run it now.
Channel connections
openclaw channels status --probeThis actually probes each configured channel rather than just reading cached auth state. A Telegram bot token that expired between your last session and the upgrade won't show as a problem in status alone, but --probe will catch it. Send a test message through each active channel and confirm you get a response.
Memory integrity
If you're using the default Markdown memory system, check that MEMORY.md and your memory files are intact and the index rebuilt correctly. For QMD setups, trigger a reindex and run a test query:
# Test memory retrieval
# In a chat session:
# "Search memory for [something you know is in MEMORY.md]"Memory loss after upgrades is the most common complaint in the community, and it almost always traces back to one of two things: the session history format changed between versions (older session files become unreadable), or the memory index needs to rebuild after the upgrade and hasn't finished yet. Give it a few minutes before concluding something is broken.
Cron jobs and scheduled tasks
openclaw cron list
openclaw cron statusConfirm your jobs are still defined and showing as enabled. Then trigger one manually to verify it runs correctly end-to-end. This is the step most people skip, and it's also the step that reveals when a cron job's model configuration refers to a model key that changed between versions.
Skills and tools
Run a quick test of any custom skills, especially if they use exec or read/write tools. Schema changes occasionally affect how tool calls are formatted, and a skill that worked before an upgrade can silently fail after one if the tool interface changed.
Rolling back when something goes wrong
If the upgrade broke something and you can't fix it quickly, rolling back is faster than debugging under pressure.
npm rollback
# Roll back to a specific known-good version
npm install -g [email protected]
openclaw doctor
openclaw gateway restartFind the version that was working before by checking your shell history for the previous npm install command, or by looking at npm's version list and picking one from before the upgrade date.
Source rollback
cd ~/openclaw
git checkout "$(git rev-list -n 1 --before="2026-02-17" origin/main)"
pnpm install --frozen-lockfile
pnpm build
openclaw gateway restartWhen you're ready to try moving forward again:
git checkout main
git pullDocker rollback
Before pulling new images, tag the current one so you can return to it:
docker tag openclaw/openclaw:latest openclaw/openclaw:pre-upgrade-backupIf the upgrade goes wrong:
docker compose down
# Edit docker-compose.yml to use: openclaw/openclaw:pre-upgrade-backup
docker compose up -dYour volumes are untouched throughout this, so config and memory survive the image swap.
Restoring from backup
If the config or memory itself got corrupted during an upgrade (not just the binary), restore from your pre-upgrade backup:
openclaw gateway stop
# Decrypt if you encrypted the backup
gpg --decrypt openclaw-backup-20260217-1430.tgz.gpg > openclaw-backup-20260217-1430.tgz
# Move current state aside (don't delete until you're sure restore worked)
mv ~/.openclaw ~/.openclaw.broken
# Restore
tar xzf openclaw-backup-20260217-1430.tgz -C ~/
# Pin to the version that was running when you took the backup
npm install -g openclaw@
openclaw doctor
openclaw gateway start The version pin is important here. Restoring old config and running it against a new version is what caused the problem in the first place.
Ongoing maintenance between upgrades
Upgrades are the obvious maintenance event, but there's routine work worth doing on a regular schedule.
Weekly: run openclaw doctor to catch config drift before it becomes a problem. Prune unused sessions from ~/.openclaw/sessions/ — old session files don't cause active problems but they accumulate and make backups larger. Run a full backup if you haven't had an automated one fire recently.
Monthly: rotate API keys and bot tokens. Not because they've necessarily been compromised, but because regular rotation limits the window of exposure if they have been. Also worth doing: test your backup restore process. Actually decrypt and restore a backup to confirm it works, rather than finding out it doesn't when you need it. The security best practices guide covers credential management in more depth.
After any significant configuration change: take a manual backup immediately. The automated backup schedule protects you against upgrade failures, but it doesn't protect against "I edited openclaw.json and broke something and now I can't remember what it looked like before." A pre-change snapshot takes 30 seconds and saves hours.
Migrating to a new server
Migrating OpenClaw to a new VPS is essentially the same as a restore, just to a different machine. Stop the Gateway on the old server, create a full backup, transfer it to the new server, extract it to the same path, install the same version of OpenClaw, and run openclaw doctor. The VPS hosting guide and the Ubuntu installation guide cover the initial server setup.
The one thing that commonly trips people up on migration: channel credentials. WhatsApp sessions are tied to phone state and often need to be re-established on a new server even with the credentials file intact. Telegram and Discord bot tokens transfer fine. Plan for a re-login step on any WhatsApp channels before declaring the migration complete.
