fix: warn when configured channel plugins cannot load (#96397)

849261680 · web-flow · commit 16b275a0fba7 · 2026-06-30T17:43:10.000-07:00
* fix(gateway): warn for blocked configured channel plugins

* fix(gateway): preserve configured channel warning source
diff --git a/src/gateway/server-startup-log.test.ts b/src/gateway/server-startup-log.test.ts
@@ -1,10 +1,28 @@
 // Startup log tests cover security warnings, model detail formatting, plugin
 // summaries, bind URLs, ANSI output, and dangerous config reporting.
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { stripAnsi } from "../../packages/terminal-core/src/ansi.js";
 import { formatAgentModelStartupDetails, logGatewayStartup } from "./server-startup-log.js";
 
+const pluginRegistryMocks = vi.hoisted(() => ({
+  loadPluginManifestRegistryForPluginRegistry: vi.fn(),
+}));
+
+vi.mock("../plugins/plugin-registry.js", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../plugins/plugin-registry.js")>()),
+  loadPluginManifestRegistryForPluginRegistry:
+    pluginRegistryMocks.loadPluginManifestRegistryForPluginRegistry,
+}));
+
 describe("gateway startup log", () => {
+  beforeEach(() => {
+    pluginRegistryMocks.loadPluginManifestRegistryForPluginRegistry.mockReset();
+    pluginRegistryMocks.loadPluginManifestRegistryForPluginRegistry.mockReturnValue({
+      plugins: [],
+      diagnostics: [],
+    });
+  });
+
   afterEach(() => {
     vi.useRealTimers();
   });
@@ -51,6 +69,150 @@ describe("gateway startup log", () => {
     expect(warn).not.toHaveBeenCalled();
   });
 
+  it("warns when a configured channel plugin is blocked from startup", async () => {
+    pluginRegistryMocks.loadPluginManifestRegistryForPluginRegistry.mockReturnValue({
+      plugins: [
+        {
+          id: "slack",
+          origin: "global",
+          channels: ["slack"],
+          enabledByDefault: false,
+        },
+      ],
+      diagnostics: [],
+    });
+    const info = vi.fn();
+    const warn = vi.fn();
+
+    await logGatewayStartup({
+      cfg: {
+        channels: {
+          slack: {
+            enabled: true,
+            botToken: "configured",
+          },
+        },
+      },
+      bindHost: "127.0.0.1",
+      loadedPluginIds: [],
+      port: 18789,
+      log: { info, warn },
+      isNixMode: false,
+    });
+
+    expect(warn.mock.calls).toEqual([
+      [
+        'configured channel warning: channels.slack: channel is configured, but external plugin "slack" is installed without explicit trust. Add plugins.entries.slack.enabled=true. Fix plugin enablement before relying on setup guidance for this channel.',
+      ],
+    ]);
+  });
+
+  it("warns when a configured channel has no owning plugin", async () => {
+    const info = vi.fn();
+    const warn = vi.fn();
+
+    await logGatewayStartup({
+      cfg: {
+        channels: {
+          "missing-chat": {
+            enabled: true,
+            token: "configured",
+          },
+        },
+      },
+      bindHost: "127.0.0.1",
+      loadedPluginIds: [],
+      port: 18789,
+      log: { info, warn },
+      isNixMode: false,
+    });
+
+    expect(warn.mock.calls).toEqual([
+      [
+        "configured channel warning: channels.missing-chat is configured but no channel plugin is installed or loadable (no-channel-owner). Run `openclaw doctor --fix` or install the channel plugin before relying on this channel.",
+      ],
+    ]);
+  });
+
+  it("sanitizes configured channel ids in startup warnings", async () => {
+    const unsafeChannelId = `slack${String.fromCharCode(0x1b)}[31m`;
+    pluginRegistryMocks.loadPluginManifestRegistryForPluginRegistry.mockReturnValue({
+      plugins: [
+        {
+          id: "slack",
+          origin: "global",
+          channels: [unsafeChannelId],
+          enabledByDefault: false,
+        },
+      ],
+      diagnostics: [],
+    });
+    const info = vi.fn();
+    const warn = vi.fn();
+
+    await logGatewayStartup({
+      cfg: {
+        channels: {
+          [unsafeChannelId]: {
+            enabled: true,
+            botToken: "configured",
+          },
+        },
+      },
+      bindHost: "127.0.0.1",
+      loadedPluginIds: [],
+      port: 18789,
+      log: { info, warn },
+      isNixMode: false,
+    });
+
+    expect(warn.mock.calls[0]?.[0]).toContain("channels.slack: channel is configured");
+    expect(warn.mock.calls[0]?.[0]).not.toContain(String.fromCharCode(0x1b));
+  });
+
+  it("does not warn when startup activation enables the configured channel owner", async () => {
+    pluginRegistryMocks.loadPluginManifestRegistryForPluginRegistry.mockReturnValue({
+      plugins: [
+        {
+          id: "openclaw-modern-chat",
+          origin: "global",
+          channels: ["legacy-chat"],
+          enabledByDefault: false,
+        },
+      ],
+      diagnostics: [],
+    });
+    const info = vi.fn();
+    const warn = vi.fn();
+
+    await logGatewayStartup({
+      cfg: {
+        channels: {
+          "legacy-chat": {
+            enabled: true,
+            token: "configured",
+          },
+        },
+      },
+      activationSourceConfig: {
+        plugins: {
+          entries: {
+            "openclaw-modern-chat": {
+              enabled: true,
+            },
+          },
+        },
+      },
+      bindHost: "127.0.0.1",
+      loadedPluginIds: [],
+      port: 18789,
+      log: { info, warn },
+      isNixMode: false,
+    });
+
+    expect(warn).not.toHaveBeenCalled();
+  });
+
   it("logs configured model thinking and fast mode defaults with the startup model", async () => {
     const info = vi.fn();
     const warn = vi.fn();
diff --git a/src/gateway/server-startup-log.ts b/src/gateway/server-startup-log.ts
@@ -2,6 +2,7 @@
 // Produces the compact ready banner with resolved model and safety state.
 import { normalizeSortedUniqueStringEntries } from "@openclaw/normalization-core/string-normalization";
 import chalk from "chalk";
+import { sanitizeForLog } from "../../packages/terminal-core/src/ansi.js";
 import { resolveDefaultAgentId, resolveAgentConfig } from "../agents/agent-scope.js";
 import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "../agents/defaults.js";
 import { formatFastModeValue, resolveFastModeState } from "../agents/fast-mode.js";
@@ -29,6 +30,7 @@ type StartupThinkLevel =
 /** Emit startup summary lines after Gateway bind and plugin loading complete. */
 export async function logGatewayStartup(params: {
   cfg: OpenClawConfig;
+  activationSourceConfig?: OpenClawConfig;
   bindHost: string;
   bindHosts?: string[];
   port: number;
@@ -64,6 +66,13 @@ export async function logGatewayStartup(params: {
     params.log.info("gateway: running in Nix mode (config managed externally)");
   }
 
+  for (const warning of await collectConfiguredChannelStartupWarnings({
+    cfg: params.cfg,
+    activationSourceConfig: params.activationSourceConfig,
+  })) {
+    params.log.warn(warning);
+  }
+
   const enabledDangerousFlags =
     collectEnabledInsecureOrDangerousFlagsFromCurrentSnapshot(params.cfg) ??
     (await import("../security/dangerous-config-flags.js")).collectEnabledInsecureOrDangerousFlags(
@@ -165,6 +174,53 @@ export function formatAgentModelStartupDetails(params: {
   return `thinking=${thinking}, fast=${formatFastModeValue(fast.mode)}`;
 }
 
+async function collectConfiguredChannelStartupWarnings(params: {
+  cfg: OpenClawConfig;
+  activationSourceConfig?: OpenClawConfig;
+}): Promise<string[]> {
+  const [blockerModule, presencePolicyModule, pluginRegistryModule] = await Promise.all([
+    import("../commands/doctor/shared/channel-plugin-blockers.js"),
+    import("../plugins/channel-presence-policy.js"),
+    import("../plugins/plugin-registry.js"),
+  ]);
+  const manifestRegistry = pluginRegistryModule.loadPluginManifestRegistryForPluginRegistry({
+    config: params.cfg,
+    env: process.env,
+    includeDisabled: true,
+  });
+  const hits = blockerModule.scanConfiguredChannelPluginBlockers(
+    params.cfg,
+    process.env,
+    params.activationSourceConfig,
+  );
+  const blockerWarnings = blockerModule
+    .collectConfiguredChannelPluginBlockerWarnings(hits)
+    .map((warning) => `configured channel warning: ${warning.replace(/^[-]\s*/u, "")}`);
+  const missingOwnerWarnings = presencePolicyModule
+    .resolveConfiguredChannelPresencePolicy({
+      config: params.cfg,
+      activationSourceConfig: params.activationSourceConfig,
+      includePersistedAuthState: false,
+      manifestRecords: manifestRegistry.plugins,
+    })
+    .filter((entry) => !entry.effective && entry.blockedReasons.includes("no-channel-owner"))
+    .map(formatConfiguredChannelMissingOwnerStartupWarning);
+  return [...blockerWarnings, ...missingOwnerWarnings];
+}
+
+function formatConfiguredChannelMissingOwnerStartupWarning(entry: {
+  channelId: string;
+  blockedReasons: readonly string[];
+}): string {
+  const channelId = sanitizeForLog(entry.channelId);
+  const reasons = normalizeSortedUniqueStringEntries(entry.blockedReasons).join(", ");
+  return (
+    `configured channel warning: channels.${channelId} is configured but no channel plugin ` +
+    `is installed or loadable (${reasons}). Run \`openclaw doctor --fix\` or install the ` +
+    "channel plugin before relying on this channel."
+  );
+}
+
 /** Format plugin count/list and optional startup duration for the ready log line. */
 function formatReadyDetails(
   loadedPluginIds: readonly string[],
diff --git a/src/gateway/server-startup-post-attach.test.ts b/src/gateway/server-startup-post-attach.test.ts
@@ -388,6 +388,11 @@ describe("startGatewayPostAttachRuntime", () => {
     expect(hoisted.setInternalHooksEnabled).not.toHaveBeenCalled();
     expect(hoisted.logGatewayStartup).toHaveBeenCalledTimes(1);
     expect(firstStartupLog().loadedPluginIds).toEqual(["beta", "alpha"]);
+    expect(hoisted.logGatewayStartup).toHaveBeenCalledWith(
+      expect.objectContaining({
+        activationSourceConfig: { hooks: { internal: { enabled: false } } },
+      }),
+    );
     expect(log.info).toHaveBeenCalledWith("gateway ready");
     expect(hoisted.scheduleRestartAbortedMainSessionRecovery).toHaveBeenCalledWith({
       cfg: { hooks: { internal: { enabled: false } } },
@@ -2240,6 +2245,7 @@ function createPostAttachParams(overrides: Partial<PostAttachParams> = {}): Post
       error: vi.fn(),
     },
     gatewayPluginConfigAtStart: { hooks: { internal: { enabled: false } } } as never,
+    activationSourceConfig: { hooks: { internal: { enabled: false } } } as never,
     pluginRegistry: {
       plugins: [
         { id: "beta", status: "loaded" },
diff --git a/src/gateway/server-startup-post-attach.ts b/src/gateway/server-startup-post-attach.ts
@@ -1096,6 +1096,7 @@ export async function startGatewayPostAttachRuntime(
       debug?: (msg: string) => void;
     };
     gatewayPluginConfigAtStart: OpenClawConfig;
+    activationSourceConfig: OpenClawConfig;
     pluginRegistry: ReturnType<typeof loadOpenClawPlugins>;
     defaultWorkspaceDir: string;
     deps: CliDeps;
@@ -1176,6 +1177,7 @@ export async function startGatewayPostAttachRuntime(
   const startupLogPromise = measureStartup(params.startupTrace, "post-attach.log", () =>
     runtimeDeps.logGatewayStartup({
       cfg: params.cfgAtStart,
+      activationSourceConfig: params.activationSourceConfig,
       bindHost: params.bindHost,
       bindHosts: params.bindHosts,
       port: params.port,
diff --git a/src/gateway/server.impl.ts b/src/gateway/server.impl.ts
@@ -1640,6 +1640,7 @@ export async function startGatewayServer(
             controlUiBasePath,
             logTailscale,
             gatewayPluginConfigAtStart,
+            activationSourceConfig: startupActivationSourceConfig,
             pluginRegistry,
             defaultWorkspaceDir,
             deps,
