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

feishu-channel

Office & productivity

View repository

Updated 10-15 07:58

About this skill

Feishu Channel Integration

Connect Feishu to OpenClaw to enable a bidirectional message channel.

Differences from feishu-automation

Feature feishu-channel feishu-automation
Primary purpose 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
Use cases AI conversational bot Data sync, 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 via the lark-mcp tool or by calling the Feishu API directly.

Quick Start

Prerequisites

  • Feishu Open Platform account
  • Enterprise self-built application (bot capability)
  • OpenClaw Gateway running
  • 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 Guide

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 single-chat and group messages ✅
im:message.group_at_msg Receive @bot messages in group chats ✅
im:message.p2p_msg Receive single-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

Using 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"
          }
        ]
      }
    ]
  })
});

Using 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 chat privately (dangerous)
allowlist Only allow users in the allowFrom list

Group Chat Policy

Configuration Description
requireMention: true Only respond when the bot is @mentioned
allowFrom List of users allowed to trigger in 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 Process

用户: @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 failed

  1. Check the App ID and App Secret
  2. Confirm that app permissions have been 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 the permissions have been approved
  3. Obtain the access_token again

Limitations

Feishu Platform Limitations

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

Feature Limitations

  • Voice messages are not supported
  • Interactive card messages require additional callback configuration
  • Some advanced features require enterprise verification

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 interactive card messages