飞书AI机器人实战：用长连接加大模型API打造群聊智能助手

1. 先说结论：个人AI助手接进飞书到底怎么玩

最近我把一个开源的个人AI助手框架接进了飞书，挂上免费额度的大模型API，现在在群里直接@机器人就能让它总结文章、写周报、查资料，甚至定时推送每日待办。整套玩法的核心步骤其实只有三步：在飞书开放平台创建一个带机器人能力的应用，用长连接模式接收群聊消息事件，再把消息转发给大模型API拿结果回传到群里。跑通之后，体验确实称得上“爽用”两个字，因为你日常工作的IM窗口突然变成了一个随时在线的AI入口，不需要打开网页控制台，不需要切窗口，群里一句话就有响应。

这个项目最初的代号叫Openclaw，为了避免和市面上同名产品混淆，下文统一用“助手框架”来称呼它。我写这篇文章的目的，是把从零到一接通的完整过程、选型理由和踩坑记录一次性讲清楚。文章适合三种人看：想给团队或自己搭一个飞书AI机器人的开发者，正在纠结免费大模型API怎么选型的朋友，以及只看过官方文档但还是不知道怎么把事件订阅跑通的新手。如果你已经有一定Python基础，哪怕只是写过几个脚本，跟着这篇文章走一遍，基本能在一个晚上把机器人跑起来。

先说它能解决什么问题。IM已经成了大多数人的办公主战场，但AI能力往往停留在网页端、客户端或者命令行里，和日常工作场景是割裂的。你要么把内容复制到另一个窗口，要么把结果再粘贴回来，这个往返过程非常消耗耐心。把助手框架接进飞书之后，等于把AI能力直接嵌入了消息流：群里抛一个链接，机器人返回摘要；问一个技术问题，机器人直接给出可执行的步骤；甚至定时任务也能在群里完成。这种形态最大的价值不是“有一个机器人”，而是“AI离你正在做的事更近了”。

不过也得说清楚，它不是万能的。免费API有配额限制，模型能力也有天花板，复杂推理和长文档处理还是需要专业工具。如果你指望它完全替代付费方案，那可能会失望。但如果只是日常问答、信息整理、轻量自动化，这套组合是目前性价比最高的玩法之一。

1.1 项目定位：一个可扩展的消息中转中枢

助手框架本质上不是一个现成的聊天机器人，而是一个消息处理中枢。它做的事情很纯粹：监听飞书群里的事件，解析消息内容，按规则分发到不同的处理模块，再把结果通过飞书API发回去。这种设计的最大好处是扩展性极强。你可以在不碰消息链路的情况下，往框架里加各种处理器——接大模型API只是其中的一种，你还可以接定时任务、接搜索接口、接内部工具，这让它从一个聊天机器人慢慢长成个人助理。

我见过很多开发者一开始就把所有逻辑堆在事件回调里，结果代码越写越乱。助手框架的思路是分层：接入层只负责“收到消息”和“发送消息”，业务层才处理“这句话该干什么”。这个设计看起来很基础，但对于个人项目来说足够清晰，后续加功能非常顺手。如果你准备长期维护这个机器人，我强烈建议一开始就按这个思路组织代码，而不是图省事把所有东西塞到一个文件里。

1.2 解决的真实痛点：AI能力的“最后一公里”

很多AI工具的问题不是能力不够，而是到达路径太长。网页端的AI助手要打开浏览器、登录账号、输入提示词；本地部署的模型又要维护环境、处理依赖。这些步骤单独看都不麻烦，但叠加起来就构成了使用门槛。而IM机器人把路径压缩成了一句话：你在飞书里@它，然后等结果。这个交互模型极其自然，因为它复用了一个你已经高频率使用的窗口，不需要任何新的学习成本。

另一个痛点是信息聚合。工作群里每天有大量链接、文件、讨论，这些内容散落各处，没有汇总。接入大模型API之后，机器人可以做到“丢个链接给它，它把网页内容读出来总结给你”；“把这段会议纪要贴给它，它整理成待办列表”。我在实际使用中感受最深的就是这一点：以前每天要花不少时间浏览和摘录信息，现在群里说一声就有人帮你处理了，这种体验变化是实打实的。

2. 选型思路：为什么是长连接模式加免费API的组合

