跳到主要内容OpenClaw 飞书机器人配置指南:从零搭建 AI 助手 | 极客日志TypeScriptNode.jsAI
OpenClaw 飞书机器人配置指南:从零搭建 AI 助手
OpenClaw 飞书机器人配置指南涵盖从应用创建到核心功能测试的全流程。通过配置环境变量与权限,可实现私聊、群组互动及文档操作等能力。推荐使用 WebSocket 模式保障实时通信,配合群组白名单策略增强安全性。文中提供常见问题排查方案及多账号、消息卡片等进阶技巧,帮助开发者快速搭建企业级 AI 助手。
星落15 浏览 OpenClaw 飞书机器人配置指南
OpenClaw 作为开源万能个人助理框架,支持多渠道通信。飞书(Lark)作为企业级协作平台,是集成 AI 助手的理想选择。通过本指南,你可以快速完成从应用创建到功能测试的全流程配置。
为什么需要配置飞书机器人?
飞书在企业级场景中具备天然优势:
- 多渠道接入:支持私聊、群组、频道等多种交互方式
- 富媒体交互:原生支持文本、图片、卡片及表情互动
- 企业级安全:完善的权限管理体系保障数据安全
- 开放 API:丰富的集成能力便于二次开发
准备工作
环境要求
确保你的开发环境满足以下基础条件:
OpenClaw 安装
如果你尚未安装 OpenClaw,可参考官方文档进行部署。本篇重点介绍飞书端的配置细节。
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
cp .env.example .env
pnpm dev
飞书账号要求
- 拥有飞书管理员权限或可创建应用的权限
- 可访问飞书开放平台
- 企业版或个人版飞书账号均可使用
飞书应用创建
创建企业应用
登录飞书开放平台,点击右上角进入开发者后台。点击「创建企业应用」,填写基本信息:
- 应用名称:建议命名为
OpenClaw 助手 以便识别
- 应用描述:基于 OpenClaw 的 AI 助手
- 应用图标:上传清晰的 Logo 图片
获取应用凭证
在应用详情页找到 AppID 和 AppSecret。这两个凭证至关重要,请务必妥善保管,一旦泄露需重新创建应用。
{
"appId": "your_app_id_here",
"appSecret": "your_app_secret_here"
}
开通权限
在「权限管理」中,根据功能需求开通相应权限。核心权限包括:
| 权限名称 | 说明 | 必要性 |
|---|
| im:message | 发送和接收消息 | ⭐ 必选 |
| im:chat | 群组管理 | ⭐ 必选 |
| im:contact | 联系人读取 | ⭐ 必选 |
| doc:document | 云文档读写 | 🔸 可选 |
| drive:file | 云空间文件 | 🔸 可选 |
配置事件订阅
Webhook URL 配置
https://your-domain.com/api/feishu/webhook
订阅事件
im:message:接收消息事件
im.chat:群组事件
发布应用
提交审核(企业自建应用通常无需审核),设置可见范围为全体成员或指定部门。版本管理建议标注版本号如 v1.0.0。
OpenClaw 配置
配置文件结构
openclaw/
├── .env
├── apps/
│ └── feishu/
│ └── config.ts
└── extensions/
└── feishu/
└── src/
├── client.ts
├── accounts.ts
└── types.ts
环境变量配置
FEISHU_APP_ID=your_app_id
FEISHU_APP_SECRET=your_app_secret
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_WEBHOOK_PATH=/api/feishu/webhook
FEISHU_VERIFICATION_TOKEN=your_token
飞书配置文件
在 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: {
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',
},
};
账号配置
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',
},
];
核心配置详解
连接模式配置
WebSocket 模式(推荐)
实时双向通信,适合高并发场景。注意心跳间隔和重连策略:
const wsConfig = {
connectionMode: 'websocket',
heartbeatInterval: 30000,
reconnectInterval: 5000,
maxReconnectAttempts: 10,
};
Webhook 模式
被动接收消息,适合无公网 IP 或防火墙限制的环境:
const webhookConfig = {
connectionMode: 'webhook',
path: '/api/feishu/webhook',
methods: ['POST'],
};
消息类型支持
const supportedMessageTypes = [
'text',
'image',
'file',
'audio',
'video',
'rich_text',
'card',
'interactive',
];
消息发送配置
发送富文本消息时需注意内容长度限制,超过阈值建议拆分:
export interface FeishuMessageInfo {
messageId: string;
chatId: string;
senderId?: string;
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 },
],
},
}),
});
};
群组策略配置
群白名单配置
export const groupPolicy = {
allowlist: {
enabled: true,
mode: 'whitelist',
matchSource: 'id',
allowedGroups: ['oc_xxxxxxxxxxxxx'],
matchRules: {
namePatterns: ['AI-*', '测试群'],
},
},
defaultPolicy: {
allowed: true,
responseMention: true,
typingIndicator: true,
},
};
群组功能开关
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,
},
};
权限控制
export const userPermissions = {
admins: ['ou_xxxxxxxxxxxxx'],
user: {
canUse: true,
dailyLimit: 100,
canUpload: true,
maxFileSize: 10 * 1024 * 1024,
},
anonymous: {
canUse: false,
},
};
功能测试
基础功能测试
- 私聊对话:搜索机器人并发起对话,发送测试消息如'你好,OpenClaw!'
- 群组@互动:将机器人拉入群组,@机器人提问,观察回复是否正常
高级功能测试
- 飞书文档操作:尝试读取或写入飞书云文档
- 文件传输:测试图片和文件的上传下载功能
测试用例表
| 测试项 | 测试步骤 | 预期结果 |
|---|
| 私聊对话 | 发送'你好' | 回复欢迎语 |
| 群组@互动 | @机器人提问 | AI 回复 |
| 文档读取 | 请求读取文档 | 返回文档内容 |
| 文档写入 | 添加内容 | 内容成功添加 |
| 图片发送 | 发送图片 | 图片正常显示 |
| 文件上传 | 上传文件 | 文件上传成功 |
| 断线重连 | 断开网络后重连 | 自动重连成功 |
| 高频测试 | 连续发送 10 条 | 全部正常回复 |
常见问题
Q1: WebSocket 连接失败?
检查网络连通性、防火墙设置及端口监听情况。开启调试日志查看具体错误:
ping open.feishu.cn
sudo ufw status
netstat -tlnp | grep 443
FEISHU_LOG_LEVEL=debug pnpm dev
Q2: 消息发送失败?
常见原因包括消息过长或频率超限。飞书默认限制 60 条/分钟,建议添加重试机制:
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: 机器人无响应?
- 确认机器人状态:
curl http://localhost:3000/api/feishu/status
- 检查事件订阅:
curl http://localhost:3000/api/feishu/events
- 查看运行日志:
tail -f logs/feishu.log
Q4: 权限不足?
确认已开通所有必要权限,应用已发布且用户可见范围包含当前用户。
Q5: 文档操作失败?
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('文档无写入权限');
};
进阶技巧
多账号配置
export const multiAccount = {
accounts: [
{ name: '飞书', domain: 'feishu', config: feishuConfig },
{ name: 'Lark', domain: 'lark', config: larkConfig, enabled: false },
],
loadBalancing: 'round_robin',
};
自定义消息卡片
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 助手回复**' } }] },
{ tag: 'action', actions: [{ tag: 'button', text: { tag: 'plain_text', content: '继续对话' }, type: 'primary', action_id: 'continue_chat' }] },
],
},
}),
});
};
消息缓存策略
export const messageCache = {
enabled: true,
maxSize: 1000,
ttl: 3600,
strategy: 'lru',
};
性能优化
export const performance = {
maxConcurrent: 10,
queueSize: 100,
batching: { enabled: true, maxBatchSize: 10, maxWaitTime: 100 },
pool: { min: 2, max: 10 },
};
日志与监控
export const logging = {
level: 'info',
format: 'json',
outputs: [
{ type: 'console', level: 'info' },
{ type: 'file', level: 'info', path: './logs/feishu.log', rotation: 'daily' },
],
};
总结
配置 OpenClaw 飞书机器人主要涉及以下步骤:
- 创建飞书企业应用并获取凭证
- 开通必要权限并发布应用
- 配置环境变量与连接模式
- 设置群组白名单与权限控制
- 执行功能测试验证稳定性
遵循上述流程,即可快速搭建一个稳定可靠的企业级 AI 助手。
相关免费在线工具
- RSA密钥对生成器
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
- Mermaid 预览与可视化编辑
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
- 随机西班牙地址生成器
随机生成西班牙地址(支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选),支持数量快捷选择、显示全部与下载。 在线工具,随机西班牙地址生成器在线工具,online
- Base64 字符串编码/解码
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
- Base64 文件转换器
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
- Markdown转HTML
将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML转Markdown 互为补充。 在线工具,Markdown转HTML在线工具,online