SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsfeishu-channel

feishu-channel

Office & productivity

View repository

Updated 10-15 14:00

About this skill

Feishu Channel Integration

Connect Feishu to OpenClaw to implement a bidirectional message channel.

Differences from feishu-automation

Feature feishu-channel feishu-automation
Primary Use Message channel integration Platform automation operations
Message receiving ✅ Webhook event subscription ❌ Not supported
Message sending ✅ Real-time conversation ✅ Notification push
Bitable ❌ Not involved ✅ Fully supported
Document management ❌ Not involved ✅ Fully supported
Applicable scenarios AI conversational bot Data synchronization, automated workflows

Architecture Overview

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

Core Components

1. Feishu Bot Application

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

  • Receiving user messages (via event subscription)
  • Sending messages (via the messaging API)
  • Managing permissions and security

2. Webhook Service

Receives Feishu event pushes and forwards them to the OpenClaw Gateway.

3. Message Sending API

Send messages through the lark-mcp tool or by directly calling the Feishu API.

Quick Start

Prerequisites

  • Feishu Open Platform account
  • Enterprise self-built application (bot capability)
  • OpenClaw Gateway running
  • A publicly accessible Webhook URL (or use intranet penetration)

1. Create a Feishu Application

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

2. Configure Event Subscription

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

3. Deploy the Webhook Service

cd /home/aa/clawd/skills/feishu-channel
npm install
cp .env.example .env
# 编辑 .env 填入配置
npm start

4. Publish the Application

  1. Submit for review on the Feishu Open Platform
  2. Publish after approval
  3. Search for and add the bot in Feishu

Configuration Instructions

Environment Variables (.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

Feishu Application Permissions

Permission Description Required
im:message Get and send private chat and group messages ✅
im:message.group_at_msg Receive @bot messages in group chats ✅
im:message.p2p_msg Receive private chat 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 Configuration (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
        }
      }
    }
  }
}

Message Format

Receiving Messages (Webhook Event)

Feishu raw event format:

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

Converted OpenClaw format:

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

Sending Messages

Use the lark-mcp tool

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

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

Security Policy

Event Verification

Feishu event subscription supports two verification methods:

  1. Verification Token: Simple Token verification
  2. Encrypt Key: AES encryption (recommended)
// 验证示例
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')
  );
}

Private Chat Policy

Policy Description
open Allow everyone to send private messages (dangerous)
allowlist Only allow users in the allowFrom list

Group Chat Policy

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

Use Cases

1. Intelligent Q&A Bot

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

2. Workflow Notifications

// 当任务完成时发送通知
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. Approval Processes

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

Troubleshooting

Webhook cannot receive messages

  1. Check whether the Webhook URL is publicly accessible
  2. Check whether the Verification Token is correct
  3. Check the event push logs on the Feishu Open Platform
  4. Confirm that the app has been published and the user has added the bot

Message sending fails

  1. Check the App ID and App Secret
  2. Confirm that app permissions are enabled
  3. Check whether the access_token has expired
  4. Check the error code returned by the API

Insufficient permissions

  1. Check app permissions on the Feishu Open Platform
  2. Confirm that permissions have been approved
  3. Re-obtain the access_token

Limitations

Feishu Platform Limitations

  • API call rate limits (refer to the official documentation)
  • Message length limit
  • File size limit

Feature Limitations

  • Voice messages are not supported
  • Card message interactions require additional callback configuration
  • Some advanced features require enterprise certification

Related Files

  • 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

TODO

  • Create a Feishu app and obtain credentials
  • Configure event subscription
  • Deploy the Webhook service
  • Test sending and receiving private chat messages
  • Test group chat @mentions
  • Configure security policy
  • Implement card message interactions