名称： lark-integration
描述： 通过 Webhook 桥接将 Lark（飞书）消息与 OpenClaw 连接。支持文本、富文本（帖子）和图片消息的双向传输。适用于将 Lark/飞书设置为消息通道、接收带图片的消息、向 Lark 发送回复、读取 Lark 文档/知识库/多维表格，或排查 Lark 集成问题。同时支持 Lark 国际版 (larksuite.com) 和中国版飞书 (feishu.cn)。

Lark 集成

将 Lark（飞书）连接到 OpenClaw，实现支持完整富内容的消息双向互通。

快速开始

# 1. 设置凭证
echo "FEISHU_APP_ID=cli_xxx" >> ~/.openclaw/workspace/.env
mkdir -p ~/.openclaw/secrets
echo "your_app_secret" > ~/.openclaw/secrets/feishu_app_secret

# 2. 启动桥接服务
cd skills/lark-integration/scripts
node bridge-webhook.mjs

# 3. 在开发者控制台配置 Lark Webhook URL
# https://open.larksuite.com → 你的应用 → 事件订阅
# URL: http://你的服务器IP:3000/webhook

架构

Lark 应用 ──webhook──► 桥接服务 (端口 3000) ──WebSocket──► OpenClaw 网关
                           │                                   │
                           ◄────────── 回复消息 ─────────────────┘

支持的消息类型

平台自动检测

桥接服务根据 URL 自动检测平台：
- *.larksuite.com → https://open.larksuite.com (国际版)
- *.feishu.cn → https://open.feishu.cn (中国版)

配置

环境变量

Lark 应用权限

在 Lark 开发者控制台 → 权限与安全中启用以下权限：

消息：
- im:message - 收发消息
- im:message:send_as_bot - 以机器人身份发送消息
- im:resource - 下载消息资源（图片）

文档（可选）：
- docx:document:readonly - 读取文档
- wiki:wiki:readonly - 读取知识库空间
- sheets:spreadsheet:readonly - 读取电子表格
- bitable:bitable:readonly - 读取多维表格
- drive:drive:readonly - 访问云盘文件

脚本

bridge-webhook.mjs

主 Webhook 桥接脚本。接收 Lark 事件，转发至 OpenClaw，并发送回复。

FEISHU_APP_ID=cli_xxx node scripts/bridge-webhook.mjs

setup-service.mjs

安装为 systemd 服务以实现自动启动：

node scripts/setup-service.mjs
# 创建 /etc/systemd/system/lark-bridge.service

图片处理

消息中的图片处理流程：
1. 从 post 内容或 image 消息类型中检测图片
2. 使用 message_id 和 image_key 通过 Lark API 下载
3. 转换为 base64 格式
4. 作为 attachments 参数发送至 OpenClaw 网关

attachments: [{ mimeType: "image/png", content: "<base64>" }]

群聊行为

在群聊中，桥接服务在以下情况会响应：
- 机器人被 @提及
- 消息以 ? 或 ？ 结尾
- 消息包含触发词：help, please, why, how, what, 帮, 请, 分析等
- 消息以机器人名称开头

否则，消息将被忽略以避免干扰。

读取文档

使用 feishu-doc 技能读取 Lark 文档：

node skills/feishu-doc/index.js fetch "https://xxx.larksuite.com/docx/TOKEN"

支持的 URL 类型：
- /docx/ - 新版文档
- /wiki/ - 知识库页面（自动解析为底层文档）
- /sheets/ - 电子表格
- /base/ - 多维表格

权限说明： 文档必须与机器人共享，或机器人需具备租户级的读取权限。

故障排除

读取文档时出现 "forBidden" 错误

• 文档未与机器人共享 → 将机器人添加为协作者
• 缺少权限 → 在控制台中启用 docx:document:readonly

未收到消息

• 检查 Webhook URL 可访问性：curl http://你的IP:3000/health
• 确认 Lark 控制台中 Webhook 显示“已验证”
• 查看桥接服务日志：journalctl -u lark-bridge -f

出现 "must be string" 错误

• 桥接服务版本过旧 → 更新至使用 attachments 处理图片的版本

未收到图片

• 缺少 im:resource 权限 → 在 Lark 控制台中启用
• Token 过期 → 桥接服务会自动刷新，若卡住请重启

服务管理

# 检查状态
systemctl status lark-bridge

# 查看日志
journalctl -u lark-bridge -f

# 重启
systemctl restart lark-bridge

参考

• Lark 开发者控制台 (国际版)
• 飞书开发者控制台 (中国版)
• 查看 references/api-formats.md 了解消息格式详情
• 查看 references/setup-guide.md 获取逐步设置指南