Feishu Channel

飞书 Channel 集成

将飞书接入 OpenClaw，实现双向消息通道。

与 feishu-automation 的区别

架构概述

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│   飞书用户   │ ←→  │   飞书开放平台    │ ←→  │  OpenClaw   │
│  (私聊/群聊) │     │   (Webhook)      │     │   Gateway   │
└─────────────┘     └──────────────────┘     └─────────────┘
                           ↓
                    ┌──────────────────┐
                    │   Webhook 服务    │
                    │   - 事件验证      │
                    │   - 消息解析      │
                    │   - 格式转换      │
                    └──────────────────┘

核心组件

1. 飞书机器人应用

在飞书开放平台创建的企业自建应用，负责：

• 接收用户消息（通过事件订阅）
• 发送消息（通过消息 API）
• 管理权限和安全

2. Webhook 服务

接收飞书事件推送，转发给 OpenClaw Gateway。

3. 消息发送 API

通过 lark-mcp 工具或直接调用飞书 API 发送消息。

快速开始

前置条件

• 飞书开放平台账号
• 企业自建应用（机器人能力）
• OpenClaw Gateway 运行中
• 公网可访问的 Webhook URL（或使用内网穿透）

1. 创建飞书应用

1. 访问 飞书开放平台 2. 创建企业自建应用 3. 添加「机器人」能力 4. 配置权限（见下方权限列表） 5. 获取 App ID 和 App Secret

2. 配置事件订阅

1. 在应用管理页面，进入「事件订阅」 2. 配置请求地址：https://your-domain.com/webhook/feishu 3. 订阅事件：

• 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 start

4. 发布应用

1. 在飞书开放平台提交审核 2. 审核通过后发布 3. 在飞书中搜索并添加机器人

配置说明

环境变量 (.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

飞书应用权限

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!\"}"
  }'

安全策略

事件验证

飞书事件订阅支持两种验证方式：

1. Verification Token: 简单的 Token 验证 2. 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')
  );
}

私聊策略

群聊策略

使用场景

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 无法接收消息

1. 检查 Webhook URL 是否公网可访问 2. 检查 Verification Token 是否正确 3. 查看飞书开放平台的事件推送日志 4. 确认应用已发布且用户已添加机器人

消息发送失败

1. 检查 App ID 和 App Secret 2. 确认应用权限已开启 3. 检查 access_token 是否过期 4. 查看 API 返回的错误码

权限不足

1. 在飞书开放平台检查应用权限 2. 确认权限已审核通过 3. 重新获取 access_token

限制说明

飞书平台限制

• API 调用频率限制（参考官方文档）
• 消息长度限制
• 文件大小限制

功能限制

• 不支持语音消息
• 卡片消息交互需要额外配置回调
• 部分高级功能需要企业认证

相关文件

• scripts/feishu-webhook.js - Webhook 服务代码
• .env.example - 环境变量模板
• references/feishu-api.md - 飞书 API 参考
• references/message-types.md - 消息类型说明

TODO

• [ ] 创建飞书应用并获取凭证
• [ ] 配置事件订阅
• [ ] 部署 Webhook 服务
• [ ] 测试私聊消息收发
• [ ] 测试群聊 @提及
• [ ] 配置安全策略
• [ ] 实现卡片消息交互

飞书 API 参考

认证

获取 tenant_access_token

curl -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "cli_xxx",
    "app_secret": "xxx"
  }'

响应：

{
  "code": 0,
  "msg": "success",
  "tenant_access_token": "t-xxx",
  "expire": 7200
}

消息 API

发送消息

POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id
Authorization: Bearer {tenant_access_token}
Content-Type: application/json

{
  "receive_id": "ou_xxx",
  "msg_type": "text",
  "content": "{\"text\":\"Hello!\"}"
}

receive_id_type 类型

回复消息

POST https://open.feishu.cn/open-apis/im/v1/messages/{message_id}/reply
Authorization: Bearer {tenant_access_token}
Content-Type: application/json

{
  "msg_type": "text",
  "content": "{\"text\":\"收到！\"}"
}

获取消息

GET https://open.feishu.cn/open-apis/im/v1/messages/{message_id}
Authorization: Bearer {tenant_access_token}

