前置条件：已安装并初始化openclaw，安装教程可看：https://openclaw101.dev/zh/day/2

一、检查openclaw版本

OpenClaw 2026.2.22-2 及以上版本已内置飞书插件，无需额外安装。若额外安装，可能会导致openclaw出现重复插件而报错。

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

OpenClaw 内置飞书插件依赖飞书官网Node 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

飞书插件的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 channels add

手动配置：openclaw cconfig set

但是交互式命令配置又会让你去下载飞书插件，而OpenClaw 2026.2.22-2 及以上版本已内置飞书插件，会导致openclaw出现重复插件而报错。所以推荐使用第二种手动配置

# 启用飞书插件
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"

四、测试

在飞书创建一个群聊，进入群聊->设置->添加机器人->选择刚刚创建的机器人。

在终端打开openclaw日志：

# 查看日志
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    
# 添加白名单
openclaw config set channels.feishu.groupAllowFrom '["oc_xxx1"]'
# 重启网关
openclaw gateway restart