clawdbot-feishu

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 | 中文

---

Sponsor

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

1. Create a self-built app on Feishu Open Platform
2. Get your App ID and App Secret from the Credentials page
3. Enable required permissions (see below)
4. Configure event subscriptions (see below) ⚠️ Important
5. 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

Tool Permissions

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 Comment Scopes ⚠️

Task comments require dedicated scopes:

1. Read comments: grant task:comment:read.
2. 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:

1. Local files on the OpenClaw/Node host (file_path)
2. 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:

1. When creating a task, set the requesting user as an assignee.
2. 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:

1. Create a folder in your Feishu Drive
2. Right-click the folder → Share → search for your bot name
3. 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.

1. Open the wiki space you want the bot to access
2. Click Settings (gear icon) → Members
3. Click Add Member → search for your bot name
4. 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:

1. Open the bitable you want the bot to access
2. Click Share button → search for your bot name
3. 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:

1. 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)
2. 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

3. Ensure the event permissions are approved