clawd-feishu Feishu/Lark (飞书) channel plugin for OpenClaw

1. Overview

• This document describes the Feishu/Lark (飞书) channel plugin for OpenClaw, a bridge that enables OpenClaw to interact with Feishu/Lark ecosystems through a range of permissions, event subscriptions, and tools.
• The plugin supports a comprehensive set of Feishu resources such as messages, drives, wiki, bitable, tasks, chats, and notifications, enabling automated agents to read, write, and manage content within Feishu environments.
• It covers installation, upgrade, configuration, permission scoping, event subscriptions, dynamic agent creation, and troubleshooting, with parallel sections in English and Chinese for accessibility.

1. Sponsor and Images

• Sponsorship helps sustain the project and its ecosystem. The English and Chinese sections acknowledge sponsors who provide value-added services and API access.
• Visual reference: an image is included to recognize the sponsor YouYun Zhisuan, shown as an asset named sponsor-youyunzhisuan.png. This image appears in the sponsor area of the documentation to credit support.
• Note: The sponsor image serves as a visual confirmation of collaboration and is referenced directly from the repository’s assets.

1. English Installation

• To begin, install the Feishu plugin for OpenClaw with a single command:
• openclaw plugins install @m1heng-clawd/feishu
• If you encounter Windows-specific issues during installation (spawn npm ENOENT), there are manual alternatives:
• Option A (recommended): download the latest tarball, pack it with npm pack @m1heng-clawd/feishu, then install from the generated tarball file.
• Option B (curl-based): resolve the latest tarball URL from npm and download, then install from the tarball.
• Option C (no npm): fetch the latest tarball URL directly from the npm registry and install from that tarball.
• Upgrading the plugin is straightforward:
• openclaw plugins update feishu
• Verify the installed version with: openclaw plugins list | rg -i feishu
• Configuration prerequisites include creating a self-built app on Feishu Open Platform, obtaining App ID and App Secret, enabling required permissions, and configuring event subscriptions.
• The installation section emphasizes the importance of using the proper connection mode (websocket is recommended for most deployments) and highlights Windows-specific workarounds to ensure a smooth setup experience.

1. Upgrade

• To keep your Feishu integration current, perform periodic upgrades:
• Command: openclaw plugins update feishu
• After upgrading, confirm the version by listing installed plugins and filtering for feishu:
• Command: openclaw plugins list | rg -i feishu
• Regular upgrades help ensure compatibility with Feishu API changes and OpenClaw improvements.

1. Configuration