消息类型

文本消息 (text)

{
  "msg_type": "text",
  "content": "{\"text\":\"Hello World\"}"
}

支持 @ 用户：

{
  "text": "<at user_id=\"ou_xxx\">张三</at> 你好"
}

富文本消息 (post)

{
  "msg_type": "post",
  "content": "{\"zh_cn\":{\"title\":\"标题\",\"content\":[[{\"tag\":\"text\",\"text\":\"内容\"}]]}}"
}

富文本元素：

• text - 文本
• a - 链接
• at - @用户
• img - 图片

图片消息 (image)

{
  "msg_type": "image",
  "content": "{\"image_key\":\"img_xxx\"}"
}

需要先上传图片获取 image_key。

卡片消息 (interactive)

{
  "msg_type": "interactive",
  "content": "{\"config\":{\"wide_screen_mode\":true},\"header\":{\"title\":{\"tag\":\"plain_text\",\"content\":\"标题\"}},\"elements\":[{\"tag\":\"div\",\"text\":{\"tag\":\"plain_text\",\"content\":\"内容\"}}]}"
}

卡片消息详解

基本结构

{
  "config": {
    "wide_screen_mode": true,
    "enable_forward": true
  },
  "header": {
    "title": {
      "tag": "plain_text",
      "content": "卡片标题"
    },
    "template": "blue"
  },
  "elements": []
}

header.template 颜色

• blue - 蓝色
• wathet - 浅蓝
• turquoise - 青色
• green - 绿色
• yellow - 黄色
• orange - 橙色
• red - 红色
• carmine - 深红
• violet - 紫色
• purple - 深紫
• indigo - 靛蓝
• grey - 灰色

元素类型

div - 内容块

{
  "tag": "div",
  "text": {
    "tag": "lark_md",
    "content": "**粗体** _斜体_ [链接](https://example.com)"
  }
}

hr - 分割线

{
  "tag": "hr"
}

action - 按钮组

{
  "tag": "action",
  "actions": [
    {
      "tag": "button",
      "text": {
        "tag": "plain_text",
        "content": "确认"
      },
      "type": "primary",
      "value": {
        "key": "value"
      }
    }
  ]
}

按钮类型：

• default - 默认
• primary - 主要
• danger - 危险

note - 备注

{
  "tag": "note",
  "elements": [
    {
      "tag": "plain_text",
      "content": "备注信息"
    }
  ]
}

事件订阅

消息接收事件

事件类型：im.message.receive_v1

{
  "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": "机器人"
        }
      ]
    }
  }
}

URL 验证

首次配置事件订阅时，飞书会发送验证请求：

{
  "challenge": "xxx",
  "token": "verification_token",
  "type": "url_verification"
}

需要返回：

{
  "challenge": "xxx"
}

用户 API

获取用户信息

GET https://open.feishu.cn/open-apis/contact/v3/users/{user_id}?user_id_type=open_id
Authorization: Bearer {tenant_access_token}

群聊 API

获取群信息

GET https://open.feishu.cn/open-apis/im/v1/chats/{chat_id}
Authorization: Bearer {tenant_access_token}

获取群成员

GET https://open.feishu.cn/open-apis/im/v1/chats/{chat_id}/members
Authorization: Bearer {tenant_access_token}

文件 API

上传图片

POST https://open.feishu.cn/open-apis/im/v1/images
Authorization: Bearer {tenant_access_token}
Content-Type: multipart/form-data

image_type: message
image: (binary)

上传文件

POST https://open.feishu.cn/open-apis/im/v1/files
Authorization: Bearer {tenant_access_token}
Content-Type: multipart/form-data

file_type: stream
file_name: example.pdf
file: (binary)

错误码

参考链接

• 飞书开放平台: https://open.feishu.cn/
• API 文档: https://open.feishu.cn/document/
• 消息卡片搭建工具: https://open.feishu.cn/tool/cardbuilder

飞书消息类型说明

支持的消息类型

文本消息 (text)

基本格式

{
  "text": "Hello World"
}

@用户

{
  "text": "<at user_id=\"ou_xxx\">张三</at> 你好"
}

