政安晨【零基础玩转开源AI项目】OpenClaw飞书通信端机器人配置指南（手把手配置OpenClaw飞书/Lark机器人，实现多渠道AI助手集成）（作者自己配置时留存使用，小伙伴们可酌情参考）
政安晨的个人主页：政安晨
欢迎 👍点赞✍评论⭐收藏
希望政安晨的博客能够对您有所裨益，如有不足之处，欢迎在评论区提出指正！
目录
2.2 OpenClaw安装（本篇主要介绍飞书端的配置，这里可参考我上一篇博客）
一、前言
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', text: { tag: 'plain_text', content: '结束对话', }, type: 'default', action_id: 'end_chat', }, ], }, ], }, }), }); }; 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）
- ✅ 配置群组白名单
- ✅ 测试各功能模块