• The configuration workflow proceeds in a few essential steps:
• Create a Feishu Open Platform app, then obtain App ID and App Secret.
• Grant the necessary permissions (both required and optional) to enable the plugin’s capabilities.
• Configure event subscriptions within Feishu, ensuring the right events are enabled and approved.
• Define the plugin behavior in OpenClaw’s config, including domain, connection mode, DM policies, group policies, and rendering options.
• Required permissions (summary):
• im:message: Messaging — Send and receive messages
• im:message.p2p_msg:readonly — Read direct messages to the bot
• im:message.groupatmsg:readonly — Receive group @mentions
• im:message:sendasbot — Send messages as the bot
• im:resource — Media — Upload and download images/files
• Optional permissions (summary):
• contact:user.base:readonly — Get basic user info for speaker attribution
• im:message.group_msg — Read all group messages (needed for requireMention: false in groups)
• im:message:readonly — Read message history
• im:message:update — Edit sent messages
• im:message:recall — Recall sent messages
• im:message.reactions:read — View message reactions
• Tool permissions (read-only as a baseline; optional read/write for advanced use):
• docx:document:readonly, drive:drive:readonly, wiki:wiki:readonly, bitable:app:readonly, task:task:read, tasklist:read, task:comment:read, task:attachment:read, im:chat.announcement:read, im:chat:readonly, im:message:readonly, im:message.groupatmsg:readonly, im:message.reactions:read
• Read/write permissions (optional, for creating/editing/deleting content):
• docx:document, docx:document.block:convert, drive:drive, wiki:wiki, bitable:app, task:task:write, tasklist:write, task:comment:write, task:attachment:write, im:message.urgent, im:chat.announcement, im:chat, im:chat.members, im:message.reactions:write_only
• Task-specific guidance:
• Task comments require dedicated scopes: task:comment:read for reading and task:comment:write for create/update/delete.
• Task attachments support upload/get/list/delete; uploads can come from local files or remote URLs, managed via OpenClaw’s media loader with safety checks.
• Tasklists must keep the bot as the owner; users should be added as members, otherwise the bot may lose permission.
• Task visibility rules: a user can view a task only if they are an assignee; subtasks are currently limited to being created by the task’s author.
• Drive and wiki access:
• The bot cannot access a root space; it only sees content shared with it. To enable access, share folders/spaces with the bot, grant appropriate permissions, and ensure the bot is a member of the relevant spaces.
• Wiki access requires adding the bot to the wiki space members with appropriate permissions.
• Bitable access requires sharing the bitable with the bot; supports both standard bitable URLs and wiki-embedded bitables.
• Event subscriptions:
• Event subscriptions are a common source of misconfiguration; ensure events are configured, matched to the chosen connection mode (websocket or webhook), and approved.
• In Feishu’s console, configure event subscriptions under Event configuration, selecting the mode that aligns with connectionMode (websocket or webhook).
• Configuration options (YAML)—high-level summary:
• channels.feishu.enabled
• appId and appSecret
• domain (feishu, lark, or custom)
• connectionMode (websocket or webhook)
• webhookPort and webhookPath (for webhook mode)
• encryptKey and verificationToken (for webhook mode)
• dmPolicy (pairing, open, allowlist)
• allowFrom (list of identities)
• groupPolicy (open, allowlist, disabled)
• requireMention (true or false)
• allowMentionlessInMultiBotGroup (default false)
• groupCommandMentionBypass (never, single_bot, always)
• mediaMaxMb (default 30)
• renderMode (auto, raw, card)
• Advanced options:
• dynamicAgentCreation: enabled with workspaceTemplate and agentDirTemplate to isolate each DM user with a dedicated agent workspace
• maxAgents to cap dynamic agents
• session.dmScope to define how conversations are isolated (per-peer)
• Examples and notes:
• When enabling dynamic agents, OpenClaw creates a per-user workspace and memory for each DM user, providing strong isolation between users.
• If you use per-peer DM scope without dynamic agents, only the conversation history is isolated.
• Always keep the bot as the owner of a tasklist to prevent read/edit permission issues when delegating access to members.
• Event subscription troubleshooting:
• If messages are not received, re-check event subscriptions, confirm the proper mode, and ensure the correct events such as im.message.receive_v1 are enabled and approved.

1. DM Policy and Access Control

• The dmPolicy setting governs who can trigger the Feishu bot in direct messages, and it may vary per account when multiple accounts are in use.
• Policy options:
• pairing: users can obtain a pairing code via DM, and the bot owner approves the user with a pairing command.
• open: all users are allowed to DM the bot by setting allowFrom to include all.
• allowlist: only users listed in allowFrom are permitted.
• The allowFrom list accepts Feishu IDs (openid recommended) and can include userid identifiers.
• Pairing flow details:
• A user messages the bot to obtain a pairing code.
• The bot issues a code; the bot owner runs a pairing approve command to grant access.
• After approval, the user can chat normally with the bot.
• Account-level isolation is possible via per-account overrides; default fallbacks exist for accounts that don’t override settings.
• The top-level channels.feishu.dmPolicy and channels.feishu.allowFrom apply unless overridden by account-specific settings.

1. Group Command Mention Bypass

• When requireMention is true, authorized control commands can bypass the @bot requirement in some cases.
• Bypass modes:
• never: never bypass @ requirement
• single_bot: bypass only when the group contains at most one bot (default)
• always: always allow authorized control commands to bypass
• Important caveats:
• Bypass affects only group chats and only for commands that are explicitly authorized.
• If any user is explicitly @mentioned in the same message, bypass is disabled.
• In direct messages, this bypass setting does not apply.

1. Group Mention-Free Behavior

• When requireMention is false, the plugin uses a safety default for non-@ group messages.
• Settings:
• allowMentionlessInMultiBotGroup: false by default; true enables acceptance of non-@ messages even in multi-bot groups
• Precautions:
• Receiving non-@ group messages requires im:message.group_msg, which is a sensitive permission in Feishu.
• If the permission is not approved, Feishu typically delivers only @bot messages via im:message.groupatmsg:readonly.

