企业官网建设流程全解析

文章来源说明：本文由 ZeroOne AI 整理发布，官网与 CSDN 双端同步首发，原文见 www.zeroone-ai.com。

一、问题背景

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

例如：

用户：

@小龙虾 查询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 │ ▼ 飞书外部群

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