OpenClaw飞书官方插件使用完整指南：让AI真正融入你的飞书工作流

“

本段欲回答的核心问题：为什么需要飞书官方插件？它和之前的社区版有什么区别？
一句话答案：飞书官方插件能以你的身份直接读写飞书文档、消息和日历，无需反复复制粘贴，让AI真正成为你飞书中的“数字员工”。

过去，你可能已经将OpenClaw（小龙虾）接入了飞书，它能帮你写周报、查资料、出方案。但很快你会发现一个尴尬的瓶颈：它总是回复“我没有飞书文档/消息的访问权限，请把内容发给我”。你不得不把文档复制出来，把聊天记录粘贴过去——原本用来提效的工具，反而增加了额外操作。

2026年3月6日，飞书官方正式上线了OpenClaw官方插件。这次升级彻底改变了交互模式：在获得你的授权后，OpenClaw可以直接以你的身份查看文档、检索资料、核对日历档期、理解群聊上下文。你说一句话，它就能伸出“钳子”，在飞书里把活儿干了。

下面这张图直观展示了新旧插件的差异：

一、核心能力：一句话能做什么？

“

本段欲回答的核心问题：安装插件后，OpenClaw究竟能帮我处理哪些飞书任务？

官方插件赋予了OpenClaw“用户视角”的完整操作能力，主要体现在以下几个场景：

能力维度	具体任务	一句话示例
消息处理	读取群聊/单聊消息、合并转发、表情回应	“帮我总结今天产品群未读消息的要点”
文档操作	读写文档、下载附件、复制/创建文档	“查找上周的需求文档，提取其中的用户故事”
日历管理	查看日程、创建/更新事件、查询忙闲	“看看我明天下午三点有空吗？约个会”
多维表格	查询/创建/更新记录	“在产品需求表中新增一条记录”
任务协作	读取/创建任务，管理任务列表	“提醒我下周三之前完成性能测试报告”

除了上述操作，插件还支持更自然的交互方式：流式输出卡片回复、识别合并转发消息、发送表情等。这些细节让对话体验更接近人与人之间的协作。

二、安装前的准备：你只需要这几样东西

“

本段欲回答的核心问题：安装飞书官方插件需要满足哪些前置条件？

在开始配置前，请确保你已经具备以下条件：

OpenClaw已安装，且版本符合要求：
- Linux/MacOS：openclaw 2026.2.26 及以上
- Windows：openclaw 2026.3.2 及以上（部分Windows版本仍有兼容问题，建议优先使用Mac/Linux）
- 查看版本命令：openclaw -v
- 升级命令：npm install -g openclaw
拥有飞书企业管理后台的权限，能够创建自建应用。
准备一台可以运行命令行工具的电脑（用于执行安装和配对命令）。

“

作者反思：我第一次安装时忽略了版本检查，结果折腾了半天才发现是版本过低导致事件订阅失败。版本匹配是顺利安装的第一道防线，建议在开始前务必执行 openclaw -v 确认。

三、安装步骤详解（图文实操版）

“

本段欲回答的核心问题：从零开始，如何一步步完成飞书官方插件的安装与配置？

整个安装过程分为四步：创建飞书机器人 → 安装插件 → 订阅事件 → 配对授权。下面每一步都会配上关键截图和注意事项。

1. 创建飞书机器人并导入权限

1.1 创建企业自建应用

登录飞书开发者后台，单击“创建企业自建应用”。

输入应用名称、描述及图标（可以使用默认图标），单击“创建”。

1.2 开启机器人能力

在左侧目录选择“应用能力 – 添加应用能力”，按能力添加，单击“机器人”卡片的“添加”按钮。

1.3 批量导入权限

这是最关键的一步。权限列表决定了OpenClaw能用你的身份做什么。如果权限不全，后续使用时可能会反复弹出授权窗口，或功能无法生效。

进入“开发配置 > 权限管理”，单击“批量导入/导出权限”。

将下面这份完整的权限JSON代码复制进去，覆盖原有示例，然后单击“下一步，确认新增权限”。