@所有人

{
  "text": "<at user_id=\"all\">所有人</at> 请注意"
}

富文本消息 (post)

基本结构

{
  "zh_cn": {
    "title": "标题",
    "content": [
      [
        { "tag": "text", "text": "第一段" }
      ],
      [
        { "tag": "text", "text": "第二段" }
      ]
    ]
  }
}

支持的标签

text - 文本

{
  "tag": "text",
  "text": "普通文本",
  "un_escape": false
}

a - 链接

{
  "tag": "a",
  "text": "点击查看",
  "href": "https://example.com"
}

at - @用户

{
  "tag": "at",
  "user_id": "ou_xxx",
  "user_name": "张三"
}

img - 图片

{
  "tag": "img",
  "image_key": "img_xxx",
  "width": 300,
  "height": 200
}

完整示例

{
  "zh_cn": {
    "title": "项目周报",
    "content": [
      [
        { "tag": "text", "text": "本周完成情况：" }
      ],
      [
        { "tag": "text", "text": "1. 完成了 " },
        { "tag": "a", "text": "需求文档", "href": "https://example.com/doc" }
      ],
      [
        { "tag": "text", "text": "2. 修复了 5 个 Bug" }
      ],
      [
        { "tag": "text", "text": "请 " },
        { "tag": "at", "user_id": "ou_xxx", "user_name": "张三" },
        { "tag": "text", "text": " 审核" }
      ]
    ]
  }
}

图片消息 (image)

{
  "image_key": "img_xxx"
}

需要先通过上传接口获取 image_key。

文件消息 (file)

{
  "file_key": "file_xxx"
}

需要先通过上传接口获取 file_key。

卡片消息 (interactive)

卡片消息是最灵活的消息类型，支持丰富的布局和交互。

基本结构

{
  "config": {
    "wide_screen_mode": true,
    "enable_forward": true
  },
  "header": {
    "title": {
      "tag": "plain_text",
      "content": "卡片标题"
    },
    "template": "blue"
  },
  "elements": []
}

常用元素

文本块 (div)

{
  "tag": "div",
  "text": {
    "tag": "lark_md",
    "content": "**粗体** _斜体_ ~~删除线~~"
  }
}

多列布局 (column_set)

{
  "tag": "column_set",
  "flex_mode": "none",
  "background_style": "default",
  "columns": [
    {
      "tag": "column",
      "width": "weighted",
      "weight": 1,
      "elements": [
        {
          "tag": "div",
          "text": {
            "tag": "plain_text",
            "content": "左列"
          }
        }
      ]
    },
    {
      "tag": "column",
      "width": "weighted",
      "weight": 1,
      "elements": [
        {
          "tag": "div",
          "text": {
            "tag": "plain_text",
            "content": "右列"
          }
        }
      ]
    }
  ]
}

按钮 (button)

{
  "tag": "action",
  "actions": [
    {
      "tag": "button",
      "text": {
        "tag": "plain_text",
        "content": "确认"
      },
      "type": "primary",
      "value": {
        "action": "confirm"
      }
    },
    {
      "tag": "button",
      "text": {
        "tag": "plain_text",
        "content": "取消"
      },
      "type": "default"
    }
  ]
}

图片 (img)

{
  "tag": "img",
  "img_key": "img_xxx",
  "alt": {
    "tag": "plain_text",
    "content": "图片描述"
  }
}

完整卡片示例

{
  "config": {
    "wide_screen_mode": true
  },
  "header": {
    "title": {
      "tag": "plain_text",
      "content": "🎉 任务完成通知"
    },
    "template": "green"
  },
  "elements": [
    {
      "tag": "div",
      "text": {
        "tag": "lark_md",
        "content": "**任务名称**: 数据同步\n**完成时间**: 2024-02-01 10:30\n**处理记录**: 1,234 条"
      }
    },
    {
      "tag": "hr"
    },
    {
      "tag": "action",
      "actions": [
        {
          "tag": "button",
          "text": {
            "tag": "plain_text",
            "content": "查看详情"
          },
          "type": "primary",
          "url": "https://example.com/task/123"
        }
      ]
    },
    {
      "tag": "note",
      "elements": [
        {
          "tag": "plain_text",
          "content": "由 OpenClaw 自动发送"
        }
      ]
    }
  ]
}

