上周我们团队在飞书里正式上线了一个 Clawdbot,现在群里直接 @ 它,就能让它帮忙查日志、写周报、跑代码片段,甚至接一条命令去调内部接口。整个部署过程从飞书开放平台创建应用,到 Ubuntu 服务器上把服务拉起来,再到把消息链路调通,踩了不少坑。这篇就把完整部署流程、关键代码和排错经验一次性写清楚,给准备把 Clawdbot 接进飞书(飞连)的读者一个可以直接照着做的参考。
先说清楚一件事:如果你只是想快速搞一个问答机器人,Coze 这类平台也能一键发布到飞书,没必要自己折腾。但 Clawdbot 是自托管的方案,代码、上下文、工具链全在你手里,适合把机器人做成团队基础设施的场景。它能读群消息、能回单聊、能跑自定义工具,甚至能接定时任务。这篇教程覆盖部署、配置、踩坑三个部分,单聊群聊都讲,适合有一定命令行基础但没做过飞书应用开发的人。
1. 为什么非要把 Clawdbot 塞进飞书
1.1 团队协作环境里的 AI 助手,入口很重要
我们团队日常所有协作都在飞书(飞连)里完成,之前也有同事用网页版 Claude、命令行工具,但问题是:这些工具不在你工作流里,每次切过去都要重新粘贴上下文,消息记录也没法和项目讨论保持在同一个地方。把 Clawdbot 部署到飞书之后,所有交互都发生在群聊或者单聊窗口里,消息记录随飞书走,手机端也能用,体验完全不一样。
另外一个隐藏价值是"上下文聚合"。在群聊里 @ 机器人,它能看到当前群的上下文,知道大家在讨论什么。比如研发群里有人说"刚才线上接口报错那个问题排查一下",Clawdbot 可以直接理解这是哪条线上问题,而不是像网页版那样什么都不记得。这种"长在 IM 里"的交互方式,比单独开一个聊天窗口自然得多。
1.2 自托管与平台型智能体的取舍
Coze 智能体接入飞书确实省事,不用维护服务器,点几下就发布。但实际用下来你会发现几个问题:平台侧的 prompt 编排和工具链是封闭的,想接入公司内部接口、数据库、私有知识库都很麻烦;数据全过第三方平台,敏感信息不敢往里放。
Clawdbot 这类自托管方案的优势正好补上这些短板:模型 API 由你自己配置,可以接 Anthropic 官方接口,也可以接任意 OpenAI 兼容的模型服务(比如 DeepSeek),数据流完全可控;工具调用支持自定义脚本,团队内部的服务可以通过它统一暴露成自然语言入口。代价就是部署和运维需要花点时间,但一次搭好,长期受益。
1.3 这篇教程适合谁来读
如果你是团队里负责基础设施的工程师、想给工作群加一个 AI 助手的个人开发者,或者正在评估飞书机器人方案的架构师,这篇都适用。下面从飞书开放平台配置开始,一步一步写。基础要求是:会 Linux 基本命令、能读懂 Node.js 代码、有服务器部署权限。不用提前了解飞书开放平台,我尽量把每个操作对应的"为什么"也讲清楚。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 动手之前先理清这套架构的三个核心概念
2.1 Clawdbot 到底是什么:事件网关、会话管理、工具执行器
Clawdbot 这个名字里的 Clawd 是 Claude 的社区昵称,所以它本质上是把 Claude 系列模型能力包装成 IM 机器人的一个服务。从架构角度看,它做三件事:
第一,事件网关。它监听飞书推送过来的消息事件,解析出文本、发送者、群 ID 这些信息。第二,会话管理。它维护每个用户或每个群的多轮对话历史,调用模型时把历史一起拼接进去,这样机器人才能"记得"上下文。第三,工具执行器。遇到模型想调用工具时,它负责执行本地脚本、HTTP 请求,再把执行结果返回给模型,让模型继续生成回复。
模型后端是可插拔的。Clawdbot 官方默认走 Anthropic 的接口规范,但大多数实现也支持 OpenAI 兼容协议。如果你手里的模型服务是 DeepSeek、自托管模型或者其他兼容网关,只要在配置里把 MODEL_PROVIDER 切到 openai-compatible,填上对应的 API Key 和模型名就行。这也是自托管方案最灵活的地方。
2.2 飞书机器人如何收到消息:事件订阅是核心开关
飞书机器人本质上是一个"企业自建应用",它靠事件订阅机制接收消息。你在飞书开放平台后台创建一个应用,开启机器人能力,然后订阅 im.message.receive_v1 这个事件。之后,用户给机器人发消息、或者在群里 @ 机器人,飞书服务器就会把这条消息推送到你配置的回调地址,或者通过 WebSocket 长连接推送到你的服务。
这里有两个接收通道:Webhook 模式需要你的服务器有一个公网可访问的 HTTPS 地址,飞书服务器会把事件 POST 到这个地址;长连接模式则是你的服务主动和飞书服务器建立 WebSocket 连接,不需要公网回调地址。我强烈推荐长连接模式,它是较新的方案,不用处理回调地址暴露在外网的安全风险,也不用担心内网环境回调不到的问题,部署难度低很多。
2.3 一条消息从群聊到 Clawdbot 再回到群聊的完整链路
为了后面排查问题方便,先记清楚这条链路。假设你在群里发了一条"@Clawdbot 帮我看一下 Nginx 日志",它的生命周期是这样的:
- 飞书客户端把消息发到飞书服务器。
- 飞书服务器根据事件订阅配置,把
im.message.receive_v1事件推给 Clawdbot 服务(长连接或 Webhook)。 - Clawdbot 服务校验事件有效性,提取消息文本和会话信息。
- Clawdbot 把文本拼上对话历史,发给模型 API,模型返回回复。
- Clawdbot 调用飞书开放平台的"发送消息" API,把回复发到同一个聊天会话里。
关键点在第 2 步到第 5 步之间。飞书对于 Webhook 推送有超时要求,建议 3 秒内返回 HTTP 200,所以工程师的通用做法是:先立刻返回 200 确认收到,再异步去调模型、发消息。长连接模式没有明确的超时限制,但同样建议用异步处理,避免事件堆积阻塞。这条链路是后面所有逻辑的基础,记住它,后面看代码就不乱了。
3. 飞书开放平台侧配置:应用、权限、事件订阅
3.1 创建企业自建应用
打开飞书开放平台,进入开发者后台,点击"创建企业自建应用"。应用名称最好带个容易辨认的后缀,比如"Clawdbot 助手",图标随便传一个,审核主要看名称是否规范,不会卡太严。创建完成后,进入应用详情页。
这里有个刚接触的人容易懵的点:飞书开放平台有"企业自建应用"和"商店应用"两种。自建应用只给当前企业用,审核流程短;商店应用要上架审核,不需要。我们做内部工具,一律选企业自建应用。
3.2 开启机器人能力,配置权限
在应用详情页左侧菜单找到"添加应用能力",选择"机器人",启用后你的应用就拥有了机器人身份。接着在"权限管理"页面配置权限。这是最关键的一步,权限没配上,后面事件订阅验证成功也收不到消息。
需要配的权限清单如下:
| 权限标识 | 用途 |
|---|---|
im:message |
获取消息内容的基本权限,必开 |
im:message.p2p_msg |
读取单聊消息,用于处理用户私聊机器人 |
im:message.group_at_msg |
读取群聊中 @ 机器人的消息,群聊场景必开 |
im:chat |
获取群基础信息,用于知道消息来自哪个群 |
im:resource |
如果要接收图片、文件等附件,需要这个权限 |
contact:user.base:readonly |
可选,用于获取发送者姓名等用户信息 |
权限申请后,有的需要管理员审核。自建应用一般企业管理员在后台点一下就行。
3.3 配置事件订阅:推荐长连接模式
在"事件与回调"页面,选择事件订阅方式。如果你不想处理公网回调地址,就选"使用长连接接收事件"。选了长连接之后,你的服务端只需要用官方 SDK 启动一个 WebS
