What's new in OpenClaw 2.0, and should you upgrade yet?

What 2.0 actually is

The version number is still date-shaped; “2.0” is the name the project gave the release, and the project’s own write-up calls it accidental: work on simpler setup and a proper browser app grew until “doing that properly meant carrying the cleanup through the rest of OpenClaw until it became OpenClaw 2.0.” The scale is real. More than 16,000 pull requests went in, roughly half of every pull request ever merged into OpenClaw, from 933 contributors, 569 of them first-timers, over nearly seven weeks without a release from a project that had shipped 106 releases in the previous 230 days. The fixes for its first-day bugs arrived fast: 2026.8.2 the next day, and 2026.9.1 two days after that with another 1,186 pull requests behind it. The 2.x line is now the one that moves; each point release is a normal update, not a migration.

What you will notice

The web app. The Control UI is rebuilt. You can search past conversations by exact words and reopen the surrounding messages; rewind or fork a conversation from any earlier message and switch between the branches; follow a durable progress card through reloads; answer the agent’s questions through cards and buttons instead of prose; pin interactive widgets to a session dashboard; create goals without slash commands; and set up a fresh install through guided option cards (the project calls the guide “Custodian”). Themes and fonts are choosable, with four more themes added in 2026.8.2. The “new version available” reload now waits for the restarting Gateway instead of asking for a hard refresh, and since 2026.9.1 Mermaid diagrams render inside conversations.

Conversations no longer reset on their own. On 2026.7.1 the default was a fresh session every day at 04:00. On 2.0 the default is no automatic reset: the same session runs until you type /new or /reset, or configure session.reset yourself. Explicit daily or idle policies you already set are kept. The practical consequence is that context keeps growing until compaction, so a chat you never reset costs more per turn than it did. The session guide covers what a reset keeps and loses.

Sessions can run elsewhere. The work of a session can now be placed on your own paired hardware or on throwaway cloud machines leased on demand, while the Gateway stays the owner of the conversation and the workspace. Cloud sessions, nodes, and cloud workers get their own explainer, including the question the announcement raises: you still need a home for the Gateway.

Memory that works while you sleep. Three things are on by default and each has an off switch.“Grounded dreaming” runs background memory consolidation, promoting material into long-term memory and keeping a Dream Diary. Automatic self-learning captures reusable lessons and applies scanner-approved new skills on its own. Personal conversation recall pulls context from your own earlier private conversations with the same agent (groups and channels stay excluded). Each of these is a model call you did not ask for, so on a metered key expect a small, steady background spend.

Heartbeat alerts come to you. The heartbeat now delivers ambient alerts to a resolvable owner DM by default, where 2026.7.1 delivered nothing unless you configured a target. Expect unprompted messages on Telegram or wherever your owner identity lives when the agent decides something needs attention.

Models. Aliases and per-model settings are now separate from restrictions. Adding an entry to agents.defaults.models no longer limits what /model can pick; restrictions live in agents.defaults.modelPolicy.allow, with per-agent policies and provider wildcards. A fresh 2.0 install has no allowlist at all. A migrated install keeps whatever its old models map restricted, because doctor “migrates valid legacy restrictions without silently opening access.” The refusal message changes accordingly: an off-policy pick now fails with “not allowed by agents.defaults.modelPolicy.allow.” Changing model also asks whether the change applies to this session, this agent, or the shared default, and model lists are discovered live from providers instead of a built-in snapshot.

Credentials. The agent can ask you for a credential through a masked prompt in the Control UI without the value entering the chat or the model context, and a shared credential store in SQLite holds secret and environment entries. An optional 1Password broker resolves secrets from a service account.

Providers that moved out. BytePlus, ComfyUI, Mistral, NovitaAI, OpenCode, Synthetic, Volcengine, Vydra and Xiaomi, plus Cohere and Meta, DuckDuckGo search, Voyage embeddings and iMessage, are now separate official packages. If you use one, openclaw update repair or openclaw doctor --fix reinstalls it. Anything not on that list, OpenRouter included, is still bundled.

Smaller things you may still feel. A daily version check is on, with feature statistics as an opt-in that defaults off. Installing a plugin from an arbitrary executable source now needs --force; ClawHub shows its security-audit information before an install. External plugin authors had a deprecation gate on September 1, 2026 for old SDK import paths; if you only use plugins, that is not your problem. 2026.8.2 retired the ClawDock helper scripts in favour of plain Docker Compose and the CLI, so if your shell still sources them, that line goes.

The two breaking changes, and what doctor migrates

