小龙虾智能体不响应飞书群消息：飞书与智能体连接问题排查与解决

企业员工在飞书外部群 @小龙虾却得不到任何响应，而发送消息、查询接口又都正常——问题往往不在AI模型，而在飞书事件订阅链路。本文梳理飞书与智能体之间的双向通信架构，从事件订阅、消息接收事件、机器人权限、公网Webhook到@消息解析逐层排查，配合日志与Trace ID定位故障，最终给出“能收、能理解、能处理、能回复”的完整闭环方案。

一、问题背景

在企业智能体应用中，可以将"小龙虾"接入飞书，让员工直接在飞书群中与智能体交流。

例如：

用户：

@小龙虾查询LA生产线当前设备状态

小龙虾：

LA生产线当前共有11台设备在线，设备运行正常。

但是实际部署过程中，经常出现一个非常典型的问题：

小龙虾可以向飞书群发送消息，也可以通过接口查询飞书消息，但是用户在飞书外部群中 @小龙虾后，小龙虾没有任何响应。

这个问题容易被误认为是：

AI模型故障
MCP故障
Token失效
网络故障
飞书API故障

实际上，最需要检查的是：

飞书是否把实时消息事件发送给了小龙虾。

二、先理解飞书与小龙虾的两条通信链路

飞书和小龙虾之间实际上存在两个方向。

1. 小龙虾主动发送消息

小龙虾
 │
 │ HTTP API
 ▼
飞书 Open API
 │
 ▼
飞书群

例如小龙虾主动通知：

LA-01设备发生报警，请及时处理。

这个方向正常，只能说明：

小龙虾 → 飞书

的通信正常。

2. 飞书主动通知小龙虾

用户在群里发送：

@小龙虾查询设备状态

通信方向变成：

飞书群
 │
 ▼
飞书事件系统
 │
 ▼
Webhook
 │
 ▼
小龙虾

这个方向属于：

飞书 → 小龙虾

如果这一条链路没有建立，那么小龙虾当然不会响应。

因此：

能够发送消息，并不能证明能够接收消息。

这是排查问题时最重要的认识。

三、正确的整体架构

小龙虾与飞书推荐采用事件驱动架构：

飞书
 │
 飞书外部群
 │
 │ @小龙虾
 ▼
 飞书事件订阅服务
 │
 │ HTTPS POST
 ▼
 公网 Webhook
 │
 ┌──────┴──────┐
 │             │
 Nginx        FRP
 │             │
 └──────┬──────┘
        ▼
 小龙虾 Gateway
        │
        ▼
 消息事件解析
        │
        ▼
 小龙虾 Agent
        │
        ▼
 飞书 Reply API
        │
        ▼
 飞书群

其中最重要的是：

飞书事件订阅
 ↓
Webhook
 ↓
小龙虾 Gateway

四、为什么外部群特别容易出现问题？

飞书内部群和外部群并不是完全相同的使用场景。

内部群通常是：

企业员工
+
机器人

而外部群可能是：

企业员工
+
客户
+
供应商
+
其他企业用户
+
机器人

因此，在测试小龙虾时：

内部群正常，并不一定意味着外部群正常。

需要特别确认机器人应用是否支持加入外部群，以及相关消息事件是否允许触发。

五、第一步：检查飞书事件订阅

进入飞书开放平台，找到小龙虾对应的应用。

检查：

应用
 ↓
事件订阅

确认已经配置事件订阅。

核心是让飞书知道：

群里发生消息以后，应该把消息发送到哪里。

例如：

https://xxx.example.com/feishu/event

这个地址就是小龙虾的消息入口。

六、第二步：检查消息接收事件

仅仅配置机器人还不够。

需要订阅消息接收事件。

重点检查：

im.message.receive_v1

它负责将飞书中的相关消息事件发送给机器人后台。

完整链路：

用户
 ↓
飞书群
 ↓
@小龙虾
 ↓
im.message.receive_v1
 ↓
Webhook
 ↓
小龙虾

如果没有订阅这个事件：

飞书群
 ↓
@小龙虾
 ↓
小龙虾

中间没有消息事件传递，小龙虾自然不会响应。

