feishu-channel

用途

飞书 Channel 集成技能用于将飞书接入 OpenClaw，实现双向消息通道。它通过飞书机器人接收用户消息（私聊、群聊、@提及），并将消息转发给 OpenClaw Gateway 触发 AI 响应，同时支持从 OpenClaw 向飞书发送消息。

与 feishu-automation 的区别

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

架构概述

飞书用户（私聊/群聊）与飞书开放平台（Webhook）双向通信，飞书开放平台与 OpenClaw Gateway 双向通信。Webhook 服务负责事件验证、消息解析和格式转换。

核心组件包括：飞书机器人应用（企业自建应用，负责接收用户消息、发送消息、管理权限和安全）、Webhook 服务（接收飞书事件推送并转发给 OpenClaw Gateway）、消息发送 API（通过 lark-mcp 工具或直接调用飞书 API 发送消息）。

快速开始

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

创建飞书应用：访问飞书开放平台，创建企业自建应用，添加「机器人」能力，配置权限，获取 App ID 和 App Secret。
配置事件订阅：在应用管理页面进入「事件订阅」，配置请求地址（如 https://your-domain.com/webhook/feishu），订阅事件 im.message.receive_v1（接收消息）和 im.message.message_read_v1（消息已读，可选）。
部署 Webhook 服务：

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

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

配置说明

环境变量（.env）包括：飞书应用配置（FEISHU_APP_ID、FEISHU_APP_SECRET）、事件订阅验证 Token（FEISHU_VERIFICATION_TOKEN）、事件加密 Key（FEISHU_ENCRYPT_KEY，可选推荐启用）、OpenClaw Gateway 配置（OPENCLAW_GATEWAY_URL、OPENCLAW_WEBHOOK_SECRET）、安全配置（ALLOWED_USERS、ALLOWED_GROUPS）、群聊行为（REQUIRE_MENTION_IN_GROUP）、服务端口（PORT）、日志级别（LOG_LEVEL）。

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

OpenClaw 配置（openclaw.json）中可设置 channels.feishu 的 enabled、appId、appSecret、webhookUrl、dmPolicy、allowFrom、groups 等字段。

消息格式

接收消息时，飞书原始事件格式包含 schema、header（event_id、event_type、create_time、token、app_id）和 event（sender、message）。转换后的 OpenClaw 格式包含 type、channel、messageId、from、chat、text、mentions、isMentioned、timestamp。

发送消息可使用 lark-mcp 工具（支持文本、富文本、卡片消息）或直接调用 HTTP API。

安全策略

事件验证支持 Verification Token 简单验证和 Encrypt Key AES 加密（推荐）。私聊策略包括 open（允许所有人私聊，危险）和 allowlist（仅允许 allowFrom 列表中的用户）。群聊策略可配置 requireMention（必须@机器人才响应）和 allowFrom（群内允许触发的用户列表）。

使用场景

智能问答机器人：用户@机器人提问，机器人返回答案。
工作流通知：任务完成时向群聊发送卡片通知。
审批流程：用户提交申请，机器人返回审批卡片。

故障排查

Webhook 无法接收消息时，检查 Webhook URL 是否公网可访问、Verification Token 是否正确、查看飞书开放平台的事件推送日志、确认应用已发布且用户已添加机器人。消息发送失败时，检查 App ID 和 App Secret、确认应用权限已开启、检查 access_token 是否过期、查看 API 返回的错误码。权限不足时，在飞书开放平台检查应用权限、确认权限已审核通过、重新获取 access_token。

限制说明

飞书平台限制包括 API 调用频率限制（参考官方文档）、消息长度限制、文件大小限制。功能限制包括不支持语音消息、卡片消息交互需要额外配置回调、部分高级功能需要企业认证。

技能介绍

用途