飞书（Lark）集成

将飞书（Feishu）与 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. 在飞书开发者控制台中配置 Webhook URL
# https://open.larksuite.com → 您的应用 → 事件订阅
# URL: http://YOUR_SERVER_IP:3000/webhook

架构

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

支持的消息类型

平台自动识别

桥接服务会根据 URL 自动识别飞书平台：

• *.larksuite.com → https://open.larksuite.com（国际版）
• *.feishu.cn → https://open.feishu.cn（中国版）

配置

环境变量

飞书应用权限

请在飞书开发者控制台 → 权限与范围中启用以下权限范围：

消息相关：

• im:message —— 收发消息
• im:message:send_as_bot —— 以 Bot 身份发送消息
• im:resource —— 下载消息资源（如图片）

文档相关（可选）：

• docx:document:readonly —— 读取文档
• wiki:wiki:readonly —— 读取知识库页面
• sheets:spreadsheet:readonly —— 读取电子表格
• bitable:bitable:readonly —— 读取多维表格（Bitables）
• 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
# 将创建 /etc/systemd/system/lark-bridge.service

图片处理

消息中的图片将按如下流程处理：

1. 从 post 内容或 image 类型消息中识别图片
2. 使用 message_id 和 image_key 通过飞书 API 下载图片
3. 转换为 base64 编码
4. 作为 attachments 参数发送至 OpenClaw Gateway

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

群聊行为

在群聊中，桥接服务仅在满足以下任一条件时响应：

• Bot 被 @ 提及
• 消息以 ? 或 ？ 结尾
• 消息中包含触发词：help、please、why、how、what、帮、请、分析 等
• 消息以 Bot 名称开头

其余消息将被忽略，以避免干扰。

文档读取

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

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

支持的 URL 类型包括：

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

权限说明： 文档必须已共享给 Bot，或 Bot 已获得租户级只读权限。

故障排查

读取文档时出现 “forBidden” 错误

• 文档未共享给 Bot → 将 Bot 添加为协作者
• 缺少对应权限范围 → 在控制台中启用 docx:document:readonly

未收到任何消息

• 检查 Webhook 地址是否可达：curl http://YOUR_IP:3000/health
• 确认飞书控制台中 Webhook 显示为 “已验证”
• 查看桥接日志：journalctl -u lark-bridge -f

出现 “must be string” 错误

• 桥接版本过旧 → 升级至支持使用 attachments 字段传输图片的新版本

图片未成功接收

• 缺少 im:resource 权限范围 → 在飞书控制台中启用
• 访问令牌过期 → 桥接服务支持自动刷新；若卡住，请手动重启

服务管理

# 查看服务状态
systemctl status lark-bridge

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

# 重启服务
systemctl restart lark-bridge

参考资料

• 飞书开发者控制台（国际版）
• 飞书开发者控制台（中国版）
• 消息格式详情参见 references/api-formats.md
• 分步搭建指南参见 references/setup-guide.md