Clawdbot飞书插件对接实战：踩坑与解决方案
Clawdbot飞书插件对接实战：踩坑与解决方案
前言
最近在给Clawdbot（一个基于Node.js的AI Bot框架）对接飞书消息渠道时，遇到了一些坑。虽然官方文档写得还算详细，但实际操作中还是踩了不少雷。这篇文章记录了我遇到的问题和最终的解决方案，希望能帮到同样在做飞书集成的开发者。
技术背景
Clawdbot简介
Clawdbot是一个模块化的AI Bot框架，支持多渠道接入（Telegram、WhatsApp、QQ、飞书等）。它的架构是：
用户消息 → 各渠道插件 → Gateway（消息网关） → AI处理 → 回复用户飞书插件负责：
- 接收飞书消息
- 转换成统一格式
- 发送回复到飞书
飞书开放平台
飞书开放平台提供了两种消息接收方式：
- Webhook模式：HTTP回调，适合有公网IP的服务器
- 长连接模式：WebSocket连接，适合内网环境
我们选择长连接模式，因为服务器在内网，没有公网IP。
踩坑记录
坑1：插件登录成功，但收不到消息
症状：
- 日志显示
[feishu:default] logged in to feishu as cli_xxx - 说明登录认证通过了
- 但在飞书发消息，Bot完全没有反应
- 日志里也没有任何消息接收记录
原因分析：
飞书插件的代码使用的是Lark SDK的WebSocket客户端：
// gateway.ts
const wsClient = new WSClient({
appID: config.appId,
appSecret: config.appSecret,
eventTypes: ['im.message.receive_v1'], // 订阅消息事件
});
wsClient.start();虽然SDK代码里订阅了 im.message.receive_v1 事件，但飞书开放平台需要手动配置订阅！
解决方案：
登录飞书开放平台
- 进入你的自建应用
- 找到"事件订阅"配置
配置订阅模式
- 订阅模式选择：长连接
- 订阅事件必须勾选：
im.message.receive_v1
关键步骤：发布应用
- 点击右上角"发布"按钮
- 选择"正式发布"
- ⚠️ 这一步容易被忽略！
重启Clawdbot
clawdbot gateway restart
验证：
# 查看日志，应该能看到连接建立
tail -f /tmp/clawdbot/clawdbot-*.log | grep feishu坑2：长连接WebSocket没有真正建立
症状：
- 配置都做了
- 应用也发布了
- 但还是收不到消息
原因：
Lark SDK的WebSocket连接建立有一些时序问题。如果SDK启动太快，飞书开放平台还没来得及处理应用发布，连接会失败。
解决方案：
在插件启动代码中添加重试逻辑：
async function startFeishuGateway() {
let retries = 3;
while (retries > 0) {
try {
await wsClient.start();
console.log('[feishu] WebSocket connected');
break;
} catch (error) {
retries--;
console.log(`[feishu] Connection failed, ${retries} retries left`);
if (retries > 0) {
await new Promise(resolve => setTimeout(resolve, 5000));
}
}
}
}坑3：消息格式转换问题
症状：
- 终于收到消息了
- 但回复时飞书报错：
invalid message format
原因：
飞书的消息格式和其他平台（如Telegram）差异很大。飞书支持多种消息类型：
- text（纯文本）
- post（富文本）
- interactive（交互式卡片）
Clawdbot统一使用 text 类型，但飞书的text类型需要特定的JSON结构。
解决方案：
在飞书插件的发送逻辑中做格式转换：
function formatMessageForFeishu(text: string) {
return {
msg_type: 'text',
content: JSON.stringify({
text: text
})
};
}最终配置清单
飞书开放平台配置
- [ ] 创建自建应用，获取App ID和App Secret
- [ ] 权限管理：添加"获取与发送消息"权限
[ ] 事件订阅：
- [ ] 订阅模式：长连接
- [ ] 订阅事件：
im.message.receive_v1
- [ ] 发布应用：正式发布
- [ ] 版本管理：记录版本号，方便回滚
Clawdbot配置
{
"channels": {
"feishu": {
"enabled": true,
"appId": "cli_xxx",
"appSecret": "your_secret_here",
"encryptKey": "", // 长连接模式可留空
"verificationToken": "", // 长连接模式可留空
"capabilities": {
"inlineButtons": "allowlist" // 按钮功能
}
}
}
}日志检查
# 查看飞书插件状态
tail -100 /tmp/clawdbot/clawdbot-*.log | grep feishu
# 应该看到：
# [feishu:default] logged in to feishu as cli_xxx
# [feishu] WebSocket connected架构图
┌─────────┐ WebSocket ┌──────────────┐
│ │ ◄──────────────────► │ │
│ 飞书 │ 长连接 │ Clawdbot │
│ server │ │ Gateway │
│ │ │ │
└─────────┘ └──────┬───────┘
│
│ 消息分发
▼
┌─────────────┐
│ AI Agent │
│ (GLM-4.7) │
└─────────────┘经验总结
- 文档要看仔细：飞书开放平台的文档很长，但"事件订阅"部分一定要逐字读完
- 发布应用别忘：这是最容易漏的一步，配置改了必须重新发布
- 日志是最好的朋友：遇到问题先看日志，能定位90%的问题
- 长连接≠即时生效：应用发布后可能需要等待几分钟才能生效
- 消息格式要统一：不同渠道的消息格式差异大，需要做好适配层
参考资源
后续优化
目前飞书渠道已经可以正常收发消息了，后续计划：
- 支持更多消息类型（图片、文件、卡片）
- 实现消息已读状态同步
- 支持群消息@机器人
- 添加飞书特有功能（如工作通知）
作者：twg2020
发布时间：2026-02-15
技术栈：Node.js、TypeScript、飞书开放平台、Clawdbot
标签：#飞书 #Bot开发 #WebSocket #Clawdbot
本文记录了实际开发中遇到的问题和解决方案，如果你也在做类似的集成，希望对你有帮助。有问题欢迎交流！