How to Update to OpenClaw 2.0 (Step-by-Step)

OpenClaw's release notes lead the upgrade section with one instruction: back up your configuration and state before updating. For a release that lands nearly two months of changes at once, treat that as non-optional.

Conveniently, 2.0 ships better backup tooling than 1.x had:

• openclaw backup sqlite — creates, lists, verifies, and restores compact snapshots of the global and per-agent databases
• Recoverable scheduled backups — versioned snapshots pushed to a Git repository you own, restorable as a verified archive into a fresh staging directory

At minimum, before you touch anything: snapshot the databases, copy your configuration directory, and note which plugins and channels you have enabled. On 1.x, where the new backup command does not exist yet, a plain file copy of your OpenClaw state directory does the job.

Budget 15–30 minutes for the whole update, most of it verification at the end.

Use the same update path you normally use:

• CLI and server installs: run your usual update command. If it fails partway, openclaw update repair recovers missing packages — do not start deleting directories by hand.
• macOS app: 2.0 ships as a signed, notarized DMG and ZIP; the app updates in place.
• Linux: AppImage installs update through signed updates with a user-confirmed restart; package-managed installs get a release notice and update through your package manager.
• iOS and Android: the store builds follow the Gateway release separately — update the Gateway first, then the mobile apps when they appear.

One 2.0-specific tip straight from the release notes: keep a coding agent handy (Claude Code or similar) in case an automatic update fails midway — it is genuinely the fastest way to diagnose a migration error and verify the Gateway starts cleanly.

doctor --fix is the migration workhorse for 2.0. Run it once right after updating. What it does in this release:

• Removes the retired OpenProse plugin and its /prose command from your configuration. Your .prose source files are left untouched; if you relied on that workflow, the upstream project documents a migration to Agent Skills.
• Rewrites OpenAI model routes. Anything referencing codex/* or openai-codex/* — provider config, stored sessions, automations — migrates to the unified openai/* namespace. Model behavior does not change; the reference format does.
• Applies safe configuration migrations that 2.0 would otherwise apply silently at first startup, so you see them happen explicitly.

Run it, read the output, and re-run it until it reports nothing left to fix — it is safe to run repeatedly.

Start the Gateway and walk a short verification pass:

1. Gateway starts cleanly. 2.0 starts dramatically faster (about 575 milliseconds), so a slow or looping startup is itself a signal — check the logs rather than waiting it out.
2. Channels reconnect. Telegram, Discord, and WhatsApp configurations carry over untouched. WhatsApp now holds its auth and lease until the Gateway stops, so you should not need to re-link — if you are asked to re-scan a QR code, restore your state backup and retry rather than re-linking blind.
3. Message a skill. Send one real task to a skill on each channel you use. Confirm replies thread correctly (a 2.0 fix on WhatsApp) and that memory context survived.
4. Check your automations. Scheduled jobs interrupted by the restart are recovered in 2.0, but confirm the next run time on anything business-critical. Recurring automations now use approve-once permissions — a changed automation asks for fresh approval instead of silently running.

If all four pass, you are done. The rest of this guide is for when they do not.

Everything that can actually break, and who it affects:

• OpenProse plugin removed — affects anyone using /prose. doctor --fix cleans the config; .prose files remain; migrate the workflow to Agent Skills.
• codex/* and openai-codex/* routes retired — affects anyone with OpenAI models configured. doctor --fix migrates references in config, sessions, and automations to openai/*.
• Plugin SDK subpath imports deprecated — affects plugin authors only. Five legacy subpaths (config-runtime, channel-reply-pipeline, channel-lifecycle, channel-message, infra-runtime) must move to focused openclaw/plugin-sdk imports by September 1, 2026. Published plugins keep working until their authors update.
• Skills: no changes. The SKILL.md format is untouched — skills from the marketplace or ClawHub run as-is.
• Channel configs: no changes. Telegram, Discord, WhatsApp, Slack, and the rest carry over.

If your deployment is skills-on-channels — the standard OpenClaw Masterclass setup — you likely have zero manual migration work.

The update is the boring part. These are the 2.0 features worth ten minutes each once you are across:

• Session permission modes. Review which mode your sessions run in and tighten filesystem scope to the workspace — a first-class setting now, not a config hack.
• Conversation search. No setup, just awareness: exact-phrase search across your agent's history, reopening results in context.
• Telegram /dashboard. If your agent lives on Telegram, send /dashboard to your bot — the full Control UI opens as a Mini App inside Telegram.
• Scheduled backups. Point recoverable backups at a private Git repository so your next update starts from a known-good snapshot automatically.
• Memory controls. Grounded dreaming (background memory consolidation) is on by default in 2.0. Skim the Dream Diary to see what it is learning, and remember openclaw memory forget exists for anything you want unremembered.

For the full tour of what changed, see OpenClaw 2.0 Explained.

The likely failure modes, in order:

• Gateway won't start. Run openclaw doctor --fix again and read the output — most post-2.0 startup failures are unmigrated configuration. openclaw update repair recovers missing or half-installed packages.
• A plugin refuses to load. 2.0 reviews plugin capability and trust information before enabling; a plugin built against deprecated SDK subpaths may need an update from its author. Declining an update keeps the previous version running.
• Something is deeply wrong. Restore your pre-update snapshot into a fresh staging directory (2.0's restore verifies the archive first) and bring channels up one at a time. Because you took the backup in step one, this is a 10-minute reset, not a rebuild.
• Downgrade protection kicks in. If you point an older Gateway at a 2.0 database, it refuses to start rather than corrupting state. That refusal is working as designed — restore the matching snapshot instead of forcing it.

Stuck beyond that? The official release notes carry the canonical migration list, and the OpenClaw community on GitHub and Discord is fast on upgrade issues in release week.

Once you are stable on 2.0, the useful next question is not how to upgrade but how to operate: which permission mode each session should run in, what belongs in the credential store, and what your recovery plan looks like when an agent does something unexpected. That is the ground the OpenClaw Masterclass covers — permissions and sandboxing, security and incident response, across 15 chapters with lifetime updates so the curriculum tracks releases like this one.