---

name: lark-integration description: 通过 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. 通过Lark API使用message_id和image_key下载图片
3. 转换为base64格式
4. 作为attachments参数发送至OpenClaw Gateway

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

群聊行为规则

在群聊场景中，聊天桥接器会在以下情况响应：

• 机器人被@提及时
• 消息以问号结尾（? 或 ？）
• 消息包含触发词：help/please/why/how/what/帮/请/分析等
• 消息以机器人名称开头

其他消息将被自动忽略，避免信息干扰。

文档阅读功能

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

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

支持的URL类型：

• /docx/ - 新版文档
• /wiki/ - 知识库文档（自动解析为底层文档）
• /sheets/ - 电子表格
• /base/ - 多维表格

权限说明： 文档需与机器人共享，或为机器人开启租户级读取权限。

故障排查

读取文档报错 "forBidden"

• 文档未共享 → 添加机器人为协作者
• 权限不足 → 在开发者后台开启 docx:document:readonly 权限

收不到消息

• 检查webhook可达性：curl http://YOUR_IP:3000/health
• 确认飞书后台webhook显示"已验证"
• 查看桥接日志：journalctl -u lark-bridge -f

报错 "must be string"

• 桥接器版本过旧 → 升级版本以支持图片 attachments 格式

无法接收图片

• 缺少 im:resource 权限 → 前往飞书后台开启
• token过期 → 桥接器会自动刷新，若失败需重启服务

服务管理命令

# 查看状态
systemctl status lark-bridge

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

# 重启服务
systemctl restart lark-bridge

参考资源

• Lark开发者后台（国际版）
• 飞书开发者后台（国内版）
• 消息格式详见 references/api-formats.md
• 部署指南详见 references/setup-guide.md