Back up the state directory before you upgrade: OpenClaw 2.0 migration, rollback and credential-hardening SOP

OpenClaw's previous stable release went quiet for nearly seven weeks. In the project's own cadence that is an abnormal signal: in the prior 230 days it shipped 106 versions, roughly one every two days. On 2026-08-31 at 03:30:51 UTC the answer landed: tag v2026.8.1, release name "OpenClaw 2026.8.1", Mac / Linux / Windows in one drop. This version had 933 contributors and merged 16,000+ PRs — about half of the project's entire historical PR count.

This article does not recap "what 2.0 released" — that is a separate OpenClaw 2.0 release writeup. This is for engineers already running OpenClaw: how to get an existing deployment up safely, how to roll back if it does not, and how to tighten credentials afterward. The whole piece answers one operational question: what exact order do you do things in, sitting at the machine this afternoon.

Boundary first: the operations here are based on the official release notes and blog. For specific paths, parameters, and plugin-internal interfaces, defer to the official release notes and the actual output of openclaw doctor.

Why this time you cannot blindly click update

Three reasons, any one of which turns "click auto-update then go get coffee" into an incident.

First, there are two breaking changes. One is the OpenProse migration: the built-in OpenProse plugin and the /prose command are removed; you must run openclaw doctor --fix to clear stale config, then reconnect via the upstream Agent Skill migration path. The other is the OpenAI route migration: codex/* and openai-codex/* model references, provider config, stored sessions, and automation routes all move to openai/*, and conflicts are not auto-resolved.

Second, the session storage format changed, and rollback is bounded. The upgrade migrates file-backed sessions and transcripts into SQLite; the cost is that the old version cannot read sessions created after the move to SQLite. See section nine.

Third, and most easily missed — the vendor itself expects the auto-update to fail. The release notes' update advice, verbatim:

"If the automatic update fails, use a local coding harness to help complete the update, diagnose any migration errors, and verify that the Gateway starts correctly. Back up your configuration and state before making changes."

In plain terms: if the auto-update fails, use a local coding harness to finish the update, diagnose migration errors, and confirm the Gateway starts correctly; back up configuration and state before you touch anything. That the publisher wrote this line is itself the signal, and it is this article's first principle.

Before upgrading: back up configuration and state

Know your backup target before backing up. Many get this wrong because they model OpenClaw as "a client on my computer."

The correct mental model: the Gateway is the service that holds ordinary session state, model credentials, permissions and durable work; the browser, CLI, connected devices and remote workers are merely different entry points to that Gateway.

That yields a direct conclusion: you back up the Gateway's configuration and state, not a single client. Exporting one client's config is backing up nothing.

Concrete steps:

1. Back up the entire state directory, not just config files. Use an OS-level copy that preserves timestamps and permissions:

# macOS / Linux: archive whole, preserve permissions and timestamps
# Replace <state-dir> with the actual path from `openclaw doctor` output or official docs
cp -a "<state-dir>" "<state-dir>.bak.$(date +%Y%m%d-%H%M%S)"

# Windows (PowerShell): mirror copy
# robocopy "<state-dir>" "<state-dir>.bak.20260831" /MIR /COPYALL

2. Verify the backup is recoverable. An unverified backup is no backup. At minimum, confirm a restored copy can start, or directly check that archived file counts and sizes match the source.

3. Record the current version and installed plugin list. On rollback you need to know where you came from — especially external plugins, because the deprecation deadline in section six lands on them.

4. Inventory the two breaking changes' blast radius. Search your repos, configs and scripts for /prose call sites and codex/* / openai-codex/* model references:

# Inventory codex route references (run inside managed projects and config dirs)
grep -rn "codex/\*\|openai-codex/\*\|codex/" --include="*.json" --include="*.toml" --include="*.yaml" --include="*.yml" --include="*.ts" --include="*.js" .

# Inventory /prose usage
grep -rn "/prose" .

This inventory is the work order for sections four and five, and the reference table for rollback in section nine. Starting the upgrade without it is disassembling an engine blindfolded.

Execute the upgrade in four steps: check, fix, restart, verify

The official path is four steps, in order:

1. Check the installation
2. Run the config and migration tool — openclaw doctor --fix
3. Restart the Gateway
4. Verify service health

# Step 2: run the config and migration tool
openclaw doctor --fix

One fact that must go into the runbook: your existing install does not automatically become 2.0. You must complete the local update, pass the checks, restart, and pass model-access verification before 2.0 is truly live. A changed version number is not a completed migration — many people think they are done here, then discover some automation broken the next day.

For auto-update failures, copy the official advice verbatim: use a local coding harness to diagnose and repair, to read migration errors, resolve conflicts, and confirm the Gateway starts — instead of guessing parameters yourself.

Handle the OpenProse migration: plugin and /prose gone, but files remain

This is the first breaking change (issue #128494, thanks @obviyus, @vincentkoc). Its impact has three layers, handled separately:

Layer one: the built-in OpenProse plugin and /prose command are removed. After upgrade, anything depending on /prose fails. You should have completed the inventory from section two and listed the hit locations.

Layer two: stale config must be cleared. Run openclaw doctor --fix to remove config entries pointing at the removed plugin. Leftover config is a common source of later startup errors.

Layer three: migrate to Agent Skill. The upstream path follows the Agent Skill migration; docs at https://docs.openclaw.ai/prose — follow that document, do not copy old wording from memory.

The most important line here too: your existing .prose source files are preserved. Files are not lost; only the invocation changes. So the right mindset is "assets to reconnect," not "assets gone." The backup in section two lets you proceed safely.

Handle the OpenAI route migration: four object types, manual conflict fixes

This is the second breaking change (thanks @vincentkoc), and the easiest to miss, because its blast radius spreads across four different places.

Use openclaw doctor --fix to migrate the following into openai/*:

• Model references: codex/* and openai-codex/* references
• Provider config
• Stored sessions
• Automation routes

Three things to watch when operating:

1. Check all four object types, not just config. Most people only change the model name in config files, missing stale old refs in stored sessions and automation routes. Those leaks surface days later — e.g. an automation silently failing at 3 a.m.

2. The migration preserves Codex runtime intent. This is a unification of routing and naming, not a semantic rewrite. The runtime intent you wanted is not erased.

3. Conflicts require manual operator fixes. Treat this as a hard constraint: openclaw doctor --fix will not decide conflicts for you. When it hits a conflict it stops and hands it to you. Do not guess — follow the official advice and let a local coding harness help diagnose, or compare against the inventory from section two line by line. Where the automation tool stays silent is exactly where a human must stand watch.

Handle the 2026-09-01 plugin SDK deprecation: the deadline is today

The most time-sensitive item, landing on external-plugin maintainers.

External plugins must migrate before the SDK removal gate:

• plugin-sdk-config-runtime-subpath → api.pluginConfig

The effective date is 2026-09-01 — today. If you maintain or depend on external plugins, this is the only item in this batch that "will definitely break if skipped, with no grace period."

Note: the release-notes entry is truncated; we have no fuller context. For the complete wording, defer to the official release notes and openclaw doctor output. You can pull the full GitHub release body to check yourself, searching for "Upcoming deprecations":

curl -s "https://api.github.com/repos/openclaw/openclaw/releases/latest"

If you also maintain plugins on other open-source agent projects, cross-check their interface-stability cadence; this site's OpenHuman open-source profile is another sample.

Post-upgrade verification checklist: four things, none skippable

After restarting the Gateway, do not pack up just because the process is up. Verify in order:

1. Gateway health: service healthy and responding. Step four requires verifying the service is healthy.
2. Session migration integrity: are historical sessions and transcripts fully migrated into SQLite? Spot-check a few old sessions open correctly.
3. Do automation routes still point at old refs? This is the high-frequency miss from section five; go through every automation route.
4. Do scheduled tasks still fire? Do not just look at config — wait one real trigger cycle, or trigger one manually.

Plus one more: model-access verification passes. It is the final determinant of "did this upgrade count," not optional.

Credential hardening: five things to enable actively after upgrade

2.0 brings a set of credential-governance capabilities, but they do not turn on automatically just because you upgraded — most need explicit enablement or configuration. The theory is expanded in our Agent credential and permission governance comparison; here are only the steps.

1. Enable Private credential requests. The agent requests credentials via a masked prompt; the value never enters chat or model context (issues #129670, #123216, #132122). This should be on by default: it turns "secret appears in conversation" from possible to impossible.

2. Configure the opt-in proxy's destination allowlist. When enabled, protected-secret substitution is limited to addresses you approved — the secret is substituted only into domains or addresses you authorized. This directly closes a real attack surface: the agent carrying the secret to another site.

3. Grant automation precise authorization (Approve recurring work once). Grant a precise operation, not a blanket one-time pass; after granting you can inspect or revoke anytime. The key mechanism: when the job or operation changes, re-approval is required (#129526, #131602). Make this the default posture for automation, not "open everything wide and sort it later."

4. Narrow access scope with roles. The Gateway uses roles to narrow access scope. Assign roles per person and per purpose; do not share one all-powerful identity.

5. Correct the Incognito misconception. Called out separately because it is the most common misuse: Incognito only keeps the transcript in memory until restart; it does not stop the provider or tools. It is not a privacy switch. Let an agent call external services with Incognito on and the request still goes out, the provider still sees it. If what you want is "no outbound," you need network-layer and permission-layer controls, not a switch called Incognito.

One more architectural dividend: under shared cloud sessions the Gateway proxies model requests, so provider credentials stay Gateway-side; a vanished remote worker can be restarted from the persistent Gateway state. That is both an availability win and another reason for "back up Gateway state" in section two.

Rollback plan: downgrade is possible, but bounded

This is the most important section to finish reading.

The upgrade migrates file-backed sessions and transcripts into SQLite. The downgrade path is bounded, with two edges you must distinguish:

Edge one: session visibility. The old file-backed version can restore archives that existed before migration, but cannot see sessions created after the move to SQLite. In plain terms: you upgrade to 2.0, use it for three days, decide it is wrong and go back to the old version — the sessions opened in those three days are invisible to the old version. They may not be lost, but your old version can do nothing with them.

Edge two: rolling back the whole state directory hits harder. If you take the blunt approach of "swap the whole state directory back to the old copy," the impact is not just sessions: approvals and delivery/dedup records roll back too, and some ratcheting channel credentials may need re-linking. That means rollback carries away permissions you granted and dedup state of messages already delivered — in automation, dedup rollback is a real, not theoretical, loss; duplicate delivery is not hypothetical.

So the conclusion must be stated without ambiguity: you can return to the old software, but do not assume new sessions or state changes follow automatically. Backup is not optional — it is your only exit.

Before rollback, mandatory actions: confirm the backup is recoverable; export key sessions created under the 2.0 state; know that approvals and dedup records will roll back; reserve time to re-link ratcheting channel credentials.

Copy-paste checklist

Before upgrade:

• Full backup of the Gateway's configuration and state (not a single client config)
• Backup verified recoverable
• Current version and installed plugin list recorded
• /prose call sites inventoried
• codex/* and openai-codex/* model-reference locations inventoried
• Confirmed whether external plugins need the 2026-09-01 SDK deprecation handled

During upgrade:

• On auto-update failure, followed official advice with a local coding harness for diagnosis
• openclaw doctor --fix ran with no unresolved conflicts
• Gateway restarted
• Model-access verification passed

After upgrade:

• Gateway service healthy
• Historical sessions and transcripts migrated completely
• .prose source files still present, invocation reconnected via Agent Skill migration path
• All four object types (model refs / provider config / stored sessions / automation routes) free of old refs
• Scheduled tasks verified by an actual trigger
• Masked credential requests enabled
• Proxy destination allowlist configured
• Automation switched to precise authorization, confirmed change triggers re-approval
• Roles narrowed
• Team informed Incognito is not a privacy switch

Seven pitfalls

1. Back up config files only, not the state directory. Sessions, permissions and dedup records live in state; config can be rewritten, state lost is gone.
2. Assume a changed version number means the upgrade finished. You must complete "local update → checks → restart → model-access verification."
3. Treat Incognito as a privacy switch. It only keeps the transcript in memory until restart; it does not stop the provider or tools.
4. Only change the model name in config, missing stored sessions and automation routes. Symptoms surface days later at 3 a.m.
5. Expect openclaw doctor --fix to resolve all conflicts. It will not. Conflicts are for the operator; the tool does not decide for you.
6. Assume the .prose file was deleted, then scramble for a backup. Files are preserved; only the invocation changed — follow the Agent Skill migration.
7. Assume rollback is lossless. Downgrade is bounded: new sessions after SQLite are invisible to the old version; a full rollback also takes approvals and delivery/dedup records back, and some ratcheting channel credentials need re-linking.

FAQ

Q1: Auto-update failed. What is the first step? A1: Confirm the backup exists — the official line is to back up configuration and state before changes. Then follow the official advice: use a local coding harness to finish the update, diagnose migration errors, and verify the Gateway starts. Do not guess parameters; specific errors defer to openclaw doctor output.

Q2: After upgrade the /prose command is gone. Are the .prose files I wrote still there? A2: Yes. This breaking change removes the built-in OpenProse plugin and the /prose command; your existing .prose source files are preserved. Run openclaw doctor --fix to clear stale config, then reconnect the invocation via the upstream Agent Skill migration path; docs at https://docs.openclaw.ai/prose.

Q3: openclaw doctor --fix reports a conflict. Can it resolve itself? A3: No. Conflicts require manual operator fixes; the tool will not decide for you. The right move is a local coding harness for diagnosis, or compare line by line against the codex/* / openai-codex/* inventory from before upgrade. The migration preserves Codex runtime intent, so conflicts are usually "which target ref," not semantic.

Q4: I roll back to the old version. Are sessions created after upgrade still there? A4: The old version cannot see them. Downgrade is bounded: the old file-backed version can restore archives that existed before migration, but not sessions created after the move to SQLite. A full state-directory rollback hits harder — approvals and delivery/dedup records roll back too, and some ratcheting channel credentials may need re-linking. Export newly produced key content before rollback.

Q5: With Incognito on, can the provider no longer see it? A5: No. Incognito keeps the transcript in memory until restart, but it does not stop the provider or tools. It is not a privacy switch. If what you need is "no outbound," that comes from network-layer and permission-layer controls, not this mode.

Sources

• OpenClaw official blog "OpenClaw 2.0, Accidentally": https://openclaw.ai/blog/openclaw-2-accidentally/
• GitHub release v2026.8.1 (published 2026-08-31T03:30:51Z, Mac / Linux / Windows)
• Update advice, OpenProse migration (#128494), OpenAI route migration, and Upcoming deprecations from the official release notes
• Upstream Agent Skill migration docs: https://docs.openclaw.ai/prose
• Same-site further reading: OpenClaw 2.0 release hotspot · OpenHuman open-source profile · Agent credential and permission governance comparison
• Note: the 2026-09-01 plugin SDK deprecation entry in the release notes is truncated; defer to the official release notes and openclaw doctor output for the complete wording.