@openclaw/feishu 2026.2.25 → 2026.3.2

package/src/card-action.ts

@@ -0,0 +1,79 @@
+import type { ClawdbotConfig, RuntimeEnv } from "openclaw/plugin-sdk";
+import { resolveFeishuAccount } from "./accounts.js";
+import { handleFeishuMessage, type FeishuMessageEvent } from "./bot.js";
+
+export type FeishuCardActionEvent = {
+  operator: {
+    open_id: string;
+    user_id: string;
+    union_id: string;
+  };
+  token: string;
+  action: {
+    value: Record<string, unknown>;
+    tag: string;
+  };
+  context: {
+    open_id: string;
+    user_id: string;
+    chat_id: string;
+  };
+};
+
+export async function handleFeishuCardAction(params: {
+  cfg: ClawdbotConfig;
+  event: FeishuCardActionEvent;
+  botOpenId?: string;
+  runtime?: RuntimeEnv;
+  accountId?: string;
+}): Promise<void> {
+  const { cfg, event, runtime, accountId } = params;
+  const account = resolveFeishuAccount({ cfg, accountId });
+  const log = runtime?.log ?? console.log;
+
+  // Extract action value
+  const actionValue = event.action.value;
+  let content = "";
+  if (typeof actionValue === "object" && actionValue !== null) {
+    if ("text" in actionValue && typeof actionValue.text === "string") {
+      content = actionValue.text;
+    } else if ("command" in actionValue && typeof actionValue.command === "string") {
+      content = actionValue.command;
+    } else {
+      content = JSON.stringify(actionValue);
+    }
+  } else {
+    content = String(actionValue);
+  }
+
+  // Construct a synthetic message event
+  const messageEvent: FeishuMessageEvent = {
+    sender: {
+      sender_id: {
+        open_id: event.operator.open_id,
+        user_id: event.operator.user_id,
+        union_id: event.operator.union_id,
+      },
+    },
+    message: {
+      message_id: `card-action-${event.token}`,
+      chat_id: event.context.chat_id || event.operator.open_id,
+      chat_type: event.context.chat_id ? "group" : "p2p",
+      message_type: "text",
+      content: JSON.stringify({ text: content }),
+    },
+  };
+
+  log(
+    `feishu[${account.accountId}]: handling card action from ${event.operator.open_id}: ${content}`,
+  );
+
+  // Dispatch as normal message
+  await handleFeishuMessage({
+    cfg,
+    event: messageEvent,
+    botOpenId: params.botOpenId,
+    runtime,
+    accountId,
+  });
+}

package/src/channel.ts

@@ -38,6 +38,22 @@ const meta: ChannelMeta = {
   order: 70,
 };
 