{
  "scopes": {
    "tenant": [
      "contact:contact.base:readonly",
      "docx:document:readonly",
      "im:chat:read",
      "im:chat:update",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message.pins:read",
      "im:message.pins:write_only",
      "im:message.reactions:read",
      "im:message.reactions:write_only",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "im:message:send_multi_users",
      "im:message:send_sys_msg",
      "im:message:update",
      "im:resource",
      "application:application:self_manage",
      "cardkit:card:write",
      "cardkit:card:read"
    ],
    "user": [
      "contact:user.employee_id:readonly",
      "offline_access",
      "base:app:copy",
      "base:field:create",
      "base:field:delete",
      "base:field:read",
      "base:field:update",
      "base:record:create",
      "base:record:delete",
      "base:record:retrieve",
      "base:record:update",
      "base:table:create",
      "base:table:delete",
      "base:table:read",
      "base:table:update",
      "base:view:read",
      "base:view:write_only",
      "base:app:create",
      "base:app:update",
      "base:app:read",
      "board:whiteboard:node:create",
      "board:whiteboard:node:read",
      "calendar:calendar:read",
      "calendar:calendar.event:create",
      "calendar:calendar.event:delete",
      "calendar:calendar.event:read",
      "calendar:calendar.event:reply",
      "calendar:calendar.event:update",
      "calendar:calendar.free_busy:read",
      "contact:contact.base:readonly",
      "contact:user.base:readonly",
      "contact:user:search",
      "docs:document.comment:create",
      "docs:document.comment:read",
      "docs:document.comment:update",
      "docs:document.media:download",
      "docs:document:copy",
      "docx:document:create",
      "docx:document:readonly",
      "docx:document:write_only",
      "drive:drive.metadata:readonly",
      "drive:file:download",
      "drive:file:upload",
      "im:chat.members:read",
      "im:chat:read",
      "im:message",
      "im:message.group_msg:get_as_user",
      "im:message.p2p_msg:get_as_user",
      "im:message:readonly",
      "search:docs:read",
      "search:message",
      "space:document:delete",
      "space:document:move",
      "space:document:retrieve",
      "task:comment:read",
      "task:comment:write",
      "task:task:read",
      "task:task:write",
      "task:task:writeonly",
      "task:tasklist:read",
      "task:tasklist:write",
      "wiki:node:copy",
      "wiki:node:create",
      "wiki:node:move",
      "wiki:node:read",
      "wiki:node:retrieve",
      "wiki:space:read",
      "wiki:space:retrieve",
      "wiki:space:write_only"
    ]
  }
}

确认无误后，单击“申请开通”。

1.4 发布应用版本

返回应用管理页面，单击顶部“创建版本”。

填写版本号、更新说明等信息（可随意填写，如“v1.0.0”）。

单击“保存”后，再单击右上角“确认发布”按钮，等待飞书审核（通常几分钟内自动通过）。

1.5 获取App ID和App Secret

发布成功后，在左侧“基础信息 > 凭证与基础信息”中，找到“应用凭证”区域，记下App ID和App Secret。这两个值稍后安装插件时会用到。

2. 安装飞书插件到OpenClaw

“

如果之前安装过其他飞书插件，安装新插件时会自动禁用旧插件，无需手动处理。

打开终端（Mac/Linux推荐使用原生终端，Windows建议使用PowerShell或WSL），依次执行以下命令：

# 设置npm镜像（国内环境可加速）
npm config set registry https://registry.npmjs.org

# 安装飞书官方插件
npm install -g @openclaw/plugin-feishu

安装过程中，脚本会提示你选择“是否沿用历史飞书应用”或“创建新应用”。由于我们是第一次配置，选择“创建或关联新应用”，然后输入上一步获取的App ID和App Secret。

安装完成后，运行以下命令启动OpenClaw网关（让插件开始监听飞书事件）：

openclaw gateway run

如果看到类似下面的日志，说明监听已成功启动：

验证插件状态：打开另一个终端窗口，执行：

openclaw plugins list

检查列表中是否出现 feishu-openclaw-plugin，且状态为 loaded，而原来的 feishu 插件状态为 disabled。这表示新插件已启用。

3. 配置飞书机器人事件订阅与卡片回调

为了让OpenClaw能够接收你在飞书中的消息、点击卡片等操作，需要配置事件订阅方式为长连接。

3.1 设置事件订阅

回到飞书开发者后台，在应用详情页左侧选择“事件订阅”。将“订阅方式”改为长连接。

然后添加以下事件（建议全部勾选）：

接收消息（im.message.receive_v1）
消息被添加表情（im.message.reaction.created_v1）
消息被取消表情（im.message.reaction.deleted_v1）

添加事件1
添加事件2

3.2 配置卡片回调

为了让OpenClaw能响应你点击卡片按钮的操作，在左侧选择“回调配置”，同样将方式改为长连接，并添加回调（直接点击“添加”按钮即可）。

配置卡片回调
添加回调

配置完成后，再次发布应用版本（重复1.4的发布步骤），使配置生效。

4. 配对授权：让OpenClaw以你的身份操作

