开门见山说结论OpenClaw 接入飞书真正的核心不在 OpenClaw 本身而在飞书开放平台那一套“企业自建应用 机器人能力 消息权限 长连接订阅”的组合拳。把这套组合拳打好再用 OpenClaw 的 WebSocket 模式连上去你就彻底绕开了公网 Webhook 这个最折磨人的环节。整个过程不需要公网 IP不需要域名和 HTTPS 证书也不需要内网穿透本地电脑能跑云服务器也能跑。这篇文章就把这条路径从头到尾拆开讲透包括飞书后台每一步操作的目的、OpenClaw 侧配置的原理以及我实际跑的时候踩过的三个坑和完整排查思路给正准备接飞书通道的朋友做个参考。1. 为什么我放弃 Webhook公网回调方案的三个硬伤早期把机器人接到各类 IM 平台主流做法都是“事件订阅 Webhook 回调”。这套模式的逻辑是飞书那边有人发消息飞书服务器就把事件 POST 到你预先配置的回调地址上你的服务收到之后处理完再主动调飞书 API 把回复发回去。听起来很顺但跑起来处处是坑。第一个硬伤是公网可达性。你的服务必须有一个外网能访问到的 HTTP 端点这意味着你必须有公网 IP或者在路由器上做端口映射或者借助各种内网穿透工具。我本机在公司内网没有独立公网 IP路由器的端口映射因为安全策略根本开不了。第一次接的时候我在这一步卡了整整半个晚上。第二个硬伤是 HTTPS。飞书平台要求事件回调地址必须是 HTTPS而且证书还得是可信证书。这就牵扯出域名、证书申请、续期、甚至 CDN 或网关层配置一堆额外工作。证书一旦过期事件推送直接失败而且失败日志散落在多个环节里排查起来非常折磨。第三个硬伤是链路稳定性。Webhook 是飞书主动找你的服务你的出口网络只要有一点波动或者服务临时重启回调就会失败。飞书可能重试几次但重试的间隔和次数都是平台定的你没有控制权。消息丢了对用户来说就是“机器人没理我”体验很糟糕。后来我翻飞书开放平台文档发现事件订阅其实还有一条长连接通道。飞书官方支持 WebSocket 长连接接入你的服务主动向飞书网关发起连接建立一条双向实时通道消息事件在这条通道里推送给你回复也走同一条链路。它不需要公网回调地址不需要处理那些复杂的回调签名校验因为长连接方式下这些认证在连接建立时就已经完成了。从机制上讲Webhook 是“飞书来找你”WebSocket 是“你去找飞书”。前者要求你暴露一个入口后者只要求你有出站访问公网的能力。对绝大多数个人开发者、企业内部服务器来说出站访问比入站暴露容易得多这就是我坚定选 WebSocket 方案的根本原因。而 OpenClaw 对飞书通道的支持走的正是这条长连接路线你只要把 App ID 和 App Secret 填给它它自己会去飞书网关建立 WebSocket 连接不需要你手动维护任何回调服务。2. 飞书后台五步配置自建应用、机器人能力与长连接订阅飞书开放平台的后台配置是我见过最容易让人半途而废的地方——不是操作难而是概念多。这里按我实际操作的顺序把五步走完整。配置之前先确认一件事你的飞书账号必须归属于一个企业租户个人飞书账号没有企业组织的话得先创建或者加入一个企业组织。2.1 创建企业自建应用打开飞书开放平台进入开发者后台点“创建应用”类型选“企业自建应用”。填应用名称比如“OpenClaw Agent”上传图标写好描述创建完就进入了应用详情页。左侧菜单里有一个“应用凭证”入口里面可以看到 App ID 和 App Secret——这两个值后面要填给 OpenClaw先记下来。为什么选“企业自建应用”而不是“商店应用”因为自建应用是给企业内部用的权限配置、事件订阅、版本发布都在你自己控制范围内不需要走应用市场的上架审核。商店应用需要面向外部用户审核链路长完全没必要。2.2 开通机器人能力在应用详情页找到“添加应用能力”选择“机器人”。这一步会在你企业内创建一个机器人账号也就是用户在飞书里看到的那个能聊天的对象。开通之后企业内部成员就可以通过搜索找到这个机器人开始单聊也可以把它拉进群。这里要说清楚一个容易混淆的点应用是后台的壳机器人是这个壳对外提供聊天服务的那张脸。创建应用不等于有机器人必须额外添加机器人能力。2.3 权限配置不要只给“发消息”权限管理是翻车率最高的环节。很多新手在权限里只勾了“以机器人身份发送消息”结果机器人能主动发消息出去但收不到用户发来的任何内容。因为接收消息需要的是另一类权限。结合 OpenClaw 的实际对接需求建议至少把这些权限开通权限标识用途备注im:message读取用户发给机器人的单聊消息接收消息的底层权限im:message:send_as_bot以机器人身份发送消息回复消息必备im:message.p2p_msg接收单聊消息事件事件订阅中的单聊推送im:message.group_msg接收群聊消息事件群聊艾特机器人时触发im:chat读取群基本信息群聊场景辅助这些权限在后台的“权限管理”里搜索就能找到开通之后还要记得“批量开通”并且最终要通过发布版本才能真正生效。注意权限和事件订阅是两个独立的开关权限管“能不能”事件订阅管“消息来了要不要通知你”两个都得配。2.4 事件订阅选择长连接模式进入“事件订阅”页面这是整个配置的核心。页面会让你选择接收事件的方式有“使用 Webhook 接收事件”和“使用长连接接收事件”两个选项。这里必须选“使用长连接接收事件”。选完之后页面要求添加事件。需要添加的关键事件是“接收消息 im.message.receive_v1”这个事件会在用户给机器人发消息时触发。如果机器人要放群里用再把群消息相关的艾特事件也加上。这里有个非常隐蔽的坑如果你之前为了测试在事件订阅里配置过 Webhook 地址那么飞书会优先走 Webhook长连接反而不会生效。OpenClaw 那边就会出现连接看起来建立成功、但消息永远收不到的情况。所以选完长连接之后一定要检查页面上有没有残留的回调地址有就清掉。长连接模式下不需要配置 Encrypt Key也不需要公网地址。2.5 发布版本最后一步在“版本管理与发布”里创建新版本填个版本号描述随便写提交发布。企业自建应用的发布审核人通常是企业管理员如果你自己就是管理员后台点一下就能通过。这一步不做机器人不会出现在企业成员的可搜索列表里权限也不会生效前面全部白配。发布完成后去飞书里找到这个机器人发一条测试消息。如果飞书后台的“事件订阅”页面显示长连接在线并且能看到这条消息的事件记录说明飞书侧已经全部打通剩下就是 OpenClaw 的事了。3. OpenClaw 侧配置从 App ID 到连接建立再到模型联动飞书后台弄完回到 OpenClaw 这边。OpenClaw 的定位可以理解成一个消息中枢不同 IM 平台的消息从各自通道进来OpenClaw 把它们交给配置好的大模型处理再把回答原路返回。所以配置 OpenClaw 实际上要配两件事飞书通道连不连得通模型答不答得了。3.1 三个关键凭证的用途在飞书后台的“应用凭证”页面你能拿到几个值其中最重要的是 App ID 和 App Secret。App ID 是应用的公开标识相当于“用户名”App Secret 是私有密钥相当于“密码”。OpenClaw 拿着这两个值去飞书网关认证认证通过才能建立 WebSocket 长连接。另一个值是 Encrypt Key在“事件订阅”页面设置。长连接模式下它可有可无但如果此前配置过 Webhook后台可能已经生成过这个值。OpenClaw 配置里能填就填不填也不影响长连接通信。有一点必须强调App Secret 属于敏感凭证。如果 OpenClaw 部署在云服务器或者多人可访问的机器上千万不要把这个值硬编码在配置文件里提交到仓库用环境变量或密钥管理服务去存。这不算什么高深的安全理念纯粹是基本素养。3.2 WebSocket 长连接是怎么建立的OpenClaw 的配置通常是一个 YAML 文件飞书通道的核心配置段类似这样channels: feishu: enabled: true app_id: cli_xxxxxxxxxxxxxxxx app_secret: ${FEISHU_APP_SECRET} mode: websocketmode 这个字段就是在告诉 OpenClaw 走长连接而不是 Webhook。启动之后OpenClaw 会先拿 App ID 和 App Secret 向飞书网关请求一个长连接凭证也就是 ticket然后基于这个凭证发起 WebSocket 握手。握手成功后这条连接就挂在飞书网关上后续的消息事件会实时通过它推给 OpenClaw。理解这个流程对排查问题很有帮助。如果启动日志停在“获取 ticket”这一步通常是 App Secret 配错或者飞书后台的长连接模式没开启。如果握手一直超时那就要看你的服务器能不能正常访问飞书网关的域名——这是网络层的问题和代码无关。日志里看到类似 “Feishu WebSocket connected” 的输出说明通道已经通了。3.3 channel 选择和模型配置要分开理解OpenClaw 配置里经常出现“channel”这个词我见过不少人把它和大模型提供商混在一起结果配了飞书之后不知道怎么让消息走指定的模型。这里要理清一个概念channel 是消息的输入通道决定“消息从哪个平台进来”模型是大模型后端决定“这一轮对话由谁来回答”。飞书消息进来之后OpenClaw 内部会走 channel 的消息分发逻辑把文本提取出来再转交给配置好的模型接口。它们是两个独立的配置维度。我的建议是先把这两个维度在脑子里分开。先用飞书通道把消息接进来哪怕模型先用最简单的一个跑通全链路跑通之后再去纠结模型切换、会话记忆这些进阶功能。上来就想一步到位配置多个模型和通道出了问题你根本分不清是哪一层的问题。3.4 和 Qwen 之类的模型联动时要留意什么如果使用 Qwen 作为 OpenClaw 后端模型配置上除了 provider 和 model 名称之外还要确认机器能访问模型服务的 API 地址并且 API Key 有足够额度。配置段大致是这个样子model: provider: qwen api_key: ${QWEN_API_KEY} model: qwen-plus我实际遇到过一种情况飞书连接一切正常消息也能收到机器人就是不回话。查日志发现 OpenClaw 已经把消息发出去了但模型服务那边超时了。这种问题跟飞书通道毫无关系纯粹是模型侧网络或额度问题。所以遇到“机器人没反应”不要第一反应就去改飞书配置先看日志再定位是哪一层卡住了。4. 本地部署与云端部署两种跑法各自的坑OpenClaw 接飞书的一个卖点是“本地 / 云端部署均可”。这话没错但两种跑法的坑完全不一样我分别说一下。4.1 本地部署零公网依赖但别小看休眠和防火墙本地部署最大的优势就是零公网依赖。你的电脑只要能访问外网OpenClaw 就能主动连上飞书网关。不需要对路由器做任何端口映射不需要申请公网 IP开发调试时特别舒服。但本地部署有一个非常容易忽略的问题电脑休眠。笔记本合盖之后系统进入睡眠WebSocket 连接会断开。飞书网关的长连接有超时机制连接断开后并不会立刻报错——等你再打开电脑连接可能早就失效了OpenClaw 却不自知。结果就是机器人看起来在线实际消息全收不到。处理办法是配置系统不休眠或者养成本地跑的时候每隔一段时间看一眼日志的习惯。Windows 用户还有两个额外的坑。第一个是防火墙第一次启动 OpenClaw 时系统防火墙会弹窗询问是否允许网络访问一定要点允许。第二个是本地网络环境如果有流量拦截类的软件在跑WebSocket 出站连接可能被拦走需要确认飞书网关的域名被放行。这两个问题都遇到过表现都是“机器人连不上”但本质完全不一样排查时先看日志确认是连接失败还是握手超时。4.2 云端部署systemd 守护比 nohup 靠谱云端部署就简单很多。一台小规格的云服务器就够用OpenClaw 本身不重主要开销在模型 API 调用和会话文件读写上。把二进制和配置文件传上去跑起来和本地没有区别——因为 WebSocket 是主动出站连接云服务器不需要额外开放任何入站端口安全组规则基本不用动。很多人第一次跑云端习惯用 nohup 丢后台nohup ./openclaw --config ./config.yaml openclaw.log 21 nohup 能撑住当前会话但服务器重启之后不会自动拉起进程。我建议直接写一个 systemd service 文件配置好 ExecStart、WorkingDirectory 和日志输出然后执行 systemctl enable 设置开机自启。这样进程崩溃了 systemd 会帮忙重启机器重启了也会自动拉起来省心很多。云端部署还有一个小问题服务器时区。OpenClaw 处理会话超时、会话过期逻辑的时候如果服务器时区和飞书时间差太多会出现一些“会话看起来过期了”的诡异现象。解决办法很简单把服务器时区统一设成 Asia/Shanghai。4.3 本地和云端怎么选对比维度本地部署云端部署公网依赖只需出站访问只需出站访问稳定性受休眠、断电影响受服务器运行状态影响运维成本低随开随用中需要配置守护进程会话持久化存本机存服务器适合场景开发调试、个人自用7x24 小时对外服务如果只是自己把玩本地部署足够。如果想让同事、群里的多个人一起用直接上云。上云之前务必先在本地把飞书通道整个跑通一遍把配置链路验证清楚再搬到服务器上这样排查问题能省一大半时间。5. 实测翻车记录三个高频问题的完整排查链路最后这部分是我实际跑 OpenClaw 接飞书时遇到的三个问题每一个都花了我不少时间写出来给后来人当排查参考。5.1 “agent failed before reply: session file locked” 到底是怎么回事这个报错我刚开始跑通时经常见日志里显示类似 “agent failed before reply: session file locked (timeout 60000ms)”。第一眼以为是 OpenClaw 有 Bug后来排查下来大部分情况是并发触发的会话文件锁竞争。OpenClaw 的会话状态保存在本地文件里每个会话对应一个 session 文件。当同一个会话被并发请求时多个请求同时想对这个 session 文件加锁写状态就会互相争抢。一个请求等锁超过 60 秒还没有拿到就抛出这个超时错误。典型的触发场景是同一个群里好几个人同时艾特机器人消息几乎同时进来OpenClaw 可能把它们归到了同一个会话串行处理不过来前面的请求把锁占住后面的请求全在排队等锁。解决方向有两个一是把会话按“每个用户一个 session”来隔离别让不同用户挤在同一个会话文件里二是降低并发压力比如群里使用场景提醒大家不要同时连发多条消息。如果你是自己单聊测试也遇到这个报错那就更常见了上一条请求还在处理中你又紧跟着发了一条。模型生成回答本身就要几秒甚至几十秒处理长文本时锁被占用很久下一消息过来自然要等。后面我养成了习惯发完消息等当前请求完全结束再发下一条问题基本不再出现。5.2 飞书输出容易被截断不是 OpenClaw 的锅“OpenClaw 在飞书输出容易被截断”这个问题我见过很多人问我也遇到过。现象是机器人回消息前半段正常后半段突然没了像话说到一半被掐断。这个锅不能全甩给 OpenClaw飞书自身的消息长度限制才是主因。飞书机器人单条文本消息有明确的长度上限超过之后内容会被直接丢弃。OpenClaw 把模型生成的完整回答一次性通过 API 发给飞书内容一长就必然截断。解法是把长回复拆成多条消息发。我自己的做法是给飞书通道配置回复分片策略超过一定长度自动按段落拆成多条逐条发送。如果你的 OpenClaw 版本没有现成的分片配置还有一个土办法在系统提示词里约束模型“回答控制在 500 字以内”或者改用富文本格式发送富文本的承载能力比纯文本大不少。另外有个隐蔽的坑如果模型输出里包含大段无空格的代码块飞书在预览渲染时可能把它当超长内容处理即使整体字符数没超限也可能出问题。这种场景下优先让模型用精简的纯文本描述而不是整段贴代码。5.3 消息收不到时的排查顺序飞书里艾特机器人没反应OpenClaw 日志里也没看到消息进来这时候不要慌着改配置按顺序排查第一看飞书后台“事件订阅”页面确认长连接状态是“在线”。如果显示离线说明 OpenClaw 根本没连上来去 OpenClaw 日志里看有没有握手失败的记录。第二确认权限已经通过“版本管理与发布”真正生效。权限改了必须发新版本发布之后还要等一两分钟生效。第三确认你测试时的消息场景匹配。有些配置默认只处理单聊消息或者只处理群聊里艾特机器人的消息场景不对就会被忽略这不是 Bug是策略。第四确认 OpenClaw 进程还活着。本地部署最常见的场景是电脑休眠之后连接断了但进程还在重启进程就能解决云端部署就去查 systemd 状态和日志。按这个顺序走完九成问题都能定位。剩下那一成里最常见的是网络出站限制——企业内网环境访问不了飞书网关域名WebSocket 握手压根成功不了这个在本地开发和公司内网部署时要特别留意。5.4 长期维护的几个小习惯跑了一段时间之后我总结了几个很朴素的维护习惯。第一日志别删太早。OpenClaw 日志里包含每次消息的会话标识、连接状态、模型调用耗时。飞书通道出问题时往日志里翻一翻比瞎猜有用得多。记得给日志配轮转别让它在磁盘上无限膨胀。第二飞书后台的“事件订阅”页面是最好的调试工具。消息收不到的时候去那里看实时事件记录能直接确认消息到底有没有到达飞书这一层一下子就把问题范围缩小了一半。第三模型 API 额度和限额要提前配。OpenClaw 接上飞书之后机器人等于变成了高频消费入口账单涨得飞快都是因为没设上限。在上生产环境之前给模型接口配好单条回复长度上限和每日额度不然就是给自己挖坑。第四App Secret 定期轮换。怀疑泄露就立刻去飞书后台重置然后同步更新 OpenClaw 配置不要拖。说实话OpenClaw 接飞书这件事真正劝退人的不是 OpenClaw 本身而是飞书后台那套权限、订阅、版本发布之间环环相扣的关系。WebSocket 模式把网络层面的硬骨头啃掉之后剩下的就是耐心地把每一层配置对应起来。我写这篇东西就是因为当初自己在这上面绕了不少弯路——权限漏开、长连接和 Webhook 混配、并发请求把会话锁打死、长回复被截断这些问题每一个都很具体也都完全可以避免。如果你照着这篇文章的路径走一遍能少熬一个晚上那这字就算没白码。