Introduction

OpenClaw 2.0 (2026.8.1) changes session storage to SQLite. Before an upgrade that changes stored state, create a verified backup and check how you would recover your installation. Installing an older package alone does not restore the previous data format.

This guide covers backup, update, migration checks, and recovery on a Mac, home server, or VPS. The commands below follow the documentation reviewed on October 2, 2026; check the current updating guide for your installed version before proceeding.

What Actually Changes in the 2.0 Upgrade

Knowing what the updater will do to your machine makes the backup step feel less paranoid:

  1. Session storage migrates to SQLite. Your conversation history and session state move from the file-based store into a database. New sessions after migration use SQLite storage. This is the breaking change — if the migration fails halfway, you want your original session files intact.
  2. Security internals change. Runtime hardening, plugin loading rules, and secret handling all shift. Occasional third-party skills or plugins need updates to match.
  3. Existing configuration needs verification. Preserve your channel credentials, model settings, and gateway configuration, then check that they still work after the update.
  4. New onboarding runs only for fresh installs. The smart detection of existing subscriptions and API keys does not re-run on your machine.

Step 1 — Create a Verified Backup

OpenClaw's CLI ships a backup command that archives state, config, auth profiles, channel and provider credentials, and sessions — the exact set of things a botched migration could damage. The full flags are documented in the official backup docs:

# Create an archive and verify it before updating
openclaw backup create --verify

Keep the archive path printed by the command. To verify an existing archive, replace the example path with that actual file:

openclaw backup verify /path/to/openclaw-backup.tar.gz

backup list --from <location> inventories offsite archives; it does not verify a local archive. Do not continue if creation or verification fails. These backups are not one atomic snapshot of all configuration and databases, and later writes may be absent.

Two extra precautions from the backups guide:

  • Keep a protected copy off the machine so host or disk failure does not remove your recovery copy.
  • Note that these archives contain private messages and credentials. Encrypt them in transit and at rest, and don't leave them lying around on a shared server.

Running on a VPS? Also use your provider's documented snapshot procedure and check what it captures, including attached storage. Record the snapshot identifier and test recovery before relying on it.

Step 2 — Update OpenClaw

With a verified backup in hand, update the runtime:

npm install -g openclaw@latest --allow-scripts=openclaw

Or re-run the install script, which upgrades in place:

curl -fsSL https://openclaw.ai/install.sh | bash

Check what you're now running and let the built-in doctor catch obvious breakage:

openclaw --version
openclaw doctor

If you pinned a specific version anywhere (Docker tags, systemd scripts, cron jobs that invoke the binary), update those references too. Docker users: pull the new image tag and recreate the container — see the Docker installation guide for the compose patterns.

Step 3 — Verify the SQLite Session Migration

The migration runs on first launch after the update. Start your gateway the way you normally do and watch the logs — you're looking for the session migration to complete without errors. Then verify with a real conversation:

  1. History check — open any ongoing conversation and confirm past messages are intact
  2. New-session check — send a fresh message, restart the gateway, and confirm the new exchange survives (proving new sessions are being written to SQLite)
  3. Channel check — ping your agent from each connected channel (WhatsApp, Telegram, Discord, whatever you use) and confirm responses arrive

If any of these fail, pause new work, preserve logs and current state, and assess recovery (Step 5). Do not edit a partially migrated session store by hand.

Step 4 — Audit Plugins and Skills

Because 2.0 changed plugin loading and security internals, third-party code deserves a pass:

  • Update every plugin and skill you've installed (2.0's own update flows handle first-party plugins; for ClawHub skills use the built-in update commands or the clawhub CLI)
  • Re-check that each skill still has the access it needs — and no more. If a skill breaks under 2.0, treat it as an opportunity to ask whether you needed it at all (see our guide to vetting ClawHub skills)
  • Re-test anything that touches credentials, since secret handling changed

Step 5 — Roll Back If Something Broke

Preserve the failing installation before replacing anything. Recovery returns you to the data captured in a backup or snapshot; messages and other changes made afterward may be lost. Follow the official backups guide and version-specific recovery instructions.

Snapshot route (VPS): follow your provider's recovery procedure. Where supported, restore to a separate instance first and verify storage, configuration, history, and channels before switching traffic. Keep the current instance and any newer data until you have a working recovery. A snapshot is not a guarantee of zero data loss.

Backup archive route:

First extract the verified archive to a fresh directory outside your live OpenClaw state:

openclaw backup restore /path/to/openclaw-backup.tar.gz --target /path/to/restored-openclaw

This extracts files; it does not activate them or overwrite live state. The target must be new or empty. Then:

  1. Stop the Gateway and any node hosts using the files. Back up current state or move it aside.
  2. Use the archive manifest to locate restored state, configuration, and custom agent roots. Follow the documented activation steps, including restoring custom paths; the extraction directory itself is not necessarily the state directory.
  3. Use the backup's matching release and follow the official rollback and recovery instructions. Installing an older package cannot undo a data migration; check database compatibility before using a different runtime.
  4. Run openclaw doctor, start one Gateway, and repeat the history, new-session, and channel checks from Step 3.

Restored WhatsApp credentials can be out of sync with the linked device and may require re-linking. Review approval and delivery state before resuming jobs; restored state can also replay or omit actions.

Special Case: Upgrading a VPS Deployment

Remote deployments need one extra precaution. Before upgrading:

  1. Snapshot the instance (not just the OpenClaw backup)
  2. Note your firewall rules — 2.0's security overhaul tightened gateway exposure defaults, and a strict default could lock out a setup that previously relied on loose behavior
  3. Upgrade during a low-traffic window, since the migration runs on first launch

If your gateway is exposed to the internet at all, read the official security guide and our hardening checklist before you update — there's no reason to migrate an insecure deployment forward when you can fix both at once.

FAQ

Do I need to re-pair my WhatsApp/Telegram after upgrading? Credentials may carry over, but verify each channel. Check logs and channel status before re-onboarding. Restoring older WhatsApp credentials can require a fresh QR login; account linking and sender approval are separate steps.

How long does the SQLite migration take? Measure it on a restored copy of your own backup in a separate test installation, using the target release and comparable hardware. Record the first-start migration logs and verify history, new sessions, and channels before scheduling the live upgrade. This guide has no measured migration-duration benchmark.

Can I skip 2.0 and stay on my current version? You can skip one release, but you'll be stranded quickly: the security fixes in 2.0 answer the exposed-instance problems security researchers demonstrated earlier in 2026, and future releases build on the SQLite state layer. Upgrade — with a backup.

Is openclaw doctor still the right diagnostic? Yes — it checks config, gateway reachability, and channel health after any upgrade. If it reports issues the docs don't cover, the official FAQ covers local dev, VPS, multi-agent, and OAuth/API-key troubleshooting.