最后一步，你需要将OpenClaw与你的飞书账号绑定，并授予它代表你执行操作的权限。

在飞书中向刚刚创建的应用机器人发送任意一条消息（例如“你好”）。
机器人会自动回复一条包含配对码的消息（由字母和数字组合，有效期5分钟）。
在服务器终端执行以下命令（将 <配对码> 替换为实际收到的代码）：

openclaw pairing approve feishu <配对码> --notify

执行成功后，机器人会给你发送一条确认消息，并附带一个授权链接。

点击链接（或在浏览器中打开），完成用户授权。这一步非常重要——只有授权后，OpenClaw才能读取你的文档、日历等私有数据。

如果你暂时不想授权，也可以先开始对话，后续在对话框中输入 /feishu auth 来触发批量授权。

验证安装成功

与机器人对话，发送：/feishu start
如果返回了插件版本号信息，说明安装已全部完成。

最后，为了让OpenClaw了解新插件的能力，可以发送：“学习一下我安装的新飞书插件，列出有哪些能力”。它会自动加载功能清单。

四、实战场景：让AI替你“跑腿”的三种典型用法

“

本段欲回答的核心问题：安装插件后，具体能用OpenClaw完成哪些实际工作任务？

为了帮你更直观地理解插件的价值，这里列举三个日常工作中最高频的场景。

场景一：会议纪要自动生成

痛点：每次开完会，都要手动翻聊天记录、整理待办。
新方式：在群聊中@OpenClaw：“帮我总结今天下午产品需求评审会的讨论要点，并列出待办事项”。
OpenClaw会读取群消息（包括文件、链接），自动生成结构化的会议纪要，甚至可以直接把待办创建到你的任务列表。

场景二：文档快速检索与摘要

痛点：文档散落在各个知识库，找一份历史方案要翻半天。
新方式：在私聊中对OpenClaw说：“查找去年12月关于性能优化的技术方案文档，提取核心结论”。
OpenClaw通过飞书搜索接口，以你的权限搜索所有文档，找到后阅读内容并提炼摘要返回。

场景三：日程冲突自动协调

痛点：约会议时反复查看彼此忙闲，来回沟通耗时。
新方式：在群里@OpenClaw：“我和市场部王经理明天下午2-4点都有空吗？有的话帮我创建一个会议，邀请他和李总”。
OpenClaw会查看你和王经理的日历，如果空闲则自动创建会议事件并发送邀请，如果冲突则建议其他时段。

“

作者反思：这些场景听起来很美好，但实际使用时，授权范围的精确性会影响体验。比如在场景三中，如果OpenClaw没有读取对方日历的权限（需要对方也授权或应用拥有相关权限），就无法完成冲突检测。因此，建议在团队内部使用时，统一安装并授权同一应用，或者使用租户级权限。

五、日常维护与故障排查

“

本段欲回答的核心问题：插件如何更新？遇到报错怎么快速修复？

1. 更新插件到最新版本

官方插件会持续优化，建议定期更新。执行以下命令即可：

feishu-plugin-onboard update

如果系统提示找不到该指令，可能是辅助脚本未安装。可以先手动安装：

Linux/MacOS：

npm config set registry https://registry.npmjs.org
curl -o /tmp/feishu-openclaw-plugin-onboard-cli.tgz https://registry.npmjs.org/@openclaw/plugin-feishu-onboard/-/plugin-feishu-onboard-最新版本.tgz
npm install /tmp/feishu-openclaw-plugin-onboard-cli.tgz -g
rm /tmp/feishu-openclaw-plugin-onboard-cli.tgz

（请将“最新版本”替换为实际版本号，或直接使用上面提供的通用URL）

Windows（CMD）：

npm config set registry https://registry.npmjs.org
curl -o "%TEMP%\feishu.tgz" https://registry.npmjs.org/@openclaw/plugin-feishu-onboard/-/plugin-feishu-onboard-最新版本.tgz
npm install -g "%TEMP%\feishu.tgz"
del "%TEMP%\feishu.tgz"

2. 常见问题自检

OpenClaw内置了多个诊断指令，可以帮助你快速定位问题：

命令	作用
`/feishu start`	确认插件是否安装成功
`/feishu doctor`	检查配置是否正常，输出诊断报告
`/feishu auth`	批量完成用户授权（如果之前跳过）
`feishu-plugin-onboard doctor`	在终端查看更详细的系统级问题
`feishu-plugin-onboard doctor --fix`	尝试自动修复常见配置问题
`feishu-plugin-onboard info --all`	查看完整版本和配置信息（反馈问题时带上）

