clawd-feishu
Feishu/Lark (飞书) channel plugin for OpenClaw.
中文社区资料 - 配置教程、常见问题、使用技巧：Wiki
Contributing / 贡献指南: CONTRIBUTING.md
Issue Reporting / 问题反馈: Please check Discussions first for common solutions, then open a structured Issue Form if needed.
问题反馈前请先查看 Discussions 是否已有常见解答；如仍未解决，再提交结构化 Issue 模板。
Questions / 使用咨询: Use Question issue for troubleshooting; use Discussions for open-ended Q&A.
排查型咨询请提交 Question Issue；开放式交流请使用 Discussions。
English | 中文
Thanks to our sponsors for supporting the project.
If you need an API key platform whose models can be used as an OpenClaw provider and work with Kimi, MiniMax, Claude Code, Codex, or direct API usage, YouYun Zhisuan is worth considering:
UCloud's YouYun Zhisuan is an AI cloud platform that provides stable and comprehensive domestic and international model APIs through a single API key. Its high-value Coding Plan offers both monthly and pay-as-you-go options, typically at 20% to 50% of official pricing. It supports Claude Code, Codex, and direct API integrations, as well as enterprise-grade high concurrency, 24/7 technical support, and self-service invoicing. Register through this link to receive a free RMB 5 platform trial credit.
感谢赞助方对本项目的支持。
如果你需要一个可作为 OpenClaw 模型 provider，并适用于 Kimi、MiniMax、Claude Code、Codex 或直接 API 调用的稳定 API Key 平台，可以了解一下优云智算：
优云智算是UCloud旗下AI云平台，提供稳定、全面的国内外模型API，仅一个key即可调用。主打包月、按量的高性价比 Coding Plan 套餐，基于官方2~5折优惠。支持接入 Claude Code、Codex 及 API 调用。支持企业高并发、7*24技术支持、自助开票。通过此链接注册的用户，可得免费5元平台体验金！
English
Installation
openclaw plugins install @m1heng-clawd/feishu
[!IMPORTANT]
Windows Troubleshooting (spawn npm ENOENT)
If openclaw plugins install fails, install manually with the latest tarball:
# Option A (recommended): download latest package tarball
npm pack @m1heng-clawd/feishu
openclaw plugins install ./m1heng-clawd-feishu-<version>.tgz
# Option B (keep curl flow): resolve latest tarball URL, then download/install
TARBALL_URL="$(npm view @m1heng-clawd/feishu dist.tarball)"
curl -L -o feishu-latest.tgz "$TARBALL_URL"
openclaw plugins install ./feishu-latest.tgz
# Windows PowerShell (Option B)
$tarball = npm view @m1heng-clawd/feishu dist.tarball
curl.exe -L $tarball -o feishu-latest.tgz
openclaw plugins install .\feishu-latest.tgz
# Option C (no npm command): use URL template with latest version from npm Versions tab
# https://www.npmjs.com/package/@m1heng-clawd/feishu?activeTab=versions
curl -L -o feishu-latest.tgz https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-<version>.tgz
openclaw plugins install ./feishu-latest.tgz
Upgrade
openclaw plugins update feishu
Check installed version:
openclaw plugins list | rg -i feishu
Configuration
- Create a self-built app on Feishu Open Platform
- Get your App ID and App Secret from the Credentials page
- Enable required permissions (see below)
- Configure event subscriptions (see below) ⚠️ Important
- Configure the plugin:
Required Permissions
| Permission |
Scope |
Description |
im:message |
Messaging |
Send and receive messages |
im:message.p2p_msg:readonly |
DM |
Read direct messages to bot |
im:message.group_at_msg:readonly |
Group |
Receive @mention messages in groups |
im:message:send_as_bot |
Send |
Send messages as the bot |
im:resource |
Media |
Upload and download images/files |
Optional Permissions
| Permission |
Scope |
Description |
contact:user.base:readonly |
User info |
Get basic user info (required to resolve sender display names for speaker attribution) |
im:message.group_msg |
Group |
Read all group messages (sensitive). Required when you want requireMention: false to work for non-@ group messages |
im:message:readonly |
Read |
Get message history |
im:message:update |
Edit |
Update/edit sent messages |
im:message:recall |
Recall |
Recall sent messages |
im:message.reactions:read |
Reactions |
View message reactions |
Read-only (minimum required):
| Permission |
Tool |
Description |
docx:document:readonly |
feishu_doc |
Read documents |
drive:drive:readonly |
feishu_drive |
List folders, get file info |
wiki:wiki:readonly |
feishu_wiki |
List spaces, list nodes, get node info, search |
bitable:app:readonly |
feishu_bitable |
Read bitable records and fields |
task:task:read |
feishu_task_get |
Get task details |
task:tasklist:read |
feishu_tasklist_get, feishu_tasklist_list |
Get/list tasklists |
task:comment:read |
feishu_task_comment_list, feishu_task_comment_get |
List/get task comments |
task:attachment:read |
feishu_task_attachment_list, feishu_task_attachment_get |
List/get task attachments |
im:chat.announcement:read |
feishu_chat |
Read group announcement |
im:chat:readonly |
feishu_chat |
Get chat info, check bot membership |
im:message or im:message:readonly |
feishu_message |
Read single/DM messages |
im:message.group_at_msg:readonly |
feishu_message |
Read all messages in group chats |
im:message.reactions:read |
feishu_reaction |
List reactions on messages |
Read-write (optional, for create/edit/delete operations):
| Permission |
Tool |
Description |
docx:document |
feishu_doc |
Create/edit documents |
docx:document.block:convert |
feishu_doc |
Markdown to blocks conversion (required for write/append/create_and_write; also used by feishu_drive.import_document) |
drive:drive |
feishu_doc, feishu_drive |
Upload images to documents, create folders, move/delete files |
wiki:wiki |
feishu_wiki |
Create/move/rename wiki nodes |
bitable:app |
feishu_bitable |
Create/update/delete bitable records and manage fields |
task:task:write |
feishu_task_create, feishu_task_subtask_create, feishu_task_update, feishu_task_delete |
Create/update/delete tasks |
task:tasklist:write |
feishu_tasklist_create, feishu_tasklist_update, feishu_tasklist_delete, feishu_tasklist_add_members, feishu_tasklist_remove_members, feishu_task_add_tasklist, feishu_task_remove_tasklist |
Create/update/delete tasklists and manage membership |
task:comment:write |
feishu_task_comment_create, feishu_task_comment_update, feishu_task_comment_delete |
Create/update/delete task comments |
task:attachment:write |
feishu_task_attachment_upload, feishu_task_attachment_delete |
Upload/delete task attachments |
im:message.urgent |
feishu_urgent |
Send urgent (buzz) notifications via app (in-app). Use sms and phone variants (im:message.urgent:sms, im:message.urgent:phone) for SMS and voice call. |
im:chat.announcement |
feishu_chat |
Write/update group announcement |
im:chat |
feishu_chat |
Create and delete group chats |
im:chat.members |
feishu_chat |
Add members to group chats |
im:message.reactions:write_only |
feishu_reaction |
Add and remove reactions |
Task scope names may vary slightly in Feishu console UI. If needed, search for Task / Tasklist / Comment / Attachment-related permissions and grant read/write accordingly.
Task comments require dedicated scopes:
- Read comments: grant
task:comment:read.
- Create/update/delete comments: grant
task:comment:write.
If these scopes are missing, comment APIs will return permission-denied errors.
Task Attachment Upload ⚠️
Task attachments support upload/get/list/delete. Upload sources:
- Local files on the OpenClaw/Node host (
file_path)
- Remote links (
file_url, public or presigned)
For file_url, OpenClaw runtime media loader is used with safety checks and size limit (mediaMaxMb), then the downloaded file is uploaded via a temporary local file.
Tasklist Ownership ⚠️
Important: Keep tasklist owner as the bot. Add users as members instead.
Tasklist access is granted based on owner + member roles. If you change the owner to a user and the bot is not a member, the bot may lose permission to read/edit/manage that tasklist (and subsequent operations will fail).
Task Visibility & Subtasks ⚠️
Important: A user can only view a task when they are included as an assignee.
Limitation: The bot can currently only create subtasks for tasks created by itself.
To avoid “task created but not visible” issues:
- When creating a task, set the requesting user as an assignee.
- If you need more flexible subtask organization/visibility, consider using tasklists.
Drive Access ⚠️
Important: Bots don't have their own "My Space" (root folder). Bots can only access files/folders that have been shared with them.
To let the bot manage files:
- Create a folder in your Feishu Drive
- Right-click the folder → Share → search for your bot name
- Grant appropriate permission (view/edit)
Without this step, feishu_drive operations like create_folder will fail because the bot has no root folder to create in.
Wiki Space Access ⚠️
Important: API permissions alone are not enough for wiki access. You must also add the bot to each wiki space.
- Open the wiki space you want the bot to access
- Click Settings (gear icon) → Members
- Click Add Member → search for your bot name
- Select appropriate permission level (view/edit)
Without this step, feishu_wiki will return empty results even with correct API permissions.
Reference: Wiki FAQ - How to add app to wiki
Bitable Access ⚠️
Important: Like other resources, the bot can only access bitables that have been shared with it.
To let the bot access a bitable:
- Open the bitable you want the bot to access
- Click Share button → search for your bot name
- Grant appropriate permission (view/edit)
The feishu_bitable tools support both URL formats:
/base/XXX?table=YYY - Standard bitable URL/wiki/XXX?table=YYY - Bitable embedded in wiki (auto-converts to app_token)
Event Subscriptions ⚠️
This is the most commonly missed configuration! If the bot can send messages but cannot receive them, check this section.
In the Feishu Open Platform console, go to Events & Callbacks:
- Event configuration: Select the subscription mode matching your
connectionMode:
- Long connection — for
connectionMode: "websocket" (recommended, no public URL needed)
- Request URL — for
connectionMode: "webhook" (requires a publicly accessible URL)
- Add event subscriptions:
| Event |
Description |
im.message.receive_v1 |
Receive messages (required) |
im.message.message_read_v1 |
Message read receipts |
im.chat.member.bot.added_v1 |
Bot added to group |
im.chat.member.bot.deleted_v1 |
Bot removed from group |
- Ensure the event permissions are approved
openclaw config set channels.feishu.appId "cli_xxxxx"
openclaw config set channels.feishu.appSecret "your_app_secret"
openclaw config set channels.feishu.enabled true
Configuration Options
channels:
feishu:
enabled: true
appId: "cli_xxxxx"
appSecret: "secret"
# Domain: "feishu" (China), "lark" (International), or custom URL
domain: "feishu" # or "https://open.xxx.cn" for private deployment
# Connection mode: "websocket" (recommended) or "webhook"
connectionMode: "websocket"
# DM policy: "pairing" | "open" | "allowlist"
dmPolicy: "pairing"
# DM allowlist (open_id/user_id). Include "*" when dmPolicy="open"
allowFrom: []
# Group policy: "open" | "allowlist" | "disabled"
groupPolicy: "allowlist"
# Require @mention in groups
requireMention: true
# Safety default for mention-free mode (`requireMention: false`):
# only allow non-@ messages in groups with <= 1 bot.
# Set true to also allow mention-free messages in multi-bot groups.
allowMentionlessInMultiBotGroup: false
# Group command mention bypass: "never" | "single_bot" | "always"
# Default "single_bot": allow authorized command-only messages without @
# only when the group has a single bot.
groupCommandMentionBypass: "single_bot"
# Max media size in MB (default: 30)
mediaMaxMb: 30
# Render mode for bot replies: "auto" | "raw" | "card"
renderMode: "auto"
DM Policy & Access Control
dmPolicy controls who can interact with the bot in direct messages (DM).
In multi-account mode, this is resolved per account (channels.feishu.accounts.<accountId>).
dmPolicy |
Who can send DM |
How to grant access to a user |
pairing |
Users in allowFrom, or users approved through pairing |
User sends a DM and gets a pairing code; bot owner runs openclaw pairing approve feishu <code>. |
open |
Everyone |
Set allowFrom: ["*"] so all users are treated as allowed. |
allowlist |
Only users in allowFrom |
Add the user's open_id/user_id to allowFrom, then reload config. |
Notes:
allowFrom accepts Feishu user IDs (open_id recommended, user_id also supported).- If
dmPolicy: "open", use allowFrom: ["*"]. This is required by top-level schema validation and keeps access behavior explicit.
pairing and allowlist can both pre-authorize users with allowFrom.
Pairing flow (owner approval):
- User sends any DM to the bot.
- Bot replies with a pairing code (for example
H9ZEHY8R).
- Bot owner approves:
openclaw pairing approve feishu H9ZEHY8R
- The user is added to the allow store and can chat immediately.
Example: open to everyone
channels:
feishu:
dmPolicy: "open"
allowFrom: ["*"]
Example: controlled rollout (pairing + pre-approved users)
channels:
feishu:
dmPolicy: "pairing"
allowFrom:
- "ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Example: strict allowlist
channels:
feishu:
dmPolicy: "allowlist"
allowFrom:
- "ou_alice"
- "ou_bob"
Example: account-level isolation
channels:
feishu:
accounts:
lobster-1:
dmPolicy: "open"
allowFrom: ["*"]
lobster-5:
dmPolicy: "pairing"
Top-level channels.feishu.dmPolicy / channels.feishu.allowFrom are fallback defaults for accounts that do not override them.
dmPolicy only controls who can trigger the bot.
To actually read/write docs or files, you still need: (1) correct Feishu app scopes, and (2) sharing the target resources (Drive/Wiki/Bitable) with the bot.
Group Command Mention Bypass
When requireMention: true, Feishu can still allow authorized control commands (such as /new) without @bot.
groupCommandMentionBypass |
Behavior |
never |
Never bypass @ requirement for group commands. |
single_bot |
Bypass only when the group contains at most one bot (default). |
always |
Always allow authorized control commands to bypass mention gating. |
Notes:
- Bypass only applies to authorized control commands in group chats.
- If any user is explicitly
@-mentioned in the same message, bypass is disabled.
- In DMs, this setting does not apply.
Group Mention-Free Behavior (requireMention: false)
When requireMention: false, non-@ group messages are handled with a safety default:
allowMentionlessInMultiBotGroup |
Behavior for non-@ group messages |
false (default) |
Only accepted when the group has at most one bot. In multi-bot groups, explicit @bot is still required. |
true |
Accepted even in multi-bot groups (use only if you accept duplicate-trigger risk). |
Important:
im:message.group_msg is required for receiving non-@ group messages and this is a sensitive permission in Feishu.- If this scope is not approved, Feishu usually only delivers
@bot group messages (im:message.group_at_msg:readonly).
Connection Mode
Two connection modes are available for receiving events from Feishu:
| Mode |
Description |
websocket |
(Default, recommended) Long-polling WebSocket connection. No public URL required, works behind NAT/firewall. Best for local development and most deployments. |
webhook |
HTTP server that receives event callbacks. Requires a publicly accessible URL. Suitable for server deployments behind a reverse proxy (e.g. Nginx). |
WebSocket mode (default, no extra config needed):
channels:
feishu:
connectionMode: "websocket" # or just omit this line
In Feishu console: Events & Callbacks → select Long connection.
Webhook mode:
channels:
feishu:
connectionMode: "webhook"
webhookPort: 3000 # HTTP server port (default: 3000)
webhookPath: "/feishu/events" # Event callback path (default: "/feishu/events")
encryptKey: "your_encrypt_key" # From Feishu console → Events & Callbacks → Encrypt Key
verificationToken: "your_verify_token" # From Feishu console → Events & Callbacks → Verification Token
In Feishu console: Events & Callbacks → select Request URL → set the URL to:
https://your-domain.com/feishu/events
Note: The Request URL must be HTTPS and publicly accessible. For local development, you can use tools like ngrok to create a tunnel: ngrok http 3000, then use the generated URL.
Render Mode
| Mode |
Description |
auto |
(Default) Automatically detect: use card for messages with code blocks or tables, plain text otherwise. |
raw |
Always send replies as plain text. Markdown tables are converted to ASCII. |
card |
Always send replies as interactive cards with full markdown rendering (syntax highlighting, tables, clickable links). |
Dynamic Agent Creation (Multi-User Workspace Isolation)
When enabled, each DM user automatically gets their own isolated agent instance with a dedicated workspace. This provides complete isolation including separate conversation history, memory (MEMORY.md), and workspace files.
Chat Management Limitations ⚠️
Important: delete_chat requires the bot to be the group owner. If the bot was added to an existing chat as a member (not the owner), it cannot disband it.
If you need to disba
clawd-feishu — плагин, подключающий OpenClaw к Feishu/Lark (飞书): бот OpenClaw может отправлять и получать сообщения, читать и писать документы, работать с файлами Drive, страницами wiki, записями bitable и задачами внутри Feishu.