飞书机器人如何实现长连接？

想象一下，你的飞书机器人就像一个永不疲倦的24小时在线客服，无需用户主动“呼叫”，就能随时感知到新消息的到来。这种实时、双向的通信能力，其核心技术就是长连接。与传统的Webhook短连接相比，长连接彻底改变了机器人与平台交互的“姿势”。

WebSocket：长连接的核心引擎

飞书机器人实现长连接，主要依赖于WebSocket协议。这可不是什么新玩意儿，但用在这里却恰到好处。你可以把它理解成在机器人和飞书服务器之间，建立了一条专属的、双向的“数据管道”。一旦握手成功，这条管道就会一直保持打开状态，直到一方主动关闭。

这个过程和打电话有点像。Webhook模式就像对讲机，你说一句“完毕”，对方才能说下一句，每次通信都要重新建立连接。而WebSocket则像接通了一个电话，只要不挂断，双方可以随时你一言我一语地聊下去，延迟极低。飞书开放平台正是通过这种方式，将消息、事件实时“推送”到你的机器人服务端，而不是让你的服务端隔三差五地去“询问”。

技术实现的三层架构

要让你的机器人用上WebSocket，可不是在配置文件里改个参数那么简单。它背后是一个精巧的握手与订阅流程。

• 第一步：身份握手。你的机器人服务需要携带有效的App ID和App Secret，向飞书服务器发起一个特殊的请求，申请建立WebSocket连接。飞书服务器验证身份后，会返回一个唯一的连接标识（Connection ID）和一个临时的WebSocket链接地址。这个地址是动态生成的，每次连接都可能不同。
• 第二步：建立连接。你的服务端拿到这个临时地址后，立即发起标准的WebSocket连接。一旦握手成功，那条双向管道就算正式搭好了。此时，你的服务端必须实现一个心跳机制，定期发送Ping帧，告诉飞书“我还活着”，防止连接因超时被意外断开。
• 第三步：事件订阅。管道通了，但里面流什么数据，得提前说好。你需要在飞书开放平台或通过API，明确订阅你的机器人关心哪些事件类型，比如“接收消息”、“用户进群”、“消息已读”等。只有订阅了的事件，飞书才会通过这条管道推送过来。

与Webhook的抉择

你可能会问，既然长连接这么好，为什么还要保留Webhook选项？说白了，各有各的适用场景。WebSocket对服务端的网络环境要求更高，需要具备公网可达性（或者通过内网穿透工具），并且要能稳定维持连接。对于部署在动态IP或严格防火墙后的服务，配置起来会比较折腾。

而Webhook虽然被动、有延迟，但它基于HTTP，对网络环境更宽容，尤其适合服务器部署在私有网络、但可以通过回调地址触达的场景。很多框架，比如OpenClaw，会将connectionMode配置项设计为可选项（websocket或webhook），把选择权交给开发者。

实践中必须绕开的“坑”

理论很美好，但一上手，几个常见的陷阱就会冒出来。首先是重连机制。网络波动、服务重启都可能导致连接断开。一个健壮的机器人服务必须实现自动重连逻辑，在检测到连接关闭后，能自动重新执行上述的握手、连接流程，对业务层做到无感切换。

其次是消息去重与顺序。飞书可能会因为网络原因重发消息，你的服务端需要根据消息ID进行去重处理。同时，尽管飞书会尽力保证事件推送的顺序，但在高并发或重连场景下，仍需考虑消息乱序的潜在可能，特别是对状态有依赖的业务逻辑。

最后是资源管理。一个长期打开的连接会占用服务器资源。当你的机器人需要服务成千上万个租户（企业）时，如何高效地管理成千上万个并发的WebSocket连接，就成了架构设计上的关键挑战。这涉及到连接池、异步IO、资源隔离等一系列后端工程问题。

所以，当你轻松地在配置文件中写下"connectionMode": "websocket"时，背后其实是这套复杂的通信协议、握手流程和容错机制在支撑。它让机器人从“应答机”变成了“感知体”，而理解这背后的原理，才能在你遇到连接闪断、消息丢失时，不至于手足无措。