例如，执行 feishu-plugin-onboard doctor 会输出类似下面的诊断结果，指出可能缺失的权限或配置错误：

如果自动修复失败，可以截取诊断信息到官方反馈群寻求帮助。

六、作者反思：为什么这次升级是分水岭？

从社区版到官方插件，最大的变化不是技术栈，而是交互哲学的转变。

过去，AI是“外挂”——你需要把信息喂给它，它才能工作。现在，AI是“内嵌”——它主动去拿信息，你只负责下达指令。这背后依赖的是飞书开放平台对用户身份授权的完善支持。OpenClaw不再以机器人的固定身份存在，而是可以代表你，去做你能做的事。

但这也带来了新的考量：

安全边界：插件要求“以用户身份”操作，意味着一旦授权，它能接触到你权限范围内的所有数据。因此，官方建议不要将这样的机器人作为群机器人供多人使用，因为那样会混淆授权主体。更适合的方式是个人助手，或者由管理员统一授权后，在特定场景下使用。
权限管理成本：导入的权限列表非常长，覆盖了几乎所有飞书核心功能。虽然一次性授权后体验丝滑，但也要求管理员或用户理解每个权限的用途，避免过度授权。好在飞书支持按需撤销，你可以随时在“账号安全”中查看并取消应用的某些权限。

“

学到的教训：在配置阶段，很多人容易忽略卡片回调的配置，导致点击按钮后AI无响应。实际上，只要按照本文步骤，确保长连接和回调都配置正确，就能避免这个坑。

七、一页速览：安装与使用操作清单

为了方便你快速落地，这里提炼了一份精简版操作清单：

[ ] 检查OpenClaw版本：openclaw -v，如低于要求则升级。
[ ] 创建飞书应用：在开发者后台创建企业自建应用，开启机器人能力。
[ ] 导入权限JSON：批量导入文中提供的完整权限列表。
[ ] 发布应用版本：保存并发布，获取App ID和App Secret。
[ ] 安装插件：npm install -g @openclaw/plugin-feishu，输入App ID/Secret。
[ ] 启动网关：openclaw gateway run（保持运行）。
[ ] 配置事件订阅：改为长连接，添加消息、表情事件。
[ ] 配置卡片回调：改为长连接，添加回调。
[ ] 再次发布应用：使事件配置生效。
[ ] 配对授权：向机器人发消息获得配对码，执行openclaw pairing approve，完成网页授权。
[ ] 验证：发送/feishu start，让AI学习插件能力。

八、常见问题（FAQ）

1. 安装插件后，原来的飞书插件会冲突吗？

不会。安装官方插件时会自动禁用旧版飞书插件（状态变为disabled），两者可共存但只有新插件生效。

2. 为什么AI无法读取我的文档/日历？

通常是因为未完成用户授权。请检查是否点击了配对后收到的授权链接，或手动发送/feishu auth完成批量授权。另外，确保应用已获取相应权限（权限JSON中已包含所有user scope）。

3. 插件适合部署在群聊中供多人使用吗？

官方建议暂不适合。因为插件以单个用户身份授权，若放在群中，多个用户的消息会使用同一授权身份，可能引发权限混乱或数据泄露。更适合个人助手或管理员专用场景。

4. 如何更新插件到最新版？

执行 feishu-plugin-onboard update。如果命令不存在，请先手动安装辅助脚本（见第五节）。

5. 运行`openclaw gateway run`后，终端可以关闭吗？

不能关闭。该进程需要一直运行以监听飞书事件。建议使用进程管理工具（如pm2、screen）或将其托管为后台服务。

6. 配对码有效期多长？过期怎么办？

配对码有效期为5分钟。过期后只需再次向机器人发送任意消息，即可获得新码。

7. 安装过程中提示“权限不足”怎么办？

请确认你使用的飞书账号具有管理员权限（至少是企业自建应用的管理员）。部分权限申请需要管理员审核。

8. 如何确认插件已成功监听事件？

查看运行gateway run的终端日志，如果看到类似“事件监听已启动”的日志，并且发送消息给机器人能得到回复，说明监听正常。

“

本文基于飞书OpenClaw官方插件公开文档整理编写，旨在提供一份可直接落地的实操指南。如果你在配置过程中遇到本文未覆盖的问题，欢迎在社区反馈，或直接在飞书对话框中输入/feishu doctor获取诊断帮助。让AI长出“钳子”，你的飞书工作流将迎来真正的智能化升级。

飞书官方插件终极指南：3步让OpenClaw成为你的数字员工