七、第三步：检查机器人权限

需要检查飞书应用的权限配置。

重点关注：

消息
机器人
事件订阅
群聊

特别是消息接收相关权限。

修改权限后，还需要注意一个经常被忽略的问题：

权限修改不代表线上应用马上使用了新权限。

通常需要：

修改权限
 ↓
创建应用版本
 ↓
发布版本
 ↓
重新测试

如果只是修改了配置，没有发布新的应用版本，实际运行的机器人可能仍然使用旧配置。

八、第四步：检查Webhook地址

如果小龙虾部署在本地服务器：

192.168.20.100:8000

不能直接把：

http://192.168.20.100:8000/feishu/event

作为飞书事件地址。

因为飞书服务器位于公网。

正确方式应该是：

飞书
 │
 │ HTTPS
 ▼
公网服务器
 │
 │ FRP
 ▼
工厂服务器
 │
 ▼
小龙虾

例如：

https://claw.example.com/feishu/event

公网服务器再通过 FRP 转发：

公网服务器
 ↓
192.168.20.100:8000

九、第五步：最关键的测试——Webhook有没有收到消息？

不要一开始就测试AI。

先测试：

小龙虾到底有没有收到飞书消息。

例如使用 FastAPI 建立一个简单Webhook：

from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/feishu/event")
async def feishu_event(request: Request):
    data = await request.json()
    print("========== FEISHU EVENT ==========")
    print(data)
    return {
        "code": 0
    }

启动：

python server.py

然后在飞书外部群：

@小龙虾测试

观察服务器日志。

十、如果完全没有收到日志

如果服务器没有任何：

FEISHU EVENT

那么可以确定：

问题还没有到小龙虾Agent。

应该检查：

飞书
 ↓
事件订阅
 ↓
Webhook URL
 ↓
HTTPS
 ↓
公网服务器
 ↓
Nginx
 ↓
FRP
 ↓
小龙虾

建议逐层测试。

首先从公网服务器测试：

curl https://claw.example.com/feishu/event

再检查 Nginx：

systemctl status nginx

检查 FRP：

systemctl status frpc

最后检查小龙虾：

8000端口是否监听

十一、如果Webhook已经收到消息

假设日志已经出现：

========== FEISHU EVENT ==========

说明：

飞书
 ↓
Webhook
 ↓
小龙虾

已经正常。

此时问题就进入下一层：

Webhook
 ↓
消息解析
 ↓
Agent

十二、外部群消息中的@信息需要正确解析

用户发送：

@小龙虾查询LA设备状态

飞书事件中的消息内容可能包含机器人提及信息。

因此不能简单地：

content = message["content"]

然后直接发送给AI。

需要进行：

消息解析
 ↓
识别机器人是否被@
 ↓
删除@机器人标记
 ↓
提取真正的问题

最终得到：

查询LA设备状态

然后：

查询LA设备状态
 ↓
小龙虾 Agent

十三、建立统一的消息处理流程

推荐小龙虾不要让Webhook直接调用AI。

采用：

Feishu Webhook
 ↓
Message Parser
 ↓
Message Router
 ↓
Agent
 ↓
Reply

例如：

async def handle_feishu_message(event):
    message = parse_feishu_message(event)
    if not message:
        return
    if not message.is_mention_bot:
        return
    question = message.text.strip()
    if not question:
        return
    answer = await agent.ask(question)
    await feishu_reply(
        message_id=message.message_id,
        content=answer
    )

这样结构更加清晰。

十四、回复应该关联原始消息

用户：

@小龙虾查询LA设备状态

飞书事件中会携带消息ID。

小龙虾应该保存：

message_id
chat_id
sender_id

然后根据：

message_id

回复。

流程：

用户消息
 │
 │ message_id
 ▼
小龙虾
 │
 ▼
AI处理
 │
 ▼
Reply message_id
 │
 ▼
飞书

这样能够保证回复与用户问题对应。

十五、增加完整日志

解决智能体"不响应"问题时，日志非常重要。

建议至少记录：

