Updates and rollbacks

After an update

Use when an update finishes but the Gateway is down, channels are empty, or model calls fail with 401s.

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

Look for:

• Update restart in openclaw status / openclaw status --all. Pending or failed handoffs include the next command to run.
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix under Channels: the channel config still exists, but plugin registration failed before the channel could load.
• Provider 401s after re-auth: openclaw doctor --fix checks for stale per-agent OAuth auth shadows and removes old copies so all agents resolve the current shared profile.

Prepared model runtime publication timeout

If startup reports prepared model runtime publication (...) timed out, the parenthesized detail identifies the pending stage and, during workspace preparation, its agent. Collect that error together with openclaw gateway status --deep and the startup logs.

An ambient credentials stage can be waiting for a plugin's external login check even when the Gateway process uses little CPU. For Claude CLI, run claude auth status --json as the Gateway user with the same environment. Startup shares this check across workspaces; a large roster should not launch one native-login subprocess per agent. A successful /health response alone does not establish that model runtime publication completed.

Split brain installs and newer config guard

Use when a gateway service unexpectedly stops after an update, or logs show one openclaw binary is older than the version that last wrote openclaw.json.

OpenClaw stamps config writes with meta.lastTouchedVersion. Read-only commands can inspect a config written by a newer OpenClaw, but process and service mutations refuse to run from an older binary. Blocked actions: gateway service start/stop/restart/uninstall, forced service reinstall, service-mode gateway startup, and gateway --force port cleanup.

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

Protocol mismatch after rollback

Use when logs keep printing protocol mismatch after a downgrade or rollback. An older Gateway is running, but a newer local client process is still reconnecting with a protocol range the older Gateway cannot speak.

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

Look for:

• protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> in Gateway logs.
• Established clients: in openclaw gateway status --deep or Gateway clients in openclaw doctor --deep: active TCP clients connected to the Gateway port, with PIDs and command lines when the OS allows it.
• A client process whose command line points at the newer OpenClaw install or wrapper you rolled back from.

Fix:

1. Stop or restart the stale OpenClaw client process shown by gateway status --deep.
2. Restart apps or wrappers that embed OpenClaw: local dashboards, editors, app-server helpers, or long-running openclaw logs --follow shells.
3. Re-run openclaw gateway status --deep or openclaw doctor --deep and confirm the stale client PID is gone.

Do not make an older Gateway accept a newer incompatible protocol. Protocol bumps protect the wire contract; rollback recovery is a process/version cleanup problem.