clawd-feishu

飞书/Lark 频道插件，用于 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):

权限	工具	描述
docx:document	feishu_doc	创建/编辑文档
docx:document.block:convert	feishu_doc	Markdown 转块操作（用于写入/追加/创建并写入；也被 feishu_drive.import_document 使用）
drive:drive	feishu_doc, feishu_drive	向文档上传图片、创建文件夹、移动/删除文件
wiki:wiki	feishu_wiki	创建/移动/重命名维基节点
bitable:app	feishu_bitable	创建/更新/删除多维表格记录及管理字段
task:task:write	feishu_task_create, feishu_task_subtask_create, feishu_task_update, feishu_task_delete	创建/更新/删除任务
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	创建/更新/删除任务列表及管理成员
task:comment:write	feishu_task_comment_create, feishu_task_comment_update, feishu_task_comment_delete	创建/更新/删除任务评论
task:attachment:write	feishu_task_attachment_upload, feishu_task_attachment_delete	上传/删除任务附件
im:message.urgent	feishu_urgent	通过应用内发送紧急通知（震动提醒）。如需短信或语音通话，请使用 sms 和 phone 变体（im:message.urgent:sms, im:message.urgent:phone）。
im:chat.announcement	feishu_chat	发布/更新群公告
im:chat	feishu_chat	创建和删除群聊
im:chat.members	feishu_chat	向群聊添加成员
im:message.reactions:write_only	feishu_reaction	添加和移除表情反应

在飞书控制台界面中，任务范围名称可能会略有不同。如有需要，请搜索与任务/任务列表/评论/附件相关的权限，并相应授予读取/写入权限。

任务评论范围 ⚠️

任务评论需要专用的权限范围：

1. 读取评论：授予 task:comment:read。
2. 创建/更新/删除评论：授予 task:comment:write。

如果缺少这些权限范围，评论相关 API 将返回权限拒绝错误。

任务附件上传 ⚠️

任务附件支持上传/获取/列出/删除。上传来源包括：

1. OpenClaw/Node 主机上的本地文件（file_path）
2. 远程链接（file_url，公开或预签名）

对于 file_url，OpenClaw 运行时会使用媒体加载器进行安全检查和大小限制（mediaMaxMb），然后将下载的文件通过临时本地文件上传。

任务列表所有权 ⚠️

重要提示：请始终将任务列表的所有者设置为机器人，用户则作为成员加入。

任务列表的访问权限基于所有者和成员角色分配。如果将所有者更改为用户而机器人未被设为成员，则机器人可能失去对该任务列表的读取/编辑/管理权限，后续操作也将失败。

任务可见性与子任务 ⚠️

重要提示：只有当用户被指定为任务的指派人时，才能查看该任务。

限制：目前机器人只能为其自身创建的的任务创建子任务。

为避免“任务已创建但不可见”的问题：

1. 创建任务时，将请求用户设置为指派人。
2. 如果需要更灵活的子任务组织和可见性，建议使用任务列表。

驱动器访问 ⚠️

重要提示：机器人没有自己的“我的空间”（根目录）。机器人仅能访问已被共享给它的文件/文件夹。

要让机器人管理文件：

1. 在您的飞书网盘中创建一个文件夹。
2. 右键单击该文件夹 → 分享 → 搜索您的机器人名称。
3. 授予适当的权限（查看/编辑）。

若未执行此步骤，feishu_drive 的操作（如 create_folder）将失败，因为机器人没有可创建的根目录。

维基空间访问 ⚠️

重要提示：仅凭 API 权限不足以访问维基空间。您还需将机器人添加到每个维基空间中。

1. 打开您希望机器人访问的维基空间。
2. 点击 设置（齿轮图标）→ 成员。
3. 点击 添加成员 → 搜索您的机器人名称。
4. 选择适当的权限级别（查看/编辑）。

若未执行此步骤，即使 API 权限正确，feishu_wiki 也会返回空结果。

参考：维基常见问题解答 - 如何将应用添加到维基

多维表格访问 ⚠️

重要提示：与其他资源一样，机器人仅能访问已被共享给它的多维表格。

要让机器人访问多维表格：

1. 打开您希望机器人访问的多维表格。
2. 点击 分享 按钮 → 搜索您的机器人名称。
3. 授予适当的权限（查看/编辑）。

feishu_bitable 工具支持两种 URL 格式：

• /base/XXX?table=YYY — 标准多维表格 URL
• /wiki/XXX?table=YYY — 嵌入维基中的多维表格（自动转换为 app_token）

事件订阅 ⚠️

这是最容易被忽略的配置！ 如果机器人可以发送消息但无法接收消息，请检查本节内容。

在飞书开放平台控制台中，前往 事件与回调：

1. 事件配置：根据您的 connectionMode 选择相应的订阅模式：
   • 长连接 — 适用于 connectionMode: "websocket"（推荐，无需公共 URL）
   • 请求 URL — 适用于 connectionMode: "webhook"（需要一个可公开访问的 URL）
2. 添加事件订阅：

事件	描述
im.message.receive_v1	接收消息（必选）
im.message.message_read_v1	消息已读回执
im.chat.member.bot.added_v1	机器人被加入群聊
im.chat.member.bot.deleted_v1	机器人从群聊中移除

