feishu-channel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

飞书 Channel 集成

Feishu Channel Integration

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

Integrate Feishu into OpenClaw to implement a two-way message channel.

与 feishu-automation 的区别

Difference from feishu-automation

特性	feishu-channel	feishu-automation
主要用途	消息通道集成	平台自动化操作
消息接收	✅ Webhook 事件订阅	❌ 不支持
消息发送	✅ 实时对话	✅ 通知推送
多维表格	❌ 不涉及	✅ 完整支持
文档管理	❌ 不涉及	✅ 完整支持
适用场景	AI 对话机器人	数据同步、自动化工作流

Feature	feishu-channel	feishu-automation
Main Purpose	Message channel integration	Platform automation operations
Message Receiving	✅ Webhook event subscription	❌ Not supported
Message Sending	✅ Real-time conversation	✅ Notification push
Multidimensional Table	❌ Not involved	✅ Full support
Document Management	❌ Not involved	✅ Full support
Applicable Scenarios	AI chatbot	Data synchronization, automated workflow

架构概述

Architecture Overview

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

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│   Feishu User   │ ←→  │   Feishu Open Platform    │ ←→  │  OpenClaw   │
│  (Private/Group Chat) │     │   (Webhook)      │     │   Gateway   │
└─────────────┘     └──────────────────┘     └─────────────┘
                           ↓
                    ┌──────────────────┐
                    │   Webhook Service    │
                    │   - Event Verification      │
                    │   - Message Parsing      │
                    │   - Format Conversion      │
                    └──────────────────┘

核心组件

Core Components

1. 飞书机器人应用

1. Feishu Bot Application

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

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

A self-built enterprise application created on Feishu Open Platform, responsible for:

Receiving user messages (via event subscription)
Sending messages (via message API)
Managing permissions and security

2. Webhook 服务

2. Webhook Service

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

Receives Feishu event pushes and forwards them to OpenClaw Gateway.

3. 消息发送 API

3. Message Sending API

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

Send messages via lark-mcp tool or directly calling Feishu API.

快速开始

Quick Start

前置条件

Prerequisites

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

Feishu Open Platform account
Enterprise self-built application (with bot capability)
OpenClaw Gateway is running
Publicly accessible Webhook URL (or use intranet penetration)

1. 创建飞书应用

1. Create Feishu Application

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

Visit Feishu Open Platform
Create an enterprise self-built application
Add the "Bot" capability
Configure permissions (see the permission list below)
Obtain App ID and App Secret

2. 配置事件订阅

2. Configure Event Subscription

在应用管理页面，进入「事件订阅」
配置请求地址：
```
https://your-domain.com/webhook/feishu
```
订阅事件：
- ```
im.message.receive_v1
```
  - 接收消息
- ```
im.message.message_read_v1
```
  - 消息已读（可选）

On the application management page, enter "Event Subscription"
Configure request URL:
```
https://your-domain.com/webhook/feishu
```
Subscribe to events:
- ```
im.message.receive_v1
```
  - Receive messages
- ```
im.message.message_read_v1
```
  - Message read (optional)

3. 部署 Webhook 服务

3. Deploy Webhook Service

bash

cd /home/aa/clawd/skills/feishu-channel
npm install
cp .env.example .env

bash

cd /home/aa/clawd/skills/feishu-channel
npm install
cp .env.example .env

编辑 .env 填入配置

Edit .env to fill in the configuration

npm start

undefined

npm start

undefined

4. 发布应用

4. Publish Application

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

Submit for review on Feishu Open Platform
Publish after passing the review
Search for and add the bot in Feishu

配置说明

Configuration Instructions

环境变量 (.env)

Environment Variables (.env)

env

undefined

env

undefined

飞书应用配置 (必需)

Feishu application configuration (required)

FEISHU_APP_ID=cli_xxxxxxxxxx FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx

事件订阅验证 Token

Event subscription verification Token

FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxxxx

事件加密 Key (可选，推荐启用)

Event encryption Key (optional, recommended to enable)

FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxxxx

OpenClaw Gateway 配置

OpenClaw Gateway configuration

OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789 OPENCLAW_WEBHOOK_SECRET=your_webhook_secret

安全配置

Security configuration

允许的用户 open_id (逗号分隔，留空允许所有)

Allowed user open_id (comma separated, leave blank to allow all)

ALLOWED_USERS=ou_xxx,ou_yyy

允许的群聊 chat_id (逗号分隔，留空允许所有)

Allowed group chat chat_id (comma separated, leave blank to allow all)

ALLOWED_GROUPS=oc_xxx,oc_yyy

群聊行为

Group chat behavior

REQUIRE_MENTION_IN_GROUP=true

服务端口

Service port

PORT=3002

日志级别

Log level

LOG_LEVEL=info

undefined

LOG_LEVEL=info

undefined

飞书应用权限

Feishu Application Permissions

权限	说明	必需
`im:message`	获取与发送单聊、群组消息	✅
`im:message.group_at_msg`	接收群聊中@机器人消息	✅
`im:message.p2p_msg`	接收用户发给机器人的单聊消息	✅
`im:chat`	获取群组信息	推荐
`contact:user.base`	获取用户基本信息	推荐
`im:resource`	获取与上传图片或文件资源	可选

Permission	Description	Required
`im:message`	Get and send private and group messages	✅
`im:message.group_at_msg`	Receive messages @bot in group chat	✅
`im:message.p2p_msg`	Receive private messages sent by users to the bot	✅
`im:chat`	Get group information	Recommended
`contact:user.base`	Get basic user information	Recommended
`im:resource`	Get and upload image or file resources	Optional

OpenClaw 配置 (openclaw.json)

OpenClaw Configuration (openclaw.json)

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
        }
      }
    }
  }
}

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": "Work Group",
          "requireMention": true
        }
      }
    }
  }
}

