飞书 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 start

4. 发布应用

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

配置说明

环境变量 (.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 调用频率限制（参考官方文档）
消息长度限制
文件大小限制

功能限制

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

TODO

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

飞书 Channel 集成

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

与 feishu-automation 的区别

架构概述

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│   飞书用户   │ ←→  │   飞书开放平台    │ ←→  │  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 start

4. 发布应用

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

配置说明

环境变量 (.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!\"}"
  }'

安全策略

事件验证

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

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 调用频率限制（参考官方文档）
消息长度限制
文件大小限制

功能限制

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

TODO

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

Adoption

aaaaqwq/feishu-channel

$ install --global

Security Scan Results

SKILL.md

飞书 Channel 集成

与 feishu-automation 的区别

架构概述

核心组件

1. 飞书机器人应用

2. Webhook 服务

3. 消息发送 API

快速开始

前置条件

1. 创建飞书应用

2. 配置事件订阅

3. 部署 Webhook 服务

4. 发布应用

配置说明

环境变量 (.env)

飞书应用权限

OpenClaw 配置 (openclaw.json)

消息格式

接收消息 (Webhook Event)

发送消息

使用 lark-mcp 工具

使用 HTTP API

安全策略

事件验证

私聊策略

群聊策略

使用场景

1. 智能问答机器人

2. 工作流通知

3. 审批流程

故障排查

Webhook 无法接收消息

消息发送失败

权限不足

限制说明

飞书平台限制

功能限制

相关文件

TODO

Related Skills

aaaaqwq/code-exemplars-blueprint-generator

aaaaqwq/chrome-devtools

aaaaqwq/breakdown-feature-implementation

aaaaqwq/boost-prompt

aaaaqwq/feishu-channel

$ install --global

Security Scan Results

SKILL.md

飞书 Channel 集成

与 feishu-automation 的区别

架构概述

核心组件

1. 飞书机器人应用

2. Webhook 服务

3. 消息发送 API

快速开始

前置条件

1. 创建飞书应用

2. 配置事件订阅

3. 部署 Webhook 服务

4. 发布应用

配置说明

环境变量 (.env)

飞书应用权限

OpenClaw 配置 (openclaw.json)

消息格式

接收消息 (Webhook Event)

发送消息

使用 lark-mcp 工具

使用 HTTP API

安全策略

事件验证

私聊策略

群聊策略

使用场景