OpenClaw Upgrade: The Safer Path I Wish I Had Followed

I recently went through another OpenClaw upgrade cycle and hit enough sharp edges that it was worth writing down a cleaner process.

This is the version I would use next time if I wanted the highest chance of upgrading successfully without getting trapped in a long recovery loop.

The short version is:

back up everything first
upgrade second
verify the gateway before touching anything else
verify plugins separately
avoid known bad versions
expect local plugin fixes to be fragile unless upstream ships a proper update

1. Back up first, or do not upgrade yet

This is the one step I would not skip.

At the moment, OpenClaw upgrades are not guaranteed to be fully backward compatible, especially around:

openclaw.json
agent state and memory
plugin state

So before doing anything else, create a dated backup:

cp -r ~/.openclaw ~/.openclaw-2026.3.12

My recommendation:

use a backup directory with a date in the name
keep one backup per upgrade attempt
do not overwrite the previous one

That backup is your rollback path. If the upgrade damages config, plugin state, or local fixes, you will want a clean copy more than you will want a clever workaround.

2. Run the upgrade

The official command is straightforward:

openclaw update

In practice this will pull the new version and update plugins.

That sounds simple, but it also means you are changing both the core system and the extension layer in one move. That is why I treat the next verification steps as mandatory rather than optional.

3. Verify the main service before debugging anything else

After the upgrade, the first question is not whether your favorite plugin still works.

The first question is whether the main OpenClaw service is healthy.

Start with:

openclaw doctor

If it reports issues, try:

openclaw doctor --fix

And if you do not want to manually interpret the entire repair flow, one of the more practical OpenClaw patterns is simply to ask OpenClaw to repair itself from the dashboard or chat:

gateway has a problem, help me fix it

If the dashboard is also broken, fall back to the terminal UI:

openclaw tui

The main point here is sequencing.

Do not spend an hour debugging plugins if the gateway itself is already unhealthy.

4. Check plugins separately

A lot of upgrade failures look like “OpenClaw is broken” when the real problem is narrower: the core service is fine, but one or more plugins are not.

So after checking the main service, run:

openclaw plugins doctor

If that reports problems, my practical advice is the same:

plugins have a problem, help me fix them

That may sound lazy, but in this case it is often the fastest path. Plugin failures are frequently caused by compatibility drift, package issues, or state that OpenClaw itself can diagnose more directly than you can from a cold start.

5. Avoid the bad release

One version is especially worth calling out:

do not use 2026.2.22

That release caused enough trouble that the most visible issue for me was simple: the dashboard UI would not open at all.

If you need a known better option from that window, I would recommend:

2026.2.23-1

That version felt materially more stable.

Before deciding to upgrade at all, I would also check the issue tracker for openclaw/openclaw.

That is usually the fastest way to see whether a new release is causing broad failures in the wild, especially around the dashboard, gateway, channels, or plugin compatibility.

So my practical rule now is:

check openclaw/openclaw issues first
skip releases that are already generating breakage reports
prefer the safer patch release if one already exists

If you are reading this much later, the more general rule still holds: if one release is actively breaking the UI or gateway, do not try to be heroic about it. Move to the safer patch release or wait for the next one.

6. The WeChat plugin was the biggest upgrade trap

The slowest part of this upgrade round was not the OpenClaw core.

It was the WeChat plugin: openclaw-weixin, used by ClawBot.

The plugin had not yet shipped an updated version compatible with the current SDK migration, so after the OpenClaw upgrade it effectively stopped working. I ended up repairing it locally and keeping notes on every change.

If you are willing to wait, the cleanest outcome is still an upstream plugin release.

Before patching files by hand, I would first ask OpenClaw to fix the plugin issue for you.

In practice, that means telling it the plugin is broken and giving it enough context to work from. You can even paste the relevant part of this post directly into OpenClaw and ask it to apply the repair.

If you are not willing to wait, here is the condensed version of what actually had to be fixed.

7. Why `openclaw-weixin` broke

The plugin version I was using, v1.0.3, failed at compile time against OpenClaw SDK 2026.3.23.

The root issue was an SDK migration:

the old bundled plugin SDK layout changed
public imports moved to openclaw/plugin-sdk/* subpaths
some previously available helpers were removed entirely

So the plugin was not just “a little out of date.” It was compiled against the wrong SDK surface.

One representative runtime failure was:

TypeError: (0, _pluginSdk.resolvePreferredOpenClawTmpDir) is not a function

That error was a symptom of the larger migration mismatch.

8. What I changed to recover the plugin locally

The repair work fell into a few categories.

Redirect SDK imports

The plugin was importing symbols from openclaw/plugin-sdk that now lived in specific subpaths.

I had to redirect six imports, including moves like:

normalizeAccountId -> openclaw/plugin-sdk/account-id
stripMarkdown -> openclaw/plugin-sdk/text-runtime
createTypingCallbacks -> openclaw/plugin-sdk/channel-runtime
command authorization helpers -> openclaw/plugin-sdk/command-auth
buildChannelConfigSchema -> openclaw/plugin-sdk/channel-config-schema

Replace removed SDK helpers

resolvePreferredOpenClawTmpDir no longer existed, so I replaced it with os.tmpdir() in the places that needed temporary file paths.

That affected outbound media handling, logging, message processing, and log upload.

Recreate missing lock behavior locally

The plugin imported withFileLock, which was also gone from the SDK.

To recover that behavior, I implemented a local inline version with the same basic signature and retry or stale-lock semantics the plugin expected.

Add the missing dependency

The plugin referenced silk-wasm without declaring it explicitly.

So I installed it in the plugin directory:

cd ~/.openclaw/extensions/openclaw-weixin
npm install silk-wasm

Point the package at built output

The plugin package.json entry point was set to ./index.ts, which was a bad fit for reliable gateway hot reload.

I changed it to:

./dist/index.js

That made the gateway load the compiled output instead of bouncing back into the broken source entry path.

Relax TypeScript strictness for compatibility

I added a tsconfig.json with:

exactOptionalPropertyTypes: false
skipLibCheck: true

The plugin had a large number of strict optional type mismatches against the new SDK types. In this case those were compatibility noise rather than meaningful runtime defects, so suppressing them was the pragmatic choice for a third-party plugin patch.

9. Prevent OpenClaw from overwriting the fix

This turned out to be one of the most important details.

OpenClaw was configured to reinstall the plugin from npm on restart through plugins.installs, which meant every local fix could be wiped out automatically.

So I removed that install entry:

openclaw config unset plugins.installs.openclaw-weixin

Without that step, the rest of the repair work was not durable.

That is also the reason I strongly recommend backups before every upgrade. Local plugin patches are real state, and OpenClaw can overwrite them if you are not paying attention.

10. Files I ended up modifying

These were the local plugin files touched during the repair:

~/.openclaw/extensions/openclaw-weixin/src/channel.ts
~/.openclaw/extensions/openclaw-weixin/src/auth/accounts.ts
~/.openclaw/extensions/openclaw-weixin/src/auth/pairing.ts
~/.openclaw/extensions/openclaw-weixin/src/messaging/send.ts
~/.openclaw/extensions/openclaw-weixin/src/messaging/process-message.ts
~/.openclaw/extensions/openclaw-weixin/src/util/logger.ts
~/.openclaw/extensions/openclaw-weixin/src/log-upload.ts
~/.openclaw/extensions/openclaw-weixin/index.ts
~/.openclaw/extensions/openclaw-weixin/package.json
~/.openclaw/extensions/openclaw-weixin/tsconfig.json

If your local copy differs, do not copy these changes blindly. Use them as a map for where the incompatibilities are likely to live.

11. The upgrade flow I would actually follow next time

If I were doing this again, I would reduce the whole process to this:

Back up ~/.openclaw to a dated directory.
Run openclaw update.
Run openclaw doctor.
If needed, run openclaw doctor --fix.
Run openclaw plugins doctor.
If a plugin breaks, ask OpenClaw to repair it before manually patching files. If needed, paste this post directly into OpenClaw as repair context.
Avoid known bad releases like 2026.2.22.
If you depend on openclaw-weixin, assume you may need a temporary local patch until maintainers ship a compatible release.
Remove plugins.installs.openclaw-weixin if automatic reinstalls would overwrite your local repair.

That is not a glamorous workflow, but it is a workable one.

Right now, the safest mindset for OpenClaw upgrades is not “one command and done.”

It is “upgrade carefully, verify in layers, and keep a rollback path.”

References

The ideas in this post are mine. OpenClaw and Codex helped me write it.