The release notes label two items breaking. First, OpenProse is removed: the bundled plugin and the /prose command are gone, doctor cleans the stale configuration, your .prose files are kept, and the upstream Agent Skill migration replaces it. Second, the codex/* and openai-codex/* model routes become openai/*: doctor rewrites model refs, provider config, stored sessions and automation routes, and flags conflicts for you to resolve. If you connected a ChatGPT subscription, this one touches you.

The change most people will actually hit is not labelled breaking. The session store moved to SQLite, by default at

~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite

The doctor reference is blunt about the consequence: “Gateway and local CLI startup do not import, restore, or rewrite legacy session JSON/JSONL files. When startup finds a legacy session store, it refuses readiness and prints a doctor --fix command.” And doctor is “the only owner for persistent file-to-SQLite migrations.” So any 2026.7.x install with history goes through one doctor run, full stop. The same run migrates the old models map into a modelPolicy, moves legacy main-session history to its named owner, upgrades the exec approvals format, folds a workspace TOOLS.md into AGENTS.md, migrates the cron store, and reinstalls any provider package that moved out.

What the Gateway does by itself on first start is narrower: safe, prompt-free config migrations, backed up into a five-slot openclaw.json.bak ring. Container images get a little more. When you swap the image but keep the mounted state, “the new gateway runs startup-safe upgrade migrations and plugin convergence before readiness,” and routine image upgrades are meant not to need a separate doctor pass. When startup cannot finish safely, “the gateway exits instead of reporting healthy,” which with a restart policy looks like a crash loop. The documented fix is to run the same image once with doctor as the command, against the same mounts:

docker run -it --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fix

The docs’ own upgrade sequence for an existing install is: stop the Gateway, back up its state, run openclaw doctor --fix, restart. The command has more jobs than this migration; what doctor actually does is its own guide.

The release-day bug, and where it stands

Issue #134036, filed on release day, was rated P1 and labelled crash-loop. The reporter upgraded 2026.7.1-2 to 2026.8.1 over SSH and ran openclaw doctor --fix, doctor --fix --force and doctor --repair --non-interactive without a TTY. Every variant printed the same advice to run doctor and skipped the 2.0 state migrations. The identical command under ssh -tt migrated immediately. In between, the Gateway refused to start with

Gateway failed to start: Legacy session store requires migration:
~/.openclaw/agents/main/sessions/sessions.json. Run 'openclaw doctor --fix'

and agent turns were refused with “Legacy workspace setup state requires migration for ~/.openclaw/workspace; run openclaw doctor --fix.” The fix merged the same day (pull request #134078, August 31) and the issue is closed; 2026.8.2 and 2026.9.1 both shipped after it. A second report from the same day, #134046, a circular failure on installs with more than one agent where doctor refused to migrate the legacy exec-approvals.json until agents.ownership was set, is closed too. If the version you are installing is 2026.8.1 itself, the bug is in it: install the current release instead.

What the episode leaves behind is a habit worth keeping. A server is exactly where doctor runs without a terminal: a deploy script, cron, ssh host "openclaw doctor --fix", docker compose exec -T. Give it one anyway (ssh -t host openclaw doctor --fix, or the -it in the docker run command above) and read the output: a run that migrated says so, with the database path and the before-and-after schema versions, and a run that only repeats “run openclaw doctor --fix” has done nothing.

Should you upgrade now?

Starting fresh: yes, install the current release. There is nothing to migrate, so none of the above applies to you, and the problems reported so far cluster around upgrading existing installs, the npm updater and the macOS app rather than fresh installs from the image.

An agent you depend on: the first-week advice was to wait for a patch. Two have shipped and the doctor bug is closed, so what remains is the ordinary care a migration deserves, plus the current state of the tracker. As this is written, the update path still has open P1 reports against 2026.9.1: one where an update started from inside a running agent kept the Gateway offline for about twenty minutes (#137580, September 3), and one where doctor left legacy Discord owner identities unresolved after the upgrade, so owner-only commands failed (#137749, September 4). Neither touches a fresh install; both are the kind of thing to read about before the day you pick. Nothing on 2026.7.1 stops working because 2.0 exists; the only thing you will see until you move is the update banner naming a newer version. Read the Fixes section of the release notes for anything that affects your setup specifically. A security fix that applies to you moves the date forward, and nothing else does.

On Docker: the 2.x images have reached ghcr the same day as each npm release, so the July wait for a patched image has not repeated. Pin the version tag you are moving to, run the doctor recipe above against the same mounts, then start the container on its default command. Checking which channel you actually install from tells you what is current.

When you do it: back up the state directory first, stop the Gateway, run doctor in a real terminal, restart, then send the agent a real message through a real channel and check that history and channels came back. Know the way back before you need it: for an older, file-backed version to see your history again, the archived transcripts have to be restored first:

openclaw doctor --session-sqlite restore --session-sqlite-all-agents

Sessions created after the SQLite switch exist only in SQLite, so the older version will not show them.