飞书 Channel 集成
将飞书接入 OpenClaw，实现双向消息通道。
与 feishu-automation 的区别
| 特性 | feishu-channel | feishu-automation |
|---|---|---|
| 主要用途 | 消息通道集成 | 平台自动化操作 |
| 消息接收 | ✅ Webhook 事件订阅 | ❌ 不支持 |
| 消息发送 | ✅ 实时对话 | ✅ 通知推送 |
| 多维表格 | ❌ 不涉及 | ✅ 完整支持 |
| 文档管理 | ❌ 不涉及 | ✅ 完整支持 |
| 适用场景 | AI 对话机器人 | 数据同步、自动化工作流 |
架构概述
┌─────────────┐ ┌──────────────────┐ ┌─────────────┐
│ 飞书用户 │ ←→ │ 飞书开放平台 │ ←→ │ OpenClaw │
│ (私聊/群聊) │ │ (Webhook) │ │ Gateway │
└─────────────┘ └──────────────────┘ └─────────────┘
↓
┌──────────────────┐
│ Webhook 服务 │
│ - 事件验证 │
│ - 消息解析 │
│ - 格式转换 │
└──────────────────┘核心组件
1. 飞书机器人应用
在飞书开放平台创建的企业自建应用，负责：
- 接收用户消息（通过事件订阅）
- 发送消息（通过消息 API）
- 管理权限和安全
2. Webhook 服务
接收飞书事件推送，转发给 OpenClaw Gateway。
3. 消息发送 API
通过 lark-mcp 工具或直接调用飞书 API 发送消息。
快速开始
前置条件
- 飞书开放平台账号
- 企业自建应用（机器人能力）
- OpenClaw Gateway 运行中
- 公网可访问的 Webhook URL（或使用内网穿透）
1. 创建飞书应用
- 访问 飞书开放平台
- 创建企业自建应用
- 添加「机器人」能力
- 配置权限（见下方权限列表）
- 获取 App ID 和 App Secret
2. 配置事件订阅
- 在应用管理页面，进入「事件订阅」
- 配置请求地址：
https://your-domain.com/webhook/feishu - 订阅事件：
- im.message.receive_v1 - 接收消息 - im.message.message_read_v1 - 消息已读（可选）
3. 部署 Webhook 服务
cd /home/aa/clawd/skills/feishu-channel
npm install
cp .env.example .env
# 编辑 .env 填入配置
npm start4. 发布应用
- 在飞书开放平台提交审核
- 审核通过后发布
- 在飞书中搜索并添加机器人
配置说明
环境变量 (.env)
# 飞书应用配置 (必需)
FEISHU_APP_ID=cli_xxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx
# 事件订阅验证 Token
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxxxx
# 事件加密 Key (可选，推荐启用)
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxxxx
# OpenClaw Gateway 配置
OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789
OPENCLAW_WEBHOOK_SECRET=your_webhook_secret
# 安全配置
# 允许的用户 open_id (逗号分隔，留空允许所有)
ALLOWED_USERS=ou_xxx,ou_yyy
# 允许的群聊 chat_id (逗号分隔，留空允许所有)
ALLOWED_GROUPS=oc_xxx,oc_yyy
# 群聊行为
REQUIRE_MENTION_IN_GROUP=true
# 服务端口
PORT=3002
# 日志级别
LOG_LEVEL=info飞书应用权限
| 权限 | 说明 | 必需 |
|---|---|---|
im:message | 获取与发送单聊、群组消息 | ✅ |
im:message.group_at_msg | 接收群聊中@机器人消息 | ✅ |
im:message.p2p_msg | 接收用户发给机器人的单聊消息 | ✅ |
im:chat | 获取群组信息 | 推荐 |
contact:user.base | 获取用户基本信息 | 推荐 |
im:resource | 获取与上传图片或文件资源 | 可选 |
OpenClaw 配置 (openclaw.json)
{
"channels": {
"feishu": {
"enabled": true,
"appId": "cli_xxxxxxxxxx",
"appSecret": "env:FEISHU_APP_SECRET",
"webhookUrl": "https://your-domain.com/webhook/feishu",
"dmPolicy": "allowlist",
"allowFrom": ["ou_xxx", "ou_yyy"],
"groups": {
"oc_xxx": {
"name": "工作群",
"requireMention": true
}
}
}
}
}消息格式
接收消息 (Webhook Event)
飞书原始事件格式：
{
"schema": "2.0",
"header": {
"event_id": "xxx",
"event_type": "im.message.receive_v1",
"create_time": "1706745600000",
"token": "verification_token",
"app_id": "cli_xxx"
},
"event": {
"sender": {
"sender_id": {
"open_id": "ou_xxx",
"user_id": "xxx",
"union_id": "on_xxx"
},
"sender_type": "user"
},
"message": {
"message_id": "om_xxx",
"root_id": "",
"parent_id": "",
"create_time": "1706745600000",
"chat_id": "oc_xxx",
"chat_type": "group",
"message_type": "text",
"content": "{\"text\":\"@_user_1 你好\"}",
"mentions": [
{
"key": "@_user_1",
"id": {
"open_id": "ou_bot"
},
"name": "OpenClaw助手"
}
]
}
}
}转换后的 OpenClaw 格式：
{
"type": "message",
"channel": "feishu",
"messageId": "om_xxx",
"from": {
"id": "ou_xxx",
"name": "张三"
},
"chat": {
"id": "oc_xxx",
"type": "group",
"name": "工作群"
},
"text": "你好",
"mentions": ["ou_bot"],
"isMentioned": true,
"timestamp": 1706745600000
}发送消息
使用 lark-mcp 工具
// 发送文本消息
await mcp__lark-mcp_sendMessage({
receive_id: "ou_xxx", // 或 oc_xxx (群聊)
receive_id_type: "open_id", // 或 chat_id
msg_type: "text",
content: JSON.stringify({
text: "收到，正在处理..."
})
});
// 发送富文本消息
await mcp__lark-mcp_sendMessage({
receive_id: "oc_xxx",
receive_id_type: "chat_id",
msg_type: "post",
content: JSON.stringify({
zh_cn: {
title: "任务完成",
content: [
[
{ tag: "text", text: "已完成 " },
{ tag: "a", text: "查看详情", href: "https://example.com" }
]
]
}
})
});
// 发送卡片消息
await mcp__lark-mcp_sendMessage({
receive_id: "oc_xxx",
receive_id_type: "chat_id",
msg_type: "interactive",
content: JSON.stringify({
config: { wide_screen_mode: true },
header: {
template: "turquoise",
title: { content: "通知", tag: "plain_text" }
},
elements: [
{
tag: "div",
text: { content: "**重要通知**", tag: "lark_md" }
},
{
tag: "action",
actions: [
{
tag: "button",
text: { content: "确认", tag: "plain_text" },
type: "primary"
}
]
}
]
})
});使用 HTTP API
# 发送文本消息
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"receive_id": "ou_xxx",
"msg_type": "text",
"content": "{\"text\":\"Hello!\"}"
}'安全策略
事件验证
飞书事件订阅支持两种验证方式：
- Verification Token: 简单的 Token 验证
- Encrypt Key: AES 加密（推荐）
// 验证示例
function verifyEvent(body, token) {
if (body.token !== token) {
throw new Error('Invalid verification token');
}
}
// 解密示例
function decryptEvent(encrypt, key) {
const crypto = require('crypto');
const decipher = crypto.createDecipheriv(
'aes-256-cbc',
crypto.createHash('sha256').update(key).digest(),
Buffer.alloc(16, 0)
);
return JSON.parse(
decipher.update(encrypt, 'base64', 'utf8') + decipher.final('utf8')
);
}私聊策略
| 策略 | 说明 |
|---|---|
open | 允许所有人私聊（危险） |
allowlist | 仅允许 allowFrom 列表中的用户 |
群聊策略
| 配置 | 说明 |
|---|---|
requireMention: true | 必须@机器人才响应 |
allowFrom | 群内允许触发的用户列表 |
使用场景
1. 智能问答机器人
用户: @OpenClaw助手 帮我查一下今天的会议安排
Bot: 今天的会议安排：
- 10:00 产品评审会 (会议室A)
- 14:00 技术分享会 (线上)
- 16:00 周例会 (会议室B)2. 工作流通知
// 当任务完成时发送通知
await mcp__lark-mcp_sendMessage({
receive_id: "oc_work_group",
receive_id_type: "chat_id",
msg_type: "interactive",
content: JSON.stringify({
header: {
template: "green",
title: { content: "✅ 任务完成", tag: "plain_text" }
},
elements: [
{
tag: "div",
text: { content: "数据同步任务已完成\n处理记录: 1,234 条", tag: "lark_md" }
}
]
})
});3. 审批流程
用户: @OpenClaw助手 提交请假申请，明天休息一天
Bot: 已收到请假申请，正在提交审批...
[卡片消息: 请假申请详情 + 审批按钮]故障排查
Webhook 无法接收消息
- 检查 Webhook URL 是否公网可访问
- 检查 Verification Token 是否正确
- 查看飞书开放平台的事件推送日志
- 确认应用已发布且用户已添加机器人
消息发送失败
- 检查 App ID 和 App Secret
- 确认应用权限已开启
- 检查 access_token 是否过期
- 查看 API 返回的错误码
权限不足
- 在飞书开放平台检查应用权限
- 确认权限已审核通过
- 重新获取 access_token
限制说明
飞书平台限制
- API 调用频率限制（参考官方文档）
- 消息长度限制
- 文件大小限制
功能限制
- 不支持语音消息
- 卡片消息交互需要额外配置回调
- 部分高级功能需要企业认证
相关文件
scripts/feishu-webhook.js- Webhook 服务代码.env.example- 环境变量模板references/feishu-api.md- 飞书 API 参考references/message-types.md- 消息类型说明
TODO
- 创建飞书应用并获取凭证
- 配置事件订阅
- 部署 Webhook 服务
- 测试私聊消息收发
- 测试群聊 @提及
- 配置安全策略
- 实现卡片消息交互