fix(channels): surface missing external plugin repairs

vincentkoc · web-flow · commit f482e4d3359c · 2026-05-07T12:49:17.000-07:00
## Summary - Add catalog-backed repair hints for official external channel plugins. - Show configured Feishu/WhatsApp-style external channels as missing-plugin warning rows in status surfaces. - Keep installed-but-unconfigured, disabled, allowlist-denied, and untrusted plugins on their real activation/configuration error paths. Fixes #78702 Fixes #78593
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -21,6 +21,7 @@ Docs: https://docs.openclaw.ai
 - Discord/streaming: default Discord replies to progress draft previews so tool/work activity appears in one edited Discord message unless `channels.discord.streaming.mode` is set to `off`.
 - OpenAI: support `openai/chat-latest` as an explicit direct API-key model override for trying the moving ChatGPT Instant API alias without changing the stable default model.
 - Plugins/install: add `npm-pack:<path.tgz>` installs so local npm pack artifacts run through the same managed npm-root install, lockfile verification, dependency scan, and install-record path as registry npm plugins.
+- Channels/plugins: show configured official external channels as missing-plugin status rows and send errors with exact install/doctor repair commands after raw package-manager upgrades leave Feishu or WhatsApp uninstalled. Fixes #78702 and #78593. Thanks @MarkMa84 and @mkupiainen.
 - Codex app-server: disarm the short post-tool completion watchdog after current-turn activity, expose `appServer.turnCompletionIdleTimeoutMs`, and include raw assistant item context in idle-timeout diagnostics so status-only post-tool stalls stop failing as idle. Fixes #77984. Thanks @roseware-dev and @rubencu.
 - Plugin skills/Windows: publish plugin-provided skill directories as junctions on Windows so standard users without Developer Mode can register plugin skills without symlink EPERM failures. Fixes #77958. (#77971) Thanks @hclsys and @jarro.
 - MS Teams: surface blocked Bot Framework egress by logging JWKS fetch network failures and adding a Bot Connector send hint for transport-level reply failures. Fixes #77674. (#78081) Thanks @Beandon13.
diff --git a/src/commands/channels.status.command-flow.test.ts b/src/commands/channels.status.command-flow.test.ts
@@ -12,6 +12,7 @@ const mocks = vi.hoisted(() => ({
   requireValidConfigSnapshot: vi.fn(),
   listChannelPlugins: vi.fn(),
   listConfiguredChannelIdsForReadOnlyScope: vi.fn((_params: unknown) => ["discord"]),
+  missingOfficialExternalChannels: new Set<string>(),
   withProgress: vi.fn(async (_opts: unknown, run: () => Promise<unknown>) => await run()),
 }));
 
@@ -36,10 +37,28 @@ vi.mock("../config/config.js", () => ({
 }));
 
 vi.mock("../plugins/channel-plugin-ids.js", () => ({
+  listExplicitConfiguredChannelIdsForConfig: (config: { channels?: Record<string, unknown> }) =>
+    Object.keys(config.channels ?? {}),
   listConfiguredChannelIdsForReadOnlyScope: (params: unknown) =>
     mocks.listConfiguredChannelIdsForReadOnlyScope(params),
 }));
 