消息格式

Message Format

接收消息 (Webhook Event)

Received Message (Webhook Event)

飞书原始事件格式：

json

{
  "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 格式：

json

{
  "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
}

Original Feishu event format:

json

{
  "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 Assistant"
        }
      ]
    }
  }
}

Converted OpenClaw format:

json

{
  "type": "message",
  "channel": "feishu",
  "messageId": "om_xxx",
  "from": {
    "id": "ou_xxx",
    "name": "Zhang San"
  },
  "chat": {
    "id": "oc_xxx",
    "type": "group",
    "name": "Work Group"
  },
  "text": "Hello",
  "mentions": ["ou_bot"],
  "isMentioned": true,
  "timestamp": 1706745600000
}

发送消息

Sending Message

使用 lark-mcp 工具

Using lark-mcp Tool

javascript

// 发送文本消息
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"
          }
        ]
      }
    ]
  })
});

javascript

// Send text message
await mcp__lark-mcp_sendMessage({
  receive_id: "ou_xxx",  // or oc_xxx (group chat)
  receive_id_type: "open_id",  // or chat_id
  msg_type: "text",
  content: JSON.stringify({
    text: "Received, processing..."
  })
});

// Send rich text message
await mcp__lark-mcp_sendMessage({
  receive_id: "oc_xxx",
  receive_id_type: "chat_id",
  msg_type: "post",
  content: JSON.stringify({
    zh_cn: {
      title: "Task Completed",
      content: [
        [
          { tag: "text", text: "Completed " },
          { tag: "a", text: "View Details", href: "https://example.com" }
        ]
      ]
    }
  })
});

// Send card message
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: "Notification", tag: "plain_text" }
    },
    elements: [
      {
        tag: "div",
        text: { content: "**Important Notice**", tag: "lark_md" }
      },
      {
        tag: "action",
        actions: [
          {
            tag: "button",
            text: { content: "Confirm", tag: "plain_text" },
            type: "primary"
          }
        ]
      }
    ]
  })
});

使用 HTTP API

Using HTTP API

bash

undefined

bash

undefined

发送文本消息

Send text message

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

undefined

undefined

安全策略

Security Policy

事件验证

Event Verification

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

Verification Token: 简单的 Token 验证
Encrypt Key: AES 加密（推荐）

javascript

// 验证示例
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')
  );
}

Feishu event subscription supports two verification methods:

Verification Token: Simple Token verification
Encrypt Key: AES encryption (recommended)

javascript

// Verification example
function verifyEvent(body, token) {
  if (body.token !== token) {
    throw new Error('Invalid verification token');
  }
}

// Decryption example
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')
  );
}

私聊策略

Private Chat Policy

策略	说明
`open`	允许所有人私聊（危险）
`allowlist`	仅允许 allowFrom 列表中的用户

Policy	Description
`open`	Allow all users to send private chats (dangerous)
`allowlist`	Only allow users in the allowFrom list

群聊策略

Group Chat Policy

配置	说明
`requireMention: true`	必须@机器人才响应
`allowFrom`	群内允许触发的用户列表

Configuration	Description
`requireMention: true`	Must @the bot to respond
`allowFrom`	List of users allowed to trigger in the group

使用场景

Usage Scenarios

1. 智能问答机器人

1. Intelligent Q&A Bot

用户: @OpenClaw助手 帮我查一下今天的会议安排
Bot: 今天的会议安排：
- 10:00 产品评审会 (会议室A)
- 14:00 技术分享会 (线上)
- 16:00 周例会 (会议室B)

User: @OpenClaw Assistant Help me check today's meeting schedule
Bot: Today's meeting schedule:
- 10:00 Product Review Meeting (Conference Room A)
- 14:00 Technology Sharing Meeting (Online)
- 16:00 Weekly Meeting (Conference Room B)

2. 工作流通知

2. Workflow Notification

javascript

// 当任务完成时发送通知
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" }
      }
    ]
  })
});

javascript

// Send notification when task is completed
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: "✅ Task Completed", tag: "plain_text" }
    },
    elements: [
      {
        tag: "div",
        text: { content: "Data synchronization task completed\nProcessed records: 1,234 entries", tag: "lark_md" }
      }
    ]
  })
});

3. 审批流程

3. Approval Process

用户: @OpenClaw助手 提交请假申请，明天休息一天
Bot: 已收到请假申请，正在提交审批...
     [卡片消息: 请假申请详情 + 审批按钮]

User: @OpenClaw Assistant Submit leave application, take one day off tomorrow
Bot: Leave application received, submitting for approval...
     [Card message: Leave application details + Approval button]

故障排查

Troubleshooting

Webhook 无法接收消息

Webhook Cannot Receive Messages

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

Check if the Webhook URL is publicly accessible
Check if the Verification Token is correct
View the event push log of Feishu Open Platform
Confirm that the application has been published and the user has added the robot

消息发送失败

Message Sending Failed

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

Check App ID and App Secret
Confirm that the application permissions are enabled
Check if access_token is expired
View the error code returned by the API

权限不足

Insufficient Permissions

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

Check application permissions on Feishu Open Platform
Confirm that the permissions have been approved
Re-obtain access_token

限制说明

Limit Description

飞书平台限制

Feishu Platform Limits

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

API call frequency limit (refer to official documentation)
Message length limit
File size limit

功能限制

Functional Limits

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

Voice messages are not supported
Card message interaction requires additional callback configuration
Some advanced functions require enterprise authentication

Related Files

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

```
scripts/feishu-webhook.js
```
- Webhook service code
```
.env.example
```
- Environment variable template
```
references/feishu-api.md
```
- Feishu API reference
```
references/message-types.md
```
- Message type description