Markdown 语法 (lark_md)

在卡片消息中使用 lark_md 标签时，支持以下 Markdown 语法：

消息接收解析

文本消息

{
  "message_type": "text",
  "content": "{\"text\":\"Hello\"}"
}

解析：

const content = JSON.parse(message.content);
const text = content.text; // "Hello"

带 @提及的消息

{
  "message_type": "text",
  "content": "{\"text\":\"@_user_1 你好\"}",
  "mentions": [
    {
      "key": "@_user_1",
      "id": {
        "open_id": "ou_xxx"
      },
      "name": "机器人"
    }
  ]
}

解析：

const content = JSON.parse(message.content);
let text = content.text; // "@_user_1 你好"

// 移除 @提及占位符
for (const mention of message.mentions) {
  text = text.replace(mention.key, '').trim();
}
// text = "你好"

参考链接

• 消息类型文档: https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/im-v1/message/create_json
• 卡片搭建工具: https://open.feishu.cn/tool/cardbuilder

Feishu Channel TODO

必需配置项

1. 飞书应用凭证

• App ID: 在飞书开放平台创建应用后获取
• App Secret: 应用密钥
• Verification Token: 事件订阅验证 Token
• Encrypt Key: 事件加密密钥（推荐）

2. 应用权限

需要在飞书开放平台开启以下权限：

• im:message - 消息读写
• im:message.group_at_msg - 群聊@消息
• im:message.p2p_msg - 私聊消息
• im:chat - 群聊信息
• contact:user.base - 用户基本信息

3. 事件订阅

• 配置 Webhook URL（需要公网可访问）
• 订阅 im.message.receive_v1 事件

待解决问题

架构问题

1. OpenClaw Channel 插件开发

• 当前方案使用独立 Webhook 服务桥接
• 可考虑开发原生 OpenClaw 插件（参考 telegram 插件）
• 需要研究 OpenClaw 插件 SDK

2. 消息路由

• Webhook 服务如何与 OpenClaw Gateway 通信
• 会话上下文如何保持

3. 卡片消息交互

• 按钮点击回调需要额外配置
• 需要实现卡片交互处理逻辑

技术问题

1. Webhook URL

• 需要公网可访问的 URL
• 可使用 ngrok/frp 等内网穿透工具
• 或部署到云服务器

2. Access Token 管理

• Token 有效期 2 小时
• 需要自动刷新机制

3. 消息可靠性

• 飞书事件推送有重试机制
• 需要实现幂等处理

安全问题

1. 事件验证

• 必须验证 Verification Token
• 推荐启用 Encrypt Key 加密

2. 权限控制

• 私聊白名单
• 群聊白名单

后续优化方向

功能增强

• [ ] 支持图片消息
• [ ] 支持文件消息
• [ ] 支持卡片消息交互
• [ ] 支持消息撤回
• [ ] 支持消息已读回执

稳定性

• [ ] Token 自动刷新
• [ ] 事件去重
• [ ] 错误重试
• [ ] 日志监控

部署

• [ ] Docker 容器化
• [ ] 系统服务配置
• [ ] 健康检查
• [ ] 自动重启

与 feishu-automation 的集成

feishu-channel 专注于消息通道，可以与 feishu-automation 配合使用：

1. 消息触发自动化

• 用户发送消息 → feishu-channel 接收
• AI 处理后调用 feishu-automation 操作多维表格

2. 自动化结果通知

• feishu-automation 完成任务
• 通过 feishu-channel 发送通知

替代方案

如果不想自建 Webhook 服务：

1. 使用 lark-mcp 的消息功能

• 仅支持发送，不支持接收
• 适合单向通知场景

2. 飞书机器人 Webhook

• 仅支持发送到群聊
• 不需要创建应用

参考资源

• 飞书开放平台: https://open.feishu.cn/
• 事件订阅文档: https://open.feishu.cn/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM
• 消息 API 文档: https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/im-v1/message/create
• 卡片搭建工具: https://open.feishu.cn/tool/cardbuilder