1. Connection Mode

• Feishu channel connections support two modes:
• websocket: default and recommended; a long-polling WebSocket connection that does not require public exposure; suitable for most deployments.
• webhook: requires a publicly accessible URL; Feishu will push events to your server via HTTP callbacks.
• WebSocket setup:
• In Feishu, select Long connection.
• Webhook setup:
• Provide a public URL, port (default 3000), and a path for event callbacks (e.g., /feishu/events).
• Ensure HTTPS is used; tools like ngrok can expose a local server for development.
• Practical note: For local testing, websocket is often the simplest path; webhook is valuable when you have a public endpoint and want a conventional webhook pattern.

1. Render Mode

• Rendering determines how the bot’s replies are displayed:
• auto: automatically detects if content should be shown as a card (for code blocks, tables) or as plain text
• raw: always send plain text; markdown tables convert to ASCII
• card: always send as interactive cards with full markdown rendering (including syntax highlighting, tables, and clickable links)
• Choice of render mode can affect readability, formatting fidelity, and the user experience within Feishu.

1. Dynamic Agent Creation (Multi-User Workspace Isolation)

• When enabled, each DM user gets an isolated agent with its own workspace, memory, and identity.
• How it works (summary): 1) A new DM user triggers the creation of a new agent entry in openclaw.json 2) A binding routes that user’s DM to their dedicated agent 3) Workspaces and agent directories are created automatically 4) Future messages from that user use the dedicated agent
• Key distinction:
• dynamicAgentCreation provides full isolation (workspace and tools) in addition to per-peer conversation isolation imposed by dmScope.
• Config knobs:
• workspaceTemplate supports {userId} and {agentId}
• agentDirTemplate defines where agent-related files live
• maxAgents caps the number of dynamic agents
• Practical implications:
• Strong isolation helps prevent cross-user data leakage, memory bleed, or shared context between users.
• Manage resources carefully to avoid hitting the maxAgents limit in large deployments.

1. Features

• The plugin offers a robust feature set across communication, content management, and collaboration domains:
• WebSocket and Webhook connection modes
• Support for both direct messages and group chats
• Message replies and context-aware quoting
• Inbound media support (images, PDFs, Excel, etc.)
• Outbound content: image and file uploads
• Typing indicators via emoji reactions
• Pairing workflow for DM approval
• Directory lookups for users and groups
• Card render mode for richer responses
• Document tools: read, create, and write Feishu documents with markdown
• Wiki tools: navigate knowledge bases, search, and node operations
• Drive tools: list folders, get file info, create folders, manage files
• Bitable tools: read/create/update/delete bitable records and manage fields
• Task tools: create, read, update, delete tasks via Task v2 API
• Chat tools: read/write group announcements, create and manage group chats
• Urgent notifications: app-internal buzz notifications, plus SMS/voice variants
• Message tools: access to single messages and chat history with time range/pagination
• Reaction tools: manage message reactions
• Mention forwarding: automatically forward @mentions into bot responses
• Permission error notification: informs users when Feishu API permissions are insufficient
• Dynamic agent creation: optional per-user workspace isolation
• These capabilities are designed to cover most Feishu workflows a bot might need, from simple chat interactions to integrated knowledge management.

1. @Mention Forwarding

• A convenient feature that mirrors @mentions from user messages into the bot’s replies:
• In Direct Messages: a user can DM, for example, “@张三 say hello,” and the bot replies including “@张三 Hello!”
• In Groups: a command such as “@bot @张三 say hello” yields the bot’s reply including “@张三 Hello!”
• Behavior: the bot automatically detects mentions in the user’s message and propagates them into its reply, enhancing context and clarity.
• Permissions: no additional permissions are required beyond the standard messaging permissions for this behavior to work.

1. FAQ and Common Issues