3. 确保事件权限已获批准

openclaw config set channels.feishu.appId "cli_xxxxx"
openclaw config set channels.feishu.appSecret "your_app_secret"
openclaw config set channels.feishu.enabled true

配置选项

channels:
  feishu:
    enabled: true
    appId: "cli_xxxxx"
    appSecret: "secret"
    # 域名：可选“feishu”（中国）、“lark”（国际）或自定义URL
    domain: "feishu"  # 或者对于私有部署，使用 "https://open.xxx.cn"
    # 连接模式：“websocket”（推荐）或“webhook”
    connectionMode: "websocket"
    # 私信策略：“pairing” | “open” | “allowlist”
    dmPolicy: "pairing"
    # 私信白名单（open_id/user_id）。当dmPolicy="open"时，包含"*"
    allowFrom: []
    # 群组策略：“open” | “allowlist” | “disabled”
    groupPolicy: "allowlist"
    # 要求在群组中@提及
    requireMention: true
    # 在无@提及模式下的安全默认值（`requireMention: false`）：
    # 只允许在最多1个机器人的群组中发送非@消息。
    # 设置为true则允许在多机器人群组中也发送无@消息。
    allowMentionlessInMultiBotGroup: false
    # 群组命令免提及机制：“never” | “single_bot” | “always”
    # 默认为“single_bot”：仅当群组中只有一个机器人时，允许授权的纯命令消息无需@。
    groupCommandMentionBypass: "single_bot"
    # 最大媒体文件大小（单位：MB，默认30）
    mediaMaxMb: 30
    # 机器人回复的渲染模式：“auto” | “raw” | “card”
    renderMode: "auto"

私信策略与访问控制

dmPolicy 控制哪些用户可以在私信中与机器人互动。
在多账号模式下，此设置按每个账号单独配置（channels.feishu.accounts.<accountId>）。

dmPolicy	允许发送私信的人	如何授予用户访问权限
pairing	allowFrom中的用户，或通过配对流程批准的用户	用户发送一条私信并获取配对码；机器人所有者运行 openclaw pairing approve feishu <code>。
open	所有用户	设置 allowFrom: ["*"]，这样所有用户都被视为允许。
allowlist	仅限 allowFrom 中的用户	将用户的 open_id/user_id 添加到 allowFrom 中，然后重新加载配置。

注意事项：

• allowFrom 接受飞书用户ID（推荐使用 open_id，也支持 user_id）。
• 如果 dmPolicy: "open"，请使用 allowFrom: ["*"]。这是顶层架构验证所必需的，并且能明确访问行为。
• pairing 和 allowlist 都可以通过 allowFrom 提前授权用户。

配对流程（所有者批准）：

1. 用户向机器人发送任意一条私信。
2. 机器人回复一个配对码（例如 H9ZEHY8R）。
3. 机器人所有者批准：

openclaw pairing approve feishu H9ZEHY8R

4. 用户将被添加到允许列表中，并可立即开始聊天。

示例：对所有人开放

channels:
  feishu:
    dmPolicy: "open"
    allowFrom: ["*"]

示例：受控上线（配对 + 预先批准用户）

channels:
  feishu:
    dmPolicy: "pairing"
    allowFrom:
      - "ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

示例：严格白名单

channels:
  feishu:
    dmPolicy: "allowlist"
    allowFrom:
      - "ou_alice"
      - "ou_bob"

示例：账号级隔离

channels:
  feishu:
    accounts:
      lobster-1:
        dmPolicy: "open"
        allowFrom: ["*"]
      lobster-5:
        dmPolicy: "pairing"

顶层的 channels.feishu.dmPolicy / channels.feishu.allowFrom 是未覆盖该设置的账号的默认值。

dmPolicy 仅控制谁可以触发机器人。
要真正读取/写入文档或文件，您仍然需要：(1) 正确的飞书应用权限范围，以及 (2) 将目标资源（云盘/知识库/多维表格）共享给机器人。

群组命令免提及机制

当 requireMention: true 时，飞书仍允许授权的控制命令（如 /new）无需 @机器人 即可执行。

groupCommandMentionBypass	行为
never	永远不绕过群组命令的@要求。
single_bot	仅当群组中至多有一个机器人时才绕过（默认）。
always	总是允许授权的控制命令绕过提及限制。

注意事项：

• 绕过仅适用于群聊中的授权控制命令。
• 如果同一消息中明确提到了任何用户，则会禁用绕过功能。
• 在私信中，此设置不适用。

群组无@提及行为（requireMention: false）

当 requireMention: false 时，非@群组消息会遵循一个安全默认值：

allowMentionlessInMultiBotGroup	非@群组消息的行为
false（默认）	仅当群组中至多有一个机器人时才接受。在多机器人群组中，仍然需要明确的@机器人。
true	即使在多机器人群组中也接受（仅在您能接受重复触发风险时使用）。

重要提示：

• im:message.group_msg 是接收非@群组消息所必需的权限，这在飞书中属于敏感权限。
• 如果未批准此权限，飞书通常只会传递@机器人的群组消息（im:message.group_at_msg:readonly）。

连接模式

有两种连接模式可用于从飞书接收事件：

