飞书集成

将飞书连接至OpenClaw，实现支持完整富媒体内容双向消息互通。

快速开始

# 1. Set credentials
echo "FEISHU_APP_ID=cli_xxx" >> ~/.openclaw/workspace/.env
mkdir -p ~/.openclaw/secrets
echo "your_app_secret" > ~/.openclaw/secrets/feishu_app_secret

# 2. Start bridge
cd skills/lark-integration/scripts
node bridge-webhook.mjs

# 3. Configure Lark webhook URL in developer console
# https://open.larksuite.com → Your App → Event Subscriptions
# URL: http://YOUR_SERVER_IP:3000/webhook

架构说明

Lark App ──webhook──► Bridge (port 3000) ──WebSocket──► OpenClaw Gateway
                           │                                   │
                           ◄────────── Reply ──────────────────┘

支持的消息类型

平台检测

桥接器自动从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 桥接器。接收飞书事件，转发至 OpenClaw，并发送回复。

FEISHU_APP_ID=cli_xxx node scripts/bridge-webhook.mjs

setup-service.mjs

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

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

图像处理

消息中的图像：

1. 从帖子内容或图像消息类型中检测
2. 通过飞书 API 使用message_id和image_key
3. 下载
4. 转换为 base64 格式作为attachments

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

参数发送至 OpenClaw 网关

群聊行为

• 机器人被@提及
• 消息以?或？
• 消息包含触发词：help, please, why, how, what, 帮, 请, 分析等。
• 消息以机器人名称开头

否则，消息将被忽略以避免噪音。

读取文档

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

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

支持的URL类型：

• /docx/- 新文档
• /wiki/- Wiki页面（自动解析到底层文档）
• /sheets/- 电子表格
• /base/- 多维表格

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

故障排除

读取文档时出现“禁止访问”错误

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

检查Webhook URL是否可访问：

• curl http://你的IP:3000/health验证飞书控制台中的Webhook显示为“已验证”
• 检查桥接器日志：
• journalctl -u lark-bridge -f“必须为字符串”错误

桥接器版本过旧 → 更新以使用

• 附件功能用于接收图片未收到图片

缺少

• im:resource权限范围 → 在飞书控制台启用令牌过期 → 桥接器会自动刷新，如果卡住请重启
• 服务管理

Service Management

# Check status
systemctl status lark-bridge

# View logs
journalctl -u lark-bridge -f

# Restart
systemctl restart lark-bridge

参考资料

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