• Bot cannot receive messages:
• Confirm event subscriptions are configured
• Ensure the event subscription mode matches connectionMode
• Confirm that the im.message.receive_v1 event is added
• Verify that required permissions have been approved
• For webhook mode, ensure the server is running and the URL is publicly accessible
• requireMention: false but group still requires @:
• Check that im:message.group_msg is approved (sensitive permission)
• If there are multiple bots in the group, ensure allowMentionlessInMultiBotGroup is true
• Verify that requireMention: false applies to the effective account/group
• 403 error when sending messages:
• Ensure im:message:sendasbot is approved
• Clearing history or starting a new conversation:
• Use the /new command within the chat
• Why messages aren’t streaming:
• Feishu API rate limits are in play; the plugin may use a complete-then-send approach for stability
• Bot not found in Feishu:
• Ensure the app is published (at least to a test version)
• Search by the bot’s name in Feishu
• Confirm the app’s availability scope includes your account

1. Troubleshooting and Best Practices

• If messages fail to arrive, review the entire configuration chain: Feishu app permissions, Feishu event subscriptions, OpenClaw config, and network reachability.
• Prefer long-lived websocket connections for local development and most deployment scenarios; reserve webhook mode for servers with reliable public endpoints.
• When enabling sensitive permissions (groupmsg, messageread, etc.), plan for approval cycles and ensure governance around the bot’s access is sound.
• For large organizations, consider per-account overrides to tailor DM and group policies, ensuring predictable behavior across teams.

1. 中文（Chinese Section）

• 安装与安装注意事项
• 使用命令：openclaw plugins install @m1heng-clawd/feishu
• 针对 Windows 的排错方案包括多种替代安装路径，确保能够在没有 npm 的情况下完成插件安装
• 升级与版本检查
• 使用 openclaw plugins update feishu 进行升级
• 使用 openclaw plugins list | rg -i feishu 查看已安装版本
• 配置与权限
• 在飞书开放平台创建自建应用，获取 AppId 与 AppSecret
• 启用所需权限：消息、群消息、发送为机器人、媒体等
• 配置事件订阅（Event Subscriptions），选择长连接或请求地址模式，并确保审核通过
• 功能与使用要点
• 私聊、群聊、消息引用、图片/文件处理、卡片渲染、文档/知识库/云盘/多维表格/任务等工具
• 支持卡片渲染、Markdown 写入，蜂窝式工作区、工作区模板和 agent 目录模板等动态 Agent 创建
• 支持 @ 转发、权限错误通知、动态 Agent 创建等高级能力
• 私聊策略与访问控制
• dmPolicy 支持 pairing、open、allowlist，并可通过 allowFrom 列表进行细粒度控制
• 配对审批流程：用户私聊机器人获取配对码，机器人所有者执行 pairing approve feishu
• 账户级隔离与默认值继承的说明
• 群聊与免 @ 策略
• groupCommandMentionBypass、requireMention、allowMentionlessInMultiBotGroup 等设置的含义和使用场景
• 在多机器人群组中谨慎设置免 @，以避免重复触发
• 连接模式与渲染模式
• websocket 为默认推荐，webhook 适合具备公网可达端点的部署
• renderMode 提供 auto/raw/card 三种渲染模式，便于在中文环境中优化显示效果
• 动态 Agent 创建与工作区隔离
• 针对每个私聊用户创建独立的 agent 实例和工作区，确保个人化、隔离性的对话与数据
• FAQ 与 常见问题
• 机器人无法接收消息、权限不足、如何清理历史、以及为什么不流式输出等问题及解法

1. License

• The plugin and its documentation are released under the MIT license, allowing broad reuse with attribution and appropriate credit to the authors and sponsors.

1. Closing Notes

• This Feishu/Lark channel plugin for OpenClaw is designed to be a comprehensive, enterprise-friendly integration that covers messaging, file and content management, and knowledge workflows within Feishu’s ecosystem.
• It emphasizes careful permission scoping, clear event subscriptions, and robust fallback guidance to help operators achieve a reliable, scalable Feishu assistant.
• By offering both English and Chinese sections, the project aims to be accessible to diverse teams and communities, accelerating adoption and collaboration.

Images mentioned

• Sponsor image: sponsor-youyunzhisuan.png (referenced in the Sponsor section to credit the sponsor). This image is part of the repository assets and appears as a visual acknowledgment of support.

Note on formatting

• This description is structured with numbered sections and bullet-point subsections, avoiding tables as requested.
• The content preserves the key topics from the input while presenting them as an organized, readable guide for users implementing the Feishu/Lark channel plugin with OpenClaw.