fix(channels): stop unavailable targets repeating plugin scans (#100377)

xialonglee · steipete · web-flow · commit 585914fcd510 · 2026-07-11T01:29:33.000-07:00
* fix(channels): suppress repeated failed bootstrap

Co-authored-by: Peter Lee &lt;li.xialong@xydigit.com&gt;

* docs(changelog): credit recent fixes

---------

Co-authored-by: Peter Steinberger &lt;steipete@gmail.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -28,6 +28,9 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- **Outbound channel bootstrap:** suppress repeated failed plugin activation for the same channel, config, and registry generation while retrying after config or registry reloads. (#100377) Thanks @xialonglee.
+- **OpenAI Realtime client-secret deadlines:** bound voice and transcription secret acquisition to 30 seconds through the guarded fetch boundary while preserving authentication and bounded response parsing. (#102860) Thanks @Alix-007.
+- **Gateway client watchdog:** keep transport-stall detection active for unbounded and mixed pending requests so dead sockets reject pending requests, reconnect, and never replay rejected requests. (#103407) Thanks @NianJiuZst.
 - **iOS Share Extension drafts:** preserve legitimate shared text beginning with scaffold-like prefixes, remove only exact legacy scaffold lines, avoid treating scheme-like prose as a URL, and deduplicate host-mirrored content. (#103453) Thanks @lin-hongkuan.
 - **Telegram reasoning previews:** reposition split reasoning previews through deferred deletion so prior preview messages do not remain stale while preserving client scroll position. (#97828) Thanks @ly-wang19.
 - **Feishu native-card threading:** normalize whitespace reply targets once and reuse the shared reply mode for card and media parts so native-card topic replies stay in their thread. (#102804) Thanks @sunlit-deng.
diff --git a/src/infra/outbound/channel-bootstrap.runtime.test.ts b/src/infra/outbound/channel-bootstrap.runtime.test.ts
@@ -26,6 +26,25 @@ const discordConfig = {
   },
 } satisfies OpenClawConfig;
 
+const updatedDiscordConfig = {
+  channels: {
+    discord: { enabled: true },
+  },
+} satisfies OpenClawConfig;
+
+function pinDiscordSetupShell(): void {
+  const registry = createEmptyPluginRegistry();
+  registry.channels = [
+    {
+      pluginId: "discord",
+      plugin: { id: "discord", meta: {} },
+      source: "setup",
+    },
+  ] as never;
+  setActivePluginRegistry(registry);
+  pinActivePluginChannelRegistry(registry);
+}
+
 describe("bootstrapOutboundChannelPlugin", () => {
   afterEach(() => {
     loaderMocks.resolveRuntimePluginRegistry.mockReset();
@@ -34,16 +53,7 @@ describe("bootstrapOutboundChannelPlugin", () => {
   });
 
   it("bootstraps when the selected channel registry has only a setup shell", () => {
-    const registry = createEmptyPluginRegistry();
-    registry.channels = [
-      {
-        pluginId: "discord",
-        plugin: { id: "discord", meta: {} },
-        source: "setup",
-      },
-    ] as never;
-    setActivePluginRegistry(registry);
-    pinActivePluginChannelRegistry(registry);
+    pinDiscordSetupShell();
 
     bootstrapOutboundChannelPlugin({
       channel: "discord",
@@ -143,17 +153,11 @@ describe("bootstrapOutboundChannelPlugin", () => {
     expect(loaderMocks.resolveRuntimePluginRegistry).not.toHaveBeenCalled();
   });
 
-  it("retries when bootstrap returns without making the channel send-capable", () => {
-    const registry = createEmptyPluginRegistry();
-    registry.channels = [
-      {
-        pluginId: "discord",
-        plugin: { id: "discord", meta: {} },
-        source: "setup",
-      },
-    ] as never;
-    setActivePluginRegistry(registry);
-    pinActivePluginChannelRegistry(registry);
+  it("does not retry an unusable replacement registry in the same generation", () => {
+    pinDiscordSetupShell();
+    loaderMocks.resolveRuntimePluginRegistry.mockImplementation(() => {
+      setActivePluginRegistry(createEmptyPluginRegistry());
+    });
 
     bootstrapOutboundChannelPlugin({
       channel: "discord",
@@ -164,6 +168,39 @@ describe("bootstrapOutboundChannelPlugin", () => {
       cfg: discordConfig,
     });
 
+    expect(loaderMocks.resolveRuntimePluginRegistry).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not retry a thrown bootstrap in the same generation", () => {
+    pinDiscordSetupShell();
+    loaderMocks.resolveRuntimePluginRegistry.mockImplementation(() => {
+      throw new Error("load failed");
+    });
+
+    bootstrapOutboundChannelPlugin({ channel: "discord", cfg: discordConfig });
+    bootstrapOutboundChannelPlugin({ channel: "discord", cfg: discordConfig });
+
+    expect(loaderMocks.resolveRuntimePluginRegistry).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries after the runtime config changes", () => {
+    pinDiscordSetupShell();
+    bootstrapOutboundChannelPlugin({ channel: "discord", cfg: discordConfig });
+    bootstrapOutboundChannelPlugin({ channel: "discord", cfg: updatedDiscordConfig });
+
+    expect(loaderMocks.resolveRuntimePluginRegistry).toHaveBeenCalledTimes(2);
+  });
+
+  it("retains failed attempts when distinct runtime configs interleave", () => {
+    pinDiscordSetupShell();
+    loaderMocks.resolveRuntimePluginRegistry.mockImplementation(() => {
+      setActivePluginRegistry(createEmptyPluginRegistry());
+    });
+
+    bootstrapOutboundChannelPlugin({ channel: "discord", cfg: discordConfig });
+    bootstrapOutboundChannelPlugin({ channel: "discord", cfg: updatedDiscordConfig });
+    bootstrapOutboundChannelPlugin({ channel: "discord", cfg: discordConfig });
+
     expect(loaderMocks.resolveRuntimePluginRegistry).toHaveBeenCalledTimes(2);
   });
 });
diff --git a/src/infra/outbound/channel-bootstrap.runtime.ts b/src/infra/outbound/channel-bootstrap.runtime.ts
@@ -2,6 +2,7 @@
 // when only setup-shell metadata is active.
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../../agents/agent-scope.js";
 import { applyPluginAutoEnable } from "../../config/plugin-auto-enable.js";
+import { resolveRuntimeConfigCacheKey } from "../../config/runtime-snapshot.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { resolveRuntimePluginRegistry } from "../../plugins/loader.js";
 import type { PluginChannelRegistration } from "../../plugins/registry-types.js";
@@ -13,11 +14,44 @@ import {
 } from "../../plugins/runtime.js";
 import type { DeliverableMessageChannel } from "../../utils/message-channel.js";
 
-const bootstrapAttempts = new Set<string>();
+const MAX_BOOTSTRAP_CONFIG_GENERATIONS = 64;
+let bootstrapRegistryGeneration: string | undefined;
+const bootstrapAttemptedChannelsByConfig = new Map<string, Set<DeliverableMessageChannel>>();
 
-/** Clears the per-registry channel bootstrap retry guard for isolated tests. */
+function resolveBootstrapRegistryGeneration(): string {
+  return `${getActivePluginChannelRegistryVersion()}:${getActivePluginRegistryVersion()}`;
+}
+
+function resolveBootstrapAttemptedChannels(cfg: OpenClawConfig): Set<DeliverableMessageChannel> {
+  const registryGeneration = resolveBootstrapRegistryGeneration();
+  if (registryGeneration !== bootstrapRegistryGeneration) {
+    bootstrapRegistryGeneration = registryGeneration;
+    bootstrapAttemptedChannelsByConfig.clear();
+  }
+  const configKey = resolveRuntimeConfigCacheKey(cfg);
+  const existing = bootstrapAttemptedChannelsByConfig.get(configKey);
+  if (existing) {
+    bootstrapAttemptedChannelsByConfig.delete(configKey);
+    bootstrapAttemptedChannelsByConfig.set(configKey, existing);
+    return existing;
+  }
+  // Agent-scoped configs may interleave within one registry generation. Keep a
+  // bounded LRU so one caller cannot evict another on every delivery attempt.
+  if (bootstrapAttemptedChannelsByConfig.size >= MAX_BOOTSTRAP_CONFIG_GENERATIONS) {
+    const oldestConfigKey = bootstrapAttemptedChannelsByConfig.keys().next().value;
+    if (oldestConfigKey !== undefined) {
+      bootstrapAttemptedChannelsByConfig.delete(oldestConfigKey);
+    }
+  }
+  const attemptedChannels = new Set<DeliverableMessageChannel>();
+  bootstrapAttemptedChannelsByConfig.set(configKey, attemptedChannels);
+  return attemptedChannels;
+}
+
+/** Clears the per-generation channel bootstrap retry guard for isolated tests. */
 export function resetOutboundChannelBootstrapStateForTests(): void {
-  bootstrapAttempts.clear();
+  bootstrapRegistryGeneration = undefined;
+  bootstrapAttemptedChannelsByConfig.clear();
 }
 
 function channelEntryCanSend(entry: PluginChannelRegistration | undefined): boolean {
@@ -59,13 +93,11 @@ export function bootstrapOutboundChannelPlugin(params: {
     return;
   }
 
-  const attemptKey = `${getActivePluginChannelRegistryVersion()}:${getActivePluginRegistryVersion()}:${params.channel}`;
-  if (bootstrapAttempts.has(attemptKey)) {
+  const attemptedChannels = resolveBootstrapAttemptedChannels(cfg);
+  if (attemptedChannels.has(params.channel)) {
     return;
   }
-  // Retry once per registry version/channel; failed loads clear the guard below
-  // so config fixes in the same process can try again.
-  bootstrapAttempts.add(attemptKey);
+  attemptedChannels.add(params.channel);
 
   const autoEnabled = applyPluginAutoEnable({ config: cfg });
   const defaultAgentId = resolveDefaultAgentId(autoEnabled.config);
@@ -80,10 +112,16 @@ export function bootstrapOutboundChannelPlugin(params: {
         allowGatewaySubagentBinding: true,
       },
     });
-    if (!canResolveSendCapableChannel(params.channel)) {
-      bootstrapAttempts.delete(attemptKey);
-    }
   } catch {
-    bootstrapAttempts.delete(attemptKey);
+    // Best-effort bootstrap; the caller reports the unavailable channel.
+  }
+  // A bootstrap can replace the registry itself. Adopt that generation without
+  // forgetting failures for interleaved configs; external replacements observed
+  // before the next attempt still clear the guard above.
+  bootstrapRegistryGeneration = resolveBootstrapRegistryGeneration();
+  if (!canResolveSendCapableChannel(params.channel)) {
+    // Loading can replace the active registry without making this channel usable.
+    // Carry the failure forward so polling callers wait for config or registry reload.
+    resolveBootstrapAttemptedChannels(cfg).add(params.channel);
   }
 }
diff --git a/src/infra/outbound/channel-resolution.test.ts b/src/infra/outbound/channel-resolution.test.ts
@@ -492,7 +492,7 @@ describe("outbound channel resolution", () => {
     expect(resolveRuntimePluginRegistryMock).toHaveBeenCalledTimes(1);
   });
 
-  it("retries registry loads after bootstrap does not make the channel send-capable", async () => {
+  it("does not repeat registry loads after bootstrap misses in the same generation", async () => {
     getChannelPluginMock.mockReturnValue(undefined);
     const channelResolution = await importChannelResolution("bootstrap-retry");
 
@@ -509,7 +509,7 @@ describe("outbound channel resolution", () => {
       cfg: { channels: {} } as never,
       allowBootstrap: true,
     });
-    expect(resolveRuntimePluginRegistryMock).toHaveBeenCalledTimes(2);
+    expect(resolveRuntimePluginRegistryMock).toHaveBeenCalledTimes(1);
   });
 
   it("allows another activation attempt when the pinned channel registry version changes", async () => {
@@ -532,6 +532,26 @@ describe("outbound channel resolution", () => {
     expect(resolveRuntimePluginRegistryMock).toHaveBeenCalledTimes(2);
   });
 
+  it("allows another activation attempt when the active registry version changes", async () => {
+    getChannelPluginMock.mockReturnValue(undefined);
+    const channelResolution = await importChannelResolution("active-version-change");
+
+    channelResolution.resolveOutboundChannelPlugin({
+      channel: "alpha",
+      cfg: { channels: {} } as never,
+      allowBootstrap: true,
+    });
+    expect(resolveRuntimePluginRegistryMock).toHaveBeenCalledTimes(1);
+
+    getActivePluginRegistryVersionMock.mockReturnValue(2);
+    channelResolution.resolveOutboundChannelPlugin({
+      channel: "alpha",
+      cfg: { channels: {} } as never,
+      allowBootstrap: true,
+    });
+    expect(resolveRuntimePluginRegistryMock).toHaveBeenCalledTimes(2);
+  });
+
   it("resolves message adapters through the activation-aware channel plugin path", async () => {
     const message = { send: { text: vi.fn() } };
     const plugin = { id: "alpha", message };