[FEISHU] Event Received
[FEISHU] event_type=im.message.receive_v1
[FEISHU] chat_id=oc_xxxxx
[FEISHU] message_id=om_xxxxx
[FEISHU] mention_bot=true
[FEISHU] text=查询LA设备状态
[AGENT] Start
[AGENT] Response Success
[FEISHU] Reply Success

如果出现：

[FEISHU] Event Received

但没有：

[AGENT] Start

说明消息解析或路由出现问题。

如果有：

[AGENT] Start

但没有：

[FEISHU] Reply Success

说明回复阶段出现问题。

这样可以快速确定故障位置。

十六、增加消息Trace ID

进一步可以给每条飞书消息增加一个 Trace ID：

FEI-20260904-000001

例如：

[FEI-20260904-000001] Event Received
[FEI-20260904-000001] Parse Message
[FEI-20260904-000001] Agent Start
[FEI-20260904-000001] Agent Success
[FEI-20260904-000001] Feishu Reply Success

以后出现：

为什么小龙虾没有回复？

只需要搜索：

FEI-20260904-000001

就可以完整查看一次请求。

十七、最常见的故障与解决方法

现象	可能原因	解决方法
可以发消息，不能收消息	未配置事件订阅	开启消息事件
内部群正常，外部群不响应	外部群权限/机器人能力限制	检查外部群支持
飞书事件没有进入服务器	Webhook不可访问	检查公网HTTPS
Webhook没有日志	Nginx/FRP问题	检查网络转发
收到事件但Agent不工作	消息解析失败	检查@机器人解析
Agent执行了但没有回复	Reply API失败	检查Token和message_id
修改权限后仍不工作	新版本未发布	发布应用版本
偶尔重复回复	没有消息幂等	根据message_id去重

十八、推荐的小龙虾飞书Gateway

最终可以把飞书连接独立成一个：

Feishu Gateway

结构：

飞书
 │
 ▼
Feishu Gateway
 │
 ┌──────────┼──────────┐
 │          │          │
 Event    Parser     Reply
 Receive
 │          │          │
 └──────────┼──────────┘
            ▼
     小龙虾Agent

Gateway只负责：

接收飞书事件
解析消息
识别@机器人
提取用户问题
调用Agent
回复飞书

而不负责MES业务逻辑。

这样以后小龙虾即使增加：

MES
MQTT
ERPNext
数据库
工业设备

也不会影响飞书通信层。

十九、最终解决方案

针对"小龙虾能够发送、能够查询，但是不能响应飞书外部群消息"的问题，推荐按照下面顺序处理：

① 检查机器人是否支持外部群
② 开启飞书事件订阅
③ 配置消息接收事件
④ 检查消息接收权限
⑤ 发布最新应用版本
⑥ 配置公网HTTPS Webhook
⑦ Nginx / FRP 转发到小龙虾
⑧ 测试 im.message.receive_v1
⑨ 检查小龙虾是否收到Event
⑩ 解析@小龙虾消息
⑪ 将文本交给Agent
⑫ 使用message_id回复飞书

二十、结语

飞书与小龙虾的连接，本质上不是简单的"调用一个API"。

它实际上是一个双向通信系统：

飞书
 ↙ ↘
↙   ↘
接收事件  API调用
↓        ↑
↓        ↑
小龙虾 Gateway ─────┘
 │
 ▼
AI Agent

其中：

小龙虾 → 飞书

解决的是主动发送问题；

飞书 → 小龙虾

解决的是事件订阅和消息接收问题。

因此，当出现：

小龙虾可以发消息，也能查询飞书，但 @它没有响应。

第一检查点不应该是AI模型，而应该是：

飞书事件订阅 → Webhook → 外部群消息事件 → 小龙虾Gateway

只要这条链路建立起来，再进行消息解析、Agent调用和飞书回复，整个智能体闭环才能真正跑通。

最终形成：

飞书外部群
 │
 │ @小龙虾
 ▼
飞书 Event
 │
 ▼
Webhook
 │
 ▼
小龙虾 Gateway
 │
 ▼
AI Agent
 │
 ▼
Feishu Reply API
 │
 ▼
飞书外部群

这就是小龙虾接入飞书后实现**"能收、能理解、能处理、能回复"**的完整通信闭环。