OpenClaw 2026.8.1 upgrade guide: migrate OpenProse and Codex routes safely

OpenClaw v2026.8.1, released August 31, 2026 and described by its maintainers as “OpenClaw 2.0,” adds richer conversation, session, dashboard, credential, and automation controls. It also contains two breaking migrations that matter before any feature tour: bundled OpenProse is gone, and shipped legacy Codex routes move under the openai/* provider namespace.

After these migrations pass, continue with the OpenClaw v2026.8.2 upgrade guide for the changed session-visibility default, Linux desktop packages, Gateway recovery, and rollback rehearsal.

Bottom line: take a supported backup, preserve the original offline, and rehearse openclaw doctor --fix on a disconnected copy. Do not reconnect channels, workers, or a production Gateway until you have reviewed the diff, exercised the health gate, and restored the backup successfully.

What is verified, and what is a vendor claim

The accompanying clean-room upgrade packet fetched the exact npm artifact without installing plugins or using credentials. The registry reported openclaw@2026.8.1, npm integrity sha512-bSaFeaDFnQH/bU1vgKMac6eHkHHPHG0C/uwduXGI3eIS3lyiYSwmDU5ehhBUUhlPeV85tL5/KVwmoH48nX1tWw==, and the downloaded tarball produced SHA-256 43c4b1f81afcd50244c85bcb5686fa6e39f0da6a5941735811b58064b7e0ca10.

Claim	Evidence status	What it means
Exact npm artifact	Observed	Package version, registry integrity, tarball size, and locally calculated hashes were recorded.
OpenProse and route migration behavior	Maintainer-documented; fixture prepared	The packet models both legacy surfaces, but it did not run Doctor and does not present its expected diff as captured output.
Gateway health and rollback	Unmeasured	No live Gateway was started and no live state was restored. The packet rejects a fabricated pass.
Conversation search, progress cards, questions, widgets, and reusable automation grants	Vendor claims	These are release-note capabilities, not results independently exercised for this article.

That distinction is important. A checksum proves which archive was downloaded; it does not prove that your database, plugins, channels, models, or Gateway survive the upgrade.

The two breaking migrations

1. Bundled OpenProse and /prose are removed

The release removes the bundled OpenProse plugin and its /prose command. The prescribed cleanup is openclaw doctor --fix, followed by migration to the upstream Agent Skill. Existing .prose source files are not supposed to be deleted as part of that instruction: preserve them, inventory them before the upgrade, and convert their workflow deliberately.

Treat this as two separate jobs:

1. let Doctor detect and clean stale bundled-plugin configuration;
2. replace every automation, prompt, shortcut, or runbook that invokes /prose with the upstream skill’s supported workflow.

Do not mark the migration complete because the warning disappeared. Pass only when every .prose file has the same hash as before, each caller has an owned replacement, and a disposable representative workflow produces an inspected result.

2. codex/* and openai-codex/* become openai/*

The release directs operators to use openclaw doctor --fix to migrate shipped model references, provider configuration, stored sessions, and automation routes from codex/* and openai-codex/* to openai/*. The maintainer says this retains Codex runtime intent and flags conflicts for operator repair.

That last clause is the safety boundary. Two old provider blocks can contain different endpoints, credentials, or defaults; flattening both into openai is not always mechanically decidable. Search the backup for both prefixes, inspect config plus durable sessions and automations, and resolve every reported conflict. Never paste credentials into a diff or support log.

SDK notices are upcoming gates, not removals in 2026.8.1

The August 31 release notes label several external-plugin migrations as upcoming deprecations beginning September 1. They are not removals in this release. Plugin authors should move away from broad compatibility subpaths before their documented gate:

• plugin-sdk/config-runtime callers should use api.pluginConfig or focused config mutation, snapshot, and contract imports;
• channel reply-pipeline, lifecycle, and message helpers move to focused channel inbound/outbound surfaces;
• plugin-sdk/infra-runtime helpers move to the matching focused runtime subpath.

The SDK migration guide is the authority for per-helper mappings and compatibility conditions. It explains that a date can begin review without itself authorizing deletion, while some removals depend on a named SDK-major gate or a clean published-plugin reader sweep. Audit now, but do not write “2026.8.1 removed these SDK paths” in an incident report.

Official provider packages still require trust review

The release offers official packages for providers including BytePlus, Cohere, ComfyUI, Meta, Mistral, NovitaAI, OpenCode, Synthetic, Volcengine, Vydra, Xiaomi, Voyage embeddings, DuckDuckGo search, and iMessage. Missing configured packages can be recovered through the documented update, Doctor, or explicit install flow; OpenCode Go remains bundled.

“Official” is provenance, not a sandbox. A plugin runs code and may request provider, network, filesystem, secret, tool, or Gateway capabilities. Pin the exact package, confirm it is named in OpenClaw’s official inventory, inspect its manifest and dependencies, review requested capabilities against the workload, install into a disposable home, then restart and test the Gateway. Do not enable every package merely because onboarding lists it, and do not substitute an similarly named registry package.

Session modes and team roles are controls, not hostile-tenant isolation

The permission-mode guide defines deny, allowlist, ask, auto, and full host-exec modes. These control how a session gets authority. They do not decide where execution happens, and harness-level permissions can add another layer. Verify the effective policy rather than trusting a UI label; full is appropriate only for a deliberately trusted host and session.

Team Gateways can bind authenticated profiles to operator roles, constrain agents and participation, and require per-creator sandboxes. Those are useful least-privilege controls. OpenClaw’s multi-user documentation is nevertheless explicit that people operating the same agent are trusted: ownership, participant history, presence, and sidebar filtering are not security boundaries. If users must be unable to reach one another’s sessions, files, tools, or credentials, separate the agent and, when needed, the Gateway or host trust boundary.

Masked credentials: what protection does and does not mean

The release adds private credential requests: an agent can ask through a masked prompt so the value does not enter chat or model context, with an opt-in proxy restricting protected-secret substitution to approved destinations. This is materially better than asking a user to paste a token into chat.

It does not make a secret harmless. The destination still receives the resolved credential, the configured tool or plugin still operates inside its capability boundary, and the logging guide calls redaction best-effort rather than universal. Registered secrets and recognized credential forms are masked across several text surfaces, but arbitrary opaque values, identifiers, and binary payloads are not guaranteed to be caught. Use a fake token for tests, register real secrets through the supported store, restrict proxy destinations, and rotate any value that entered chat, a prompt, source control, or an unreviewed log.

A safe upgrade and rollback gate

1. Record the starting OpenClaw version, Node/package manager, install channel, plugin inventory, model routes, session and automation inventory, and current documented health result.
2. Create a supported backup and record its checksum and permissions. Keep the original home and backup offline.
3. Verify the exact 2026.8.1 artifact against the GitHub release and npm version.
4. Clone the backup into a disposable home with channels, cloud workers, scheduled delivery, and real provider calls disabled.
5. Inventory .prose, /prose, openprose, codex/, and openai-codex/ references. Run the exact installed version’s Doctor preview/help before authorizing fixes.
6. Run openclaw doctor --fix, retain a sanitized transcript, inspect conflicts, and compare config, sessions, automations, plugin ownership, and source-file hashes.
7. Start only a loopback test Gateway. Run the documented health check, one fake-data session under the intended permission mode, and any reviewed plugin smoke tests.
8. Restore the pre-upgrade backup using the supported procedure and compatible version. Prove the restored inventory and health match the baseline before attempting promotion.

Safe rollback is restoration, not merely reinstalling an older npm package over newly migrated state. Preserve the backup until production has passed its observation window. If rollback fails, stop; do not reconnect messaging channels while trying successive repair commands against the only copy.

Sources and packet

• OpenClaw 2026.8.1 release notes
• GitHub v2026.8.1 release
• Plugin SDK migration guide
• Doctor documentation
• Permission modes
• Operator roles and scopes
• Multi-user trust boundary
• Logging and redaction
• Reproducible clean-room packet

The packet’s artifact check passed. Doctor, Gateway health, provider execution, and live rollback remain explicitly unmeasured; no conclusion in this article upgrades those absent tests into evidence.

Put this to work

Separate release-note claims, artifact evidence, and behavior you have actually tested.

Try

Rehearse `doctor --fix` only against a disconnected backup copy and inspect every config and session change.

Prove it worked

Record the exact package checksum, before/after inventories, loopback health, and a successful restore before promotion.

Where it can pay

A documented, reversible OpenClaw upgrade is more valuable than an unverified feature summary.

Keep in view

• Conversation search, durable progress cards, interactive questions, dashboards, credential requests, and reusable automation permissions headline the release.
• Bundled OpenProse and `/prose` are removed; `.prose` source files stay yours but need conversion to the upstream Agent Skill.
• Legacy `codex/*` and `openai-codex/*` routes migrate to `openai/*`, with conflicts left for operator repair.

Learn the workflow: comparing OpenClaw with other agent platforms →