模式	描述
websocket	（默认，推荐）长轮询WebSocket连接。无需公网URL，可在NAT/防火墙后工作。最适合本地开发和大多数部署场景。
webhook	接收事件回调的HTTP服务器。需要一个可公开访问的URL。适合部署在反向代理（如Nginx）后的服务器环境。

WebSocket模式（默认，无需额外配置）：

channels:
  feishu:
    connectionMode: "websocket"  # 或者直接省略这一行

在飞书控制台：事件与回调 → 选择 长连接。

Webhook模式：

channels:
  feishu:
    connectionMode: "webhook"
    webhookPort: 3000               # HTTP服务器端口（默认3000）
    webhookPath: "/feishu/events"   # 事件回调路径（默认"/feishu/events"）
    encryptKey: "your_encrypt_key"           # 来自飞书控制台→事件与回调→加密密钥
    verificationToken: "your_verify_token"   # 来自飞书控制台→事件与回调→验证令牌

在飞书控制台：事件与回调 → 选择 请求URL → 设置URL为：

https://your-domain.com/feishu/events

注意： 请求URL必须是HTTPS且可公开访问。对于本地开发，可以使用 ngrok 等工具创建隧道：ngrok http 3000，然后使用生成的URL。

渲染模式

模式	描述
auto	（默认）自动检测：带有代码块或表格的消息使用卡片格式，其他情况使用纯文本。
raw	始终以纯文本形式发送回复。Markdown表格会被转换为ASCII格式。
card	始终以交互式卡片形式发送回复，支持完整的Markdown渲染（语法高亮、表格、可点击链接）。

动态代理创建（多用户工作空间隔离）

启用后，每位私信用户都会自动获得一个独立的代理实例，并配备专用的工作空间。这提供了完全的隔离，包括独立的对话历史、内存（MEMORY.md）和工作空间文件。

聊天管理限制 ⚠️

重要提示： delete_chat 需要机器人是群组所有者。如果机器人是以成员身份（非所有者）被加入到现有聊天中，则无法解散该聊天。

如果需要解散机器人不拥有的聊天：

1. 群组所有者应先将所有权转移给机器人，或
2. 群组所有者直接在飞书应用中解散群组。

channels:
  feishu:
    dmPolicy: "open"
    allowFrom: ["*"]
    dynamicAgentCreation:
      enabled: true
      # 工作空间目录模板 ({userId} = OpenID, {agentId} = 生成的代理ID)
      workspaceTemplate: "~/workspaces/feishu-{agentId}"
      # 代理配置目录模板
      agentDirTemplate: "~/.openclaw/agents/{agentId}/agent"
      # 可选：限制动态代理总数
      maxAgents: 100

session:
  # 同时设置会话隔离的 dmScope（对话历史）
  dmScope: "per-peer"

选项	描述
enabled	为 DM 用户启用动态代理创建
workspaceTemplate	工作空间路径模板。支持 {userId}（OpenID）和 {agentId}（= feishu-{openId}）
agentDirTemplate	代理目录路径模板
maxAgents	动态代理数量的可选上限

工作原理：

1. 当新用户发送私信时，系统会在 openclaw.json 中创建一个新的代理条目。
2. 创建绑定以将该用户的私信路由到其专属代理。
3. 自动创建工作空间和代理目录。
4. 该用户后续的消息将发送到其隔离的代理。

与 dmScope: "per-peer" 的区别：

• dmScope: "per-peer" 仅隔离对话历史。
• dynamicAgentCreation 提供全面隔离（工作空间、内存、身份、工具）。

功能

• WebSocket 和 Webhook 连接模式
• 私信和群聊
• 消息回复和引用消息上下文
• 入站媒体支持：AI 可以查看图片、读取文件（PDF、Excel 等），并处理包含嵌入式图片的富文本。
• 图片和文件上传（出站）
• 键入指示器（通过表情符号反应）
• 私信批准的配对流程
• 用户和群组目录查找
• 卡片渲染模式：可选的 Markdown 渲染，带有语法高亮。
• 文档工具：使用 Markdown 读取、创建和写入飞书文档，包括原子化的 create_and_write / import_document 流程，以确保可靠地创建并写入内容。
• 维基工具：导航知识库、列出空间、获取节点详情、搜索、创建/移动/重命名节点。
• 云盘工具：列出文件夹、获取文件信息、创建文件夹、移动/删除文件。
• 多维表格工具：管理多维表格字段和记录（读取/创建/更新/删除），支持 /base/ 和 /wiki/ URL。
• 任务工具：通过飞书任务 v2 API 创建、获取详细信息、更新和删除任务。
• 聊天工具：读取和写入群公告、创建群聊、添加成员、检查机器人是否为成员、删除聊天（feishu_chat）。
• 紧急通知工具：通过 feishu_urgent 发送震动/紧急通知（应用、短信、语音通话）。
• 消息工具：读取单条消息或按时间范围和分页列出最近的聊天历史（feishu_message）。
• 反应工具：在消息上添加、移除和列出表情符号反应（feishu_reaction）。
• @提及转发：当您在消息中提到某人时，机器人的回复也会自动提及他们。
• 权限错误通知：当机器人遇到飞书 API 权限错误时，会自动向用户发送权限授予链接。
• 动态代理创建：每个 DM 用户都可以拥有自己的独立代理实例，并配备专用的工作空间（可选）。

