OpenClaw 2.0 Breaks In-Place Upgrades: The Fixes That Work

You ran the update, the terminal proudly reports the new version, and the Gateway never comes back. Then the logs tell you your state database "uses newer schema version 15; this OpenClaw build supports 1" — a version mismatch on a machine you only upgraded once.

That failure has a specific cause and a five-minute fix, and it is the most common of six documented ways an in-place OpenClaw 2.0 upgrade goes wrong. Here is what breaks, why, and the order to fix it in.

Why 2.0 breaks environments that 1.x was fine with

OpenClaw 2.0 (v2026.8.1) is, per the project's release notes, the biggest release in its history: 933 contributors and over 16,000 merged pull requests — roughly half of all PRs ever merged — with the installer, browser Control UI, session storage and permission system almost entirely rewritten.

Four of those rewrites are what make an upgrade different from an install:

• Sessions moved from JSONL files to SQLite — a global database plus per-workspace databases. Migration runs automatically on first boot, but older releases cannot read the new databases.
• The Gateway was rebuilt. Cold start dropped from ~1.6s to ~575ms and default agent concurrency now scales with CPU (8-16 sessions on a typical machine) — but the config structure and channel management changed with it.
• The plugin system got stricter. Official provider packages are installed on demand, and plugin API version checks are enforced: plugins built against older APIs are skipped at discovery.
• Node.js floor moved up. Fresh CLI setups require Node.js 22.22.2+; older Node fails outright.

Fresh installs land on the far side of all four. In-place upgrades have to cross them with a running system.

Two breaking changes that guarantee errors

The bundled OpenProse plugin and the /prose command are gone in 2.0. Run openclaw doctor --fix after upgrading to clean up leftover config; your .prose source files are kept, and the official migration path moves you to an upstream Agent Skill.

Separately, every model reference, provider config, stored session and automation route under codex/* and openai-codex/* is migrated to openai/*. The Codex runtime intent is preserved, and conflicting configs are flagged for review rather than silently resolved.

The six failures, in the order you will hit them

1. Dead Gateway from schema version drift

The error above looks like a corrupted database. It is not. The documented root cause is multiple OpenClaw entry points on one machine — global npm, pnpm and brew installs coexisting. Only one got upgraded, so the terminal reports the new version while the background Gateway is still the old build, which then tries to open a SQLite database written by the newer schema.

The fix is to unify the entry points: stop every Gateway process with openclaw gateway stop, list all binaries with which -a openclaw (or where.exe openclaw on Windows), run openclaw --version on each, then upgrade or uninstall the stale ones until every path reports the same version. If you were on the beta channel, switch with openclaw update --channel stable first.

2. Provider plugins that no longer ship in core

Provider packages — Volcano Engine, Mistral, BytePlus and others — moved out of core and install on demand, so doctor reports "plugin not installed" for each. Install them individually with openclaw plugins install. Third-party plugins that have not adopted the new tool-schema contract get blocked at registration, and the guide is blunt that there is no safe workaround: you wait for the plugin author to update.

3. Silent channels after the Gateway finally starts

This is the misleading one. You fix the Gateway, and DingTalk, Feishu, WeChat, WhatsApp and Telegram all refuse to auto-start, with logs saying auto-start was "suppressed by the crash-loop breaker".

Your channel config is not wrong. The breaker locked channel auto-start after repeated Gateway crashes, specifically to stop fault amplification. Let the Gateway run stably for a while, then bring channels up manually and normal auto-start resumes. Deleting and rebuilding channel configs is wasted work.

4. Insecure defaults that survive the upgrade

The 2.0 installer blocks unauthenticated network Gateways. Upgrading in place does not guarantee the same safe defaults. Run openclaw security audit and openclaw sandbox explain and resolve every high-risk item — the guide singles out the case where config says bind-to-LAN but the process is actually listening on 0.0.0.0. Never expose the Gateway to the public internet without authentication; on cloud hosts, lock security groups down or put an authenticating reverse proxy in front.

5. Environment prerequisites

Node.js 22.22.2+ is mandatory. Git must be on PATH — 2.0 uses it for config sync and versioning, and a missing Git throws hard. Keep 20GB+ free disk for session logs, memory snapshots and model temp files. Avoid system directories on Windows, and do not mix sudo runs on Linux or macOS, which corrupts file ownership.

6. Automations that read the old file layout

Backup scripts, analysis tools and CI/CD integrations that read ~/.openclaw/sessions/ JSON files directly fail silently once sessions live in SQLite — no error, just no data. Audit external automations before upgrading, move them to the sessions API, and run openclaw config validate afterwards to flush deprecated options.

The upgrade sequence

1. Back up config and state — cp -r ~/.openclaw ~/.openclaw.bak-$(date +%F). This is your only rollback path.
2. openclaw update --channel stable
3. openclaw doctor --fix to migrate breaking changes and clean leftover config
4. openclaw doctor, openclaw gateway status, openclaw logs --follow to confirm a healthy Gateway
5. openclaw update repair, then openclaw gateway restart

You are done when every entry point reports the same version, the Control UI answers a test message, one low-risk Skill exercises the permission chain, each channel you use responds, and openclaw security audit shows no high-risk items.

Rollback is a restore, not a downgrade

Because old releases cannot read the new SQLite databases, rolling back means stopping every process, moving ~/.openclaw aside, restoring the dated backup and reinstalling the previous release through your package manager. JSONL transcripts are imported into SQLite automatically on first boot, but that import is one-way — downgrade without the backup and old builds will not see your sessions.

Is it worth upgrading?

Fresh setups should install 2.0 directly. For existing installs the guide's position is that the gains are real — Control UI, cloud sessions, the new permission model, a roughly 3x faster Gateway — provided you back up first and follow the sequence. If OpenClaw runs anything mission-critical, rehearse the whole upgrade on a test box or a cheap cloud instance, confirm plugins and channels come back, and only then touch the machine that matters.

Watch two things after you land: whether your third-party plugins ship tool-schema updates, and whether the crash-loop breaker trips again — a second trip means the Gateway is still unstable, not that your channels are misconfigured.