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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

@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.

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

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.

中文（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 与 常见问题
机器人无法接收消息、权限不足、如何清理历史、以及为什么不流式输出等问题及解法



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.


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.

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

`Enjoying this project?`

GitHub - m1heng/clawdbot-feishu: clawd-feishu Feishu/Lark (飞书) channel plugin for OpenClaw

`Stay Updated`

`Product`

`Learn`

`Company`

`Legal`

`Stay Updated`

`Browse by Category`