@提及转发

当您希望机器人在回复中提及某人时，只需在您的消息中提及他们即可：

• 私信中：@张三 say hello → 机器人回复 @张三 Hello!
• 群聊中：@bot @张三 say hello → 机器人回复 @张三 Hello!

机器人会自动检测您消息中的 @提及，并将其包含在回复中。无需额外的权限，只需标准的消息权限即可。

常见问题解答

机器人无法接收消息

请检查以下事项：

1. 您是否已配置事件订阅？（参见“事件订阅”部分）
2. 事件订阅模式是否与您的 connectionMode 匹配？
   • websocket → 飞书控制台中的长连接
   • webhook → 飞书控制台中的请求 URL（URL 必须可访问）
3. 您是否添加了 im.message.receive_v1 事件？
4. 权限是否已批准？
5. 对于 webhook 模式：您的服务器是否正在运行，且 URL 是否对外公开？

requireMention: false 但群聊仍需 @提及

请检查以下事项：

1. im:message.group_msg 是否已批准？（敏感权限，用于非 @提及的群聊消息）
2. 如果群聊中有多个机器人，您是否明确设置了 allowMentionlessInMultiBotGroup: true？
3. 在有效账户/群组上是否配置了 requireMention: false？

发送消息时出现 403 错误

请确保 im:message:send_as_bot 权限已批准。

如何清除历史记录/开始新对话

在聊天中发送 /new 命令即可。

为什么输出不是流式传输

飞书 API 存在速率限制。流式更新很容易触发限流。为了稳定性，我们采用先完成再发送的方式。

在飞书中找不到机器人

1. 确保应用已发布（至少为测试版本）。
2. 在飞书搜索框中搜索机器人名称。
3. 检查您的账号是否在应用的可用范围内。

---

中文

安装

openclaw plugins install @m1heng-clawd/feishu

[!IMPORTANT] Windows 排错（spawn npm ENOENT）

如果 openclaw plugins install 失败，可通过最新 tarball 手动安装：

# 方案 A（推荐）：下载最新插件 tarball
npm pack @m1heng-clawd/feishu
openclaw plugins install ./m1heng-clawd-feishu-<version>.tgz

# 方案 B（保留 curl 路径）：先解析最新 tarball 地址，再下载安装
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（方案 B）
$tarball = npm view @m1heng-clawd/feishu dist.tarball
curl.exe -L $tarball -o feishu-latest.tgz
openclaw plugins install .\feishu-latest.tgz

# 方案 C（无 npm 命令）：先在 npm Versions 页查到最新版本号，再套用 URL 模板
# 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

升级

openclaw plugins update feishu

查看已安装版本：

openclaw plugins list | rg -i feishu

配置

1. 在 飞书开放平台 创建自建应用
2. 在凭证页面获取 App ID 和 App Secret
3. 开启所需权限（见下方）
4. 配置事件订阅（见下方）⚠️ 重要
5. 配置插件：

必需权限

权限	范围	说明
im:message	消息	发送和接收消息
im:message.p2p_msg:readonly	私聊	读取发给机器人的私聊消息
im:message.group_at_msg:readonly	群聊	接收群内 @机器人 的消息
im:message:send_as_bot	发送	以机器人身份发送消息
im:resource	媒体	上传和下载图片/文件

可选权限

权限	范围	说明
contact:user.base:readonly	用户信息	获取用户基本信息（用于解析发送者姓名，避免群聊/私聊把不同人当成同一说话者）
im:message.group_msg	群聊	读取所有群消息（敏感权限）。当你希望 requireMention: false 对“未 @ 的群消息”生效时必需
im:message:readonly	读取	获取历史消息
im:message:update	编辑	更新/编辑已发送消息
im:message:recall	撤回	撤回已发送消息
im:message.reactions:read	表情	查看消息表情回复

工具权限

只读权限（最低要求）：

权限	工具	说明
docx:document:readonly	feishu_doc	读取文档
drive:drive:readonly	feishu_drive	列出文件夹、获取文件信息
wiki:wiki:readonly	feishu_wiki	列出空间、列出节点、获取节点详情、搜索
bitable:app:readonly	feishu_bitable	读取多维表格记录和字段
task:task:read	feishu_task_get	获取任务详情
task:tasklist:read	feishu_tasklist_get, feishu_tasklist_list	获取/列出任务清单（tasklists）
task:comment:read	feishu_task_comment_list, feishu_task_comment_get	列出/获取任务评论
task:attachment:read	feishu_task_attachment_list, feishu_task_attachment_get	列出/获取任务附件
im:chat.announcement:read	feishu_chat	读取群公告
im:chat:readonly	feishu_chat	获取群信息、检查机器人是否在群内
im:message 或 im:message:readonly	feishu_message	读取单条/私聊消息
im:message.group_at_msg:readonly	feishu_message	读取群聊中所有消息
im:message.reactions:read	feishu_reaction	查看消息表情回复

读写权限（可选，用于创建/编辑/删除操作）：

