最近团队里把飞书机器人接到了自建的龙虾网关后面想实现的效果是在飞书里发一条消息机器人能像助理一样调用后端的AI模型和工具把结果直接回传到群里。想法很好结果一上线就翻车——机器人在飞书里显示在线但消息发过去石沉大海一个字都回不来。这就是典型的“飞书接入龙虾后失联”。这个场景最近在开发圈里讨论得挺多尤其在大家普遍把 Codex、Claude Code 这类工具往自建网关里塞的时候飞书作为消息入口就成了刚需。我这次把飞书开放平台的配置、龙虾网关的日志、回调地址、回发权限全部翻了一遍花了大半天才把链路打通。这篇文章就把这次失联的排查思路和修复方法完整写下来给正在折腾同样组合的朋友一个参考。1. 先搞清楚“飞书接入龙虾”到底是怎么一条链路1.1 这是什么组合解决什么问题先说清楚这套东西是干嘛的。龙虾是我们团队内部对 OpenClaw 的戏称它是一个本地化的AI网关程序负责把来自不同渠道的消息统一收进来经过规则匹配后转给后端的大模型或工具去处理再把结果返回给消息渠道。这么做的好处是不用为每个IM渠道单独写一套AI对接逻辑飞书、钉钉、微信群之类都能走同一个网关。而飞书这一侧我们用的是飞书开放平台的“自建应用”能力把它配置成一个机器人。飞书机器人负责接收用户在群聊或单聊里发送的消息事件然后通过事件订阅机制把消息内容推给龙虾网关。龙虾处理完之后再调用飞书开放平台的发消息API把结果回传。所以这套组合的本质是飞书提供IM界面和消息收发的开放接口龙虾提供AI推理和工具调用的能力两者通过事件订阅和API调用串成一条完整的数据通路。对普通用户来说他看到的就是“飞书里多了一个AI机器人”对开发团队来说相当于给内部AI能力加了个人人都会用的聊天入口。1.2 一条消息从飞书到龙虾再回来的完整路径我曾经跟同事开玩笑说排查这类问题之前先把消息走过的路画一遍。看似简单的一句“机器人 帮我写个周报”在系统里其实要经过六七个环节。完整链路是这样的用户先进入验证范围。你在飞书客户端里 机器人或者给机器人发私聊消息实际上先到了飞书开放平台的服务器由平台判断这条消息应该路由给哪个应用。平台根据你在“事件订阅”里配置的订阅方式把事件推送给龙虾网关可能是通过Webhook回调也可能是长连接模式这一步是能不能收到消息的分水岭。龙虾网关的飞书接入适配层收到事件后先验签、解密然后解析出消息内容、发送者ID、会话ID等关键信息转成内部统一格式。网关把消息交给AI处理器这里可能是一次大模型调用也可能是触发某个工具链比如查询数据库、调内部接口。AI处理完成后生成回复文本网关再拼装一个飞书消息结构调用飞书开放平台的“发送消息”API。飞书平台把这个消息推送到用户的会话里用户看到机器人回复。这六步环环相扣任何一环挂了表现在用户侧就是“失联”。但失联有一个最坑爹的特征它不是报错给你看而是静默失败。机器人头像亮着消息发出去后没有反馈没有错误弹窗也不知道是平台没推过来还是网关没收到还是回复时接口报错但错误被吞了。所以排查的核心思路就两字——分段。1.3 为什么会“失联”失联这个词听起来很玄乎但落到技术上其实就是链路中断。我这次遇到的失联暴露出来之后仔细分析原因可能出在几个层面最表层的是飞书开放平台侧的配置问题比如事件订阅没有正确保存、订阅的地址填错了、应用的权限范围不够、机器人没有上线等。这些配置里任何一项不对飞书平台压根就不会把消息推送下来但机器人在客户端里看起来仍然是“在线”状态。中间层是网络可达性问题。如果事件回调用的是Webhook模式那飞书平台必须能访问到你的回调地址。本地开发环境下没有公网IP的话飞书就根本找不到你的网关消息自然送不到。深层的是龙虾网关自身的逻辑问题比如接入配置里的App ID或密钥填错了、事件签名校验失败、长连接断开后没有自动重连、网关进程本身挂了等等。还有个容易被忽略的是回发权限问题。飞书OpenAPI对发消息有权限管控即使网关收到并处理了消息调用发送API时如果应用没有对应的权限返回结果是错误码但如果你没在代码里处理这个错误从用户视角看依然是机器人没回复。所以“失联”不是一个单一故障而是一个症状。要解决它必须按链路逐层排查先确认是哪一段断了再针对性修复。2. 定位失联先判断断在哪一环2.1 第一层排查飞书机器人是不是真的“在线”面对失联我习惯从用户侧往底层倒着查。第一步先去飞书管理后台确认机器人应用的状态重点看两个地方一是“应用发布”状态必须是“已发布”或者至少处于“可用”状态如果应用还停在“测试中”并且当前用户不在测试白名单里那消息根本不会路由过来二是“机器人”能力是否已经启用对应的是应用详情里的“添加应用能力”中的机器人开关。检查完这些之后最简单的验证方法是找一个不在白名单限制下的测试账号直接在飞书里给机器人发一条消息。如果飞书客户端里出现了“以上消息未发送成功”之类的提示说明消息压根就没出客户端通常是应用被禁用或权限异常。如果消息正常发出去了但机器人不回复那问题就往下走。还可以在飞书管理后台的“开发配置→事件订阅”里点“推送调试”按钮手动模拟推送一个事件到你的回调地址。这个功能非常好用它能告诉你飞书平台往你的回调地址发请求时有没有收到2xx响应如果这里就显示“推送失败”那说明平台到网关这一段根本不通后面的排查都可以暂时放一放。2.2 第二层排查龙虾网关进程有没有收到事件飞书这一侧没问题之后下一步是确认龙虾网关到底有没有收到消息。这一步需要打开网关的日志和调试输出。不同的网关实现日志位置不一样但原理相通你要看到“收到来自飞书的消息”这样的日志记录。我当时用的是日志文件加终端实时输出并行的方式。如果网关是以前台方式运行的直接在终端里观察如果是后台进程去日志文件里grep飞书相关的关键字比如feishu、event、callback等。这里分享一个排查技巧先把网关的日志级别调到 DEBUG这样能看到的细节多得多。DEBUG级别的日志里会有事件原始载荷、签名校验结果、解析出的消息内容等。很多失联问题其实在这一步就能看出端倪比如日志里明确写着“signature verify failed”或者“unknown event type”那就直接能定位到问题方向。如果DEBUG日志里压根没有任何飞书相关的记录那基本可以断定飞书的事件没有到达网关。这时候就要回头检查事件订阅的地址或长连接状态了。2.3 第三层排查回复消息有没有发出去如果网关已经收到消息并在日志里能看到AI处理完成但用户还是没收到回复那问题就出在回发这条链路上。回发链路的核心是飞书发送消息API排查方法有两个。第一种是看网关日志里调用飞书API时返回的HTTP状态码和业务状态码。飞书开放平台的API返回结构里有个code字段0表示成功非0表示失败不同的错误码对应不同的原因。常见的有99991663机器人未启用、9499权限不足、99991672消息类型不支持等。我建议在网关里对飞书API的响应做完整日志输出如果你发现日志里只有请求记录而没有响应记录那多半是请求直接超时了。第二种排查方法是我个人很推荐的独立于网关直接用curl手动调用飞书的发消息API做验证。这样做的好处是能把网关自身的逻辑问题排除在外单独确认API调用是否通畅。手动调用需要先获取tenant_access_token然后用这个token去发消息如果手动调用能发成功说明凭证和API没有问题那问题一定出在网关调用API的方式上比如没带token、请求头不对、参数结构不匹配等。2.4 分段排除法小结飞书侧、网关接收侧、网关回发侧这三段排查完基本就能把失联的原因定位到某一段了。为了更直观我列了个排查决策表是我这次实际用到的思路排查段落关键检查项如果这段有问题表现是什么飞书平台侧应用状态、机器人能力、事件订阅配置消息发不出去或管理后台推送调试就失败网关接收侧进程状态、日志、长连接/回调可达性网关日志里完全没有事件记录网关处理侧AI调用、工具执行、异常捕获日志有事件但处理卡住或报错网关回发侧token获取、API调用、权限范围日志有成功处理但飞书没消息返回这个表不一定覆盖所有情况但80%的失联问题都能靠它定位到具体环节。下面我就按这个排查结果把每一步的修复操作完整写出来。3. 一步一步修复飞书接入龙虾的完整配置与验证方法3.1 飞书开放平台的三个关键凭证飞书接入的第一步是把凭证弄对这也是最容易出错的地方。开放平台的自建应用需要三个关键凭证缺一个或者混用都会导致失联App ID应用的唯一标识类似身份证号。在飞书开放平台的“凭证与基础信息”页面里可以看到。龙虾网关接入时需要配置这个值飞书推送事件时也会带上它。App Secret密钥用来获取tenant_access_token或app_access_token相当于登录飞书API的密码。这个值只显示一次如果之前在创建应用时没保存需要重置。Verification Token 和 Encrypt Key这两个在事件订阅配置里用到。Verification Token 用于URL验证Encrypt Key 用于事件内容的加密解密。如果你在飞书后台配置了加密策略那网关侧也必须用同一个Encrypt Key解密否则收到的就是密文根本解析不出消息内容。我遇到过一种情况同事把事件订阅里的Encrypt Key填错了飞书每次推送事件都是加密的网关拿错误的key去解密解密失败后网关直接把事件丢掉只打了一行warn日志。从用户视角看就是机器人失联从日志看却只有一行不痛不痒的警告。所以配置完凭证之后第一件事是去飞书管理后台的“事件订阅”页面点击“推送调试”看网关能不能正确应答。再说一下tenant_access_token怎么拿。这个token是飞书OpenAPI调用时用来认证的凭证类似临时令牌。获取方式是请求飞书的/auth/v3/tenant_access_token/internal接口带上App ID和App Secret返回的JSON里有tenant_access_token和expire字段。这个token的有效期一般是2小时正式接网关时要做缓存和自动续期不能在每次发消息时都重新请求。很多人在这一步会顺手踩坑直接用app_access_token去调发送消息接口结果报权限错误因为两者能调用的API范围不一样。这一点和dify首次接飞书云文档时拿授权凭证是同一个道理需要明确你到底是要以应用身份操作还是要以用户身份操作对应的凭证获取路径完全不同。龙虾网关这种场景下按机器人身份发消息用tenant_access_token就对了。3.2 事件订阅长连接模式还是Webhook回调飞到龙虾之间的事件推送有两种模式选错了也是失联大户。一种是Webhook回调模式需要你提供一个公网可访问的HTTP接口飞书平台每个事件都往这个接口POST一个JSON。这种模式的问题是本地开发时比较麻烦如果你的网关跑在开发机上没有公网地址飞书根本访问不到事件全丢。有些团队会用一个内网映射工具把本地端口暴露出去但操作起来很麻烦还牵扯到域名、HTTPS证书、签名校验这些额外工作。另一种是长连接模式飞书开发平台提供了一种WebSocket接入方式飞书SDK会在应用启动时主动跟飞书服务器建立一个长连接事件推送直接通过这个连接灌进来。这种模式不需要公网回调地址对跑在本地或内网的网关非常友好也是我这次最后选择的方案。我个人的建议是只要你的龙虾网关跑在非公网环境里优先用长连接模式。它省去了配网段、配域名、配HTTPS的麻烦消息到达率也比Webhook稳定。长连接模式唯一的弱点是网关进程必须保持运行一旦进程退出连接就断了但这是可控的用systemd或supervisor做进程守护就行。飞书SDK在长连接模式下一般会内置自动重连逻辑不过具体能不能稳定重连还要看你用的SDK版本。3.3 龙虾OpenClaw侧的接入配置示例龙虾接入飞书的配置方式不同版本略有差异但整体上就是配置飞书机器人相关的环境变量或启动参数。下面是我实际使用的配置结构关键位置用占位符代替# 飞书开放平台应用凭证 FEISHU_APP_IDcli_xxxxxxxxxxxxxxx FEISHU_APP_SECRETxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 事件订阅相关 FEISHU_ENCRYPT_KEYxxxxxxxxxxxxxxxxxxxxxx FEISHU_VERIFICATION_TOKENxxxxxxxxxxxxxxxxxxxxxx # 事件订阅模式websocket / webhook FEISHU_MODEwebsocket # Webhook模式下的回调路径前缀如果选webhook则需要配置 # FEISHU_WEBHOOK_PATH/feishu/event # 机器人回发消息的默认模式 FEISHU_REPLY_MODEim_message配置完成之后启动网关日志里如果出现类似“feishu websocket connected”的记录说明长连接已经建立成功。此时在飞书里给机器人发一条测试消息正常情况下网关日志会出现事件接收记录。这里有个容易被忽略的细节飞书自建应用的“机器人”能力和“事件订阅”是两个独立的配置项。你只添加了“机器人”能力但没订阅事件那机器人能收到消息吗不能。必须在“事件订阅”里显式添加对应的事件类型比如im.message.receive_v1然后发布版本或用测试账号生效事件才会真正推送过来。3.4 回发消息的两个场景被动回复与主动推送配置好接收之后还要处理好回发。飞书聊天机器人回消息有两种场景权限和实现方式不同。第一种是被动回复也就是用户发消息触发AI处理后网关调用API把结果发回同一个会话。这种场景需要机器人具备im:message或im:message:send_as_bot这样的权限。在飞书管理后台的“权限管理”里搜索“发送消息”相关权限为应用申请并开通。需要特别说明的是飞书的权限开通之后通常需要重新发布应用版本才能生效光在后台勾选权限而没发布调用API时依然会报权限不足。第二种是主动推送也就是AI在处理完某个定时任务或后台事件后主动给某个用户或群发消息。这种场景走的接口参数里需要明确的receive_id比如open_id、user_id或chat_id而且对权限要求更高。如果发现主动推送时飞书返回“no permission”之类的错误基本就是权限没开够。我在排查时还发现一个问题被动回复不一定要调发送消息API。如果网关是在收到事件回调的同一个HTTP请求生命周期里回复飞书支持在回调响应里直接返回消息内容实现“被动回复”但请注意这种模式的前提是你的事件订阅配置中启用了“允许机器人被动回复消息”的选项并且响应体格式要符合要求。如果不想深入研究这个机制最简单的做法还是统一走发送消息API。3.5 用一条命令验证链路通了配置完之后别急着手动聊天先用一条命令验证回发链路是否通畅。这一步能大幅缩短验证时间也方便后续问题定位。先把飞书的tenant_access_token拿下来然后手动发送一条消息。命令大概是这样的# 1. 获取 tenant_access_token curl -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \ -H Content-Type: application/json \ -d {app_id:cli_xxxxxxxx,app_secret:xxxxxxxx}拿到返回的tenant_access_token后用它发一条文本消息到指定会话# 2. 用 token 发送消息将 TOKEN 换成上面获取到的值 curl -X POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_typechat_id \ -H Authorization: Bearer TOKEN \ -H Content-Type: application/json \ -d {receive_id:oc_xxxxxx,msg_type:text,content:{\text\:\链路验证成功\}}如果这条命令返回的JSON里code为0说明凭证、权限、会话ID格式都没问题。之后再去飞书里给机器人发消息看网关日志和飞书客户端是否同步收到回复。两步全通说明“飞书接入龙虾”这条链路已经畅通了。4. 常见失联问题与排查技巧实录4.1 高频问题速查表排查了这么多案例我把飞书接入龙虾后最常见的失联原因整理成一个速查表遇到问题直接对号入座问题现象可能原因解决方法消息发出去但机器人没反应网关日志完全无记录长连接没建立或断开检查网关日志里是否有websocket连接成功记录重启网关并做进程保活网关日志提示 signature verify failedVerification Token或Encrypt Key配置错误核对飞书管理后台的事件订阅配置重新复制Key网关收到事件但解析不出消息内容Encrypt Key不匹配或未配置解密逻辑确认飞书后台加密开关状态保持两端加密key一致AI处理完但飞书里没有回复发送消息API权限不足在飞书后台的权限管理里申请im:message权限并重新发布应用单聊正常群里机器人没反应事件订阅里缺少群消息事件检查后台事件列表确认已添加im.message.receive_v1网关经常隔一段时间就失联长连接被系统杀掉或网络切换导致重连失败配置systemd守护、断线自动重启逻辑回调模式下管理后台推送调试失败回调地址不可公网访问换成WebSocket长连接模式手动curl发消息成功但网关自动发消息失败网关内部token缓存失效或请求头不对清理token缓存检查HTTP请求的Authorization头这张表是我在实际排查中反复用到的高频清单基本覆盖了“龙虾失联”这个搜索引擎常见求助词的绝大多数场景。4.2 三个真实踩坑案例第一个案例是本地开发机上长连接被系统休眠断掉。我们把龙虾跑在一台台式机上飞书消息时好时坏早上来的时候总是失联的状态重启网关就好但用不了几个小时又断了。后来查日志发现连接断开前系统日志里有休眠记录是电脑自动睡眠把进程的网络连接断了而进程本身没有退出所以看起来像是“网关还活着”实际上长连接早没了。最后把电脑休眠关掉加了一个systemd的定时健康检查这问题才算彻底解决。第二个案例是事件订阅里漏加了群消息事件。当时我们只订阅了机器人单聊事件私聊机器人一切正常但在群里机器人完全没反应。排查了半天才发现飞书开放平台对群场景有单独的事件类型光订阅im.message.receive_v1不够还要在事件列表里确认这个事件是否覆盖群消息。加上了之后群里也能正常触发这个坑比较隐蔽因为后台页面默认只给了一个“接收消息”的选项很容易以为这一个就够了。第三个案例最能说明问题回调地址配置成了内网IP。同事把网关的Webhook回调地址填成了http://192.168.x.x:8080/feishu/event在本地用curl测这个地址完全没问题但飞书服务器在公网它怎么可能访问到一个内网IP这种问题连看日志都看不出端倪因为网关压根没收到任何东西。最后我们放弃了Webhook模式全部改用长连接从根上避免了公网回调的问题。4.3 稳定性建议把“失联”概率压到最低排查完失联问题之后我更关注的是怎么防止它再次发生。稳定性的核心其实就三件事保活、可观测、快速恢复。保活方面网关进程一定要有守护机制。在Linux服务器上我推荐用systemd写一个service单元配置Restartalways进程挂了自动拉起。如果是在Windows上跑可以用计划任务或nssm把进程注册成服务注意不要用那种依赖用户登录会话的启动方式否则用户一注销网关就没了。可观测方面日志一定要标准化。建议在网关外层包一层日志中间件统一记录事件接收时间、处理耗时、飞书API响应码。失联问题最怕的不是报错而是静默。只要日志里能看到“收到事件→处理中→API返回成功”这样的完整记录99%的失联都能在几分钟内定位。快速恢复方面可以在龙虾网关里加一个简单的健康检查接口然后用外部监控工具定期探测。如果连续几次探测失败就自动重启网关进程。更高级一点的做法是给飞书机器人做兜底回复当AI调用超时或出错时至少回复一句“当前处理超时请稍后再试”让用户知道机器人还在而不是彻底沉默。最后再分享一个小技巧如果你在一个团队里搭这套东西建议把飞书管理后台的“事件订阅”配置操作交给一个人统一管理不要把凭证在群里传来传去。我后来排查了很多失联问题有一半是有人在测试环境把凭证改成了自己的App ID导致生产环境网关拿着旧token在跑最终表现为莫名失联。这种事第一次遇到会觉得莫名其妙但只要把配置和凭证管理规范起来很多“失联”根本不会发生。
飞书机器人接入网关后失联？从事件订阅到消息回发的全链路排查指南
最近团队里把飞书机器人接到了自建的龙虾网关后面想实现的效果是在飞书里发一条消息机器人能像助理一样调用后端的AI模型和工具把结果直接回传到群里。想法很好结果一上线就翻车——机器人在飞书里显示在线但消息发过去石沉大海一个字都回不来。这就是典型的“飞书接入龙虾后失联”。这个场景最近在开发圈里讨论得挺多尤其在大家普遍把 Codex、Claude Code 这类工具往自建网关里塞的时候飞书作为消息入口就成了刚需。我这次把飞书开放平台的配置、龙虾网关的日志、回调地址、回发权限全部翻了一遍花了大半天才把链路打通。这篇文章就把这次失联的排查思路和修复方法完整写下来给正在折腾同样组合的朋友一个参考。1. 先搞清楚“飞书接入龙虾”到底是怎么一条链路1.1 这是什么组合解决什么问题先说清楚这套东西是干嘛的。龙虾是我们团队内部对 OpenClaw 的戏称它是一个本地化的AI网关程序负责把来自不同渠道的消息统一收进来经过规则匹配后转给后端的大模型或工具去处理再把结果返回给消息渠道。这么做的好处是不用为每个IM渠道单独写一套AI对接逻辑飞书、钉钉、微信群之类都能走同一个网关。而飞书这一侧我们用的是飞书开放平台的“自建应用”能力把它配置成一个机器人。飞书机器人负责接收用户在群聊或单聊里发送的消息事件然后通过事件订阅机制把消息内容推给龙虾网关。龙虾处理完之后再调用飞书开放平台的发消息API把结果回传。所以这套组合的本质是飞书提供IM界面和消息收发的开放接口龙虾提供AI推理和工具调用的能力两者通过事件订阅和API调用串成一条完整的数据通路。对普通用户来说他看到的就是“飞书里多了一个AI机器人”对开发团队来说相当于给内部AI能力加了个人人都会用的聊天入口。1.2 一条消息从飞书到龙虾再回来的完整路径我曾经跟同事开玩笑说排查这类问题之前先把消息走过的路画一遍。看似简单的一句“机器人 帮我写个周报”在系统里其实要经过六七个环节。完整链路是这样的用户先进入验证范围。你在飞书客户端里 机器人或者给机器人发私聊消息实际上先到了飞书开放平台的服务器由平台判断这条消息应该路由给哪个应用。平台根据你在“事件订阅”里配置的订阅方式把事件推送给龙虾网关可能是通过Webhook回调也可能是长连接模式这一步是能不能收到消息的分水岭。龙虾网关的飞书接入适配层收到事件后先验签、解密然后解析出消息内容、发送者ID、会话ID等关键信息转成内部统一格式。网关把消息交给AI处理器这里可能是一次大模型调用也可能是触发某个工具链比如查询数据库、调内部接口。AI处理完成后生成回复文本网关再拼装一个飞书消息结构调用飞书开放平台的“发送消息”API。飞书平台把这个消息推送到用户的会话里用户看到机器人回复。这六步环环相扣任何一环挂了表现在用户侧就是“失联”。但失联有一个最坑爹的特征它不是报错给你看而是静默失败。机器人头像亮着消息发出去后没有反馈没有错误弹窗也不知道是平台没推过来还是网关没收到还是回复时接口报错但错误被吞了。所以排查的核心思路就两字——分段。1.3 为什么会“失联”失联这个词听起来很玄乎但落到技术上其实就是链路中断。我这次遇到的失联暴露出来之后仔细分析原因可能出在几个层面最表层的是飞书开放平台侧的配置问题比如事件订阅没有正确保存、订阅的地址填错了、应用的权限范围不够、机器人没有上线等。这些配置里任何一项不对飞书平台压根就不会把消息推送下来但机器人在客户端里看起来仍然是“在线”状态。中间层是网络可达性问题。如果事件回调用的是Webhook模式那飞书平台必须能访问到你的回调地址。本地开发环境下没有公网IP的话飞书就根本找不到你的网关消息自然送不到。深层的是龙虾网关自身的逻辑问题比如接入配置里的App ID或密钥填错了、事件签名校验失败、长连接断开后没有自动重连、网关进程本身挂了等等。还有个容易被忽略的是回发权限问题。飞书OpenAPI对发消息有权限管控即使网关收到并处理了消息调用发送API时如果应用没有对应的权限返回结果是错误码但如果你没在代码里处理这个错误从用户视角看依然是机器人没回复。所以“失联”不是一个单一故障而是一个症状。要解决它必须按链路逐层排查先确认是哪一段断了再针对性修复。2. 定位失联先判断断在哪一环2.1 第一层排查飞书机器人是不是真的“在线”面对失联我习惯从用户侧往底层倒着查。第一步先去飞书管理后台确认机器人应用的状态重点看两个地方一是“应用发布”状态必须是“已发布”或者至少处于“可用”状态如果应用还停在“测试中”并且当前用户不在测试白名单里那消息根本不会路由过来二是“机器人”能力是否已经启用对应的是应用详情里的“添加应用能力”中的机器人开关。检查完这些之后最简单的验证方法是找一个不在白名单限制下的测试账号直接在飞书里给机器人发一条消息。如果飞书客户端里出现了“以上消息未发送成功”之类的提示说明消息压根就没出客户端通常是应用被禁用或权限异常。如果消息正常发出去了但机器人不回复那问题就往下走。还可以在飞书管理后台的“开发配置→事件订阅”里点“推送调试”按钮手动模拟推送一个事件到你的回调地址。这个功能非常好用它能告诉你飞书平台往你的回调地址发请求时有没有收到2xx响应如果这里就显示“推送失败”那说明平台到网关这一段根本不通后面的排查都可以暂时放一放。2.2 第二层排查龙虾网关进程有没有收到事件飞书这一侧没问题之后下一步是确认龙虾网关到底有没有收到消息。这一步需要打开网关的日志和调试输出。不同的网关实现日志位置不一样但原理相通你要看到“收到来自飞书的消息”这样的日志记录。我当时用的是日志文件加终端实时输出并行的方式。如果网关是以前台方式运行的直接在终端里观察如果是后台进程去日志文件里grep飞书相关的关键字比如feishu、event、callback等。这里分享一个排查技巧先把网关的日志级别调到 DEBUG这样能看到的细节多得多。DEBUG级别的日志里会有事件原始载荷、签名校验结果、解析出的消息内容等。很多失联问题其实在这一步就能看出端倪比如日志里明确写着“signature verify failed”或者“unknown event type”那就直接能定位到问题方向。如果DEBUG日志里压根没有任何飞书相关的记录那基本可以断定飞书的事件没有到达网关。这时候就要回头检查事件订阅的地址或长连接状态了。2.3 第三层排查回复消息有没有发出去如果网关已经收到消息并在日志里能看到AI处理完成但用户还是没收到回复那问题就出在回发这条链路上。回发链路的核心是飞书发送消息API排查方法有两个。第一种是看网关日志里调用飞书API时返回的HTTP状态码和业务状态码。飞书开放平台的API返回结构里有个code字段0表示成功非0表示失败不同的错误码对应不同的原因。常见的有99991663机器人未启用、9499权限不足、99991672消息类型不支持等。我建议在网关里对飞书API的响应做完整日志输出如果你发现日志里只有请求记录而没有响应记录那多半是请求直接超时了。第二种排查方法是我个人很推荐的独立于网关直接用curl手动调用飞书的发消息API做验证。这样做的好处是能把网关自身的逻辑问题排除在外单独确认API调用是否通畅。手动调用需要先获取tenant_access_token然后用这个token去发消息如果手动调用能发成功说明凭证和API没有问题那问题一定出在网关调用API的方式上比如没带token、请求头不对、参数结构不匹配等。2.4 分段排除法小结飞书侧、网关接收侧、网关回发侧这三段排查完基本就能把失联的原因定位到某一段了。为了更直观我列了个排查决策表是我这次实际用到的思路排查段落关键检查项如果这段有问题表现是什么飞书平台侧应用状态、机器人能力、事件订阅配置消息发不出去或管理后台推送调试就失败网关接收侧进程状态、日志、长连接/回调可达性网关日志里完全没有事件记录网关处理侧AI调用、工具执行、异常捕获日志有事件但处理卡住或报错网关回发侧token获取、API调用、权限范围日志有成功处理但飞书没消息返回这个表不一定覆盖所有情况但80%的失联问题都能靠它定位到具体环节。下面我就按这个排查结果把每一步的修复操作完整写出来。3. 一步一步修复飞书接入龙虾的完整配置与验证方法3.1 飞书开放平台的三个关键凭证飞书接入的第一步是把凭证弄对这也是最容易出错的地方。开放平台的自建应用需要三个关键凭证缺一个或者混用都会导致失联App ID应用的唯一标识类似身份证号。在飞书开放平台的“凭证与基础信息”页面里可以看到。龙虾网关接入时需要配置这个值飞书推送事件时也会带上它。App Secret密钥用来获取tenant_access_token或app_access_token相当于登录飞书API的密码。这个值只显示一次如果之前在创建应用时没保存需要重置。Verification Token 和 Encrypt Key这两个在事件订阅配置里用到。Verification Token 用于URL验证Encrypt Key 用于事件内容的加密解密。如果你在飞书后台配置了加密策略那网关侧也必须用同一个Encrypt Key解密否则收到的就是密文根本解析不出消息内容。我遇到过一种情况同事把事件订阅里的Encrypt Key填错了飞书每次推送事件都是加密的网关拿错误的key去解密解密失败后网关直接把事件丢掉只打了一行warn日志。从用户视角看就是机器人失联从日志看却只有一行不痛不痒的警告。所以配置完凭证之后第一件事是去飞书管理后台的“事件订阅”页面点击“推送调试”看网关能不能正确应答。再说一下tenant_access_token怎么拿。这个token是飞书OpenAPI调用时用来认证的凭证类似临时令牌。获取方式是请求飞书的/auth/v3/tenant_access_token/internal接口带上App ID和App Secret返回的JSON里有tenant_access_token和expire字段。这个token的有效期一般是2小时正式接网关时要做缓存和自动续期不能在每次发消息时都重新请求。很多人在这一步会顺手踩坑直接用app_access_token去调发送消息接口结果报权限错误因为两者能调用的API范围不一样。这一点和dify首次接飞书云文档时拿授权凭证是同一个道理需要明确你到底是要以应用身份操作还是要以用户身份操作对应的凭证获取路径完全不同。龙虾网关这种场景下按机器人身份发消息用tenant_access_token就对了。3.2 事件订阅长连接模式还是Webhook回调飞到龙虾之间的事件推送有两种模式选错了也是失联大户。一种是Webhook回调模式需要你提供一个公网可访问的HTTP接口飞书平台每个事件都往这个接口POST一个JSON。这种模式的问题是本地开发时比较麻烦如果你的网关跑在开发机上没有公网地址飞书根本访问不到事件全丢。有些团队会用一个内网映射工具把本地端口暴露出去但操作起来很麻烦还牵扯到域名、HTTPS证书、签名校验这些额外工作。另一种是长连接模式飞书开发平台提供了一种WebSocket接入方式飞书SDK会在应用启动时主动跟飞书服务器建立一个长连接事件推送直接通过这个连接灌进来。这种模式不需要公网回调地址对跑在本地或内网的网关非常友好也是我这次最后选择的方案。我个人的建议是只要你的龙虾网关跑在非公网环境里优先用长连接模式。它省去了配网段、配域名、配HTTPS的麻烦消息到达率也比Webhook稳定。长连接模式唯一的弱点是网关进程必须保持运行一旦进程退出连接就断了但这是可控的用systemd或supervisor做进程守护就行。飞书SDK在长连接模式下一般会内置自动重连逻辑不过具体能不能稳定重连还要看你用的SDK版本。3.3 龙虾OpenClaw侧的接入配置示例龙虾接入飞书的配置方式不同版本略有差异但整体上就是配置飞书机器人相关的环境变量或启动参数。下面是我实际使用的配置结构关键位置用占位符代替# 飞书开放平台应用凭证 FEISHU_APP_IDcli_xxxxxxxxxxxxxxx FEISHU_APP_SECRETxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 事件订阅相关 FEISHU_ENCRYPT_KEYxxxxxxxxxxxxxxxxxxxxxx FEISHU_VERIFICATION_TOKENxxxxxxxxxxxxxxxxxxxxxx # 事件订阅模式websocket / webhook FEISHU_MODEwebsocket # Webhook模式下的回调路径前缀如果选webhook则需要配置 # FEISHU_WEBHOOK_PATH/feishu/event # 机器人回发消息的默认模式 FEISHU_REPLY_MODEim_message配置完成之后启动网关日志里如果出现类似“feishu websocket connected”的记录说明长连接已经建立成功。此时在飞书里给机器人发一条测试消息正常情况下网关日志会出现事件接收记录。这里有个容易被忽略的细节飞书自建应用的“机器人”能力和“事件订阅”是两个独立的配置项。你只添加了“机器人”能力但没订阅事件那机器人能收到消息吗不能。必须在“事件订阅”里显式添加对应的事件类型比如im.message.receive_v1然后发布版本或用测试账号生效事件才会真正推送过来。3.4 回发消息的两个场景被动回复与主动推送配置好接收之后还要处理好回发。飞书聊天机器人回消息有两种场景权限和实现方式不同。第一种是被动回复也就是用户发消息触发AI处理后网关调用API把结果发回同一个会话。这种场景需要机器人具备im:message或im:message:send_as_bot这样的权限。在飞书管理后台的“权限管理”里搜索“发送消息”相关权限为应用申请并开通。需要特别说明的是飞书的权限开通之后通常需要重新发布应用版本才能生效光在后台勾选权限而没发布调用API时依然会报权限不足。第二种是主动推送也就是AI在处理完某个定时任务或后台事件后主动给某个用户或群发消息。这种场景走的接口参数里需要明确的receive_id比如open_id、user_id或chat_id而且对权限要求更高。如果发现主动推送时飞书返回“no permission”之类的错误基本就是权限没开够。我在排查时还发现一个问题被动回复不一定要调发送消息API。如果网关是在收到事件回调的同一个HTTP请求生命周期里回复飞书支持在回调响应里直接返回消息内容实现“被动回复”但请注意这种模式的前提是你的事件订阅配置中启用了“允许机器人被动回复消息”的选项并且响应体格式要符合要求。如果不想深入研究这个机制最简单的做法还是统一走发送消息API。3.5 用一条命令验证链路通了配置完之后别急着手动聊天先用一条命令验证回发链路是否通畅。这一步能大幅缩短验证时间也方便后续问题定位。先把飞书的tenant_access_token拿下来然后手动发送一条消息。命令大概是这样的# 1. 获取 tenant_access_token curl -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \ -H Content-Type: application/json \ -d {app_id:cli_xxxxxxxx,app_secret:xxxxxxxx}拿到返回的tenant_access_token后用它发一条文本消息到指定会话# 2. 用 token 发送消息将 TOKEN 换成上面获取到的值 curl -X POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_typechat_id \ -H Authorization: Bearer TOKEN \ -H Content-Type: application/json \ -d {receive_id:oc_xxxxxx,msg_type:text,content:{\text\:\链路验证成功\}}如果这条命令返回的JSON里code为0说明凭证、权限、会话ID格式都没问题。之后再去飞书里给机器人发消息看网关日志和飞书客户端是否同步收到回复。两步全通说明“飞书接入龙虾”这条链路已经畅通了。4. 常见失联问题与排查技巧实录4.1 高频问题速查表排查了这么多案例我把飞书接入龙虾后最常见的失联原因整理成一个速查表遇到问题直接对号入座问题现象可能原因解决方法消息发出去但机器人没反应网关日志完全无记录长连接没建立或断开检查网关日志里是否有websocket连接成功记录重启网关并做进程保活网关日志提示 signature verify failedVerification Token或Encrypt Key配置错误核对飞书管理后台的事件订阅配置重新复制Key网关收到事件但解析不出消息内容Encrypt Key不匹配或未配置解密逻辑确认飞书后台加密开关状态保持两端加密key一致AI处理完但飞书里没有回复发送消息API权限不足在飞书后台的权限管理里申请im:message权限并重新发布应用单聊正常群里机器人没反应事件订阅里缺少群消息事件检查后台事件列表确认已添加im.message.receive_v1网关经常隔一段时间就失联长连接被系统杀掉或网络切换导致重连失败配置systemd守护、断线自动重启逻辑回调模式下管理后台推送调试失败回调地址不可公网访问换成WebSocket长连接模式手动curl发消息成功但网关自动发消息失败网关内部token缓存失效或请求头不对清理token缓存检查HTTP请求的Authorization头这张表是我在实际排查中反复用到的高频清单基本覆盖了“龙虾失联”这个搜索引擎常见求助词的绝大多数场景。4.2 三个真实踩坑案例第一个案例是本地开发机上长连接被系统休眠断掉。我们把龙虾跑在一台台式机上飞书消息时好时坏早上来的时候总是失联的状态重启网关就好但用不了几个小时又断了。后来查日志发现连接断开前系统日志里有休眠记录是电脑自动睡眠把进程的网络连接断了而进程本身没有退出所以看起来像是“网关还活着”实际上长连接早没了。最后把电脑休眠关掉加了一个systemd的定时健康检查这问题才算彻底解决。第二个案例是事件订阅里漏加了群消息事件。当时我们只订阅了机器人单聊事件私聊机器人一切正常但在群里机器人完全没反应。排查了半天才发现飞书开放平台对群场景有单独的事件类型光订阅im.message.receive_v1不够还要在事件列表里确认这个事件是否覆盖群消息。加上了之后群里也能正常触发这个坑比较隐蔽因为后台页面默认只给了一个“接收消息”的选项很容易以为这一个就够了。第三个案例最能说明问题回调地址配置成了内网IP。同事把网关的Webhook回调地址填成了http://192.168.x.x:8080/feishu/event在本地用curl测这个地址完全没问题但飞书服务器在公网它怎么可能访问到一个内网IP这种问题连看日志都看不出端倪因为网关压根没收到任何东西。最后我们放弃了Webhook模式全部改用长连接从根上避免了公网回调的问题。4.3 稳定性建议把“失联”概率压到最低排查完失联问题之后我更关注的是怎么防止它再次发生。稳定性的核心其实就三件事保活、可观测、快速恢复。保活方面网关进程一定要有守护机制。在Linux服务器上我推荐用systemd写一个service单元配置Restartalways进程挂了自动拉起。如果是在Windows上跑可以用计划任务或nssm把进程注册成服务注意不要用那种依赖用户登录会话的启动方式否则用户一注销网关就没了。可观测方面日志一定要标准化。建议在网关外层包一层日志中间件统一记录事件接收时间、处理耗时、飞书API响应码。失联问题最怕的不是报错而是静默。只要日志里能看到“收到事件→处理中→API返回成功”这样的完整记录99%的失联都能在几分钟内定位。快速恢复方面可以在龙虾网关里加一个简单的健康检查接口然后用外部监控工具定期探测。如果连续几次探测失败就自动重启网关进程。更高级一点的做法是给飞书机器人做兜底回复当AI调用超时或出错时至少回复一句“当前处理超时请稍后再试”让用户知道机器人还在而不是彻底沉默。最后再分享一个小技巧如果你在一个团队里搭这套东西建议把飞书管理后台的“事件订阅”配置操作交给一个人统一管理不要把凭证在群里传来传去。我后来排查了很多失联问题有一半是有人在测试环境把凭证改成了自己的App ID导致生产环境网关拿着旧token在跑最终表现为莫名失联。这种事第一次遇到会觉得莫名其妙但只要把配置和凭证管理规范起来很多“失联”根本不会发生。
