用openclaw内置插件接入飞书教程

前置条件这里已经明确，咱们都默认已经按照官方教程安装并初始化了OpenClaw。如果还没做这一步，建议先移步 https://openclaw101.dev/zh/day/2 完成基础设置，不然下面的操作都是空谈。

免费影视、动漫、音乐、游戏、小说资源长期稳定更新！ 👉 点此立即查看 👈

一、检查openclaw版本

首先，得确认你的OpenClaw版本。从2026年2月22日的2号版本（OpenClaw 2026.2.22-2）开始，飞书插件就已经内置在核心包里了。这意味着，绝大多数情况下你不需要再手动安装任何额外插件。这里有个关键提醒：如果你不小心又去手动安装了一遍飞书插件，系统里出现两个一模一样的插件，反而会导致OpenClaw启动报错。所以，第一步先别急着动手，检查版本号总没错。

二、补充可能缺失的依赖包

虽然插件内置了，但它运行还得靠飞书官方的Node.js SDK（也就是 @larksuiteoapi/node-sdk 这个包）。有时候，这个SDK可能因为网络或环境原因没有自动装好，结果就是插件加载失败。怎么判断呢？可以走一套标准的排查流程。

在动手下载SDK前，建议先执行下面几个命令来做个健康检查：

# 启用飞书插件
openclaw config set channels.feishu.enabled true
# 重启网关让配置生效
openclaw gateway restart
# 动态查看日志输出，捕捉错误信息
openclaw logs --follow

重点看日志输出。如果一切正常，恭喜你，可以直接跳到第三步。但如果日志里出现了下面这样的报错，那就明确指向了SDK缺失的问题：

error plugins {"subsystem":"plugins"} [plugins] feishu failed to load from /usr/lib/node_modules/openclaw/extensions/feishu/index.ts: Error: Cannot find module '@larksuiteoapi/node-sdk' Require stack: - /usr/lib/node_modules/openclaw/extensions/feishu/src/client.ts

修复的路径也很清晰，跟着错误提示走就行：

# 1. 切换到 OpenClaw 飞书插件目录（路径要和报错信息里的一模一样）
cd /usr/lib/node_modules/openclaw/extensions/feishu
# 2. 安装缺失的飞书官方SDK（这是最核心的一步）
npm install @larksuiteoapi/node-sdk --save
# 3. 重新启用一下飞书插件
openclaw plugins enable feishu
# 4. 重启 OpenClaw 网关使修复生效
openclaw gateway restart
# 5. 再次查看日志，确认报错是否消失
openclaw logs --follow

等上面的命令跑完，之前的报错应该就没了。为了确认插件真的加载成功，可以执行：

# 查看所有插件状态
openclaw plugins list

在输出的列表里，找到飞书插件（feishu），只要看到它的 status 显示为 loaded，就大功告成了。

三、配置飞书机器人

插件搞定，接下来就是在飞书平台和本地终端两头配置机器人了。先说飞书端的操作，步骤虽然多，但照着做一遍就清楚了。

飞书端操作：

1. 进入飞书开放平台：访问飞书开放平台，用你的飞书账号登录，进入开发者后台。

2. 创建自建应用：点击“创建应用”，选择“企业自建应用”。填好应用名称（比如 OpenClaw-AI）、描述，上传个图标，然后点击创建。创建成功后，进入应用详情页，务必记下这里的应用 ID（后续称为 App ID，格式类似 cli_xxxxxx）。

3. 获取 App Secret：在应用详情页，找到“凭证与基础信息”部分。点击生成（或显示）App Secret，复制并妥善保存。这里必须划个重点：App Secret 是最高权限的密钥，绝对不能泄露，也避免提交到任何公开的代码仓库。

4. 启用机器人能力：在应用详情页，进入“功能” -> “机器人”，点击“添加”。配置机器人名称（一般和应用名称保持一致就行），点击保存。

5. 配置事件订阅：在左侧菜单进入“开发配置” -> “事件与回调”。将订阅方式选择为“使用长连接接收事件”并保存。注意，这一步有时会要求你先在OpenClaw里配置好 App ID 和 App Secret 才能完成。

6. 添加消息接收事件：点击“添加事件”，搜索 im.message.receive_v1，添加该事件，并确认开通对应的权限。

7. 开通核心权限：在左侧菜单进入“开发配置” -> “权限管理”，需要开通以下两项：
应用身份权限：搜索 im:message，把相关的权限全部选中并开通。
用户身份权限：搜索 contact:user.base:readonly，选中并开通。

8. 发布应用：顶部菜单进入“应用发布” -> “版本管理与发布” -> “创建新版本”，简单填写更新说明后发布。因为是企业自建应用，发布后通常直接生效，无需平台审核。

飞书那边设置好了，回到终端来配置OpenClaw。官方提供了两种方式：交互式命令（openclaw channels add）和手动配置（openclaw config set）。

这里有个坑需要注意：交互式命令可能会试图再去下载一次飞书插件。而我们前面说了，新版是内置插件的，重复安装会导致冲突报错。因此，更推荐使用第二种手动配置的方式，稳当。

# 启用飞书插件
openclaw config set channels.feishu.enabled true
# 设置 App ID（替换成你飞书后台拿到的）
openclaw config set channels.feishu.accounts.main.appId "cli_xxxxxx"
# 设置 App Secret（替换成你的密钥）
openclaw config set channels.feishu.accounts.main.appSecret "你的AppSecret"
# 设置连接模式为 WebSocket（性能更好，推荐）
openclaw config set channels.feishu.connectionMode "websocket"
# （可选）设置飞书域名（国内版填 feishu，国际版填 lark）
openclaw config set channels.feishu.domain "feishu"

四、测试

配置完毕，是骡子是马得拉出来遛遛。测试很简单：

1. 在飞书里创建一个群聊（或者用已有的）。 2. 进入群聊 -> 设置 -> 添加机器人 -> 选择你刚刚创建并发布的那个机器人。

接着，在终端保持日志窗口开启，实时观察：

# 打开日志流
openclaw logs --follow

然后回到飞书群聊，@一下你的机器人并发送消息。这时候，观察终端日志，常见的初期错误无非以下几种：

1. 权限未设置完全：日志可能会提示类似下面的错误：

Access denied. One of the following scopes is required: [contact:contact.base:readonly......]

这说明飞书后台还有某个必需的权限没开通。别慌，日志通常会给一个链接，点进去按提示申请并开通对应的权限即可。开通后记得在飞书开发者后台再次发布新版本。

2. 群聊组未在白名单中：如果看到这样的日志：

group oc_3a********4 not in groupAllowFrom (groupPolicy=allowlist)

这表示当前群聊不在机器人的白名单里。解决办法是先获取这个群聊的ID（可以从日志里直接看到，或者在飞书群聊设置的页面底部找到），然后将其加入白名单：

# 将群组策略设置为白名单模式
openclaw config set channels.feishu.groupPolicy allowlist
# 添加群聊ID到白名单（注意是JSON数组格式）
openclaw config set channels.feishu.groupAllowFrom '["oc_xxx1"]'
# 重启网关使新策略生效
openclaw gateway restart

处理完这些问题，再重新@机器人测试一下。如果日志显示消息被正常接收和处理，那么恭喜你，OpenClaw与飞书的对接通道就正式打通了。