权限	工具	说明
docx:document	feishu_doc	创建/编辑文档
docx:document.block:convert	feishu_doc	Markdown 转 blocks（write/append/create_and_write 必需，feishu_drive.import_document 也会用到）
drive:drive	feishu_doc, feishu_drive	上传图片到文档、创建文件夹、移动/删除文件
wiki:wiki	feishu_wiki	创建/移动/重命名知识库节点
bitable:app	feishu_bitable	创建/更新/删除多维表格记录并管理字段
task:task:write	feishu_task_create, feishu_task_subtask_create, feishu_task_update, feishu_task_delete	创建/更新/删除任务
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	创建/更新/删除任务清单并管理成员/关联任务
task:comment:write	feishu_task_comment_create, feishu_task_comment_update, feishu_task_comment_delete	创建/更新/删除任务评论
task:attachment:write	feishu_task_attachment_upload, feishu_task_attachment_delete	上传/删除任务附件
im:message.urgent	feishu_urgent	发送应用内加急（buzz）通知。使用 sms 和 phone 变体（im:message.urgent:sms、im:message.urgent:phone）可发送短信和语音电话加急。
im:chat.announcement	feishu_chat	写入/更新群公告
im:chat	feishu_chat	创建和删除群聊
im:chat.members	feishu_chat	向群聊添加成员
im:message.reactions:write_only	feishu_reaction	发送、删除消息表情回复

飞书控制台中任务权限的显示名称可能略有差异，必要时可按关键字 task / tasklist / comment / attachment 搜索并授予对应读写权限。

任务评论权限 ⚠️

任务评论需要单独授权：

1. 读取评论：授予 task:comment:read。
2. 创建/更新/删除评论：授予 task:comment:write。

缺少上述权限时，评论相关接口会返回权限不足错误。

任务附件上传 ⚠️

任务附件支持上传/获取/列表/删除。上传来源：

1. OpenClaw/Node 所在机器的本地文件路径（file_path）
2. 可直接下载的远程链接（file_url，公开/预签名 URL）

file_url 上传路径会使用 OpenClaw 运行时的媒体下载安全校验与大小限制（mediaMaxMb），随后经临时本地文件上传到任务附件。

任务清单所有者限制 ⚠️

重要： 创建/修改任务清单时，请保持清单所有者为机器人本身，只把用户作为协作人添加。

任务清单权限基于“所有者 + 协作成员角色”授予。如果把清单所有者改成用户、且机器人不在协作成员中，机器人可能会失去对该清单的读取/编辑/管理权限，导致后续对清单的操作失败。

任务限制 ⚠️

重要： 只有当任务责任人包含用户时，用户才能查看到该任务。

限制： 机器人目前只能给自己创建出来的任务创建子任务。

为避免“任务创建了但用户看不到”的问题：

1. 创建任务时，请把发起用户设为任务负责人（assignee）。
2. 如需更灵活的子任务创建/组织/可见性管理，建议使用任务清单（tasklists）。

云空间访问权限 ⚠️

重要： 机器人没有自己的"我的空间"（根目录）。机器人只能访问被分享给它的文件/文件夹。

要让机器人管理文件：

1. 在你的飞书云空间创建一个文件夹
2. 右键文件夹 → 分享 → 搜索机器人名称
3. 授予相应权限（查看/编辑）

如果不做这一步，feishu_drive 的 create_folder 等操作会失败，因为机器人没有根目录可以创建文件夹。

知识库空间权限 ⚠️

重要： 仅有 API 权限不够，还需要将机器人添加到知识库空间。

1. 打开需要机器人访问的知识库空间
2. 点击 设置（齿轮图标）→ 成员管理
3. 点击 添加成员 → 搜索机器人名称
4. 选择权限级别（查看/编辑）

如果不做这一步，即使 API 权限正确，feishu_wiki 也会返回空结果。

参考文档：知识库常见问题 - 如何将应用添加为知识库成员

多维表格访问权限 ⚠️

重要： 与其他资源一样，机器人只能访问被分享给它的多维表格。

要让机器人访问多维表格：

1. 打开需要机器人访问的多维表格
2. 点击 分享 按钮 → 搜索机器人名称
3. 授予相应权限（查看/编辑）

feishu_bitable 工具支持两种 URL 格式：

• /base/XXX?table=YYY - 标准多维表格链接
• /wiki/XXX?table=YYY - 嵌入在知识库中的多维表格（自动转换为 app_token）

事件订阅 ⚠️

这是最容易遗漏的配置！ 如果机器人能发消息但收不到消息，请检查此项。

在飞书开放平台的应用后台，进入 事件与回调 页面：

1. 事件配置方式：根据你的 connectionMode 选择对应的订阅方式：
   • 使用长连接接收事件 — 对应 connectionMode: "websocket"（推荐，无需公网地址）
   • 使用请求地址接收事件 — 对应 connectionMode: "webhook"（需要公网可访问的 URL）
2. 添加事件订阅，勾选以下事件：

事件	说明
im.message.receive_v1	接收消息（必需）
im.message.message_read_v1	消息已读回执
im.chat.member.bot.added_v1	机器人进群
im.chat.member.bot.deleted_v1	机器人被移出群

3. 确保事件订阅的权限已申请并通过审核

