@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/channel/monitor.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * WebSocket monitoring for the Lark/Feishu channel plugin.
+ *
+ * Manages per-account WSClient connections and routes inbound Feishu
+ * events (messages, bot membership changes, read receipts) to the
+ * appropriate handlers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.monitorFeishuProvider = monitorFeishuProvider;
+const accounts_1 = require("../core/accounts.js");
+const lark_client_1 = require("../core/lark-client.js");
+const lark_logger_1 = require("../core/lark-logger.js");
+const shutdown_hooks_1 = require("../core/shutdown-hooks.js");
+const dedup_1 = require("../messaging/inbound/dedup.js");
+const event_handlers_1 = require("./event-handlers.js");
+const mlog = (0, lark_logger_1.larkLogger)('channel/monitor');
+// ---------------------------------------------------------------------------
+// Single-account monitor
+// ---------------------------------------------------------------------------
+/**
+ * Start monitoring a single Feishu account.
+ *
+ * Creates a LarkClient, probes bot identity, registers event handlers,
+ * and starts a WebSocket connection. Returns a Promise that resolves
+ * when the abort signal fires (or immediately if already aborted).
+ */
+async function monitorSingleAccount(params) {
+    const { account, runtime, abortSignal } = params;
+    const { accountId } = account;
+    const log = runtime?.log ?? ((...args) => mlog.info(args.map(String).join(' ')));
+    const error = runtime?.error ?? ((...args) => mlog.error(args.map(String).join(' ')));
+    // Only websocket mode is supported in the monitor path.
+    const connectionMode = account.config.connectionMode ?? 'websocket';
+    if (connectionMode !== 'websocket') {
+        log(`feishu[${accountId}]: webhook mode not implemented in monitor`);
+        return;
+    }
+    // Message dedup — filters duplicate deliveries from WebSocket reconnects.
+    const dedupCfg = account.config.dedup;
+    const messageDedup = new dedup_1.MessageDedup({
+        ttlMs: dedupCfg?.ttlMs,
+        maxEntries: dedupCfg?.maxEntries,
+    });
+    log(`feishu[${accountId}]: message dedup enabled (ttl=${messageDedup['ttlMs']}ms, max=${messageDedup['maxEntries']})`);
+    log(`feishu[${accountId}]: starting WebSocket connection...`);
+    // Create LarkClient instance — manages SDK client, WS, and bot identity.
+    const lark = lark_client_1.LarkClient.fromAccount(account);
+    // Attach dedup instance so it is disposed together with the client.
+    lark.messageDedup = messageDedup;
+    /** Per-chat history maps (used for group-chat context window). */
+    const chatHistories = new Map();
+    const ctx = {
+        get cfg() {
+            return lark_client_1.LarkClient.runtime.config.loadConfig();
+        },
+        lark,
+        accountId,
+        chatHistories,
+        messageDedup,
+        runtime,
+        log,
+        error,
+    };
+    await lark.startWS({
+        handlers: {
+            'im.message.receive_v1': (data) => (0, event_handlers_1.handleMessageEvent)(ctx, data),
+            'im.message.message_read_v1': async () => { },
+            'im.message.reaction.created_v1': (data) => (0, event_handlers_1.handleReactionEvent)(ctx, data),
+            // These events are expected in normal usage but do not affect the
+            // plugin's current behavior. Register no-op handlers to avoid SDK
+            // warnings about missing handlers.
+            'im.message.reaction.deleted_v1': async () => { },
+            'im.chat.access_event.bot_p2p_chat_entered_v1': async () => { },
+            'im.chat.member.bot.added_v1': (data) => (0, event_handlers_1.handleBotMembershipEvent)(ctx, data, 'added'),
+            'im.chat.member.bot.deleted_v1': (data) => (0, event_handlers_1.handleBotMembershipEvent)(ctx, data, 'removed'),
+            'vc.bot.meeting_invited_v1': (data) => (0, event_handlers_1.handleVcMeetingInvitedEvent)(ctx, data),
+            // Drive comment event — fires when a user adds a comment or reply on a document.
+            'drive.notice.comment_add_v1': (data) => (0, event_handlers_1.handleCommentEvent)(ctx, data),
+            // 飞书 SDK EventDispatcher.register 不支持带返回值的处理器，此处 as any 是 SDK 类型限制的变通
+            'card.action.trigger': ((data) => 
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (0, event_handlers_1.handleCardActionEvent)(ctx, data)),
+        },
+        abortSignal,
+    });
+    // startWS resolves when abortSignal fires — probe result is logged inside startWS.
+    log(`feishu[${accountId}]: bot open_id resolved: ${lark.botOpenId ?? 'unknown'}`);
+    log(`feishu[${accountId}]: WebSocket client started`);
+    mlog.info(`websocket started for account ${accountId}`);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Start monitoring for all enabled Feishu accounts (or a single
+ * account when `opts.accountId` is specified).
+ */
+async function monitorFeishuProvider(opts = {}) {
+    const cfg = opts.config;
+    if (!cfg) {
+        throw new Error('Config is required for Feishu monitor');
+    }
+    // Store the original global config so plugin commands (doctor, diagnose)
+    // can access cross-account information even when running inside an
+    // account-scoped config context.
+    lark_client_1.LarkClient.setGlobalConfig(cfg);
+    const log = opts.runtime?.log ?? ((...args) => mlog.info(args.map(String).join(' ')));
+    // Single-account mode.
+    if (opts.accountId) {
+        const account = (0, accounts_1.getLarkAccount)(cfg, opts.accountId);
+        if (!account.enabled || !account.configured) {
+            throw new Error(`Feishu account "${opts.accountId}" not configured or disabled`);
+        }
+        await monitorSingleAccount({
+            cfg,
+            account,
+            runtime: opts.runtime,
+            abortSignal: opts.abortSignal,
+        });
+        await (0, shutdown_hooks_1.drainShutdownHooks)({ log });
+        return;
+    }
+    // Multi-account mode: start all enabled accounts in parallel.
+    const accounts = (0, accounts_1.getEnabledLarkAccounts)(cfg);
+    if (accounts.length === 0) {
+        throw new Error('No enabled Feishu accounts configured');
+    }
+    log(`feishu: starting ${accounts.length} account(s): ${accounts.map((a) => a.accountId).join(', ')}`);
+    await Promise.all(accounts.map((account) => monitorSingleAccount({
+        cfg,
+        account,
+        runtime: opts.runtime,
+        abortSignal: opts.abortSignal,
+    })));
+    await (0, shutdown_hooks_1.drainShutdownHooks)({ log });
+}

package/src/channel/onboarding-config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Onboarding configuration mutation helpers.
+ *
+ * Pure functions that apply Feishu channel configuration changes
+ * to a ClawdbotConfig. Extracted from onboarding.ts for reuse
+ * in CLI commands and other configuration flows.
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+import type { DmPolicy } from 'openclaw/plugin-sdk/setup';
+export declare function setFeishuDmPolicy(cfg: ClawdbotConfig, dmPolicy: DmPolicy): ClawdbotConfig;
+export declare function setFeishuAllowFrom(cfg: ClawdbotConfig, allowFrom: string[]): ClawdbotConfig;
+export declare function setFeishuGroupPolicy(cfg: ClawdbotConfig, groupPolicy: 'open' | 'allowlist' | 'disabled'): ClawdbotConfig;
+export declare function setFeishuGroupAllowFrom(cfg: ClawdbotConfig, groupAllowFrom: string[]): ClawdbotConfig;
+export declare function setFeishuGroups(cfg: ClawdbotConfig, groups: Record<string, object>): ClawdbotConfig;
+export declare function parseAllowFromInput(raw: string): string[];

package/src/channel/onboarding-config.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Onboarding configuration mutation helpers.
+ *
+ * Pure functions that apply Feishu channel configuration changes
+ * to a ClawdbotConfig. Extracted from onboarding.ts for reuse
+ * in CLI commands and other configuration flows.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setFeishuDmPolicy = setFeishuDmPolicy;
+exports.setFeishuAllowFrom = setFeishuAllowFrom;
+exports.setFeishuGroupPolicy = setFeishuGroupPolicy;
+exports.setFeishuGroupAllowFrom = setFeishuGroupAllowFrom;
+exports.setFeishuGroups = setFeishuGroups;
+exports.parseAllowFromInput = parseAllowFromInput;
+const setup_1 = require("openclaw/plugin-sdk/setup");
+// ---------------------------------------------------------------------------
+// Config mutation helpers
+// ---------------------------------------------------------------------------
+function setFeishuDmPolicy(cfg, dmPolicy) {
+    const allowFrom = dmPolicy === 'open'
+        ? (0, setup_1.addWildcardAllowFrom)(cfg.channels?.feishu?.allowFrom)?.map((entry) => String(entry))
+        : undefined;
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            feishu: {
+                ...cfg.channels?.feishu,
+                dmPolicy,
+                ...(allowFrom ? { allowFrom } : {}),
+            },
+        },
+    };
+}
+function setFeishuAllowFrom(cfg, allowFrom) {
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            feishu: {
+                ...cfg.channels?.feishu,
+                allowFrom,
+            },
+        },
+    };
+}
+function setFeishuGroupPolicy(cfg, groupPolicy) {
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            feishu: {
+                ...cfg.channels?.feishu,
+                enabled: true,
+                groupPolicy,
+            },
+        },
+    };
+}
+function setFeishuGroupAllowFrom(cfg, groupAllowFrom) {
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            feishu: {
+                ...cfg.channels?.feishu,
+                groupAllowFrom,
+            },
+        },
+    };
+}
+function setFeishuGroups(cfg, groups) {
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            feishu: {
+                ...cfg.channels?.feishu,
+                groups,
+            },
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Input helpers
+// ---------------------------------------------------------------------------
+function parseAllowFromInput(raw) {
+    return raw
+        .split(/[\n,;]+/g)
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}

package/src/channel/onboarding-migrate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Legacy groupAllowFrom migration for Feishu onboarding.
+ *
+ * Handles the migration of chat_id entries (oc_xxx) from
+ * groupAllowFrom to the groups config, preserving the original
+ * semantic of "allow this group for any sender".
+ */
+import type { ClawdbotConfig, WizardPrompter } from 'openclaw/plugin-sdk';
+/**
+ * Detect and migrate legacy chat_id entries in groupAllowFrom.
+ *
+ * Old semantic: groupAllowFrom contained chat_ids (oc_xxx) to control
+ * which groups could use the bot.
+ * New semantic: groupAllowFrom is for sender filtering (open_ids like ou_xxx).
+ *
+ * This function prompts the user and, if confirmed, moves chat_ids
+ * to the groups config and keeps only sender IDs in groupAllowFrom.
+ */
+export declare function migrateLegacyGroupAllowFrom(params: {
+    cfg: ClawdbotConfig;
+    prompter: WizardPrompter;
+}): Promise<ClawdbotConfig>;

package/src/channel/onboarding-migrate.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Legacy groupAllowFrom migration for Feishu onboarding.
+ *
+ * Handles the migration of chat_id entries (oc_xxx) from
+ * groupAllowFrom to the groups config, preserving the original
+ * semantic of "allow this group for any sender".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migrateLegacyGroupAllowFrom = migrateLegacyGroupAllowFrom;
+const onboarding_config_1 = require("./onboarding-config.js");
+/**
+ * Detect and migrate legacy chat_id entries in groupAllowFrom.
+ *
+ * Old semantic: groupAllowFrom contained chat_ids (oc_xxx) to control
+ * which groups could use the bot.
+ * New semantic: groupAllowFrom is for sender filtering (open_ids like ou_xxx).
+ *
+ * This function prompts the user and, if confirmed, moves chat_ids
+ * to the groups config and keeps only sender IDs in groupAllowFrom.
+ */
+async function migrateLegacyGroupAllowFrom(params) {
+    let next = params.cfg;
+    const { prompter } = params;
+    const existingGroupAllowFrom = next.channels?.feishu?.groupAllowFrom ?? [];
+    const legacyChatIds = existingGroupAllowFrom.filter((e) => String(e).startsWith('oc_'));
+    const senderAllowFrom = existingGroupAllowFrom.filter((e) => !String(e).startsWith('oc_'));
+    if (legacyChatIds.length === 0) {
+        return next;
+    }
+    await prompter.note([
+        `⚠️  Detected legacy config: groupAllowFrom contains chat_ids (${legacyChatIds.join(', ')})`,
+        '',
+        'Old semantic: groupAllowFrom controlled which groups could use the bot.',
+        'New semantic: groupAllowFrom is for SENDER filtering (open_ids like ou_xxx).',
+        '',
+        'Recommended migration:',
+        `  1. Move chat_ids (oc_xxx) → channels.feishu.groups`,
+        `  2. Keep sender IDs (ou_xxx) in groupAllowFrom`,
+    ].join('\n'), 'Legacy config detected');
+    const migrate = await prompter.confirm({
+        message: `Migrate ${legacyChatIds.length} chat_id(s) to groups config?`,
+        initialValue: true,
+    });
+    if (migrate) {
+        const existingGroups = next.channels?.feishu?.groups ?? {};
+        const migratedGroups = {
+            ...existingGroups,
+        };
+        for (const chatId of legacyChatIds) {
+            if (!migratedGroups[String(chatId)]) {
+                migratedGroups[String(chatId)] = {
+                    enabled: true,
+                    groupPolicy: 'open',
+                };
+            }
+        }
+        next = (0, onboarding_config_1.setFeishuGroups)(next, migratedGroups);
+        next = (0, onboarding_config_1.setFeishuGroupAllowFrom)(next, senderAllowFrom);
+        await prompter.note(`✅ Migrated: ${legacyChatIds.length} chat_id(s) moved to groups, ` +
+            `${senderAllowFrom.length} sender(s) kept in groupAllowFrom`, 'Migration complete');
+    }
+    else {
+        await prompter.note('Skipped migration. Please update config manually to avoid issues.', 'Migration skipped');
+    }
+    return next;
+}

package/src/channel/onboarding.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Onboarding wizard adapter for the Lark/Feishu channel plugin.
+ *
+ * Implements the ChannelOnboardingAdapter interface so the `openclaw
+ * setup` wizard can configure Feishu credentials, domain, group
+ * policies, and DM allowlists interactively.
+ */
+import type { ChannelSetupWizardAdapter } from 'openclaw/plugin-sdk/setup';
+export declare const feishuOnboardingAdapter: ChannelSetupWizardAdapter;

package/src/channel/onboarding.js

@@ -0,0 +1,300 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Onboarding wizard adapter for the Lark/Feishu channel plugin.
+ *
+ * Implements the ChannelOnboardingAdapter interface so the `openclaw
+ * setup` wizard can configure Feishu credentials, domain, group
+ * policies, and DM allowlists interactively.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.feishuOnboardingAdapter = void 0;
+const account_id_1 = require("openclaw/plugin-sdk/account-id");
+const setup_1 = require("openclaw/plugin-sdk/setup");
+const accounts_1 = require("../core/accounts.js");
+const probe_1 = require("./probe.js");
+const onboarding_config_1 = require("./onboarding-config.js");
+const onboarding_migrate_1 = require("./onboarding-migrate.js");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const channel = 'feishu';
+// ---------------------------------------------------------------------------
+// Prompter helpers
+// ---------------------------------------------------------------------------
+async function noteFeishuCredentialHelp(prompter) {
+    await prompter.note([
+        '1) Go to Feishu Open Platform (open.feishu.cn)',
+        '2) Create a self-built app',
+        '3) Get App ID and App Secret from Credentials page',
+        '4) Enable required permissions: im:message, im:chat, contact:user.base:readonly',
+        '5) Publish the app or add it to a test group',
+        'Tip: you can also set FEISHU_APP_ID / FEISHU_APP_SECRET env vars.',
+        `Docs: ${(0, setup_1.formatDocsLink)('/channels/feishu', 'feishu')}`,
+    ].join('\n'), 'Feishu credentials');
+}
+async function promptFeishuAllowFrom(params) {
+    const existing = params.cfg.channels?.feishu?.allowFrom ?? [];
+    await params.prompter.note([
+        'Allowlist Feishu DMs by open_id or user_id.',
+        'You can find user open_id in Feishu admin console or via API.',
+        'Examples:',
+        '- ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+        '- on_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+    ].join('\n'), 'Feishu allowlist');
+    while (true) {
+        const entry = await params.prompter.text({
+            message: 'Feishu allowFrom (user open_ids)',
+            placeholder: 'ou_xxxxx, ou_yyyyy',
+            initialValue: existing[0] ? String(existing[0]) : undefined,
+            validate: (value) => (String(value ?? '').trim() ? undefined : 'Required'),
+        });
+        const parts = (0, onboarding_config_1.parseAllowFromInput)(String(entry));
+        if (parts.length === 0) {
+            await params.prompter.note('Enter at least one user.', 'Feishu allowlist');
+            continue;
+        }
+        const unique = [...new Set([...existing.map((v) => String(v).trim()).filter(Boolean), ...parts])];
+        return (0, onboarding_config_1.setFeishuAllowFrom)(params.cfg, unique);
+    }
+}
+// ---------------------------------------------------------------------------
+// Credential acquisition
+// ---------------------------------------------------------------------------
+async function acquireCredentials(params) {
+    const { prompter, feishuCfg } = params;
+    let next = params.cfg;
+    const hasConfigCreds = Boolean(feishuCfg?.appId?.trim() && feishuCfg?.appSecret?.trim());
+    const canUseEnv = Boolean(!hasConfigCreds && process.env.FEISHU_APP_ID?.trim() && process.env.FEISHU_APP_SECRET?.trim());
+    let appId = null;
+    let appSecret = null;
+    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 {
+            appId = String(await prompter.text({
+                message: 'Enter Feishu App ID',
+                validate: (value) => (value?.trim() ? undefined : 'Required'),
+            })).trim();
+            appSecret = String(await prompter.text({
+                message: 'Enter Feishu App Secret',
+                validate: (value) => (value?.trim() ? undefined : 'Required'),
+            })).trim();
+        }
+    }
+    else if (hasConfigCreds) {
+        const keep = await prompter.confirm({
+            message: 'Feishu credentials already configured. Keep them?',
+            initialValue: true,
+        });
+        if (!keep) {
+            appId = String(await prompter.text({
+                message: 'Enter Feishu App ID',
+                validate: (value) => (value?.trim() ? undefined : 'Required'),
+            })).trim();
+            appSecret = String(await prompter.text({
+                message: 'Enter Feishu App Secret',
+                validate: (value) => (value?.trim() ? undefined : 'Required'),
+            })).trim();
+        }
+    }
+    else {
+        appId = String(await prompter.text({
+            message: 'Enter Feishu App ID',
+            validate: (value) => (value?.trim() ? undefined : 'Required'),
+        })).trim();
+        appSecret = String(await prompter.text({
+            message: 'Enter Feishu App Secret',
+            validate: (value) => (value?.trim() ? undefined : 'Required'),
+        })).trim();
+    }
+    return { cfg: next, appId, appSecret };
+}
+// ---------------------------------------------------------------------------
+// DM policy
+// ---------------------------------------------------------------------------
+const dmPolicy = {
+    label: 'Feishu',
+    channel,
+    policyKey: 'channels.feishu.dmPolicy',
+    allowFromKey: 'channels.feishu.allowFrom',
+    getCurrent: (cfg) => cfg.channels?.feishu?.dmPolicy ?? 'pairing',
+    setPolicy: (cfg, policy) => (0, onboarding_config_1.setFeishuDmPolicy)(cfg, policy),
+    promptAllowFrom: promptFeishuAllowFrom,
+};
+// ---------------------------------------------------------------------------
+// Adapter
+// ---------------------------------------------------------------------------
+exports.feishuOnboardingAdapter = {
+    channel,
+    // -----------------------------------------------------------------------
+    // getStatus
+    // -----------------------------------------------------------------------
+    getStatus: async ({ cfg }) => {
+        const feishuCfg = cfg.channels?.feishu;
+        const configured = Boolean((0, accounts_1.getLarkCredentials)(feishuCfg));
+        // Attempt a live probe when credentials are present.
+        let probeResult = null;
+        if (configured && feishuCfg) {
+            try {
+                probeResult = await (0, probe_1.probeFeishu)(feishuCfg);
+            }
+            catch {
+                // Ignore probe errors -- status degrades gracefully.
+            }
+        }
+        const statusLines = [];
+        if (!configured) {
+            statusLines.push('Feishu: needs app credentials');
+        }
+        else if (probeResult?.ok) {
+            statusLines.push(`Feishu: connected as ${probeResult.botName ?? probeResult.botOpenId ?? 'bot'}`);
+        }
+        else {
+            statusLines.push('Feishu: configured (connection not verified)');
+        }
+        return {
+            channel,
+            configured,
+            statusLines,
+            selectionHint: configured ? 'configured' : 'needs app creds',
+            quickstartScore: configured ? 2 : 0,
+        };
+    },
+    // -----------------------------------------------------------------------
+    // configure
+    // -----------------------------------------------------------------------
+    configure: async ({ cfg, prompter }) => {
+        const feishuCfg = cfg.channels?.feishu;
+        const resolved = (0, accounts_1.getLarkCredentials)(feishuCfg);
+        let next = cfg;
+        // Show credential help if nothing is configured yet.
+        if (!resolved) {
+            await noteFeishuCredentialHelp(prompter);
+        }
+        // --- Credential acquisition ---
+        const creds = await acquireCredentials({ cfg: next, prompter, feishuCfg });
+        next = creds.cfg;
+        // --- Persist and test credentials ---
+        if (creds.appId && creds.appSecret) {
+            next = {
+                ...next,
+                channels: {
+                    ...next.channels,
+                    feishu: {
+                        ...next.channels?.feishu,
+                        enabled: true,
+                        appId: creds.appId,
+                        appSecret: creds.appSecret,
+                    },
+                },
+            };
+            const testCfg = next.channels?.feishu;
+            try {
+                const probe = await (0, probe_1.probeFeishu)(testCfg);
+                if (probe.ok) {
+                    await prompter.note(`Connected as ${probe.botName ?? probe.botOpenId ?? 'bot'}`, 'Feishu connection test');
+                }
+                else {
+                    await prompter.note(`Connection failed: ${probe.error ?? 'unknown error'}`, 'Feishu connection test');
+                }
+            }
+            catch (err) {
+                await prompter.note(`Connection test failed: ${String(err)}`, 'Feishu connection test');
+            }
+        }
+        // --- Domain selection ---
+        const currentDomain = next.channels?.feishu?.domain ?? 'feishu';
+        const domain = await prompter.select({
+            message: 'Which Feishu domain?',
+            options: [
+                { value: 'feishu', label: 'Feishu (feishu.cn) - China' },
+                { value: 'lark', label: 'Lark (larksuite.com) - International' },
+            ],
+            initialValue: currentDomain,
+        });
+        if (domain) {
+            next = {
+                ...next,
+                channels: {
+                    ...next.channels,
+                    feishu: {
+                        ...next.channels?.feishu,
+                        domain: domain,
+                    },
+                },
+            };
+        }
+        // --- Legacy migration ---
+        next = await (0, onboarding_migrate_1.migrateLegacyGroupAllowFrom)({ cfg: next, prompter });
+        // --- Group policy ---
+        const groupPolicy = await prompter.select({
+            message: 'Group chat policy — which groups can interact with the bot?',
+            options: [
+                {
+                    value: 'allowlist',
+                    label: 'Allowlist — only groups listed in `groups` config (default)',
+                },
+                {
+                    value: 'open',
+                    label: 'Open — any group (requires @mention)',
+                },
+                {
+                    value: 'disabled',
+                    label: 'Disabled — no group interactions',
+                },
+            ],
+            initialValue: next.channels?.feishu?.groupPolicy ?? 'allowlist',
+        });
+        if (groupPolicy) {
+            next = (0, onboarding_config_1.setFeishuGroupPolicy)(next, groupPolicy);
+        }
+        // --- Group sender allowlist ---
+        if (groupPolicy !== 'disabled') {
+            const existing = next.channels?.feishu?.groupAllowFrom ?? [];
+            const entry = await prompter.text({
+                message: 'Group sender allowlist — which users can trigger the bot in allowed groups? (user open_ids)',
+                placeholder: 'ou_xxxxx, ou_yyyyy',
+                initialValue: existing.length > 0 ? existing.map(String).join(', ') : undefined,
+            });
+            if (entry) {
+                const parts = (0, onboarding_config_1.parseAllowFromInput)(String(entry));
+                if (parts.length > 0) {
+                    next = (0, onboarding_config_1.setFeishuGroupAllowFrom)(next, parts);
+                }
+            }
+            else if (groupPolicy === 'allowlist') {
+                await prompter.note('Empty sender list + allowlist = nobody can trigger. ' +
+                    "Use groupPolicy 'open' if you want anyone in allowed groups to trigger.", 'Note');
+            }
+        }
+        return { cfg: next, accountId: account_id_1.DEFAULT_ACCOUNT_ID };
+    },
+    // -----------------------------------------------------------------------
+    // dmPolicy
+    // -----------------------------------------------------------------------
+    dmPolicy,
+    // -----------------------------------------------------------------------
+    // disable
+    // -----------------------------------------------------------------------
+    disable: (cfg) => ({
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            feishu: { ...cfg.channels?.feishu, enabled: false },
+        },
+    }),
+};

package/src/channel/plugin.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * ChannelPlugin interface implementation for the Lark/Feishu channel.
+ *
+ * This is the top-level entry point that the OpenClaw plugin system uses to
+ * discover capabilities, resolve accounts, obtain outbound adapters, and
+ * start the inbound event gateway.
+ */
+import type { ChannelPlugin } from 'openclaw/plugin-sdk';
+import type { LarkAccount } from '../core/types';
+export declare const feishuPlugin: ChannelPlugin<LarkAccount>;