Upgrade & Migration Guide

Upgrade is a backup problem first and a package problem second. Official September notes are explicit: rolling back the application does not restore your conversations or agent data.

Before you run an updater: copy config and data somewhere the updater cannot overwrite. See full backup vs snapshot. If the Gateway is already dead after an update, skip this page and open update recovery.

Atomic Updates (from v2026.9.5)

On supported update paths, Atomic Updates check the next version before switching over. That reduces “half installed” binaries. It does not:

  • Guarantee Doctor can migrate huge compressed conversation archives (fixed later in v2026.10.9, but only after you are on a build that contains the fix).
  • Preserve untracked Git edits if an older updater rolls back badly (also tightened in 10.9).
  • Replace a backup you took yourself.

Recommended upgrade path

  1. Record openclaw --version and keep the output with the backup.
  2. Back up the config directory from openclaw doctor plus any custom skills. Backup & Restore.
  3. Read notes for the target version on docs.openclaw.ai/releases. For a jump from H1 2026, also read OpenClaw 2.0.
  4. Upgrade the way you installed: npm global package, official install script, or Docker image. Re-run the same path; do not mix them on one data directory.
  5. Restart the Gateway. Run openclaw doctor and openclaw config validate.
  6. Send one test message on a non-critical channel.

Aim for current stable (as of this writing, v2026.10.9) rather than hopping through every 10.x patch by hand. Security changes in 10.9 are collected on the October patch page.

When not to upgrade from the UI

If disk is full, if Doctor already reports damaged search indexes, or if you are in the middle of a long conversation archive, free space and back up first. v2026.10.9 lets agents accept writes again after you free disk, without restarting the Gateway, once cleanup succeeds—it will not replay interrupted writes.

Migrating from Moltbot or Clawd

OpenClaw is the later name. Config keys moved. Reuse API keys via environment variables. Reinstall skills from ClawHub rather than copying old plugin folders blindly. Channel tokens usually still work; verify against channel docs.

Related