openclaw config set channels.feishu.appId "cli_xxxxx"
openclaw config set channels.feishu.appSecret "your_app_secret"
openclaw config set channels.feishu.enabled true

配置选项

channels:
  feishu:
    enabled: true
    appId: "cli_xxxxx"
    appSecret: "secret"
    # 域名: "feishu" (国内)、"lark" (国际) 或自定义 URL
    domain: "feishu"  # 私有化部署可用 "https://open.xxx.cn"
    # 连接模式: "websocket" (推荐) 或 "webhook"
    connectionMode: "websocket"
    # 私聊策略: "pairing" | "open" | "allowlist"
    dmPolicy: "pairing"
    # 私聊白名单（open_id/user_id）；当 dmPolicy="open" 时请包含 "*"
    allowFrom: []
    # 群聊策略: "open" | "allowlist" | "disabled"
    groupPolicy: "allowlist"
    # 群聊是否需要 @机器人
    requireMention: true
    # 免 @ 安全默认策略（requireMention=false 时）：
    # 仅在群内机器人数量 <= 1 时处理未 @ 的群消息。
    # 设为 true 可在多 bot 群也放开免 @（需自行承担重复触发风险）。
    allowMentionlessInMultiBotGroup: false
    # 群聊命令绕过 @ 策略: "never" | "single_bot" | "always"
    # 默认 "single_bot"：仅当群内机器人数量 <= 1 时，允许已授权命令免 @
    groupCommandMentionBypass: "single_bot"
    # 媒体文件最大大小 (MB, 默认 30)
    mediaMaxMb: 30
    # 回复渲染模式: "auto" | "raw" | "card"
    renderMode: "auto"

私聊策略（dmPolicy）与访问授权

dmPolicy 控制的是“谁可以在私聊里触发机器人”。
在多账号模式下，它按账号生效（channels.feishu.accounts.<accountId>）。

dmPolicy	谁能私聊触发机器人	如何给用户开通
pairing	allowFrom 中的用户，或已通过配对审批的用户	用户先私聊机器人拿到配对码；管理员执行 openclaw pairing approve feishu <code>。
open	所有人	配置 allowFrom: ["*"]，表示全部放开。
allowlist	仅 allowFrom 中的用户	将用户 open_id/user_id 加入 allowFrom，然后重载配置。

说明：

• allowFrom 支持飞书用户 ID（推荐 open_id，也支持 user_id）。
• 当 dmPolicy: "open" 时，建议固定写 allowFrom: ["*"]，语义最清晰，也满足顶层配置校验要求。
• pairing 和 allowlist 都可以先通过 allowFrom 预授权部分用户。

配对审批流程（pairing）：

1. 用户先给机器人发一条私聊消息。
2. 机器人返回配对码（例如 H9ZEHY8R）。
3. 管理员执行审批命令：

openclaw pairing approve feishu H9ZEHY8R

4. 审批后该用户立即可用。

示例：全部放开

channels:
  feishu:
    dmPolicy: "open"
    allowFrom: ["*"]

示例：灰度放开（pairing + 预授权）

channels:
  feishu:
    dmPolicy: "pairing"
    allowFrom:
      - "ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

示例：严格白名单

channels:
  feishu:
    dmPolicy: "allowlist"
    allowFrom:
      - "ou_alice"
      - "ou_bob"

示例：按账号隔离配置

channels:
  feishu:
    accounts:
      lobster-1:
        dmPolicy: "open"
        allowFrom: ["*"]
      lobster-5:
        dmPolicy: "pairing"

channels.feishu.dmPolicy / channels.feishu.allowFrom 是“默认值”；账号下未覆盖时才会继承。

dmPolicy 只控制“是否允许触发机器人”。
真正执行文档/云盘/知识库/多维表格操作，还需要两层权限：1）应用 API 权限（scopes）；2）把目标资源分享给机器人。

群聊命令免 @ 策略

当 requireMention: true 时，Feishu 仍可让“已授权控制命令（如 /new）”在不 @bot 的情况下通过。

groupCommandMentionBypass	行为
never	群聊命令永不绕过 @ 校验。
single_bot	仅当群内机器人数量不超过 1 个时才允许绕过（默认）。
always	已授权控制命令始终可绕过 @ 校验。

说明：

• 仅对群聊中的“已授权控制命令”生效。
• 同一条消息里如果显式 @ 了任意用户，则不会触发命令免 @。
• 私聊场景不受该配置影响。

群聊免 @ 行为（requireMention: false）

当 requireMention: false 时，插件对“未 @ 的群消息”采用安全默认策略：

allowMentionlessInMultiBotGroup	未 @ 群消息行为
false（默认）	仅当群里机器人数量不超过 1 个时处理；多 bot 群仍要求显式 @bot。
true	即使在多 bot 群也处理未 @ 消息（仅建议在可接受重复触发风险时启用）。

重要说明：

• 要接收未 @ 的群消息，必须申请并通过 im:message.group_msg，且该权限是飞书敏感权限。
• 若未通过该权限，飞书通常只会推送 @bot 群消息（im:message.group_at_msg:readonly）。

连接模式

支持两种从飞书接收事件的连接模式：

