Tools
Feishu Multi Bot Relay
By OpenClaw Feishu plugin fork with multi-bot relay support (experimental)
Install
openclaw plugins install @m1heng-clawd/feishuConfiguration Example
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
# 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"README
# clawd-feishu
Feishu/Lark (飞书) channel plugin for [OpenClaw](https://github.com/openclaw/openclaw).
> **中文社区资料** - 配置教程、常见问题、使用技巧：[Wiki](https://github.com/m1heng/clawdbot-feishu/wiki)
>
> **Contributing / 贡献指南**: [CONTRIBUTING.md](./CONTRIBUTING.md)
>
> **Issue Reporting / 问题反馈**: Please check [Discussions](https://github.com/m1heng/clawdbot-feishu/discussions) first for common solutions, then open a structured Issue Form if needed.
> 问题反馈前请先查看 [Discussions](https://github.com/m1heng/clawdbot-feishu/discussions) 是否已有常见解答；如仍未解决，再提交结构化 Issue 模板。
>
> **Questions / 使用咨询**: Use `Question` issue for troubleshooting; use [Discussions](https://github.com/m1heng/clawdbot-feishu/discussions) for open-ended Q&A.
> 排查型咨询请提交 `Question` Issue；开放式交流请使用 [Discussions](https://github.com/m1heng/clawdbot-feishu/discussions)。
[English](#english) | [中文](#中文)
---
## English
### Installation
```bash
openclaw plugins install @m1heng-clawd/feishu
```
> [!IMPORTANT]
> **Windows Troubleshooting (`spawn npm ENOENT`)**
>
> If `openclaw plugins install` fails, install manually with the latest tarball:
>
> ```bash
> # Option A (recommended): download latest package tarball
> npm pack @m1heng-clawd/feishu
> openclaw plugins install ./m1heng-clawd-feishu-<version>.tgz
> ```
>
> ```bash
> # 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
> ```
>
> ```powershell
> # 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
> ```
>
> ```bash
> # 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
```bash
openclaw plugins update feishu
```
Check installed version:
```bash
openclaw plugins list | rg -i feishu
```
### Configuration
1. Create a self-built app on [Feishu Open Platform](https://open.feishu.cn)
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) |
| `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 |
**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 |
> 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](https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa#a40ad4ca)
#### 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
```bash
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
```yaml
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 priv
... (truncated)
tools
Comments
Sign in to leave a comment