doctor --fix removes stale plugin from plugins.allow/entries but leaves dangling channel reference, causing Gateway boot loop

[yidecode]

Summary

When a plugin directory is deleted manually (e.g. during a forced reinstall), openclaw doctor --fix correctly removes the stale entries from plugins.allow and plugins.entries, but does not clean up the corresponding channels.<plugin-id> entry. This leaves the config in an inconsistent state where a channel references a plugin that no longer exists.

Steps to Reproduce

1. Install a channel plugin (e.g. openclaw-weixin)
2. Try to upgrade it: openclaw plugins install @tencent-weixin/openclaw-weixin@2.1.8
3. Install fails with plugin already exists — manually delete the plugin directory: rm -rf ~/.openclaw/extensions/openclaw-weixin
4. Run openclaw doctor --fix --yes
5. Doctor removes plugins.allow: openclaw-weixin and plugins.entries.openclaw-weixin (stale), but leaves channels.openclaw-weixin intact
6. Now run openclaw plugins install @tencent-weixin/openclaw-weixin@2.1.8 — install succeeds
7. Restart Gateway → Gateway fails to start with Config validation failed: channels.openclaw-weixin: unknown channel id: openclaw-weixin
8. With KeepAlive: true in the LaunchAgent plist, launchd repeatedly restarts the Gateway, which repeatedly fails and exits — port is never released, leading to an EADDRINUSE boot loop

Root Cause

doctor --fix does not check channels.* for references to plugins that were removed from plugins.allow. The channel entry becomes a dangling reference that fails config validation at Gateway startup.

Expected Behavior

doctor --fix should either:

• Remove (or warn about) channels.<id> entries when the corresponding plugin is no longer in plugins.allow, or
• Treat the channel entry as authoritative and restore the plugin to plugins.allow instead of removing it

Environment

• OpenClaw: 2026.4.10
• OS: macOS 26.4 (arm64)
• Plugin: @tencent-weixin/openclaw-weixin 2.1.7 → 2.1.8
• Gateway service: LaunchAgent with KeepAlive: true

Workaround

Manually remove channels.<plugin-id> from openclaw.json before reinstalling the plugin, then restore it after install succeeds.

[martingarramon]

The root cause is in src/commands/doctor/shared/channel-doctor.ts:48-76. collectChannelDoctorStaleConfigMutations (line 116) calls listChannelDoctorEntries(collectConfiguredChannelIds(cfg)), which iterates every id under channels.* and tries to resolve a doctor adapter. For a deleted third-party plugin like openclaw-weixin, getChannelPlugin(id) at line 55 throws (caught, returns undefined), and getBundledChannelPlugin(id) at line 62 returns nothing because it's not a bundled channel. The flatMap produces an empty array for that id, so no ChannelDoctorEntry is created, cleanStaleConfig is never invoked for it, and the channels.openclaw-weixin key survives untouched.

The separate stale-plugin cleanup in stale-plugin-config.ts operates on plugins.allow and plugins.entries only (StalePluginSurface is typed as "allow" | "entries" at line 8). It has no awareness of channels.* — it scans cfg.plugins, not cfg.channels. So when it removes the stale plugin references, the corresponding channel entry is orphaned.

The fix likely belongs in listChannelDoctorEntries: when both getChannelPlugin and getBundledChannelPlugin return nothing for a configured channel id, the function should still emit a mutation that removes channels.<id> rather than silently skipping it. Alternatively, scanStalePluginConfig could be extended to cross-reference channels.* against the plugin registry. Note that #45374 and #59575 cover related plugin-pruning ground but neither addresses this specific channels.* orphan gap.

[clawsweeper]

Codex automated review: keeping this open.

Current main still appears to have the reported generic doctor repair gap. Stale plugin repair removes only plugins.allow and plugins.entries; channel stale cleanup only runs for channel ids that resolve to a doctor adapter, so a deleted third-party channel plugin can leave channels.<id> behind as an unknown, fatal config entry.

Best possible solution:

Keep this issue open and fix the generic doctor repair path. The likely implementation is to extend stale plugin/channel cleanup so openclaw doctor --fix removes or explicitly warns about channels.<id> entries that no longer correspond to a built-in channel or a discoverable plugin manifest channel, after confirming plugin discovery is clean. Add a regression test with a stale third-party plugin id such as openclaw-weixin present in plugins.allow, plugins.entries, and channels.<id>, then assert doctor repair leaves a valid, non-fatal config state.

What I checked:

• Issue discussion identifies the same code path: The provided discussion points to channel-doctor.ts skipping deleted third-party channel ids and stale-plugin-config.ts having no channels.* awareness. It also notes related Doctor: prune stale plugins and flag runtime drift #45374 and feat(plugins): add plugins clean command to remove stale plugin config refs #59575 do not cover this specific orphaned channel cleanup gap.
• Stale plugin repair is scoped to plugin config only: StalePluginSurface is only "allow" | "entries", and maybeRepairStalePluginConfig deletes stale ids only from those two plugin surfaces. There is no scan or mutation of cfg.channels. (src/commands/doctor/shared/stale-plugin-config.ts:8, 4878d3e059ce)
• Channel stale cleanup skips unresolved channel ids: listChannelDoctorEntries merges doctor adapters from read-only, loaded, setup, and bundled channel plugins, then continues when no adapter exists. collectChannelDoctorStaleConfigMutations only calls cleanStaleConfig on those emitted entries, so an orphaned third-party channels.openclaw-weixin entry produces no mutation. (src/commands/doctor/shared/channel-doctor.ts:196, 4878d3e059ce)
• Unknown channel ids remain fatal validation errors: Config validation builds allowed channels from built-ins and manifest-declared plugin channels; if a configured channel id is still unknown after registry discovery, it emits channels.<id>: unknown channel id: <id>. That matches the reported invalid Gateway startup state once the plugin manifest is gone. (src/config/validation.ts:969, 4878d3e059ce)
• Doctor sequencing does not close the gap after plugin pruning: The full doctor flow runs channel stale cleanup before the repair sequence, while the repair sequence later runs maybeRepairStalePluginConfig; because plugin pruning can remove plugins.allow/plugins.entries after channel cleanup has already skipped unresolved ids, no later step removes the now-dangling channels.<id> entry. (src/commands/doctor-config-flow.ts:167, 4878d3e059ce)
• Current tests do not cover channel orphan cleanup: The stale plugin helper tests cover detection and removal for plugins.allow and plugins.entries only, and searches for openclaw-weixin, stale channel cleanup, and unknown-channel repair found no regression test for removing channels.<plugin-id> when the plugin manifest is missing. (src/commands/doctor/shared/stale-plugin-config.test.ts:63, 4878d3e059ce)

Remaining risk / open question:

• A naive fix could delete valid channel configuration during transient plugin discovery failures; the repair should be gated on clean plugin discovery or clearly warn instead of mutating when discovery has errors.
• The repair must preserve shared channel keys such as channels.defaults and channels.modelByChannel, and should distinguish built-in channel ids from manifest-declared plugin channel ids.

Codex Review notes: model gpt-5.5, reasoning high; reviewed against 4878d3e059ce.

[steipete]

Fixed on main in edb3e84 (fix: clean stale plugin channel config).

What changed:

• openclaw doctor --fix now removes stale plugin ids from plugins.allow / plugins.entries and also removes the matching dangling channels.<id> config.
• It also cleans dependent agents.*.heartbeat.target and channels.modelByChannel.*.<id> entries for that missing channel plugin.
• The repair is still gated on healthy plugin discovery, so transient plugin discovery errors do not cause config deletion.
• Unknown channel typos without stale plugin/install evidence remain strict validation errors.

Validation run on Blacksmith Testbox tbx_01kq7821bmn92y4h5e8ywk6p43:

• pnpm test src/commands/doctor/shared/stale-plugin-config.test.ts src/commands/doctor/shared/preview-warnings.test.ts src/config/config.plugin-validation.test.ts
• pnpm check:changed

Closing as fixed.