模式	说明
websocket	（默认，推荐）长连接 WebSocket 模式。无需公网地址，可在 NAT/防火墙后使用。适合本地开发和大部分部署场景。
webhook	HTTP 服务器接收事件回调。需要公网可访问的 URL。适合通过反向代理（如 Nginx）部署的服务器环境。

WebSocket 模式（默认，无需额外配置）：

channels:
  feishu:
    connectionMode: "websocket"  # 或直接省略此行

飞书控制台：事件与回调 → 选择 使用长连接接收事件。

Webhook 模式：

channels:
  feishu:
    connectionMode: "webhook"
    webhookPort: 3000               # HTTP 服务端口（默认: 3000）
    webhookPath: "/feishu/events"   # 事件回调路径（默认: "/feishu/events"）
    encryptKey: "your_encrypt_key"           # 飞书控制台 → 事件与回调 → Encrypt Key
    verificationToken: "your_verify_token"   # 飞书控制台 → 事件与回调 → Verification Token

飞书控制台：事件与回调 → 选择 使用请求地址接收事件 → 填入请求地址：

https://your-domain.com/feishu/events

提示： 请求地址必须是 HTTPS 且公网可访问。本地开发时，可使用 ngrok 等工具创建隧道：ngrok http 3000，然后使用生成的地址。

渲染模式

模式	说明
auto	（默认）自动检测：有代码块或表格时用卡片，否则纯文本
raw	始终纯文本，表格转为 ASCII
card	始终使用卡片，支持语法高亮、表格、链接等。

群管理限制 ⚠️

重要提示： delete_chat 需要机器人是该群的群主。如果机器人是以成员身份加入现有群聊（非群主），则无法解散该群聊。

如需解散机器人不拥有的群聊：

1. 群主将群主权限转让给机器人，或
2. 由群主直接在飞书客户端解散群聊。

动态 Agent 创建（多用户 Workspace 隔离）

启用后，每个私聊用户会自动获得独立的 agent 实例和专属 workspace。这提供完整的隔离，包括独立的对话历史、记忆（MEMORY.md）和工作区文件。

channels:
  feishu:
    dmPolicy: "open"
    allowFrom: ["*"]
    dynamicAgentCreation:
      enabled: true
      # workspace 目录模板 ({userId} = OpenID, {agentId} = 生成的 agent ID)
      workspaceTemplate: "~/workspaces/feishu-{agentId}"
      # agent 配置目录模板
      agentDirTemplate: "~/.openclaw/agents/{agentId}/agent"
      # 可选：限制动态 agent 总数
      maxAgents: 100

session:
  # 同时设置 dmScope 以隔离对话历史
  dmScope: "per-peer"

选项	说明
enabled	是否为私聊用户启用动态 agent 创建
workspaceTemplate	workspace 路径模板，支持 {userId}（OpenID）和 {agentId}（= feishu-{openId}）
agentDirTemplate	agent 目录路径模板
maxAgents	可选，限制动态 agent 的最大数量

工作原理：

1. 当新用户发送私聊时，系统在 openclaw.json 中创建新的 agent 条目
2. 创建 binding 将该用户的私聊路由到专属 agent
3. 自动创建 workspace 和 agent 目录
4. 该用户后续的消息都会路由到其隔离的 agent

与 dmScope: "per-peer" 的区别：

• dmScope: "per-peer" 仅隔离对话历史
• dynamicAgentCreation 提供完整隔离（workspace、记忆、身份、工具）

功能

• WebSocket 和 Webhook 连接模式
• 私聊和群聊
• 消息回复和引用上下文
• 入站媒体支持：AI 可以看到图片、读取文件（PDF、Excel 等）、处理富文本中的嵌入图片
• 图片和文件上传（出站）
• 输入指示器（通过表情回复实现）
• 私聊配对审批流程
• 用户和群组目录查询
• 卡片渲染模式：支持语法高亮的 Markdown 渲染
• 文档工具：读取、创建、用 Markdown 写入飞书文档（表格因 API 限制不支持）
• 知识库工具：浏览知识库、列出空间、获取节点详情、搜索、创建/移动/重命名节点
• 云空间工具：列出文件夹、获取文件信息、创建文件夹、移动/删除文件
• 多维表格工具：支持多维表格字段与记录的读取/创建/更新/删除，支持 /base/ 和 /wiki/ 两种链接格式
• 任务工具：基于 Task v2 API 支持任务创建、获取详情、更新和删除
• 群聊工具：读写群公告、创建群聊、添加成员、检查机器人是否在群内、删除群聊（feishu_chat）
• 加急通知工具：发送应用内加急（buzz）、短信、语音电话加急通知（feishu_urgent）
• 消息工具：读取单条消息或列出聊天历史记录，支持时间范围和分页（feishu_message）
• 表情工具：添加、删除、列出消息上的表情回复（feishu_reaction）
• @ 转发功能：在消息中 @ 某人，机器人的回复会自动 @ 该用户
• 权限错误提示：当机器人遇到飞书 API 权限错误时，会自动通知用户并提供权限授权链接
• 动态 Agent 创建：每个私聊用户可拥有独立的 agent 实例和专属 workspace（可选）

@ 转发功能

如果你希望机器人的回复中 @ 某人，只需在你的消息中 @ 他们：