动手之前，先把选型逻辑讲透。这个组合不是随便选的，每一个决定背后都有现实约束，理解了这些，你后续遇到问题才不会慌。

2.1 飞书机器人接入模式：长连接为什么更省心

飞书开放平台提供两种主流的事件接收方式：一种是传统的Webhook回调，需要你有一个公网HTTPS地址，飞书把事件POST到你的服务器；另一种是长连接模式（WebSocket），你的服务主动连上飞书的网关，事件通过长连接推下来。

两种模式我用过后，直接推荐长连接。原因很现实：个人开发环境下，公网回调要处理域名、HTTPS证书、反向代理、端口开放一堆事情，任何一个环节出问题都会导致收不到消息。而长连接只需要你的服务器能主动访问飞书网关，不需要任何入站端口，部署起来极其简单。调试的时候也舒服，本地起一个服务就能连上，不依赖外网穿透。

这里有个小提醒：长连接模式下，你的事件订阅地址可以不用配，但应用的权限和事件仍需要在后台声明好，否则飞书网关不会把对应事件推给你。我在初次接入时就因为漏掉了“接收消息”的事件声明，连接建立得很正常，却一条消息都收不到，排查了半天。

2.2 免费大模型API的挑选标准：不是所有“免费”都值得用

市面上号称免费的大模型API不少，但质量参差不齐。我的筛选标准是四条：有合法合规的公开服务协议、有明确的免费额度说明、上下文长度够用、接口兼容性好。优先考虑那些云厂商提供的限时免费额度和开源模型服务商提供的免费体验资源，这些都是正规渠道，不需要任何特殊网络环境就能访问，数据走公开接口，风险可控。

具体看参数的时候，重点关注三个：每日请求次数限制、单次请求的上下文长度、响应速度。个人聊天场景下，日请求几百次基本够用；上下文长度低于8K的，遇到长文档总结容易截断；响应速度超过20秒的，飞书端体验会很差，因为用户等太久会以为机器人坏了。我在选型时就淘汰过好几个看起来额度很大、但响应速度慢得离谱的接口，实测下来“稳定快速”比“额度大”重要得多。

2.3 整体数据流：一条消息从群聊到大模型再回来的路径

把整条链路拆开看，消息的旅程是这样的：你在飞书群里@机器人并输入文字，飞书服务器收到后，通过长连接把一条事件推送到你的服务；你的服务解析出用户ID、群ID、消息内容，去掉@占位符后，拼成一段请求发给大模型API；大模型返回文本结果后，服务调用飞书消息回复接口，把结果发到同一个会话里。整个过程看起来复杂，但实际上就是一个“接收-处理-回复”的三段式管道。

这里最关键的点是“回复”这一步。飞书的事件推送只是通知你“有人发了消息”，它不要求你同步返回内容。你可以先立即给飞书返回一个空响应表示收到，然后异步处理完再主动调用消息接口把结果发回去。这个设计给耗时操作留了很大空间，也是长连接模式调试时最需要注意的地方：如果你在事件回调里同步调用大模型API，很容易超过网关的响应超时时间，导致消息丢失或重复推送。

3. 动手实操：从创建应用到跑通第一条回复

这一部分我按完整的实操顺序写，你照着一步步来就行。我假设你有一台能联网的服务器或本地开发机，装了Python 3.9以上版本，其他依赖我们现场装。

3.1 前置准备清单

实际操作之前，先把材料备齐，能省很多来回切换的麻烦。你需要准备：一个飞书账号，用于登录开放平台；一个能持续运行Python服务的环境，本地开发可以先用电脑跑，长期运行建议放到云服务器上；一个可用的大模型API地址和对应的密钥，先准备好一个能返回文本的接口就行，后面再调优。

依赖安装很简单，只需要两个库：飞书官方Python SDK和requests。SDK负责长连接和API调用，requests用来请求大模型接口。我个人没有用第三方的消息框架，因为飞书官方SDK已经足够简洁，再加一层封装反而增加排查难度。

pip install lark-oapi requests

3.2 创建飞书应用并开启机器人能力

