OpenClaw Feishu/Lark channel plugin (fixed immediate message delivery)
npm install @overlink/openclaw-feishu---
- 🌍 双版本支持 - 同时支持飞书国内版和国际版(Lark)
- 🔌 双连接模式 - 支持 WebSocket 长连接和 Webhook 回调
- 💬 全场景支持 - 私聊、群聊、@提及、消息回复
- 🖼️ 富媒体处理 - AI 可识别图片、读取文件(PDF/Excel)、处理富文本
- 📤 文件上传 - 支持图片和文件的上传发送
- 🎨 智能渲染 - 自动选择纯文本或 Markdown 卡片渲染
- 🔐 权限控制 - 灵活的私聊/群聊白名单策略
- ⚡ 即时响应 - v0.1.5 修复:消息在生成时立即发送,无需等待全部完成
---
``bash`
openclaw plugins install @overlink/openclaw-feishu
`bash`
npm install @overlink/openclaw-feishu
`bash1. 下载插件包
curl -O https://registry.npmjs.org/@overlink/openclaw-feishu/-/openclaw-feishu-0.1.10.tgz
---
🚀 快速开始
$3
本插件同时支持飞书的两个版本:
| 版本 | 服务区域 | 开放平台地址 | 客户端名称 |
|------|---------|------------|-----------|
| 🇨🇳 飞书国内版 | 中国大陆 | open.feishu.cn | 飞书 |
| 🌏 Lark 国际版 | 海外及港澳台 | open.larksuite.com | Lark |
> 💡 提示:
> - 国内企业用户通常使用飞书国内版
> - 海外企业或跨国公司使用 Lark 国际版
> - 两个版本的应用和数据完全隔离,不互通
$3
根据你使用的版本,访问对应的开放平台:
#### 飞书国内版
1. 访问 飞书开放平台
2. 创建自建应用
3. 在凭证与基础信息页面获取:
-
App ID(如 cli_xxxxx)
- App Secret#### Lark 国际版
1. 访问 Lark Open Platform
2. 创建 Custom App
3. 在 Credentials & Basic Info 页面获取:
-
App ID(如 cli_xxxxx)
- App Secret$3
在应用后台 → 权限管理 中开启以下权限:
#### 🔴 必需权限
| 权限标识 | 权限名称 | 用途 |
|---------|---------|------|
|
contact:user.base:readonly | 获取用户基本信息 | 解析发送者姓名(避免混淆说话者) |
| im:message | 获取与发送单聊、群组消息 | 收发消息 |
| im:message.p2p_msg:readonly | 读取用户发给机器人的单聊消息 | 私聊接收 |
| im:message.group_at_msg:readonly | 获取群组中所有消息 | 群聊 @提及 |
| im:message:send_as_bot | 以应用的身份发消息 | 发送回复 |
| im:resource | 获取与上传图片或文件资源 | 媒体文件处理 |#### 🟡 可选权限(按需开启)
| 权限标识 | 权限名称 | 用途 |
|---------|---------|------|
|
im:message.group_msg | 接收群聊中所有消息 | 无需 @也能响应(敏感权限) |
| im:message:readonly | 查询消息历史 | 获取历史消息 |
| im:message:update | 更新应用发送的消息卡片 | 编辑已发送消息 |
| im:message:recall | 撤回应用发送的消息 | 撤回消息 |> 💡 提示:权限申请后需等待管理员审核通过。
$3
> 这是最容易遗漏的配置! 如果机器人能发消息但收不到消息,一定要检查此项。
在应用后台 → 事件与回调 页面:
1. 事件配置方式:选择
使用长连接接收事件(推荐)
2. 添加事件订阅,勾选以下事件:| 事件名称 | 说明 |
|---------|------|
|
接收消息 v2.0 (im.message.receive_v1) | 必需,接收用户消息 |
| 消息已读 (im.message.message_read_v1) | 可选,已读回执 |
| 机器人进群 (im.chat.member.bot.added_v1) | 可选,群组管理 |
| 机器人被移出群 (im.chat.member.bot.deleted_v1) | 可选,群组管理 |3. 确保事件订阅的权限已通过审核
$3
根据你使用的版本配置:
#### 飞书国内版
`bash
openclaw config set channels.openclaw-feishu.domain "feishu"
openclaw config set channels.openclaw-feishu.appId "cli_xxxxx"
openclaw config set channels.openclaw-feishu.appSecret "your_app_secret"
openclaw config set channels.openclaw-feishu.enabled true
openclaw restart
`#### Lark 国际版
`bash
openclaw config set channels.openclaw-feishu.domain "lark"
openclaw config set channels.openclaw-feishu.appId "cli_xxxxx"
openclaw config set channels.openclaw-feishu.appSecret "your_app_secret"
openclaw config set channels.openclaw-feishu.enabled true
openclaw restart
`> ⚠️ 重要:
domain 参数必须与你的应用版本匹配!
> - 飞书国内版:domain: "feishu"
> - Lark 国际版:domain: "lark"---
⚙️ 配置选项
$3
`yaml
channels:
feishu:
enabled: true # 启用插件
appId: "cli_xxxxx" # 应用 App ID
appSecret: "your_secret" # 应用 App Secret
domain: "feishu" # 🌍 版本选择:"feishu"(国内版)或 "lark"(国际版)
connectionMode: "websocket" # 连接模式:"websocket" 或 "webhook"
`$3
`yaml
channels:
feishu:
# 私聊策略
dmPolicy: "pairing" # "pairing"(配对审批)| "open"(全开放)| "allowlist"(白名单)
# 群聊策略
groupPolicy: "allowlist" # "open"(全开放)| "allowlist"(白名单)| "disabled"(禁用)
# 群聊是否需要 @机器人
requireMention: true # true(需要@)| false(不需要@,需开启敏感权限)
`$3
`yaml
channels:
feishu:
# 渲染模式
renderMode: "auto" # "auto"(自动)| "raw"(纯文本)| "card"(卡片)
# 媒体文件限制
mediaMaxMb: 30 # 单个文件最大大小(MB)
`$3
| 模式 | 效果 | 适用场景 |
|------|------|---------|
|
auto | 有代码块/表格时用卡片,否则纯文本 | 默认推荐,智能选择 |
| raw | 始终纯文本,表格转 ASCII | 简洁阅读,避免格式干扰 |
| card | 始终 Markdown 卡片(语法高亮、表格、链接) | 重度技术内容,需要格式化展示 |---
🔧 常见问题
$3
检查清单:
1. ✅ 是否配置了事件订阅?(见上方第 3 步)
2. ✅ 事件配置方式是否选择了长连接?
3. ✅ 是否添加了
im.message.receive_v1 事件?
4. ✅ 相关权限是否已审核通过?$3
确保
im:message:send_as_bot 权限已申请并审核通过。$3
在聊天中发送
/new 命令。$3
飞书 API 有严格的频率限制,频繁更新消息容易触发限流。v0.1.5 已优化为:消息在生成时立即发送(而非等待全部完成),在稳定性和实时性之间取得平衡。
$3
如果
openclaw plugins install` 失败,改用手动安装(见上方"方式 3")。1. 确保应用已发布(至少发布到测试版本)
2. 在飞书搜索框搜索机器人名称
3. 检查应用的可用范围是否包含你的账号
---
---
- OpenClaw 官网
- 飞书开放平台文档
- npm 包地址
- GitHub 仓库
---