Upgrade to OpenClaw 2.0+ (v2026.8–2026.10 Lines, Now at v2026.10.2)
Upgrade OpenClaw with verified backups, compatibility checks, Doctor and recovery steps; very old configurations may need an intermediate version.
Prerequisites
- A running OpenClaw 2026.x install (any channel)
- Terminal access and free disk space
- A verified backup completed before upgrading (step 1)
Steps
Check your version and create a verified backup
OpenClaw 2.0 migrates configuration, so first record your current version, then create a fully verified state restore point. Note that openclaw update only keeps an automatic config copy — not a full backup.
Commands
openclaw --version mkdir -p ~/Backups/openclaw && openclaw backup create --output ~/Backups/openclaw --verify Tips
- • Backup archives may contain credentials and channel state; store them owner-only
- • Note the backup point: restoring state later discards changes made after it
Preview and run the upgrade
openclaw update detects your install type (npm/pnpm/Bun/git), fetches the latest version, runs doctor and restarts the Gateway. Preview with --dry-run first; keep production on the stable channel.
Commands
openclaw update --dry-run openclaw update Tips
- • v2026.10.2 (Oct 12): the first upgrade from stable v2026.10.1 now completes cleanly, and successful in-place updates no longer end in errors; Windows, cloned-filesystem, and private-Node update paths finish instead of stalling or rolling back. The stable line is now at v2026.10.2; follow current release notes and backup/compatibility checks before upgrading. v2026.9.4 (Sep 11) had introduced compatible failed-update recovery and the Plugins workspace.
- • v2026.9.3 (Sep 8): updates are first rehearsed in an isolated candidate state and activated only after checks pass; the Node runtime floor rises to 24.16.0+ (or 26.1.0+) — upgrade Node BEFORE OpenClaw to avoid SQLite text truncation.
- • v2026.9.2 (Sep 5): GPT-6 Astra model support (openai/gpt-6-astra via API key or ChatGPT/Codex account); automatic updates preserve settings/skills/default agent; failures come with actionable recovery guidance. Upgrade straight to this version on the 2026.9 line.
- • v2026.9.1 (Sep 3, 2026.9-line stable): failed updates now roll back the npm candidate and preserve config and secret references — upgrade safety strengthened; new `openclaw skills library` personal skill libraries with ZIP import; fresh installs get a quick-start lane (auto-detects existing Claude Code/Codex logins). 2.0 users can upgrade across lines directly.
- • v2026.8.2 (Sep 1) is the last of the 8.x line: dock the Home agent with Cmd/Ctrl+Shift+H; a Linux .deb/AppImage desktop companion lands.
- • Avoid the beta channel on production installs
- • Extended-stable 2026.8.35 (Oct 2) is gateway-only, based on end-of-August code plus backported fixes; it is not the full 2026.9 feature set.
- • Very old configurations may need an intermediate 2026.9.5 upgrade and Doctor. Version 9.9 cannot downgrade or repair data converted by an October beta; preserve originals first.
Run doctor to complete the two migration paths
OpenClaw 2.0 ships two breaking changes: the bundled OpenProse plugin and /prose command are removed, and codex/* / openai-codex/* refs migrate to openai/* across provider config, stored sessions and automation routes. openclaw doctor --fix handles both and flags conflicts.
Commands
openclaw doctor --fix Tips
- • Gateway startup also auto-runs safe config migrations, but an explicit doctor --fix after upgrade is more reliable
Restart the Gateway and verify each item
After migration, restart the Gateway, then confirm version, health, plugin inventory and a deep probe all pass.
Commands
openclaw gateway restart openclaw health openclaw plugins list --json openclaw gateway status --deep --json Tips
- • Expect version 2026.8.1; if plugins list is missing BytePlus, Mistral, Volcengine or other provider packages, run openclaw update repair and restart — providers now install on demand in 2.0
Follow-ups: .prose files and route conflicts
Wrap up both migrations: existing .prose files are kept and follow the upstream Agent Skill path; conflicts doctor flagged on openai/* routes need manual repair — especially hardcoded codex/ refs in custom provider config and automations.
Tips
- • Search your config and automations for codex/ and openai-codex/ and switch them to openai/
- • Smoke-test any Codex-model-routed task before returning it to daily use
Plugin and SDK developers: the September 1 gate
If you maintain custom plugins, note that several plugin-sdk-* subpath imports converge into focused openclaw/plugin-sdk/ imports, gated on September 1, 2026. Retained public helpers keep their shipped caller names; run the compatibility warning in a test env to locate affected imports.
Tips
- • The official SDK migration guide lists the full subpath mapping — replace them one by one
- • Unmigrated plugins will hard-fail on the new runtime after September 1
If something breaks, roll back in two layers
Rollback has two layers: first reinstall the old OpenClaw code while keeping current state (try this first); only if the old code cannot read migrated config or databases, restore the pre-update backup — which discards changes made since (last resort).
Commands
npm i -g openclaw@2026.7.1 # code-level rollback example: reinstall old version, keep state openclaw gateway restart Tips
- • Restore the backup state only when the old code cannot read the migrated config or database