登录飞书开放平台，进入开发者后台，创建一个企业自建应用。应用创建完之后，在“应用能力”页面找到“机器人”并启用，这一步会为你的应用生成一个机器人身份，之后它就能在群里被@了。然后进入“凭证与基础信息”页面，记下App ID和App Secret，这两个凭证是后续所有API调用的身份标识，要像保管密码一样对待。

接下来配置权限。在“权限管理”页面开通两个关键权限：一个是“接收消息”相关的事件权限，用于监听群聊消息；另一个是“发送消息”或“回复消息”的权限，用于把结果发回群里。不同的权限名称在后台叫法略有差异，你搜索“消息”关键词，把读消息、发消息相关的权限都开通即可。这一步容易踩坑的是：开了权限之后，需要在“事件与回调”页面重新订阅事件，新权限才会生效。

3.3 配置事件订阅：选择长连接模式

进入“事件与回调”页面，在“事件订阅”区域添加事件。最关键的一个事件是接收消息，对应的标识通常是im.message.receive_v1。添加完成后，选择使用长连接模式接收事件。如果你在后台看到了“请求地址URL”的输入框，说明当前是Webhook模式，要切换成以长连接方式接收事件，同时不需要再填URL。

长连接模式的原理实际上是一个WebSocket客户端，你的服务启动后会连上飞书网关并保持在线。SDK内部会处理心跳、重连和事件分发，你不需要关心底层协议细节。但有一点要注意：长连接模式下，本地调试非常方便，可一旦服务重启，连接会断开并自动重连，如果重连期间有消息进来，飞书网关可能会尝试重推或直接丢弃，所以长期运行一定要配合守护进程使用。

3.4 消息处理核心代码：从收到事件到调用大模型

下面是一段简化但能跑通全流程的Python代码，实现了“收到@机器人的文本消息后，调用大模型API，把结果回复到群里”。这段代码我按最小可用原则写的，没有做复杂的模块拆分，方便你理解整条链路。

import json import os import requests import lark_oapi as lark from lark_oapi.api.im.v1 import * APP_ID = os.getenv("FEISHU_APP_ID") APP_SECRET = os.getenv("FEISHU_APP_SECRET") LLM_API_URL = os.getenv("LLM_API_URL") LLM_API_KEY = os.getenv("LLM_API_KEY") def call_llm(prompt: str) -> str: headers = {"Authorization": f"Bearer {LLM_API_KEY}", "Content-Type": "application/json"} payload = { "model": "your-model-id", "messages": [{"role": "user", "content": prompt}], "temperature": 0.7, } resp = requests.post(LLM_API_URL, json=payload, headers=headers, timeout=30) resp.raise_for_status() data = resp.json() return data["choices"][0]["message"]["content"] def do_reply(tenant_access_token: str, message_id: str, content: str): client = lark.Client.builder() \ .app_id(APP_ID) \ .app_secret(APP_SECRET) \ .log_level(lark.LogLevel.INFO) \ .build() request = ReplyMessageRequest.builder() \ .message_id(message_id) \ .request_body(ReplyMessageRequestBody.builder() .content(json.dumps({"text": content})) .msg_type("text") .build()) \ .build() response = client.im.v1.message.reply(request) if not response.success(): print(f"回复失败: {response.code} {response.msg}") def handle_message(event): message = event.event.message if message.message_type != "text": return content = json.loads(message.content) raw_text = content.get("text", "") # 去掉 @ 占位符，例如 "@_user_1" for mention in event.event.mentions or []: key = mention.key raw_text = raw_text.replace(key, "").replace("@_user_1", "") user_input = raw_text.strip() if not user_input: return try: answer = call_llm(user_input) do_reply(None, message.message_id, answer) except Exception as e: do_reply(None, message.message_id, f"处理出错: {e}") def main(): client = lark.Client.builder() \ .app_id(APP_ID) \ .app_secret(APP_SECRET) \ .log_level(lark.LogLevel.INFO) \ .build() handler = lark.EventDispatcherHandler.builder( "", "" ).register_p2_im_message_receive_v1(handle_message).build() client.im.v1.message.dispatcher = handler client.start() if __name__ == "__main__": main()

这段代码有几个细节值得说明。首先是消息解析：飞书事件里的message.content是一个JSON字符串，文本类型的消息body里有一个text字段，但实际内容会包含@占位符，比如@_user_1。如果直接用完整文本提问，模型会看到一堆奇怪的占位符，所以要先去掉。其次是回复消息：我用了reply接口，它的效果是在原消息下回复一条，用户能清楚看到机器人回应的是哪条消息，这个交互体验比单独发一条新消息更自然。