+const secretInputJsonSchema = {
+  oneOf: [
+    { type: "string" },
+    {
+      type: "object",
+      additionalProperties: false,
+      required: ["source", "provider", "id"],
+      properties: {
+        source: { type: "string", enum: ["env", "file", "exec"] },
+        provider: { type: "string", minLength: 1 },
+        id: { type: "string", minLength: 1 },
+      },
+    },
+  ],
+} as const;
+
 export const feishuPlugin: ChannelPlugin<ResolvedFeishuAccount> = {
   id: "feishu",
   meta: {
@@ -79,10 +95,11 @@ export const feishuPlugin: ChannelPlugin<ResolvedFeishuAccount> = {
       additionalProperties: false,
       properties: {
         enabled: { type: "boolean" },
+        defaultAccount: { type: "string" },
         appId: { type: "string" },
-        appSecret: { type: "string" },
+        appSecret: secretInputJsonSchema,
         encryptKey: { type: "string" },
-        verificationToken: { type: "string" },
+        verificationToken: secretInputJsonSchema,
         domain: {
           oneOf: [
             { type: "string", enum: ["feishu", "lark"] },
@@ -101,7 +118,12 @@ export const feishuPlugin: ChannelPlugin<ResolvedFeishuAccount> = {
           items: { oneOf: [{ type: "string" }, { type: "number" }] },
         },
         requireMention: { type: "boolean" },
+        groupSessionScope: {
+          type: "string",
+          enum: ["group", "group_sender", "group_topic", "group_topic_sender"],
+        },
         topicSessionMode: { type: "string", enum: ["disabled", "enabled"] },
+        replyInThread: { type: "string", enum: ["disabled", "enabled"] },
         historyLimit: { type: "integer", minimum: 0 },
         dmHistoryLimit: { type: "integer", minimum: 0 },
         textChunkLimit: { type: "integer", minimum: 1 },
@@ -116,9 +138,9 @@ export const feishuPlugin: ChannelPlugin<ResolvedFeishuAccount> = {
               enabled: { type: "boolean" },
               name: { type: "string" },
               appId: { type: "string" },
-              appSecret: { type: "string" },
+              appSecret: secretInputJsonSchema,
               encryptKey: { type: "string" },
-              verificationToken: { type: "string" },
+              verificationToken: secretInputJsonSchema,
               domain: { type: "string", enum: ["feishu", "lark"] },
               connectionMode: { type: "string", enum: ["websocket", "webhook"] },
               webhookHost: { type: "string" },

package/src/chat-schema.ts

@@ -0,0 +1,24 @@
+import { Type, type Static } from "@sinclair/typebox";
+
+const CHAT_ACTION_VALUES = ["members", "info"] as const;
+const MEMBER_ID_TYPE_VALUES = ["open_id", "user_id", "union_id"] as const;
+
+export const FeishuChatSchema = Type.Object({
+  action: Type.Unsafe<(typeof CHAT_ACTION_VALUES)[number]>({
+    type: "string",
+    enum: [...CHAT_ACTION_VALUES],
+    description: "Action to run: members | info",
+  }),
+  chat_id: Type.String({ description: "Chat ID (from URL or event payload)" }),
+  page_size: Type.Optional(Type.Number({ description: "Page size (1-100, default 50)" })),
+  page_token: Type.Optional(Type.String({ description: "Pagination token" })),
+  member_id_type: Type.Optional(
+    Type.Unsafe<(typeof MEMBER_ID_TYPE_VALUES)[number]>({
+      type: "string",
+      enum: [...MEMBER_ID_TYPE_VALUES],
+      description: "Member ID type (default: open_id)",
+    }),
+  ),
+});
+
+export type FeishuChatParams = Static<typeof FeishuChatSchema>;

package/src/chat.test.ts

@@ -0,0 +1,89 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { registerFeishuChatTools } from "./chat.js";
+
+const createFeishuClientMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./client.js", () => ({
+  createFeishuClient: createFeishuClientMock,
+}));
+
+describe("registerFeishuChatTools", () => {
+  const chatGetMock = vi.hoisted(() => vi.fn());
+  const chatMembersGetMock = vi.hoisted(() => vi.fn());
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    createFeishuClientMock.mockReturnValue({
+      im: {
+        chat: { get: chatGetMock },
+        chatMembers: { get: chatMembersGetMock },
+      },
+    });
+  });
+
+  it("registers feishu_chat and handles info/members actions", async () => {
+    const registerTool = vi.fn();
+    registerFeishuChatTools({
+      config: {
+        channels: {
+          feishu: {
+            enabled: true,
+            appId: "app_id",
+            appSecret: "app_secret",
+            tools: { chat: true },
+          },
+        },
+      } as any,
+      logger: { debug: vi.fn(), info: vi.fn() } as any,
+      registerTool,
+    } as any);
+
+    expect(registerTool).toHaveBeenCalledTimes(1);
+    const tool = registerTool.mock.calls[0]?.[0];
+    expect(tool?.name).toBe("feishu_chat");
+
+    chatGetMock.mockResolvedValueOnce({
+      code: 0,
+      data: { name: "group name", user_count: 3 },
+    });
+    const infoResult = await tool.execute("tc_1", { action: "info", chat_id: "oc_1" });
+    expect(infoResult.details).toEqual(
+      expect.objectContaining({ chat_id: "oc_1", name: "group name", user_count: 3 }),
+    );
+
+    chatMembersGetMock.mockResolvedValueOnce({
+      code: 0,
+      data: {
+        has_more: false,
+        page_token: "",
+        items: [{ member_id: "ou_1", name: "member1", member_id_type: "open_id" }],
+      },
+    });
+    const membersResult = await tool.execute("tc_2", { action: "members", chat_id: "oc_1" });
+    expect(membersResult.details).toEqual(
+      expect.objectContaining({
+        chat_id: "oc_1",
+        members: [expect.objectContaining({ member_id: "ou_1", name: "member1" })],
+      }),
+    );
+  });
+
+  it("skips registration when chat tool is disabled", () => {
+    const registerTool = vi.fn();
+    registerFeishuChatTools({
+      config: {
+        channels: {
+          feishu: {
+            enabled: true,
+            appId: "app_id",
+            appSecret: "app_secret",
+            tools: { chat: false },
+          },
+        },
+      } as any,
+      logger: { debug: vi.fn(), info: vi.fn() } as any,
+      registerTool,
+    } as any);
+    expect(registerTool).not.toHaveBeenCalled();
+  });
+});

package/src/chat.ts

@@ -0,0 +1,130 @@
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { listEnabledFeishuAccounts } from "./accounts.js";
+import { FeishuChatSchema, type FeishuChatParams } from "./chat-schema.js";
+import { createFeishuClient } from "./client.js";
+import { resolveToolsConfig } from "./tools-config.js";
+
+function json(data: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+async function getChatInfo(client: Lark.Client, chatId: string) {
+  const res = await client.im.chat.get({ path: { chat_id: chatId } });
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  const chat = res.data;
+  return {
+    chat_id: chatId,
+    name: chat?.name,
+    description: chat?.description,
+    owner_id: chat?.owner_id,
+    tenant_key: chat?.tenant_key,
+    user_count: chat?.user_count,
+    chat_mode: chat?.chat_mode,
+    chat_type: chat?.chat_type,
+    join_message_visibility: chat?.join_message_visibility,
+    leave_message_visibility: chat?.leave_message_visibility,
+    membership_approval: chat?.membership_approval,
+    moderation_permission: chat?.moderation_permission,
+    avatar: chat?.avatar,
+  };
+}
+
+async function getChatMembers(
+  client: Lark.Client,
+  chatId: string,
+  pageSize?: number,
+  pageToken?: string,
+  memberIdType?: "open_id" | "user_id" | "union_id",
+) {
+  const page_size = pageSize ? Math.max(1, Math.min(100, pageSize)) : 50;
+  const res = await client.im.chatMembers.get({
+    path: { chat_id: chatId },
+    params: {
+      page_size,
+      page_token: pageToken,
+      member_id_type: memberIdType ?? "open_id",
+    },
+  });
+
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  return {
+    chat_id: chatId,
+    has_more: res.data?.has_more,
+    page_token: res.data?.page_token,
+    members:
+      res.data?.items?.map((item) => ({
+        member_id: item.member_id,
+        name: item.name,
+        tenant_key: item.tenant_key,
+        member_id_type: item.member_id_type,
+      })) ?? [],
+  };
+}
+
+export function registerFeishuChatTools(api: OpenClawPluginApi) {
+  if (!api.config) {
+    api.logger.debug?.("feishu_chat: No config available, skipping chat tools");
+    return;
+  }
+
+  const accounts = listEnabledFeishuAccounts(api.config);
+  if (accounts.length === 0) {
+    api.logger.debug?.("feishu_chat: No Feishu accounts configured, skipping chat tools");
+    return;
+  }
+
+  const firstAccount = accounts[0];
+  const toolsCfg = resolveToolsConfig(firstAccount.config.tools);
+  if (!toolsCfg.chat) {
+    api.logger.debug?.("feishu_chat: chat tool disabled in config");
+    return;
+  }
+
+  const getClient = () => createFeishuClient(firstAccount);
+
+  api.registerTool(
+    {
+      name: "feishu_chat",
+      label: "Feishu Chat",
+      description: "Feishu chat operations. Actions: members, info",
+      parameters: FeishuChatSchema,
+      async execute(_toolCallId, params) {
+        const p = params as FeishuChatParams;
+        try {
+          const client = getClient();
+          switch (p.action) {
+            case "members":
+              return json(
+                await getChatMembers(
+                  client,
+                  p.chat_id,
+                  p.page_size,
+                  p.page_token,
+                  p.member_id_type,
+                ),
+              );
+            case "info":
+              return json(await getChatInfo(client, p.chat_id));
+            default:
+              return json({ error: `Unknown action: ${String(p.action)}` });
+          }
+        } catch (err) {
+          return json({ error: err instanceof Error ? err.message : String(err) });
+        }
+      },
+    },
+    { name: "feishu_chat" },
+  );
+
+  api.logger.info?.("feishu_chat: Registered feishu_chat tool");
+}

package/src/client.test.ts

@@ -0,0 +1,121 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { FeishuConfig, ResolvedFeishuAccount } from "./types.js";
+
+const wsClientCtorMock = vi.hoisted(() =>
+  vi.fn(function wsClientCtor() {
+    return { connected: true };
+  }),
+);
+const httpsProxyAgentCtorMock = vi.hoisted(() =>
+  vi.fn(function httpsProxyAgentCtor(proxyUrl: string) {
+    return { proxyUrl };
+  }),
+);
+
+vi.mock("@larksuiteoapi/node-sdk", () => ({
+  AppType: { SelfBuild: "self" },
+  Domain: { Feishu: "https://open.feishu.cn", Lark: "https://open.larksuite.com" },
+  LoggerLevel: { info: "info" },
+  Client: vi.fn(),
+  WSClient: wsClientCtorMock,
+  EventDispatcher: vi.fn(),
+}));
+
+vi.mock("https-proxy-agent", () => ({
+  HttpsProxyAgent: httpsProxyAgentCtorMock,
+}));
+
+import { createFeishuWSClient } from "./client.js";
+
+const proxyEnvKeys = ["https_proxy", "HTTPS_PROXY", "http_proxy", "HTTP_PROXY"] as const;
+type ProxyEnvKey = (typeof proxyEnvKeys)[number];
+
+let priorProxyEnv: Partial<Record<ProxyEnvKey, string | undefined>> = {};
+
+const baseAccount: ResolvedFeishuAccount = {
+  accountId: "main",
+  selectionSource: "explicit",
+  enabled: true,
+  configured: true,
+  appId: "app_123",
+  appSecret: "secret_123",
+  domain: "feishu",
+  config: {} as FeishuConfig,
+};
+
+function firstWsClientOptions(): { agent?: unknown } {
+  const calls = wsClientCtorMock.mock.calls as unknown as Array<[options: { agent?: unknown }]>;
+  return calls[0]?.[0] ?? {};
+}
+
+beforeEach(() => {
+  priorProxyEnv = {};
+  for (const key of proxyEnvKeys) {
+    priorProxyEnv[key] = process.env[key];
+    delete process.env[key];
+  }
+  vi.clearAllMocks();
+});
+
+afterEach(() => {
+  for (const key of proxyEnvKeys) {
+    const value = priorProxyEnv[key];
+    if (value === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+});
+
+describe("createFeishuWSClient proxy handling", () => {
+  it("does not set a ws proxy agent when proxy env is absent", () => {
+    createFeishuWSClient(baseAccount);
+
+    expect(httpsProxyAgentCtorMock).not.toHaveBeenCalled();
+    const options = firstWsClientOptions();
+    expect(options?.agent).toBeUndefined();
+  });
+
+  it("prefers HTTPS proxy vars over HTTP proxy vars across runtimes", () => {
+    process.env.https_proxy = "http://lower-https:8001";
+    process.env.HTTPS_PROXY = "http://upper-https:8002";
+    process.env.http_proxy = "http://lower-http:8003";
+    process.env.HTTP_PROXY = "http://upper-http:8004";
+
+    createFeishuWSClient(baseAccount);
+
+    // On Windows env keys are case-insensitive, so setting HTTPS_PROXY may
+    // overwrite https_proxy. We assert https proxies still win over http.
+    const expectedProxy = process.env.https_proxy || process.env.HTTPS_PROXY;
+    expect(expectedProxy).toBeTruthy();
+    expect(httpsProxyAgentCtorMock).toHaveBeenCalledTimes(1);
+    expect(httpsProxyAgentCtorMock).toHaveBeenCalledWith(expectedProxy);
+    const options = firstWsClientOptions();
+    expect(options.agent).toEqual({ proxyUrl: expectedProxy });
+  });
+
+  it("accepts lowercase https_proxy when it is the configured HTTPS proxy var", () => {
+    process.env.https_proxy = "http://lower-https:8001";
+
+    createFeishuWSClient(baseAccount);
+
+    const expectedHttpsProxy = process.env.https_proxy || process.env.HTTPS_PROXY;
+    expect(httpsProxyAgentCtorMock).toHaveBeenCalledTimes(1);
+    expect(expectedHttpsProxy).toBeTruthy();
+    expect(httpsProxyAgentCtorMock).toHaveBeenCalledWith(expectedHttpsProxy);
+    const options = firstWsClientOptions();
+    expect(options.agent).toEqual({ proxyUrl: expectedHttpsProxy });
+  });
+
+  it("passes HTTP_PROXY to ws client when https vars are unset", () => {
+    process.env.HTTP_PROXY = "http://upper-http:8999";
+
+    createFeishuWSClient(baseAccount);
+
+    expect(httpsProxyAgentCtorMock).toHaveBeenCalledTimes(1);
+    expect(httpsProxyAgentCtorMock).toHaveBeenCalledWith("http://upper-http:8999");
+    const options = firstWsClientOptions();
+    expect(options.agent).toEqual({ proxyUrl: "http://upper-http:8999" });
+  });
+});

package/src/client.ts

@@ -1,6 +1,17 @@
 import * as Lark from "@larksuiteoapi/node-sdk";
+import { HttpsProxyAgent } from "https-proxy-agent";
 import type { FeishuDomain, ResolvedFeishuAccount } from "./types.js";
 
+function getWsProxyAgent(): HttpsProxyAgent<string> | undefined {
+  const proxyUrl =
+    process.env.https_proxy ||
+    process.env.HTTPS_PROXY ||
+    process.env.http_proxy ||
+    process.env.HTTP_PROXY;
+  if (!proxyUrl) return undefined;
+  return new HttpsProxyAgent(proxyUrl);
+}
+
 // Multi-account client cache
 const clientCache = new Map<
   string,
@@ -81,11 +92,13 @@ export function createFeishuWSClient(account: ResolvedFeishuAccount): Lark.WSCli
     throw new Error(`Feishu credentials not configured for account "${accountId}"`);
   }
 
+  const agent = getWsProxyAgent();
   return new Lark.WSClient({
     appId,
     appSecret,
     domain: resolveDomain(domain),
     loggerLevel: Lark.LoggerLevel.info,
+    ...(agent ? { agent } : {}),
   });
 }
 

package/src/config-schema.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { FeishuConfigSchema } from "./config-schema.js";
+import { FeishuConfigSchema, FeishuGroupSchema } from "./config-schema.js";
 
 describe("FeishuConfigSchema webhook validation", () => {
   it("applies top-level defaults", () => {
@@ -85,4 +85,104 @@ describe("FeishuConfigSchema webhook validation", () => {
 
     expect(result.success).toBe(true);
   });
+
+  it("accepts SecretRef verificationToken in webhook mode", () => {
+    const result = FeishuConfigSchema.safeParse({
+      connectionMode: "webhook",
+      verificationToken: {
+        source: "env",
+        provider: "default",
+        id: "FEISHU_VERIFICATION_TOKEN",
+      },
+      appId: "cli_top",
+      appSecret: {
+        source: "env",
+        provider: "default",
+        id: "FEISHU_APP_SECRET",
+      },
+    });
+
+    expect(result.success).toBe(true);
+  });
+});
+
+describe("FeishuConfigSchema replyInThread", () => {
+  it("accepts replyInThread at top level", () => {
+    const result = FeishuConfigSchema.parse({ replyInThread: "enabled" });
+    expect(result.replyInThread).toBe("enabled");
+  });
+
+  it("defaults replyInThread to undefined when not set", () => {
+    const result = FeishuConfigSchema.parse({});
+    expect(result.replyInThread).toBeUndefined();
+  });
+
+  it("rejects invalid replyInThread value", () => {
+    const result = FeishuConfigSchema.safeParse({ replyInThread: "always" });
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts replyInThread in group config", () => {
+    const result = FeishuGroupSchema.parse({ replyInThread: "enabled" });
+    expect(result.replyInThread).toBe("enabled");
+  });
+
+  it("accepts replyInThread in account config", () => {
+    const result = FeishuConfigSchema.parse({
+      accounts: {
+        main: { replyInThread: "enabled" },
+      },
+    });
+    expect(result.accounts?.main?.replyInThread).toBe("enabled");
+  });
+});
+
+describe("FeishuConfigSchema optimization flags", () => {
+  it("defaults top-level typingIndicator and resolveSenderNames to true", () => {
+    const result = FeishuConfigSchema.parse({});
+    expect(result.typingIndicator).toBe(true);
+    expect(result.resolveSenderNames).toBe(true);
+  });
+
+  it("accepts account-level optimization flags", () => {
+    const result = FeishuConfigSchema.parse({
+      accounts: {
+        main: {
+          typingIndicator: false,
+          resolveSenderNames: false,
+        },
+      },
+    });
+    expect(result.accounts?.main?.typingIndicator).toBe(false);
+    expect(result.accounts?.main?.resolveSenderNames).toBe(false);
+  });
+});
+
+describe("FeishuConfigSchema defaultAccount", () => {
+  it("accepts defaultAccount when it matches an account key", () => {
+    const result = FeishuConfigSchema.safeParse({
+      defaultAccount: "router-d",
+      accounts: {
+        "router-d": { appId: "cli_router", appSecret: "secret_router" },
+      },
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects defaultAccount when it does not match an account key", () => {
+    const result = FeishuConfigSchema.safeParse({
+      defaultAccount: "router-d",
+      accounts: {
+        backup: { appId: "cli_backup", appSecret: "secret_backup" },
+      },
+    });
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.issues.some((issue) => issue.path.join(".") === "defaultAccount")).toBe(
+        true,
+      );
+    }
+  });
 });