@openclaw/feishu 2026.2.25 → 2026.3.2

package/src/onboarding.ts

@@ -3,9 +3,16 @@ import type {
   ChannelOnboardingDmPolicy,
   ClawdbotConfig,
   DmPolicy,
+  SecretInput,
   WizardPrompter,
 } from "openclaw/plugin-sdk";
-import { addWildcardAllowFrom, DEFAULT_ACCOUNT_ID, formatDocsLink } from "openclaw/plugin-sdk";
+import {
+  addWildcardAllowFrom,
+  DEFAULT_ACCOUNT_ID,
+  formatDocsLink,
+  hasConfiguredSecretInput,
+  promptSingleChannelSecretInput,
+} from "openclaw/plugin-sdk";
 import { resolveFeishuCredentials } from "./accounts.js";
 import { probeFeishu } from "./probe.js";
 import type { FeishuConfig } from "./types.js";
@@ -104,23 +111,18 @@ async function noteFeishuCredentialHelp(prompter: WizardPrompter): Promise<void>
   );
 }
 
-async function promptFeishuCredentials(prompter: WizardPrompter): Promise<{
-  appId: string;
-  appSecret: string;
-}> {
+async function promptFeishuAppId(params: {
+  prompter: WizardPrompter;
+  initialValue?: string;
+}): Promise<string> {
   const appId = String(
-    await prompter.text({
+    await params.prompter.text({
       message: "Enter Feishu App ID",
+      initialValue: params.initialValue,
       validate: (value) => (value?.trim() ? undefined : "Required"),
     }),
   ).trim();
-  const appSecret = String(
-    await prompter.text({
-      message: "Enter Feishu App Secret",
-      validate: (value) => (value?.trim() ? undefined : "Required"),
-    }),
-  ).trim();
-  return { appId, appSecret };
+  return appId;
 }
 
 function setFeishuGroupPolicy(
@@ -167,13 +169,30 @@ export const feishuOnboardingAdapter: ChannelOnboardingAdapter = {
   channel,
   getStatus: async ({ cfg }) => {
     const feishuCfg = cfg.channels?.feishu as FeishuConfig | undefined;
-    const configured = Boolean(resolveFeishuCredentials(feishuCfg));
+    const topLevelConfigured = Boolean(
+      feishuCfg?.appId?.trim() && hasConfiguredSecretInput(feishuCfg?.appSecret),
+    );
+    const accountConfigured = Object.values(feishuCfg?.accounts ?? {}).some((account) => {
+      if (!account || typeof account !== "object") {
+        return false;
+      }
+      const accountAppId =
+        typeof account.appId === "string" ? account.appId.trim() : feishuCfg?.appId?.trim();
+      const accountSecretConfigured =
+        hasConfiguredSecretInput(account.appSecret) ||
+        hasConfiguredSecretInput(feishuCfg?.appSecret);
+      return Boolean(accountAppId && accountSecretConfigured);
+    });
+    const configured = topLevelConfigured || accountConfigured;
+    const resolvedCredentials = resolveFeishuCredentials(feishuCfg, {
+      allowUnresolvedSecretRef: true,
+    });
 
     // Try to probe if configured
     let probeResult = null;
-    if (configured && feishuCfg) {
+    if (configured && resolvedCredentials) {
       try {
-        probeResult = await probeFeishu(feishuCfg);
+        probeResult = await probeFeishu(resolvedCredentials);
       } catch {
         // Ignore probe errors
       }
@@ -201,52 +220,53 @@ export const feishuOnboardingAdapter: ChannelOnboardingAdapter = {
 
   configure: async ({ cfg, prompter }) => {
     const feishuCfg = cfg.channels?.feishu as FeishuConfig | undefined;
-    const resolved = resolveFeishuCredentials(feishuCfg);
-    const hasConfigCreds = Boolean(feishuCfg?.appId?.trim() && feishuCfg?.appSecret?.trim());
+    const resolved = resolveFeishuCredentials(feishuCfg, {
+      allowUnresolvedSecretRef: true,
+    });
+    const hasConfigSecret = hasConfiguredSecretInput(feishuCfg?.appSecret);
+    const hasConfigCreds = Boolean(feishuCfg?.appId?.trim() && hasConfigSecret);
     const canUseEnv = Boolean(
       !hasConfigCreds && process.env.FEISHU_APP_ID?.trim() && process.env.FEISHU_APP_SECRET?.trim(),
     );
 
     let next = cfg;
     let appId: string | null = null;
-    let appSecret: string | null = null;
+    let appSecret: SecretInput | null = null;
+    let appSecretProbeValue: string | null = null;
 
     if (!resolved) {
       await noteFeishuCredentialHelp(prompter);
     }
 
-    if (canUseEnv) {
-      const keepEnv = await prompter.confirm({
-        message: "FEISHU_APP_ID + FEISHU_APP_SECRET detected. Use env vars?",
-        initialValue: true,
-      });
-      if (keepEnv) {
-        next = {
-          ...next,
-          channels: {
-            ...next.channels,
-            feishu: { ...next.channels?.feishu, enabled: true },
-          },
-        };
-      } else {
-        const entered = await promptFeishuCredentials(prompter);
-        appId = entered.appId;
-        appSecret = entered.appSecret;
-      }
-    } else if (hasConfigCreds) {
-      const keep = await prompter.confirm({
-        message: "Feishu credentials already configured. Keep them?",
-        initialValue: true,
+    const appSecretResult = await promptSingleChannelSecretInput({
+      cfg: next,
+      prompter,
+      providerHint: "feishu",
+      credentialLabel: "App Secret",
+      accountConfigured: Boolean(resolved),
+      canUseEnv,
+      hasConfigToken: hasConfigSecret,
+      envPrompt: "FEISHU_APP_ID + FEISHU_APP_SECRET detected. Use env vars?",
+      keepPrompt: "Feishu App Secret already configured. Keep it?",
+      inputPrompt: "Enter Feishu App Secret",
+      preferredEnvVar: "FEISHU_APP_SECRET",
+    });
+
+    if (appSecretResult.action === "use-env") {
+      next = {
+        ...next,
+        channels: {
+          ...next.channels,
+          feishu: { ...next.channels?.feishu, enabled: true },
+        },
+      };
+    } else if (appSecretResult.action === "set") {
+      appSecret = appSecretResult.value;
+      appSecretProbeValue = appSecretResult.resolvedValue;
+      appId = await promptFeishuAppId({
+        prompter,
+        initialValue: feishuCfg?.appId?.trim() || process.env.FEISHU_APP_ID?.trim(),
       });
-      if (!keep) {
-        const entered = await promptFeishuCredentials(prompter);
-        appId = entered.appId;
-        appSecret = entered.appSecret;
-      }
-    } else {
-      const entered = await promptFeishuCredentials(prompter);
-      appId = entered.appId;
-      appSecret = entered.appSecret;
     }
 
     if (appId && appSecret) {
@@ -264,9 +284,12 @@ export const feishuOnboardingAdapter: ChannelOnboardingAdapter = {
       };
 
       // Test connection
-      const testCfg = next.channels?.feishu as FeishuConfig;
       try {
-        const probe = await probeFeishu(testCfg);
+        const probe = await probeFeishu({
+          appId,
+          appSecret: appSecretProbeValue ?? undefined,
+          domain: (next.channels?.feishu as FeishuConfig | undefined)?.domain,
+        });
         if (probe.ok) {
           await prompter.note(
             `Connected as ${probe.botName ?? probe.botOpenId ?? "bot"}`,
@@ -283,6 +306,75 @@ export const feishuOnboardingAdapter: ChannelOnboardingAdapter = {
       }
     }
 
+    const currentMode =
+      (next.channels?.feishu as FeishuConfig | undefined)?.connectionMode ?? "websocket";
+    const connectionMode = (await prompter.select({
+      message: "Feishu connection mode",
+      options: [
+        { value: "websocket", label: "WebSocket (default)" },
+        { value: "webhook", label: "Webhook" },
+      ],
+      initialValue: currentMode,
+    })) as "websocket" | "webhook";
+    next = {
+      ...next,
+      channels: {
+        ...next.channels,
+        feishu: {
+          ...next.channels?.feishu,
+          connectionMode,
+        },
+      },
+    };
+
+    if (connectionMode === "webhook") {
+      const currentVerificationToken = (next.channels?.feishu as FeishuConfig | undefined)
+        ?.verificationToken;
+      const verificationTokenResult = await promptSingleChannelSecretInput({
+        cfg: next,
+        prompter,
+        providerHint: "feishu-webhook",
+        credentialLabel: "verification token",
+        accountConfigured: hasConfiguredSecretInput(currentVerificationToken),
+        canUseEnv: false,
+        hasConfigToken: hasConfiguredSecretInput(currentVerificationToken),
+        envPrompt: "",
+        keepPrompt: "Feishu verification token already configured. Keep it?",
+        inputPrompt: "Enter Feishu verification token",
+        preferredEnvVar: "FEISHU_VERIFICATION_TOKEN",
+      });
+      if (verificationTokenResult.action === "set") {
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            feishu: {
+              ...next.channels?.feishu,
+              verificationToken: verificationTokenResult.value,
+            },
+          },
+        };
+      }
+      const currentWebhookPath = (next.channels?.feishu as FeishuConfig | undefined)?.webhookPath;
+      const webhookPath = String(
+        await prompter.text({
+          message: "Feishu webhook path",
+          initialValue: currentWebhookPath ?? "/feishu/events",
+          validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+        }),
+      ).trim();
+      next = {
+        ...next,
+        channels: {
+          ...next.channels,
+          feishu: {
+            ...next.channels?.feishu,
+            webhookPath,
+          },
+        },
+      };
+    }
+
     // Domain selection
     const currentDomain = (next.channels?.feishu as FeishuConfig | undefined)?.domain ?? "feishu";
     const domain = await prompter.select({

package/src/outbound.test.ts

@@ -0,0 +1,181 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const sendMediaFeishuMock = vi.hoisted(() => vi.fn());
+const sendMessageFeishuMock = vi.hoisted(() => vi.fn());
+const sendMarkdownCardFeishuMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./media.js", () => ({
+  sendMediaFeishu: sendMediaFeishuMock,
+}));
+
+vi.mock("./send.js", () => ({
+  sendMessageFeishu: sendMessageFeishuMock,
+  sendMarkdownCardFeishu: sendMarkdownCardFeishuMock,
+}));
+
+vi.mock("./runtime.js", () => ({
+  getFeishuRuntime: () => ({
+    channel: {
+      text: {
+        chunkMarkdownText: (text: string) => [text],
+      },
+    },
+  }),
+}));
+
+import { feishuOutbound } from "./outbound.js";
+const sendText = feishuOutbound.sendText!;
+
+describe("feishuOutbound.sendText local-image auto-convert", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    sendMessageFeishuMock.mockResolvedValue({ messageId: "text_msg" });
+    sendMarkdownCardFeishuMock.mockResolvedValue({ messageId: "card_msg" });
+    sendMediaFeishuMock.mockResolvedValue({ messageId: "media_msg" });
+  });
+
+  async function createTmpImage(ext = ".png"): Promise<{ dir: string; file: string }> {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-feishu-outbound-"));
+    const file = path.join(dir, `sample${ext}`);
+    await fs.writeFile(file, "image-data");
+    return { dir, file };
+  }
+
+  it("sends an absolute existing local image path as media", async () => {
+    const { dir, file } = await createTmpImage();
+    try {
+      const result = await sendText({
+        cfg: {} as any,
+        to: "chat_1",
+        text: file,
+        accountId: "main",
+      });
+
+      expect(sendMediaFeishuMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          to: "chat_1",
+          mediaUrl: file,
+          accountId: "main",
+        }),
+      );
+      expect(sendMessageFeishuMock).not.toHaveBeenCalled();
+      expect(result).toEqual(
+        expect.objectContaining({ channel: "feishu", messageId: "media_msg" }),
+      );
+    } finally {
+      await fs.rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("keeps non-path text on the text-send path", async () => {
+    await sendText({
+      cfg: {} as any,
+      to: "chat_1",
+      text: "please upload /tmp/example.png",
+      accountId: "main",
+    });
+
+    expect(sendMediaFeishuMock).not.toHaveBeenCalled();
+    expect(sendMessageFeishuMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        to: "chat_1",
+        text: "please upload /tmp/example.png",
+        accountId: "main",
+      }),
+    );
+  });
+
+  it("falls back to plain text if local-image media send fails", async () => {
+    const { dir, file } = await createTmpImage();
+    sendMediaFeishuMock.mockRejectedValueOnce(new Error("upload failed"));
+    try {
+      await sendText({
+        cfg: {} as any,
+        to: "chat_1",
+        text: file,
+        accountId: "main",
+      });
+
+      expect(sendMediaFeishuMock).toHaveBeenCalledTimes(1);
+      expect(sendMessageFeishuMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          to: "chat_1",
+          text: file,
+          accountId: "main",
+        }),
+      );
+    } finally {
+      await fs.rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("uses markdown cards when renderMode=card", async () => {
+    const result = await sendText({
+      cfg: {
+        channels: {
+          feishu: {
+            renderMode: "card",
+          },
+        },
+      } as any,
+      to: "chat_1",
+      text: "| a | b |\n| - | - |",
+      accountId: "main",
+    });
+
+    expect(sendMarkdownCardFeishuMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        to: "chat_1",
+        text: "| a | b |\n| - | - |",
+        accountId: "main",
+      }),
+    );
+    expect(sendMessageFeishuMock).not.toHaveBeenCalled();
+    expect(result).toEqual(expect.objectContaining({ channel: "feishu", messageId: "card_msg" }));
+  });
+});
+
+describe("feishuOutbound.sendMedia renderMode", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    sendMessageFeishuMock.mockResolvedValue({ messageId: "text_msg" });
+    sendMarkdownCardFeishuMock.mockResolvedValue({ messageId: "card_msg" });
+    sendMediaFeishuMock.mockResolvedValue({ messageId: "media_msg" });
+  });
+
+  it("uses markdown cards for captions when renderMode=card", async () => {
+    const result = await feishuOutbound.sendMedia?.({
+      cfg: {
+        channels: {
+          feishu: {
+            renderMode: "card",
+          },
+        },
+      } as any,
+      to: "chat_1",
+      text: "| a | b |\n| - | - |",
+      mediaUrl: "https://example.com/image.png",
+      accountId: "main",
+    });
+
+    expect(sendMarkdownCardFeishuMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        to: "chat_1",
+        text: "| a | b |\n| - | - |",
+        accountId: "main",
+      }),
+    );
+    expect(sendMediaFeishuMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        to: "chat_1",
+        mediaUrl: "https://example.com/image.png",
+        accountId: "main",
+      }),
+    );
+    expect(sendMessageFeishuMock).not.toHaveBeenCalled();
+    expect(result).toEqual(expect.objectContaining({ channel: "feishu", messageId: "media_msg" }));
+  });
+});

package/src/outbound.ts

@@ -1,7 +1,64 @@
+import fs from "fs";
+import path from "path";
 import type { ChannelOutboundAdapter } from "openclaw/plugin-sdk";
+import { resolveFeishuAccount } from "./accounts.js";
 import { sendMediaFeishu } from "./media.js";
 import { getFeishuRuntime } from "./runtime.js";
-import { sendMessageFeishu } from "./send.js";
+import { sendMarkdownCardFeishu, sendMessageFeishu } from "./send.js";
+
+function normalizePossibleLocalImagePath(text: string | undefined): string | null {
+  const raw = text?.trim();
+  if (!raw) return null;
+
+  // Only auto-convert when the message is a pure path-like payload.
+  // Avoid converting regular sentences that merely contain a path.
+  const hasWhitespace = /\s/.test(raw);
+  if (hasWhitespace) return null;
+
+  // Ignore links/data URLs; those should stay in normal mediaUrl/text paths.
+  if (/^(https?:\/\/|data:|file:\/\/)/i.test(raw)) return null;
+
+  const ext = path.extname(raw).toLowerCase();
+  const isImageExt = [".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".ico", ".tiff"].includes(
+    ext,
+  );
+  if (!isImageExt) return null;
+
+  if (!path.isAbsolute(raw)) return null;
+  if (!fs.existsSync(raw)) return null;
+
+  // Fix race condition: wrap statSync in try-catch to handle file deletion
+  // between existsSync and statSync
+  try {
+    if (!fs.statSync(raw).isFile()) return null;
+  } catch {
+    // File may have been deleted or became inaccessible between checks
+    return null;
+  }
+
+  return raw;
+}
+
+function shouldUseCard(text: string): boolean {
+  return /```[\s\S]*?```/.test(text) || /\|.+\|[\r\n]+\|[-:| ]+\|/.test(text);
+}
+
+async function sendOutboundText(params: {
+  cfg: Parameters<typeof sendMessageFeishu>[0]["cfg"];
+  to: string;
+  text: string;
+  accountId?: string;
+}) {
+  const { cfg, to, text, accountId } = params;
+  const account = resolveFeishuAccount({ cfg, accountId });
+  const renderMode = account.config?.renderMode ?? "auto";
+
+  if (renderMode === "card" || (renderMode === "auto" && shouldUseCard(text))) {
+    return sendMarkdownCardFeishu({ cfg, to, text, accountId });
+  }
+
+  return sendMessageFeishu({ cfg, to, text, accountId });
+}
 
 export const feishuOutbound: ChannelOutboundAdapter = {
   deliveryMode: "direct",
@@ -9,16 +66,45 @@ export const feishuOutbound: ChannelOutboundAdapter = {
   chunkerMode: "markdown",
   textChunkLimit: 4000,
   sendText: async ({ cfg, to, text, accountId }) => {
-    const result = await sendMessageFeishu({ cfg, to, text, accountId: accountId ?? undefined });
+    // Scheme A compatibility shim:
+    // when upstream accidentally returns a local image path as plain text,
+    // auto-upload and send as Feishu image message instead of leaking path text.
+    const localImagePath = normalizePossibleLocalImagePath(text);
+    if (localImagePath) {
+      try {
+        const result = await sendMediaFeishu({
+          cfg,
+          to,
+          mediaUrl: localImagePath,
+          accountId: accountId ?? undefined,
+        });
+        return { channel: "feishu", ...result };
+      } catch (err) {
+        console.error(`[feishu] local image path auto-send failed:`, err);
+        // fall through to plain text as last resort
+      }
+    }
+
+    const result = await sendOutboundText({
+      cfg,
+      to,
+      text,
+      accountId: accountId ?? undefined,
+    });
     return { channel: "feishu", ...result };
   },
-  sendMedia: async ({ cfg, to, text, mediaUrl, accountId }) => {
+  sendMedia: async ({ cfg, to, text, mediaUrl, accountId, mediaLocalRoots }) => {
     // Send text first if provided
     if (text?.trim()) {
-      await sendMessageFeishu({ cfg, to, text, accountId: accountId ?? undefined });
+      await sendOutboundText({
+        cfg,
+        to,
+        text,
+        accountId: accountId ?? undefined,
+      });
     }
 
-    // Upload and send media if URL provided
+    // Upload and send media if URL or local path provided
     if (mediaUrl) {
       try {
         const result = await sendMediaFeishu({
@@ -26,6 +112,7 @@ export const feishuOutbound: ChannelOutboundAdapter = {
           to,
           mediaUrl,
           accountId: accountId ?? undefined,
+          mediaLocalRoots,
         });
         return { channel: "feishu", ...result };
       } catch (err) {
@@ -33,7 +120,7 @@ export const feishuOutbound: ChannelOutboundAdapter = {
         console.error(`[feishu] sendMediaFeishu failed:`, err);
         // Fallback to URL link if upload fails
         const fallbackText = `📎 ${mediaUrl}`;
-        const result = await sendMessageFeishu({
+        const result = await sendOutboundText({
           cfg,
           to,
           text: fallbackText,
@@ -44,7 +131,7 @@ export const feishuOutbound: ChannelOutboundAdapter = {
     }
 
     // No media URL, just return text result
-    const result = await sendMessageFeishu({
+    const result = await sendOutboundText({
       cfg,
       to,
       text: text ?? "",

package/src/perm.ts

@@ -1,9 +1,8 @@
 import type * as Lark from "@larksuiteoapi/node-sdk";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { listEnabledFeishuAccounts } from "./accounts.js";
-import { createFeishuClient } from "./client.js";
 import { FeishuPermSchema, type FeishuPermParams } from "./perm-schema.js";
-import { resolveToolsConfig } from "./tools-config.js";
+import { createFeishuToolClient, resolveAnyEnabledFeishuToolsConfig } from "./tool-account.js";
 
 // ============ Helpers ============
 
@@ -129,42 +128,50 @@ export function registerFeishuPermTools(api: OpenClawPluginApi) {
     return;
   }
 
-  const firstAccount = accounts[0];
-  const toolsCfg = resolveToolsConfig(firstAccount.config.tools);
+  const toolsCfg = resolveAnyEnabledFeishuToolsConfig(accounts);
   if (!toolsCfg.perm) {
     api.logger.debug?.("feishu_perm: perm tool disabled in config (default: false)");
     return;
   }
 
-  const getClient = () => createFeishuClient(firstAccount);
+  type FeishuPermExecuteParams = FeishuPermParams & { accountId?: string };
 
   api.registerTool(
-    {
-      name: "feishu_perm",
-      label: "Feishu Perm",
-      description: "Feishu permission management. Actions: list, add, remove",
-      parameters: FeishuPermSchema,
-      async execute(_toolCallId, params) {
-        const p = params as FeishuPermParams;
-        try {
-          const client = getClient();
-          switch (p.action) {
-            case "list":
-              return json(await listMembers(client, p.token, p.type));
-            case "add":
-              return json(
-                await addMember(client, p.token, p.type, p.member_type, p.member_id, p.perm),
-              );
-            case "remove":
-              return json(await removeMember(client, p.token, p.type, p.member_type, p.member_id));
-            default:
-              // eslint-disable-next-line @typescript-eslint/no-explicit-any -- exhaustive check fallback
-              return json({ error: `Unknown action: ${(p as any).action}` });
+    (ctx) => {
+      const defaultAccountId = ctx.agentAccountId;
+      return {
+        name: "feishu_perm",
+        label: "Feishu Perm",
+        description: "Feishu permission management. Actions: list, add, remove",
+        parameters: FeishuPermSchema,
+        async execute(_toolCallId, params) {
+          const p = params as FeishuPermExecuteParams;
+          try {
+            const client = createFeishuToolClient({
+              api,
+              executeParams: p,
+              defaultAccountId,
+            });
+            switch (p.action) {
+              case "list":
+                return json(await listMembers(client, p.token, p.type));
+              case "add":
+                return json(
+                  await addMember(client, p.token, p.type, p.member_type, p.member_id, p.perm),
+                );
+              case "remove":
+                return json(
+                  await removeMember(client, p.token, p.type, p.member_type, p.member_id),
+                );
+              default:
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- exhaustive check fallback
+                return json({ error: `Unknown action: ${(p as any).action}` });
+            }
+          } catch (err) {
+            return json({ error: err instanceof Error ? err.message : String(err) });
           }
-        } catch (err) {
-          return json({ error: err instanceof Error ? err.message : String(err) });
-        }
-      },
+        },
+      };
     },
     { name: "feishu_perm" },
   );