还有一个容易被忽略的点：长连接启动时，事件处理器注册的写法一定要和SDK版本匹配。不同版本的lark_oapi在事件注册方式上略有差异，如果你用的版本和我的不完全一样，以你安装版本对应的官方示例为准。我一开始就是因为SDK版本升级后方法名变了，照着老代码抄导致事件一直没注册上。

3.5 大模型API接入细节：请求格式和响应解析

大模型API的接口格式并不统一，有些是OpenAI兼容格式，有些是自定义格式。我建议优先选那种兼容OpenAI的接口，因为生态工具多、文档齐全、代码示例好找。OpenAI兼容格式的请求体一般是传入模型名和消息列表，响应体在choices数组里，取第一个元素的message.content就是生成的文本，上面的代码就是按这个格式写的。

实际调试中，最常见的坑是鉴权头格式不对。有的服务商要求Authorization: Bearer <key>，有的要求自定义头部，还有的要在请求体里带上密钥。我建议先写一个几行的测试脚本，把接口调通了再往下走，不要直接集成到机器人主逻辑里。我习惯的做法是先用curl验证接口返回正常，再封装成函数，这样可以隔离“接口问题”和“代码问题”。

另外，大模型API的超时时间一定要设置。飞书场景下用户大可忍受的等待时间大概在10到30秒，超过这个范围体验就很差了。我通常给请求设置30秒超时，然后做一层超时重试：第一次超时就重试一次，如果还是失败，就回复一句“当前服务繁忙”而不是让用户干等。

3.6 部署到服务器：用systemd保住进程

本地调试跑通之后，就要考虑长期运行的问题。我见过太多人用nohup python挂后台，结果服务器一重启进程就没了，机器人就悄悄下线。正确的做法是把服务注册成systemd服务，让操作系统帮你守护进程，崩溃自动拉起，开机自动启动。

下面是一个最简的systemd服务配置，把其中路径替换成你的实际路径：

[Unit] Description=Feishu AI Bot After=network.target [Service] User=your_user WorkingDirectory=/opt/feishu-bot Environment="FEISHU_APP_ID=your_app_id" Environment="FEISHU_APP_SECRET=your_app_secret" Environment="LLM_API_URL=your_llm_url" Environment="LLM_API_KEY=your_llm_key" ExecStart=/usr/bin/python3 /opt/feishu-bot/main.py Restart=always RestartSec=5 [Install] WantedBy=multi-user.target

环境变量千万要直接写在服务文件里，更稳妥的做法是用EnvironmentFile指定一个权限严格的文件，比如/etc/feishu-bot.env，这样主服务文件不用保存敏感信息。配置好之后依次执行systemctl daemon-reload、systemctl start feishu-bot、systemctl enable feishu-bot，然后看一下运行状态：systemctl status feishu-bot。如果日志里显示长连接已建立，那就说明部署成功了。

4. 调优实测：从“能回话”到“真的好用”

机器人能回话只是起点，实际好用才是重点。我在连续用了一周之后，逐步打磨了几个细节，现在把效果和做法一起分享出来。

4.1 第一轮实测：裸奔状态的表现

刚跑起来时，我用最简单的提示词让机器人回答问题。它确实能回，但问题很明显：回答太短，没有结构；你问一个开放性问题，它只丢两行字；让它总结会议纪要，它只给你一句话概括。这种状态在群里给同事用，大概率会被吐槽。所以第一件事不是调模型参数，而是优化提示词。

我把系统提示词改成了更具体的角色设定，比如这样的模板：你是一个懂技术的助手，回答问题时先给结论，再补充步骤；如果信息不足，直接说明不知道，不要编造；尽量用列表呈现操作步骤。这个简单的改变立竿见影，回答的可用性提升了一截。这里也说明一个重要问题：大模型的能力固然重要，但提示词决定了它输出的格式和风格，后者对用户体感的影响往往更大。

4.2 上下文管理：别让机器人“失忆”