• 私聊：@张三 跟他问好 → 机器人回复 @张三 你好！
• 群聊：@机器人 @张三 跟他问好 → 机器人回复 @张三 你好！

机器人会自动检测消息中的 @ 并在回复时带上。无需额外权限。

常见问题

机器人收不到消息

检查以下配置：

1. 是否配置了 事件订阅？（见上方事件订阅章节）
2. 事件订阅方式是否与 connectionMode 匹配？
   • websocket → 飞书控制台选择 使用长连接接收事件
   • webhook → 飞书控制台选择 使用请求地址接收事件（URL 必须可访问）
3. 是否添加了 im.message.receive_v1 事件？
4. 相关权限是否已申请并审核通过？
5. 如果使用 webhook 模式：服务是否正在运行？URL 是否公网可访问？

已配置 requireMention: false，群里仍然必须 @

请重点检查：

1. 是否已申请并审核通过 im:message.group_msg（敏感权限，接收未 @ 群消息必需）
2. 群里若有多个 bot，是否显式设置了 allowMentionlessInMultiBotGroup: true
3. requireMention: false 是否配置在当前生效的账号/群配置上

返回消息时 403 错误

确保已申请 im:message:send_as_bot 权限，并且权限已审核通过。

如何清理历史会话 / 开启新对话

在聊天中发送 /new 命令即可开启新对话。

消息为什么不是流式输出

飞书 API 有请求频率限制，流式更新消息很容易触发限流。当前采用完整回复后一次性发送的方式，以保证稳定性。

在飞书里找不到机器人

1. 确保应用已发布（至少发布到测试版本）
2. 在飞书搜索框中搜索机器人名称
3. 检查应用可用范围是否包含你的账号

---

许可证

MIT

clawdbot-feishu 快速上手指南

本指南帮助开发者快速将 OpenClaw 机器人接入飞书（Feishu/Lark）平台。

1. 环境准备

• 运行环境：已安装并配置好 OpenClaw 的环境（Node.js）。
• 飞书开放平台账号：拥有飞书开发者权限，可创建自建应用。
• 网络要求：
  • 若使用 websocket 模式（推荐），无需公网 IP。
  • 若使用 webhook 模式，服务器需具备公网可访问的 URL。

2. 安装步骤

方式一：标准安装（推荐 Linux/macOS）

openclaw plugins install @m1heng-clawd/feishu

方式二：Windows 或安装失败时的手动安装

若在 Windows 下遇到 spawn npm ENOENT 错误，或标准安装失败，请使用以下手动安装方式：

选项 A（推荐）：下载压缩包安装

npm pack @m1heng-clawd/feishu
openclaw plugins install ./m1heng-clawd-feishu-<version>.tgz

选项 B：通过 curl 下载最新包

# Linux/macOS
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
$tarball = npm view @m1heng-clawd/feishu dist.tarball
curl.exe -L $tarball -o feishu-latest.tgz
openclaw plugins install .\feishu-latest.tgz

验证安装

查看已安装的插件版本：

openclaw plugins list | rg -i feishu

升级插件：

openclaw plugins update feishu

3. 基本使用

第一步：配置飞书自建应用

1. 登录 飞书开放平台，创建一个自建应用。

2. 在“凭证与基础信息”页面获取 App ID 和 App Secret。

3. 配置权限：在“权限管理”中添加以下必要权限：

   • im:message (收发消息)
   • im:message.p2p_msg:readonly (读取私聊)
   • im:message.group_at_msg:readonly (读取群内 @ 消息)
   • im:message:send_as_bot (以机器人身份发送)
   • im:resource (上传下载媒体文件)

   注：如需使用文档、云盘、任务等高级功能，请按需添加对应读写权限。

4. 配置事件订阅（关键步骤）：

   • 进入“事件订阅”页面。
   • 订阅模式选择：
     • 长连接：对应配置项 connectionMode: "websocket"（推荐，无需公网）。
     • 请求 URL：对应配置项 connectionMode: "webhook"（需填写公网回调地址）。
   • 添加以下事件：
     • im.message.receive_v1 (接收消息，必选)
     • im.chat.member.bot.added_v1 (机器人被拉入群)
   • 发布版本并启用事件订阅。

5. 共享资源（重要）：

   • 云盘/多维表格：机器人无法访问所有文件，必须手动将特定文件夹或多维表格分享给机器人并授予权限。
   • 知识库：必须在知识库设置中，将机器人添加为成员。

第二步：配置 OpenClaw

使用命令行将获取到的凭证写入配置文件：

# 替换为你的实际 App ID 和 App Secret
openclaw config set channels.feishu.appId "cli_xxxxx"
openclaw config set channels.feishu.appSecret "xxxxxxxxxx"

# 可选：配置连接模式 (默认为 websocket)
openclaw config set channels.feishu.connectionMode "websocket"

# 可选：配置是否仅响应 @ 消息 (默认 true)
openclaw config set channels.feishu.requireMention "true"

第三步：启动与测试

1. 重启 OpenClaw 服务以加载插件。
2. 在飞书中找到该机器人，发送一条消息（或在群中 @ 机器人）。
3. 观察终端日志及飞书端的回复，确认交互正常。