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 回调地址
# https://open.larksuite.com → 你的应用 → 事件订阅
# URL: http://YOUR_SERVER_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 - 读取 Wiki 页面
• sheets:spreadsheet:readonly - 读取表格
• bitable:bitable:readonly - 读取多维表格
• drive:drive:readonly - 访问网盘文件

脚本说明

bridge-webhook.mjs

主回调桥接脚本。接收 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/ - Wiki 页面（自动解析为底层文档）
• /sheets/ - 表格
• /base/ - 多维表格（Bitable）

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

常见问题排查

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

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

未收到任何消息

• 检查回调地址是否可访问：curl http://YOUR_IP:3000/health
• 确认 Lark 控制台中的回调状态显示为“已验证”
• 查看桥接日志：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 开发者控制台](https://open.larksuite.com/)（国际版）
• [飞书开发者控制台](https://open.feishu.cn/)（中国版）
• 详见 references/api-formats.md 获取消息格式详情
• 详见 references/setup-guide.md 获取分步设置指南