默认情况下，每次调用大模型API都是独立的，机器人没有记忆。你上一句问它“帮我梳理一下这个项目的背景”，下一句问“那核心难点呢”，它完全不记得。要让对话连贯，就得自己维护上下文。最简单的方式是把最近的几轮问答拼进请求里，一起发给模型。

我在实现时给每个会话维护了一个长度为6的滑动窗口：保留最近3轮用户输入和3轮机器人回复，超出部分丢弃。这样既不会烧太多token，又能保证短时对话的连贯性。注意这里的会话不是按群来分的，而是按用户ID来分，否则群里不同人聊天会串味。实现上可以用一个全局字典存会话历史，进程重启后会清空，对于个人机器人来说完全够用。

4.3 并发、限流和错误兜底：稳定性才是“爽用”的关键

免费API最大的毛病就是限流，一旦短时间请求过多，接口会返回429或者直接拒连。我在实际使用中遇到过好几次：白天用的人多，请求密集时，机器人突然就不回消息了。排查下来不是服务挂了，而是API被限流，请求全部超时。解决思路是加一个本地的请求队列，把调用模型的操作变成串行的，限制每秒最多1到2个请求，超出就排队。这样单用户场景感受不到差异，但能明显降低限流概率。

错误兜底还有一个容易被忽视的点：大模型返回的内容里可能有换行、特殊字符，直接塞进飞书文本消息里时，显示格式可能乱掉。我后来发现把长回复按空行拆成段落再发，阅读体验会好很多。如果内容超过飞书单条消息的长度限制，就拆成多条消息依次发送。这些细节单独看都不起眼，但合在一起决定了用户愿意不愿意持续使用。

5. 高频问题排查：机器人为什么不理我

跑了一个多月，我把遇到过的典型问题整理了一份排查表，按“现象-原因-解法”的格式写在这里。你会发现大部分问题的根源就是身份认证、权限声明和消息格式这三个方向。

5.1 机器人完全不回复：先查连接和权限

机器人收不到消息时，先看进程是否还活着，再看日志里有没有长连接建立成功的记录。如果连接没有建立，大概率是App ID或App Secret不对，或者后台没有启用机器人能力。如果连接是正常的但收不到消息，优先检查事件订阅：有没有添加接收消息事件，权限是不是真的开通了。这里有个细节，修改权限或事件后，有时需要等待一两分钟让配置生效，别急着反复重启服务。

我遇到过一种很隐蔽的情况：开发者在后台配置了事件，但用的是旧版本SDK，事件注册代码没生效，服务日志里一条事件都没打印。遇到这种情况，先在后台的事件订阅页面查看“事件推送调试”功能，它可以手动模拟一条消息事件推给你配置的地址。如果是长连接模式，SDK客户端会收到并打印日志，这样就能判断消息到底有没有到达你的服务。

5.2 机器人提示“无权限”或回复失败：多半是密文明文问题

飞书要求部分接口传的消息内容不能是明文的。很多开发者在调用发送消息接口时，直接把JSON字符串作为content传进去，结果报错。正确做法是看接口要求的content_type，如果是text，需要传一个JSON编码后的字符串，例如json.dumps({"text": "hello"})，而不是直接传"hello"。这个错误我在刚开始接入时踩过一次，飞书SDK报的错信息又不够直观，排查了好一阵。

另一个和权限相关的问题是：机器人尝试给不是它所在群的会话发消息，或者给没有加入的群发消息，会被拒绝。个人使用场景下，建议先把机器人拉进一个测试群，用测试群跑通所有功能，再考虑扩大范围。别一上来就想着全公司部署，风险太大。

5.3 回复很慢或超时：别同步调用大模型

飞书长连接模式下，事件回调如果长时间不返回，网关可能判定处理超时并重推事件，导致你的服务重复处理同一条消息，用户会看到机器人回复了两遍甚至三遍。我的做法是：事件处理器里只做消息存储和快速应答，把真正的大模型调用放到另一个线程或进程里去执行，处理完成后再调用消息接口发出去。这样回调毫秒级返回，彻底告别超时问题。

如果还是觉得慢，就检查大模型API的响应时间。免费接口在高负载时段反应慢是常态，可以在请求里设置更高的超时容忍度，同时把系统的提示词精简一些，太长的Prompt会明显增加响应延迟。实测下来，把系统提示词控制在100字以内，比堆一大段规则要快不少。

