PR #53944: fix(gateway): pin channel registry at startup to survive registry swaps

• Repository: openclaw/openclaw
• Author: affsantos
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/53944

Description (problem / solution / changelog)

Summary

• Problem: getChannelPlugin() returns undefined after a runtime registry swap, causing Channel is unavailable: <channel> errors on all outbound message delivery — the message tool, subagent completion announces, and cron delivery. The channel is known (isKnownChannel() passes via the hardcoded CHANNEL_IDS array) but the plugin backing it is gone from the live registry.
• Why it matters: On a production Slack gateway, upgrading to 2026.3.22 introduced 38 Channel is unavailable: slack errors/day and 72 subagent announce failures/day — up from zero on the previous version. Reproduced and confirmed still present on 2026.3.23-2. Users see dropped replies and undelivered subagent results with no feedback. The issue affects all channels (Slack, Telegram, WhatsApp, Discord) — see Related Issues below.
• Root cause: Non-primary loadOpenClawPlugins() calls (config-schema reads, provider registry lookups, maybeBootstrapChannelPlugin fallback) can replace the active plugin registry via setActivePluginRegistry(). The replacement registry may have a different channel plugin set — or none at all — because it was built with different loader options. getChannelPlugin() in channels/plugins/registry.ts resolves against the live requireActivePluginRegistry(), so it immediately loses access to the channels that were present at gateway boot.
• What changed: Added a pinned channel registry (3 new functions in runtime.ts) mirroring the existing pinActivePluginHttpRouteRegistry pattern. The channel registry is pinned at gateway startup in server-runtime-state.ts and released on shutdown. resolveCachedChannelPlugins() now reads from requireActivePluginChannelRegistry() instead of requireActivePluginRegistry(), so channel resolution is immune to mid-flight registry swaps.
• What did NOT change (scope boundary): No changes to plugin loading, config reload, channel setup/teardown, message delivery pipeline, or the outbound channel resolution fallback chain. The resolveOutboundChannelPlugin bootstrap path still works as before — it just no longer needs to fire because the pinned registry already has the channels.

🤖 AI-assisted

• Marked as AI-assisted
• Degree of testing: fully tested (7 new tests + 613 existing channel/outbound/plugin tests pass)
• I understand what the code does
• Bot review conversations will be resolved

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related #48790 (underlying tracking issue for channel registry instability)
• Related #53117 (Telegram: Channel is unavailable regression in 2026.3.22)
• Related #53879 (Telegram: file upload fails with Channel is unavailable in 2026.3.23-2)
• Related #53769 (Slack: cron delivery failing with Unsupported channel: slack)
• Related #53204 (subagent announce retry blocks agent session for ~6 min on channel errors)
• Related #38055 (subagent completion announce permanently lost when channel unavailable)
• Related #38457 (Slack Socket Mode: channel_id not passed to tool context)

User-visible / Behavior Changes

Channel plugins registered at gateway startup are no longer evicted by subsequent plugin registry swaps. The message tool, subagent announces, cron delivery, and all other outbound paths that resolve channels via getChannelPlugin() will consistently find the channel plugin as long as the gateway is running.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Linux (GCE, Debian 12) / macOS
• Runtime: Node 22
• OpenClaw: 2026.3.22 through 2026.3.23-2 (confirmed on both)
• Channel: Slack (Socket Mode), also affects Telegram, WhatsApp, Discord

Steps

1. Start a gateway with Slack (or any channel) enabled
2. Trigger a non-primary plugin registry load (e.g., Control UI fetches config schema, or a subagent spawns and bootstraps plugins)
3. Send a message to the agent, or have a subagent complete and try to announce

Expected

• Channel plugin is found, message is delivered

Actual (before fix)

• getChannelPlugin("slack") returns undefined
• [tools] message failed: Channel is unavailable: slack
• Subagent completion direct announce failed: Error: Unknown channel: slack
• After 3 retries with exponential backoff, the announce is permanently dropped

Evidence from production

Before (2026.3.22, no pin) — 7-day daily error count:

Mon: 0    Thu: 0    Sun: 20
Tue: 0    Fri: 0    Mon: 38
Wed: 0    Sat: 0
# First error appeared Sunday 15:43 UTC — immediately after 2026.3.22 upgrade

Log pattern (cascading announce failures):

12:35:38 [ws] res ✗ agent errorCode=UNAVAILABLE errorMessage=Error: Unknown channel: slack
12:35:38 Subagent completion direct announce failed for run <id>: Error: Unknown channel: slack
12:35:40 Subagent completion direct announce failed for run <id>: Error: Unknown channel: slack  # retry 2
12:35:44 Subagent completion direct announce failed for run <id>: Error: Unknown channel: slack  # retry 3
# → permanently lost, parent session never notified

Affected session types:

• slack:channel:* — channel thread replies
• slack:direct:* — DM replies
• subagent:* — subagent completion announces
• openai:* — MCP/API sessions attempting Slack delivery

Tests

7 new tests covering pin/release/swap lifecycle:

✓ returns the active registry when not pinned
✓ preserves pinned channel registry across setActivePluginRegistry calls
✓ updates channel registry on swap when not pinned
✓ release restores live-tracking behavior
✓ release is a no-op when the pinned registry does not match
✓ requireActivePluginChannelRegistry creates a registry when none exists
✓ resetPluginRuntimeStateForTest clears channel pin

Full test run: 7 new + 613 existing channel/outbound/plugin tests pass.

Co-Authored: Mário Sousa (@mariosousa-finn)

Changed files

• src/channels/plugins/registry.ts (modified, +2/-2)
• src/gateway/server-runtime-state.ts (modified, +18/-1)
• src/gateway/server.impl.ts (modified, +574/-503)
• src/gateway/server.minimal-channel-pin.test.ts (added, +57/-0)
• src/plugins/runtime.channel-pin.test.ts (added, +118/-0)
• src/plugins/runtime.ts (modified, +55/-0)