clawdbot-feishu README

The project's README from github.com/m1heng/clawdbot-feishu. As one markdown file: README.md.

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

YouYun Zhisuan

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:

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
  1. 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:

Pairing flow (owner approval):

  1. User sends any DM to the bot.
  2. Bot replies with a pairing code (for example H9ZEHY8R).
  3. Bot owner approves:
openclaw pairing approve feishu H9ZEHY8R
  1. 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:

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:

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

clawdbot-feishu (m1heng/clawdbot-feishu)

webhook
Searching Database…

4.2K ·GitHub
Clawdbot-feishu
What is this?clawd-feishu is a plugin that connects OpenClaw to Feishu/Lark (飞书), letting an OpenClaw bot send and receive messages, read/write documents, drive files, wiki pages, bitable records and tasks inside Feishu.
Is this a standalone app or a plugin I add to something else?It's a channel plugin that installs into an existing OpenClaw setup via the OpenClaw plugin manager, not a standalone application.
How do I get it connected to my Feishu bot?Create a self-built app on the Feishu Open Platform, grab the App ID and App Secret from the Credentials page, enable the required permissions, set up event subscriptions, then configure the plugin with those credentials.
What Feishu app permissions does it actually need?At minimum you need the im:message messaging scopes (send/receive, DM, group @-mentions, send-as-bot, media) to get basic chat working; extra read/write scopes for docx, drive, wiki, bitable and task tools are optional and only needed for those specific features.
What's the most common setup mistake?Forgetting to configure Event Subscriptions is the most commonly missed step — if the bot can send but not receive messages, that's almost always the cause; also bots have no root Drive folder and can't access Wiki/Bitable/Drive resources until they're explicitly shared with the bot.
Does the Windows install path work out of the box?Windows users can hit a 'spawn npm ENOENT' error during plugin install and need to install manually from the latest tarball as a workaround.
Who can DM the bot by default?The dmPolicy setting controls DM access: 'pairing' (default-style) requires users to request access and be approved by the bot owner, 'open' lets everyone in, and 'allowlist' restricts to a specific list of user IDs.
Can the bot reply in a group without being @-mentioned?Yes, via requireMention: false, though this has a safety-default behavior, and there's also a groupCommandMentionBypass setting (never/singlebot/always) that lets authorized control commands skip the @-mention requirement even when requireMention is true.
Can the bot manage tasks and task comments in Feishu?Yes, with the right scopes it can create, read, update and delete tasks, tasklists, task comments and task attachments, but it can only create subtasks for tasks it created itself, and a user only sees a task if they're listed as an assignee.
Why can't the bot see my Drive files or Wiki spaces even with correct API permissions?Bots have no personal 'My Space' root folder and must be explicitly added as a member/collaborator to each Wiki space, Drive folder, or Bitable before they can access it — API scopes alone aren't enough.
What are similar projects?openclaw-china, walle-web, daily_stock_analysis, AionUi, wechaty, wechat-bot, ItChat, wxpy
Which topics is it in?webhook, wechat, chat, openclaw, document-processing, websocket, chatbot, plugin, api, chinese, automation, nodejs
Creator
m1heng
Size
225.4 MB
Stars
4.2K
Updated
CommitMar 29Releasev0.1.19Mar 29
Age
8mo
Commits · 90 Days