5.4 安全和合规：这条必须单独说

既然是接进办公IM的机器人，安全这根弦得绷紧。首先，不要在群聊里处理敏感数据，因为你无法控制谁在群里看到了机器人的回复；涉及个人信息、密钥、合同内容的对话，一律不要发给外部大模型API。其次，API密钥、App Secret这些凭证不要出现在代码仓库里，哪怕私有仓库也不要，环境变量是比较稳妥的存放方式。最后，要遵守飞书开放平台和所选大模型API的服务条款，只使用合法合规的渠道和权限，不要试图绕过平台的限制。这个意识从第一天就要有，等出了问题再补就晚了。

我还建议给机器人加一层使用范围限制：在代码里配一个允许使用机器人的用户ID或群ID白名单，非白名单内的消息一律不处理。这样做不是为了防自己人，而是防止机器人被恶意刷量导致API配额耗尽，或者被人用来测试一些不合适的内容。成本几乎为零，但能挡掉很多麻烦。

6. 后续扩展：个人助理的更多玩法

基础对话跑通之后，我开始往框架里加各种插件式功能。得益于前面的分层架构，加功能基本不碰消息链路，只在业务处理层做文章。

6.1 定时消息：让机器人每天主动汇报

配合一个定时任务库，机器人可以在每天早上固定时间往指定群里推送日报：今日天气、待办提醒、昨日项目进度摘要等。实现上很简单：定时触发后，机器人调用大模型API生成内容，再主动调用发送消息接口推送到群里。这个功能非常适合个人使用，相当于给自己配了一个每天早上准时上班的助理。

需要注意一点：定时任务服务要和飞书长连接服务跑在同一个进程里，避免出现两个进程互相抢占资源的问题。我最初把它们拆成了两个服务，结果本地调试没问题，部署到服务器后因为环境变量不一致，定时任务老是找不到API密钥。后来合并到一个进程，全局共享配置，问题就消失了。

6.2 知识库问答：把个人笔记变成私域问答

如果你积累了不少技术文档和笔记，可以把它们导出成文本文件，做一个最简版的知识库问答。做法是：把文档切成小块，建立关键词索引；用户提问时，先在本地用简单的文本检索把最相关的几个片段找出来，然后把问题加片段拼进Prompt，让大模型基于这些材料回答。这个方法不依赖向量数据库，几十个文档规模下完全够用，而且效果比直接让模型“硬答”好很多。

我实际用下来，最舒服的场景是团队内部的FAQ整理：把常见问题文档喂给机器人，群里有人问相关问题，机器人能直接从文档里找到答案并给出来源。这比让每个新人都去翻文档高效得多。缺点是文档更新后索引也要跟着更新，所以我把索引用脚本定时重建，保证内容不过期。

6.3 多模态输入：图片理解和文件摘要

如果接入的大模型API支持视觉或多模态能力，还可以扩展图片理解功能。飞书的消息事件里不直接包含图片文件，你需要先用消息ID调用接口获取图片资源，下载到本地再转成Base64或按API要求的格式传给模型。这个链路稍微长一点，但效果很惊艳：拍了照片发到群里，机器人能描述画面内容；截图发过去，它能读出里面的文字并总结要点。文件摘要功能同理，先用飞书接口下载文件，再用处理脚本提取文本，最后交给大模型总结。

不过多模态功能对免费API的消耗通常更大，配额消耗速度比纯文本快很多。我的建议是先做好文本场景，确认稳定够用之后再考虑多模态，别一上来把免费额度全烧在图片理解上。

这个项目我前后折腾了大概两个周末，最值钱的经验就是先把消息链路彻底跑通，再考虑花哨的功能。很多新手一上来就想着多模态、知识库、定时任务一把抓，结果连基础回复都没调好，最后全卡在排查环境问题上。如果你也想搞一个类似的飞书AI机器人，我建议从最简版本开始：先让机器人在测试群里回一句“你好”，再把大模型接进来，最后逐步加功能。链路通了，后面的扩展都是水到渠成的事。最后再分享一个小技巧：把调试群的名字设成“机器人测试群”，然后把你的开发号也拉进群里，调试的时候直接在群里发消息看响应，比看日志直观得多。