+vi.mock("../plugins/official-external-plugin-repair-hints.js", () => ({
+  resolveMissingOfficialExternalChannelPluginRepairHint: ({ channelId }: { channelId: string }) =>
+    mocks.missingOfficialExternalChannels.has(channelId)
+      ? {
+          pluginId: channelId,
+          channelId,
+          label: "Feishu",
+          installSpec: "@openclaw/feishu",
+          installCommand: "openclaw plugins install @openclaw/feishu",
+          doctorFixCommand: "openclaw doctor --fix",
+          repairHint:
+            "Install the official external plugin with: openclaw plugins install @openclaw/feishu, or run: openclaw doctor --fix.",
+        }
+      : null,
+}));
+
 vi.mock("./channels/shared.js", () => ({
   requireValidConfigSnapshot: (runtime: unknown) => mocks.requireValidConfigSnapshot(runtime),
   formatChannelAccountLabel: ({
@@ -184,6 +203,7 @@ describe("channelsStatusCommand SecretRef fallback flow", () => {
     mocks.readConfigFileSnapshot.mockClear();
     mocks.requireValidConfigSnapshot.mockReset();
     mocks.listChannelPlugins.mockReset();
+    mocks.missingOfficialExternalChannels.clear();
     mocks.listConfiguredChannelIdsForReadOnlyScope.mockClear();
     mocks.listConfiguredChannelIdsForReadOnlyScope.mockReturnValue(["discord"]);
     mocks.withProgress.mockClear();
@@ -240,6 +260,29 @@ describe("channelsStatusCommand SecretRef fallback flow", () => {
     expect(joined).not.toContain("token:config (unavailable)");
   });
 
+  it("shows missing official external plugin repair hints in config-only output", async () => {
+    mocks.callGateway.mockRejectedValue(new Error("gateway closed"));
+    mocks.requireValidConfigSnapshot.mockResolvedValue({
+      channels: { feishu: { appId: "cli_xxx" } },
+    });
+    mocks.resolveCommandConfigWithSecrets.mockResolvedValue({
+      resolvedConfig: { channels: { feishu: { appId: "cli_xxx" } } },
+      effectiveConfig: { channels: { feishu: { appId: "cli_xxx" } } },
+      diagnostics: [],
+    });
+    mocks.missingOfficialExternalChannels.add("feishu");
+    mocks.listChannelPlugins.mockReturnValue([]);
+    const { runtime, logs } = createCapturingTestRuntime();
+
+    await channelsStatusCommand({ probe: false }, runtime as never);
+
+    const joined = logs.join("\n");
+    expect(joined).toContain("Missing official external plugins:");
+    expect(joined).toContain(
+      "Feishu: Install the official external plugin with: openclaw plugins install @openclaw/feishu, or run: openclaw doctor --fix.",
+    );
+  });
+
   it("keeps JSON fallback structured without rendering config-only text", async () => {
     mocks.callGateway.mockRejectedValue(
       new Error(
diff --git a/src/commands/channels/status-config-format.ts b/src/commands/channels/status-config-format.ts
@@ -9,6 +9,11 @@ import {
 } from "../../channels/plugins/status.js";
 import type { ChannelAccountSnapshot } from "../../channels/plugins/types.public.js";
 import type { OpenClawConfig } from "../../config/config.js";
+import { listExplicitConfiguredChannelIdsForConfig } from "../../plugins/channel-plugin-ids.js";
+import {
+  type OfficialExternalPluginRepairHint,
+  resolveMissingOfficialExternalChannelPluginRepairHint,
+} from "../../plugins/official-external-plugin-repair-hints.js";
 import { formatDocsLink } from "../../terminal/links.js";
 import { theme } from "../../terminal/theme.js";
 import {
@@ -62,7 +67,9 @@ export async function formatConfigChannelsStatusLines(
     activationSourceConfig: sourceConfig,
     includeSetupFallbackPlugins: true,
   });
+  const visibleChannelIds = new Set<string>();
   for (const plugin of plugins) {
+    visibleChannelIds.add(plugin.id);
     const accountIds = plugin.config.listAccountIds(cfg);
     if (!accountIds.length) {
       continue;
@@ -93,6 +100,36 @@ export async function formatConfigChannelsStatusLines(
     }
   }
 
+  const missingHints: OfficialExternalPluginRepairHint[] = [];
+  const missingChannelIds = [
+    ...new Set([
+      ...listExplicitConfiguredChannelIdsForConfig(sourceConfig),
+      ...listExplicitConfiguredChannelIdsForConfig(cfg),
+    ]),
+  ];
+  for (const channelId of missingChannelIds) {
+    if (visibleChannelIds.has(channelId)) {
+      continue;
+    }
+    const hint = resolveMissingOfficialExternalChannelPluginRepairHint({
+      config: cfg,
+      activationSourceConfig: sourceConfig,
+      channelId,
+    });
+    if (!hint?.channelId || visibleChannelIds.has(hint.channelId)) {
+      continue;
+    }
+    missingHints.push(hint);
+    visibleChannelIds.add(hint.channelId);
+  }
+  if (missingHints.length > 0) {
+    lines.push("");
+    lines.push(theme.warn("Missing official external plugins:"));
+    for (const hint of missingHints) {
+      lines.push(`- ${hint.label}: ${hint.repairHint}`);
+    }
+  }
+
   lines.push("");
   lines.push(
     `Tip: ${formatDocsLink("/cli#status", "status --deep")} adds gateway health probes to status output (requires a reachable gateway).`,
diff --git a/src/commands/status-all/channels.test.ts b/src/commands/status-all/channels.test.ts
@@ -3,6 +3,8 @@ import { buildChannelsTable } from "./channels.js";
 
 const mocks = vi.hoisted(() => ({
   resolveInspectedChannelAccount: vi.fn(),
+  listReadOnlyChannelPluginsForConfig: vi.fn(),
+  missingOfficialExternalChannels: new Set<string>(),
 }));
 
 const discordPlugin = {
@@ -18,12 +20,34 @@ vi.mock("../../channels/account-inspection.js", () => ({
 }));
 
 vi.mock("../../channels/plugins/read-only.js", () => ({
-  listReadOnlyChannelPluginsForConfig: () => [discordPlugin],
+  resolveReadOnlyChannelPluginsForConfig: () => ({
+    plugins: mocks.listReadOnlyChannelPluginsForConfig(),
+    configuredChannelIds: [],
+    missingConfiguredChannelIds: [],
+  }),
+}));
+
+vi.mock("../../plugins/official-external-plugin-repair-hints.js", () => ({
+  resolveMissingOfficialExternalChannelPluginRepairHint: ({ channelId }: { channelId: string }) =>
+    mocks.missingOfficialExternalChannels.has(channelId)
+      ? {
+          pluginId: channelId,
+          channelId,
+          label: "Feishu",
+          installSpec: "@openclaw/feishu",
+          installCommand: "openclaw plugins install @openclaw/feishu",
+          doctorFixCommand: "openclaw doctor --fix",
+          repairHint:
+            "Install the official external plugin with: openclaw plugins install @openclaw/feishu, or run: openclaw doctor --fix.",
+        }
+      : null,
 }));
 
 describe("buildChannelsTable", () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    mocks.missingOfficialExternalChannels.clear();
+    mocks.listReadOnlyChannelPluginsForConfig.mockReturnValue([discordPlugin]);
     mocks.resolveInspectedChannelAccount.mockResolvedValue({
       account: {
         tokenStatus: "configured_unavailable",
@@ -79,4 +103,30 @@ describe("buildChannelsTable", () => {
       }),
     );
   });
+
+  it("shows configured official external channels when the plugin is missing", async () => {
+    mocks.listReadOnlyChannelPluginsForConfig.mockReturnValue([]);
+    mocks.missingOfficialExternalChannels.add("feishu");
+
+    const table = await buildChannelsTable({ channels: { feishu: { appId: "cli_xxx" } } });
+
+    expect(table.rows).toContainEqual({
+      id: "feishu",
+      label: "Feishu",
+      enabled: true,
+      state: "warn",
+      detail:
+        "plugin not installed - run openclaw plugins install @openclaw/feishu or openclaw doctor --fix",
+    });
+    expect(mocks.resolveInspectedChannelAccount).not.toHaveBeenCalled();
+  });
+
+  it("does not show install repair rows when an external channel owner is policy-blocked", async () => {
+    mocks.listReadOnlyChannelPluginsForConfig.mockReturnValue([]);
+
+    const table = await buildChannelsTable({ channels: { feishu: { appId: "cli_xxx" } } });
+
+    expect(table.rows).toEqual([]);
+    expect(mocks.resolveInspectedChannelAccount).not.toHaveBeenCalled();
+  });
 });
diff --git a/src/commands/status-all/channels.ts b/src/commands/status-all/channels.ts
@@ -6,14 +6,16 @@ import {
   formatChannelAllowFrom,
 } from "../../channels/account-summary.js";
 import { resolveChannelDefaultAccountId } from "../../channels/plugins/helpers.js";
-import { listReadOnlyChannelPluginsForConfig } from "../../channels/plugins/read-only.js";
+import { resolveReadOnlyChannelPluginsForConfig } from "../../channels/plugins/read-only.js";
 import { formatChannelStatusState } from "../../channels/plugins/status-state.js";
 import type {
   ChannelAccountSnapshot,
   ChannelId,
   ChannelPlugin,
 } from "../../channels/plugins/types.public.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
+import { listExplicitConfiguredChannelIdsForConfig } from "../../plugins/channel-plugin-ids.js";
+import { resolveMissingOfficialExternalChannelPluginRepairHint } from "../../plugins/official-external-plugin-repair-hints.js";
 import { asRecord } from "../../shared/record-coerce.js";
 import { normalizeOptionalString } from "../../shared/string-coerce.js";
 import {
@@ -272,10 +274,11 @@ export async function buildChannelsTable(
 
   const sourceConfig = opts?.sourceConfig ?? cfg;
   const includeSetupFallbackPlugins = opts?.includeSetupFallbackPlugins ?? true;
-  for (const plugin of listReadOnlyChannelPluginsForConfig(cfg, {
+  const readOnlyPlugins = resolveReadOnlyChannelPluginsForConfig(cfg, {
     activationSourceConfig: sourceConfig,
     includeSetupFallbackPlugins,
-  })) {
+  });
+  for (const plugin of readOnlyPlugins.plugins) {
     const accountIds = plugin.config.listAccountIds(cfg);
     const defaultAccountId = resolveChannelDefaultAccountId({
       plugin,
@@ -481,6 +484,36 @@ export async function buildChannelsTable(
     }
   }
 
+  const visibleChannelIds = new Set(rows.map((row) => row.id));
+  const missingCandidateChannelIds = [
+    ...new Set([
+      ...readOnlyPlugins.missingConfiguredChannelIds,
+      ...listExplicitConfiguredChannelIdsForConfig(sourceConfig),
+      ...listExplicitConfiguredChannelIdsForConfig(cfg),
+    ]),
+  ].toSorted((left, right) => left.localeCompare(right));
+  for (const channelId of missingCandidateChannelIds) {
+    if (visibleChannelIds.has(channelId)) {
+      continue;
+    }
+    const hint = resolveMissingOfficialExternalChannelPluginRepairHint({
+      config: cfg,
+      activationSourceConfig: sourceConfig,
+      channelId,
+    });
+    if (!hint || hint.channelId !== channelId) {
+      continue;
+    }
+    rows.push({
+      id: channelId,
+      label: hint.label,
+      enabled: true,
+      state: "warn",
+      detail: `plugin not installed - run ${hint.installCommand} or ${hint.doctorFixCommand}`,
+    });
+    visibleChannelIds.add(channelId);
+  }
+
   return {
     rows,
     details,
diff --git a/src/infra/outbound/channel-selection.test.ts b/src/infra/outbound/channel-selection.test.ts
@@ -3,9 +3,18 @@ import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 const mocks = vi.hoisted(() => ({
   listChannelPlugins: vi.fn(),
   resolveOutboundChannelPlugin: vi.fn(),
+  missingOfficialExternalChannels: new Set<string>(),
 }));
 
-const deliverableChannelIds = vi.hoisted(() => ["alpha", "beta", "gamma", "delta", "muted"]);
+const deliverableChannelIds = vi.hoisted(() => [
+  "alpha",
+  "beta",
+  "gamma",
+  "delta",
+  "feishu",
+  "muted",
+  "whatsapp",
+]);
 
 vi.mock("../../channels/plugins/index.js", () => ({
   getLoadedChannelPlugin: vi.fn(),
@@ -23,6 +32,21 @@ vi.mock("./channel-resolution.js", () => ({
   resolveOutboundChannelPlugin: mocks.resolveOutboundChannelPlugin,
 }));
 
+vi.mock("../../plugins/official-external-plugin-repair-hints.js", () => ({
+  resolveMissingOfficialExternalChannelPluginRepairHint: ({ channelId }: { channelId: string }) =>
+    mocks.missingOfficialExternalChannels.has(channelId)
+      ? {
+          pluginId: channelId,
+          channelId,
+          label: channelId === "whatsapp" ? "WhatsApp" : "Feishu",
+          installSpec: `@openclaw/${channelId}`,
+          installCommand: `openclaw plugins install @openclaw/${channelId}`,
+          doctorFixCommand: "openclaw doctor --fix",
+          repairHint: `Install the official external plugin with: openclaw plugins install @openclaw/${channelId}, or run: openclaw doctor --fix.`,
+        }
+      : null,
+}));
+
 type ChannelSelectionModule = typeof import("./channel-selection.js");
 type RuntimeModule = typeof import("../../runtime.js");
 
@@ -141,6 +165,11 @@ describe("resolveMessageChannelSelection", () => {
   beforeEach(() => {
     mocks.listChannelPlugins.mockReset();
     mocks.listChannelPlugins.mockReturnValue([]);
+    mocks.resolveOutboundChannelPlugin.mockReset();
+    mocks.resolveOutboundChannelPlugin.mockImplementation(({ channel }: { channel: string }) => ({
+      id: channel,
+    }));
+    mocks.missingOfficialExternalChannels.clear();
   });
 
   it.each([
@@ -228,10 +257,43 @@ describe("resolveMessageChannelSelection", () => {
       params: { cfg: {} as never, channel: "alpha" },
       expectedMessage: "Channel is unavailable: alpha",
     },
+    {
+      setup: () => {
+        mocks.resolveOutboundChannelPlugin.mockReturnValue(undefined);
+        mocks.missingOfficialExternalChannels.add("feishu");
+      },
+      params: {
+        cfg: { channels: { feishu: { appId: "cli_xxx" } } } as never,
+        channel: "feishu",
+      },
+      expectedMessage:
+        "Channel is unavailable: feishu. Install the official external plugin with: openclaw plugins install @openclaw/feishu, or run: openclaw doctor --fix.",
+    },
     {
       params: { cfg: {} as never },
       expectedMessage: "Channel is required (no configured channels detected).",
     },
+    {
+      setup: () => {
+        mocks.resolveOutboundChannelPlugin.mockReturnValue(undefined);
+        mocks.missingOfficialExternalChannels.add("whatsapp");
+      },
+      params: { cfg: { channels: { whatsapp: { enabled: true } } } as never },
+      expectedMessage:
+        "Channel is required (no available channels detected). Configured official external channel WhatsApp is missing its plugin. Install the official external plugin with: openclaw plugins install @openclaw/whatsapp, or run: openclaw doctor --fix.",
+    },
+    {
+      setup: () => {
+        mocks.listChannelPlugins.mockReturnValue([
+          makePlugin({
+            id: "whatsapp",
+            isConfigured: async () => false,
+          }),
+        ]);
+      },
+      params: { cfg: { channels: { whatsapp: { enabled: true } } } as never },
+      expectedMessage: "Channel is required (no configured channels detected).",
+    },
     {
       setup: () => {
         mocks.listChannelPlugins.mockReturnValue([
diff --git a/src/infra/outbound/channel-selection.ts b/src/infra/outbound/channel-selection.ts
diff --git a/src/plugins/official-external-plugin-repair-hints.test.ts b/src/plugins/official-external-plugin-repair-hints.test.ts
diff --git a/src/plugins/official-external-plugin-repair-hints.ts b/src/plugins/official-external-plugin-repair-hints.ts
