OpenClaw 2026.4.5 post-update migration bug report draft

Title

2026.4.5 post-update recovery can leave launchd gateway token drift after config migration repair when token is already SecretRef-managed

Summary

Updating from 2026.3.31 to 2026.4.5 succeeded at the npm/package level, but the runtime was left in a partially migrated state on macOS. There were two separate post-update problems:

1. 2026.4.5 correctly rejected legacy Discord channel config keys using channels.discord.accounts.<id>.guilds.<id>.channels.<id>.allow instead of enabled, which blocked gateway startup until openclaw doctor --fix --non-interactive rewrote them.
2. After recovery, the LaunchAgent plist still embedded OPENCLAW_GATEWAY_TOKEN, even though gateway.auth.token was already being resolved correctly from the global env file via SecretRef or env substitution. That left service metadata drift and triggered another cleanup/reload cycle.

Environment

• macOS LaunchAgent install
• OpenClaw upgraded from 2026.3.31 to 2026.4.5
• gateway config path: ~/.openclaw/openclaw.json
• gateway token sourced from ~/.openclaw/.env
• gateway healthy after final cleanup, RPC probe ok

Exact observed failures

First outage, config migration drift

Gateway and CLI startup failed with invalid config after update. Representative error:

Invalid config at /Users/openclaw/.openclaw/openclaw.json:
channels.discord.accounts: channels.discord.accounts.<id>.guilds.<id>.channels.<id>.allow is legacy; use channels.discord.accounts.<id>.guilds.<id>.channels.<id>.enabled instead. Run "openclaw doctor --fix".
Gateway aborted: config is invalid.

There was also a temporary service mismatch warning during the same window:

Gateway service entrypoint does not match the current install.
(/opt/homebrew/lib/node_modules/openclaw/dist/entry.js -> /opt/homebrew/lib/node_modules/openclaw/dist/index.js)

Second outage, launchd token drift cleanup

After config migration repair, runtime was healthy, but the LaunchAgent still embedded OPENCLAW_GATEWAY_TOKEN, even though token resolution from the global env file was already correct. Cleaning up that duplicated token state caused a second brief outage during launchd reload.

Recovery path that worked

1. Confirmed legacy Discord channel allow keys were still physically present in openclaw.json.
2. Backed up the config.
3. Ran:

openclaw doctor --fix --non-interactive

1. Verified doctor rewrote channel-level Discord keys from allow to enabled and restarted the LaunchAgent.
2. Verified no legacy Discord channel allow keys remained.
3. Verified gateway recovery with:

openclaw gateway status --deep
openclaw status

1. Removed duplicated OPENCLAW_GATEWAY_TOKEN from the LaunchAgent plist, keeping token sourcing only in ~/.openclaw/.env.
2. Revalidated healthy runtime, RPC probe, loaded/running service, and no remaining token embedding in the plist.

Expected behavior

• openclaw doctor --fix should migrate legacy Discord channel keys cleanly, which it did.
• openclaw gateway install and openclaw doctor --fix should not rehydrate or preserve OPENCLAW_GATEWAY_TOKEN in launchd metadata when gateway.auth.token is already managed through SecretRef or env-based resolution from the global env file.
• After recovery, the LaunchAgent should reflect the canonical token source, not duplicate it.

Actual behavior

• Config migration required a doctor repair after update, which is acceptable.
• Recovery left a second drift surface in launchd metadata, causing another cleanup pass and another outage window before reaching a truly clean end-state.

Why this matters

This creates a misleading recovery state where:

• the gateway is healthy again
• RPC/status checks pass
• but service metadata is still out of policy and can trigger another maintenance or outage window during cleanup

It is especially confusing because the runtime token source is already correct, so the remaining drift lives only in launchd metadata.

Suggested product fix

When gateway.auth.token is already resolved from the global env file or SecretRef-managed env path:

• openclaw gateway install
• openclaw doctor --fix

should avoid embedding OPENCLAW_GATEWAY_TOKEN into the LaunchAgent plist.

A smaller fallback fix would be to detect this state and emit an explicit message like:

Gateway token is already env-managed; skipping LaunchAgent token embedding.

Final verified end-state

• gateway healthy
• RPC probe ok
• service loaded/running
• no legacy Discord channel allow keys remain
• LaunchAgent no longer embeds OPENCLAW_GATEWAY_TOKEN