一、前言
1.1 为什么需要配置飞书机器人？
OpenClaw 作为开源万能个人助理框架，支持多渠道通信。飞书（Lark）作为企业级协作平台，是集成 AI 助手的理想选择：
- 多渠道接入 - 支持私聊、群组、频道
- 富媒体交互 - 支持文本、图片、卡片、表情
- 企业级安全 - 完善的权限管理
- 开放 API - 丰富的集成能力
1.2 飞书机器人支持的功能
OpenClaw 的飞书扩展支持：
| 功能 | 说明 |
|---|---|
| 私聊对话 | 与 AI 助手 1 对 1 交流 |
| 群组互动 | 群聊中@机器人对话 |
| 文档操作 | 飞书云文档读写 |
| 表情回应 | 支持各类消息互动 |
| Webhook | 实时消息推送 |
| 双模式 | WebSocket / Webhook |
二、准备工作
2.1 环境要求
# 操作系统 - Linux (Ubuntu 20.04+ 推荐) - macOS 12+ - Windows 10+ (WSL2 推荐)
# 基础环境
# Node.js 18+
# pnpm 8+
# Git
2.2 OpenClaw 安装
# 1. 克隆项目
git clone https://github.com/openclaw/openclaw.git
cd openclaw
# 2. 安装依赖
pnpm install
# 3. 配置环境变量
cp .env.example .env
# 4. 启动开发模式
pnpm dev
2.3 飞书账号要求
- 拥有飞书管理员权限
- 可访问 飞书开放平台
- 企业版或个人版飞书账号均可
三、飞书应用创建
3.1 创建企业应用
访问飞书开放平台
访问：https://open.feishu.cn/
登录你的飞书账号
此处点击右上角进入开发者后台。
创建应用
点击「创建企业应用」
填写应用名称：OpenClaw 助手
上传应用图标
- 填写应用基本信息
- 应用名称：OpenClaw 助手
- 应用描述：基于 OpenClaw 的 AI 助手
- 上传应用图标
- 配置应用信息
- 应用描述：基于 OpenClaw 的 AI 助手
- 应用主页：可选填
- 落地页：可选填
3.2 获取应用凭证
在应用详情页获取：
{
"appId": "your_app_id_here",
"appSecret": "your_app_secret_here"
}
⚠️ 注意：妥善保管 appSecret，泄露后需重新创建
3.3 开通权限
在「权限管理」中开通以下权限：
| 权限名称 | 权限说明 | 必要性 |
|---|---|---|
| im:message | 发送和接收消息 | ⭐ 必选 |
| im:chat | 群组管理 | ⭐ 必选 |
| im:contact | 联系人读取 | ⭐ 必选 |
| doc:document | 云文档读写 | 🔸 可选 |
| drive:file | 云空间文件 | 🔸 可选 |
| approval:instance | 审批流程 | 🔸 可选 |
3.4 配置事件订阅
Webhook URL 配置
# 你的服务器地址
https://your-domain.com/api/feishu/webhook
订阅事件
必需事件：
├── im:message
│ └── 接收消息事件
└── im.chat
└── 群组事件
3.5 发布应用
提交审核
审核时间：1-3 工作日
企业自建应用可无需审核
可见范围
• 全体成员
• 指定部门
• 指定用户
版本管理
版本号：v1.0.0
版本描述：首次发布
审核后看到发布成功，则 OK。
四、OpenClaw 配置
4.1 配置文件结构
openclaw/
├── .env # 环境变量
├── apps/
│ └── feishu/
│ └── config.ts # 飞书配置
└── extensions/
└── feishu/
└── src/
├── client.ts # 客户端
├── accounts.ts # 账号管理
└── types.ts # 类型定义
4.2 环境变量配置
# .env 文件
# 飞书应用凭证
FEISHU_APP_ID=your_app_id
FEISHU_APP_SECRET=your_app_secret
# 飞书域名
FEISHU_DOMAIN=feishu
# 或 lark
# 连接模式
FEISHU_CONNECTION_MODE=websocket
# websocket | webhook
# Webhook 配置
FEISHU_WEBHOOK_PATH=/api/feishu/webhook
FEISHU_VERIFICATION_TOKEN=your_token
4.3 飞书配置文件
// apps/feishu/config.ts
export const FeishuConfig = {
// 应用凭证
credentials: {
appId: process.env.FEISHU_APP_ID,
appSecret: process.env.FEISHU_APP_SECRET,
},
// 域名配置
domain: process.env.FEISHU_DOMAIN || 'feishu',
// 连接模式
connectionMode: process.env.FEISHU_CONNECTION_MODE || 'websocket',
// Webhook 配置
webhook: {
path: process.env.FEISHU_WEBHOOK_PATH || '/api/feishu/webhook',
verificationToken: process.env.FEISHU_VERIFICATION_TOKEN,
},
// 消息配置
message: {
maxLength: 20000,
retryTimes: 3,
retryInterval: 1000,
},
// 日志配置
logging: {
level: 'info',
format: 'json',
},
};
4.4 账号配置
// 支持多账号配置
export const feishuAccounts = [
{
accountId: 'main',
appId: process.env.FEISHU_APP_ID,
appSecret: process.env.FEISHU_APP_SECRET,
enabled: true,
configured: true,
domain: 'feishu',
connectionMode: 'websocket',
},
{
accountId: 'lark',
appId: 'your_lark_app_id',
appSecret: 'your_lark_app_secret',
enabled: false, // 暂不启用
configured: false,
domain: 'lark',
},
];
五、核心配置详解
5.1 连接模式配置
WebSocket 模式（推荐）
// 实时双向通信
const wsConfig = {
connectionMode: 'websocket',
heartbeatInterval: 30000, // 30 秒心跳
reconnectInterval: 5000, // 断线重连间隔
maxReconnectAttempts: 10, // 最大重连次数
};
Webhook 模式
// 被动接收消息
const webhookConfig = {
connectionMode: 'webhook',
path: '/api/feishu/webhook',
methods: ['POST'],
};
5.2 消息类型支持
// 支持的消息类型
const supportedMessageTypes = [
'text', // 纯文本
'image', // 图片
'file', // 文件
'audio', // 语音
'video', // 视频
'rich_text', // 富文本
'card', // 卡片消息
'interactive', // 交互卡片
];
5.3 消息发送配置
// apps/feishu/src/send.ts
export interface FeishuMessageInfo {
messageId: string; // 消息 ID
chatId: string; // 会话 ID
senderId?: string; // 发送者 ID
messageType: string; // 消息类型
content: string; // 消息内容
timestamp: number; // 时间戳
}
// 发送富文本消息
const sendRichText = async (chatId: string, markdown: string) => {
await client.sendMessage({
receiveId: chatId,
msgType: 'rich_text',
content: JSON.stringify({
rich_text: {
elements: [
{
type: 'text',
text: markdown,
},
],
},
}),
});
};
六、群组策略配置
6.1 群白名单配置
// 配置允许使用机器人的群组
export const groupPolicy = {
// 白名单模式
allowlist: {
enabled: true,
mode: 'whitelist', // whitelist | blacklist
// 匹配方式
matchSource: 'id', // id | name | wildcard
// 允许的群组 ID 列表
allowedGroups: [
'oc_xxxxxxxxxxxxx', // 群组 ID
],
// 匹配规则
matchRules: {
// 群名匹配（支持通配符）
namePatterns: ['AI-*', '测试群'],
},
},
// 默认策略
defaultPolicy: {
allowed: true, // 默认允许
responseMention: true, // 是否@回复用户
typingIndicator: true, // 显示"正在输入"
},
};
6.2 群组功能开关
// 群组功能配置
export const groupFeatures = {
// 是否允许机器人被@时回复
mentionReply: {
enabled: true,
prefix: '@你的名字', // 机器人昵称
},
// 是否允许私聊模式
privateChat: {
enabled: true,
requireFollow: false, // 是否需要先关注
},
// 文档功能
document: {
enabled: true,
read: true,
write: true,
create: true,
},
// 媒体功能
media: {
upload: true,
download: true,
maxSize: 20 * 1024 * 1024, // 20MB
},
};
6.3 权限控制
// 用户权限配置
export const userPermissions = {
// 管理员（可配置机器人）
admins: [
'ou_xxxxxxxxxxxxx', // 用户 OpenID
],
// 普通用户权限
user: {
canUse: true,
dailyLimit: 100, // 每日限额
canUpload: true,
maxFileSize: 10 * 1024 * 1024,
},
// 匿名用户权限
anonymous: {
canUse: false,
},
};
七、功能测试
7.1 基础功能测试
测试 1：私聊对话
# 步骤 1：在飞书中搜索机器人并发起对话
# 步骤 2：发送测试消息
你好，OpenClaw！
# 预期回复
你好！我是 OpenClaw AI 助手。有什么可以帮助你的吗？
测试 2：群组@互动
# 步骤 1：将机器人拉入群组
# 步骤 2：@机器人并提问
@OpenClaw 帮我总结今天的新闻
# 预期回复
今天的主要新闻：
1. xxx
2. xxx
3. xxx
7.2 高级功能测试
测试 3：飞书文档操作
# 测试文档读写功能
## 读文档
@OpenClaw 读取文档 [文档 ID]
## 写文档
@OpenClaw 在文档 [ID] 中添加以下内容：
## 新增章节
- 项目进度更新
- 明日工作计划
测试 4：文件传输
# 测试文件上传下载
## 上传图片
@OpenClaw 上传图片 [图片文件]
## 下载文件
@OpenClaw 下载这个文件
7.3 测试用例表
| 测试项 | 测试步骤 | 预期结果 | 实际结果 |
|---|---|---|---|
| 私聊对话 | 发送"你好" | 回复欢迎语 | ✅ |
| 群组@互动 | @机器人提问 | AI 回复 | ✅ |
| 文档读取 | 请求读取文档 | 返回文档内容 | ✅ |
| 文档写入 | 添加内容 | 内容成功添加 | ✅ |
| 图片发送 | 发送图片 | 图片正常显示 | ✅ |
| 文件上传 | 上传文件 | 文件上传成功 | ✅ |
| 断线重连 | 断开网络后重连 | 自动重连成功 | ✅ |
| 高频测试 | 连续发送 10 条 | 全部正常回复 | ✅ |
八、常见问题
Q1: WebSocket 连接失败？
问题描述：
Error: WebSocket connection failed
解决方案：
# 1. 检查网络连通性
ping open.feishu.cn
# 2. 检查防火墙设置
sudo ufw status
# 3. 检查 WebSocket 端口
netstat -tlnp | grep 443
# 4. 查看详细日志
FEISHU_LOG_LEVEL=debug pnpm dev
Q2: 消息发送失败？
问题描述：
Error: Failed to send message
解决方案：
// 1. 检查消息长度
if (message.length > 20000) {
// 拆分成多条消息发送
}
// 2. 检查频率限制
// 飞书默认限制：60 条/分钟
// 3. 添加重试机制
const sendWithRetry = async (message, retries = 3) => {
for (let i = 0; i < retries; i++) {
try {
return await sendMessage(message);
} catch (e) {
if (i === retries - 1) throw e;
await sleep(1000 * (i + 1));
}
}
};
Q3: 机器人无响应？
排查步骤：
# 1. 检查机器人是否启用
curl http://localhost:3000/api/feishu/status
# 2. 检查事件是否正常
curl http://localhost:3000/api/feishu/events
# 3. 查看运行日志
tail -f logs/feishu.log
Q4: 权限不足？
问题描述：
Error: Permission denied
解决方案：
# 1. 确认已开通所有必要权限
# 2. 确认应用已发布
# 3. 确认用户已在可见范围内
Q5: 文档操作失败？
问题描述：
Error: Document operation failed
解决方案：
// 检查文档权限
const checkDocPermission = async (docId: string) => {
const doc = await client.doc.get({
document_id: docId,
});
if (!doc.readable) {
throw new Error('文档无读取权限');
}
if (!doc.writable) {
throw new Error('文档无写入权限');
}
};
九、进阶技巧
9.1 多账号配置
// 同时连接飞书和 Lark
export const multiAccount = {
accounts: [
{
name: '飞书',
domain: 'feishu',
config: feishuConfig,
},
{
name: 'Lark',
domain: 'lark',
config: larkConfig,
enabled: false, // 暂不启用
},
],
// 负载均衡
loadBalancing: 'round_robin', // 轮询 | 随机
};
9.2 自定义消息卡片
// 发送交互式卡片
const sendCard = async (chatId: string) => {
await client.sendMessage({
receiveId: chatId,
msgType: 'interactive',
content: JSON.stringify({
card: {
config: {
wide_screen_mode: true,
enable_forward: true,
},
elements: [
{
tag: 'div',
fields: [
{
is_short: false,
text: {
tag: 'lark_md',
content: '**AI 助手回复**\n你好！有什么可以帮你？',
},
},
],
},
{
tag: 'action',
actions: [
{
tag: 'button',
text: {
tag: 'plain_text',
content: '继续对话',
},
type: 'primary',
action_id: 'continue_chat',
},
{
tag: 'button',
: {
: ,
: ,
},
: ,
: ,
},
],
},
],
},
}),
});
};
9.3 消息缓存策略
// 消息缓存配置
export const messageCache = {
enabled: true,
maxSize: 1000,
ttl: 3600, // 1 小时
strategy: 'lru', // LRU 缓存
// 缓存操作
get: async (key: string) => {},
set: async (key: string, value: any) => {},
delete: async (key: string) => {},
clear: async () => {},
};
9.4 性能优化
// 性能配置
export const performance = {
// 并发限制
maxConcurrent: 10,
// 请求队列
queueSize: 100,
// 消息批处理
batching: {
enabled: true,
maxBatchSize: 10,
maxWaitTime: 100, // 毫秒
},
// 数据库连接池
pool: {
min: 2,
max: 10,
},
};
9.5 日志与监控
// 结构化日志
export const logging = {
level: 'info',
format: 'json',
// 日志字段
fields: {
traceId: true,
userId: true,
chatId: true,
messageId: true,
timestamp: true,
},
// 日志输出
outputs: [
{
type: 'console',
level: 'info',
},
{
type: 'file',
level: 'info',
path: './logs/feishu.log',
rotation: 'daily',
},
{
type: 'remote',
level: 'warn',
endpoint: 'https://your-log-service.com',
},
],
};
十、总结
10.1 配置要点回顾
- ✅ 创建飞书企业应用
- ✅ 获取并保管好应用凭证
- ✅ 开通必要权限
- ✅ 配置环境变量
- ✅ 选择连接模式（推荐 WebSocket）
- ✅ 配置群组白名单
- ✅ 测试各功能模块
