openclaw - 💡(How to fix) Fix Protocol mismatch error after updating from 2026.5.7 to 2026.5.12 — Gateway appears offline to users

Bug Description

During a routine update from OpenClaw v2026.5.7 to v2026.5.12 (via gateway update.run), the Gateway failed to restart cleanly with a protocol mismatch error, causing the Gateway to appear offline to users even though it eventually restarted successfully.

Steps to Reproduce

1. Run openclaw gateway update.run (or gateway action=update.run)
2. Observe the update process:
   • NPM packages installed successfully (439 packages in 19s)
   • Global install swap completed (openclaw replaced)
   • Doctor checks ran and applied config changes
   • Config file backed up (~/.openclaw/openclaw.json -> ~/.openclaw/openclaw.json.bak)
   • Gateway restart signal sent (SIGUSR1)
3. Immediately after the restart signal, observe the error:

   gateway connect failed: GatewayClientRequestError: protocol mismatch

4. The user-facing Control UI becomes unreachable for a brief period
5. After a short delay (a few seconds), the Gateway becomes reachable again

Expected Behavior

• The update process should complete without leaving the Gateway in a broken state
• If a protocol mismatch occurs after a config update, the Gateway should either: (a) gracefully restart with the new protocol, or (b) roll back to the previous config and report a clear error
• The protocol mismatch error should be expanded to indicate whether it is transient and self-recovering, or whether user action is required

Actual Behavior

1. The update appears to succeed (gateway update.run returns ok: true)
2. The Gateway process is running (state: active in launchctl)
3. But the client cannot connect: protocol mismatch error is logged
4. The Gateway does recover and becomes reachable again after a few seconds (confirmed by subsequent health checks)
5. The issue is that the transition state between old config and new config is not handled gracefully

Impact

• Users who see this error during an update may incorrectly conclude the Gateway has crashed
• Users may attempt to manually restart (openclaw gateway stop/start), reinstall, or roll back the config — potentially making the situation worse
• The ambiguous error message leaves users uncertain about whether the system will recover on its own

Environment

• OpenClaw version: was 2026.5.7, updated to 2026.5.12
• Platform: macOS (Darwin 26.3, ARM64)
• Node: v22.22.2
• Gateway: local, running via LaunchAgent
• Config path: ~/.openclaw/openclaw.json
• Config SHA before update: 7815b74e917a3853c15e8c8d07d38bed2f14bea07a7f961e3b7e31af347b5ca9
• Config SHA after update: 0b3f18d957bd65ae5a0199a3349c1703c57db71cb726d15cc2757f2ea535341f

Suggested Fix

1. The update.run command should verify Gateway is fully reachable with the new config before reporting success, rather than assuming the SIGUSR1 restart is sufficient.
2. If a protocol mismatch is detected post-restart, the update process should automatically roll back to the previous config (~/.openclaw/openclaw.json.bak) and report a clear error message with recovery steps.
3. The ambiguous protocol mismatch error message should be expanded to indicate whether this is transient and the Gateway will recover automatically, or whether user action is required.