前一阵子我折腾 OpenClaw 接入飞书一开始觉得不就是加个机器人吗结果真上手才发现卡点全在“怎么让飞书找到 OpenClawOpenClaw 又能稳定收到飞书的消息”这件事上。最省心的方案就是用飞书开放平台的企业自建应用把机器人和消息权限开通然后让 OpenClaw 走 WebSocket 模式去连飞书的长连接整个过程不需要公网 Webhook本地跑、云服务器跑都行。这篇文章我会把从飞书后台到 OpenClaw 配置文件的每一步都拆开讲包括为什么要选企业自建应用、长连接和 Webhook 的本质区别、权限怎么开才不会漏以及我实际踩过的几个坑比如 session file locked、agent failed before reply、飞书消息被截断希望你看完能一次性把整条链路跑通。先说明一下适用人群如果你正在用 OpenClaw 做个人 AI 助理或者团队机器人想让它在飞书里和你对话并且不想为“公网回调地址”这件事头疼那么这套接法非常对口。即便你之前没碰过飞书开放平台只要按顺序跟着走也能把环境搭起来。1. 为什么说打通飞书的关键是 WebSocket 而不是 Webhook很多人听到接入飞书第一反应是去配 Webhook 回调地址。这确实是传统做法但放到 OpenClaw 这种跑在本地或内网的 Agent 上Webhook 会带来一连串麻烦。我先把两种方式的区别讲透你就明白为什么选长连接模式了。1.1 两条路的本质区别Webhook 的本质是飞书服务器主动把你的服务器“叫醒”。飞书收到一条消息后会根据你在事件订阅里填的请求网址把事件内容 POST 到那个地址上。这要求你的 OpenClaw 必须有一个公网可达的 HTTP 服务而且还得是 HTTPS飞书才会放心地往里推数据。本地开发时要么你去买一台有公网 IP 的服务器要么在内网穿透工具上折腾半天还要处理 HTTPS 证书、域名备案、端口暴露这些事。一旦哪天穿透服务不稳定机器人就变成“时灵时不灵”。WebSocket 长连接则完全反过来。飞书开放平台提供了一种“使用长连接接收事件”的模式OpenClaw 启动后主动向飞书的网关发起一个 WebSocket 连接然后保持这个连接不断开。飞书收到新消息时会通过这个已经建立好的连接把事件推给 OpenClaw。整个过程中你的机器不需要任何公网入站端口也不需要域名和证书。你可以把它理解成打电话和等门铃的区别Webhook 是你在家里等门铃响访客飞书得按门铃你才知道有人来WebSocket 是你直接和访客拉了一条专线对方随时能顺着线把话递过来。1.2 我为什么最终选了企业自建应用加长连接飞书开放平台支持多种应用类型包括商店应用和企业自建应用。个人或小团队使用企业自建应用是最合适的因为审批链路短、权限可控、配置也直观。你在开发者后台创建一个企业自建应用它就是属于你自己企业的内部应用管理员审批通过后就能直接使用不需要上架审核。结合 OpenClaw 的使用场景企业自建应用加 WebSocket 长连接有四个明显优势无公网依赖OpenClaw 部署在 Mac、Windows、Linux 小主机上都行长连接天然适合 Agent 这种“随时可能被动接收消息”的场景消息实时性比轮询好得多飞书后台可以清楚看到连接状态出问题容易排查不需要为 HTTPS 证书和反向代理操心安全暴露面也小所以标题里那句“无需公网 Webhook”不是噱头而是这套方案真正省心的地方。下面我会按两个大块来讲飞书开放平台怎么配OpenClaw 这边怎么写配置。2. 飞书开放平台配置企业自建应用的完整实操在碰 OpenClaw 之前先把飞书后台的环境准备好。整个过程大概需要 10 分钟最难的不是操作而是搞清楚哪些按钮必须点、哪些权限必须开。2.1 创建应用与启用机器人能力先打开飞书开放平台open.feishu.cn用企业管理员账号登录。如果你没有管理员权限可以找管理员帮忙或者让管理员把“开发者”角色授权给你否则后面创建应用和发布版本都会受限。登录后在开发者后台点击“创建企业自建应用”填一个应用名称比如“OpenClaw Assistant”。名称后面可以改不影响接入。创建完成后会进入应用详情页左侧菜单里有一个“应用能力”区域这里必须做两件事第一添加“机器人”能力。飞书的机器人能力是一个独立开关不开启的话应用只能调用 API没法在会话里收发消息。点击“添加应用能力”找到机器人启用即可。第二确认应用状态。新创建的应用默认是“测试中”状态这个状态下只有应用创建者和指定的测试人员能使用机器人。测试阶段这没问题但如果你想让其他同事也能用后面必须创建版本并发布。拿我自己举例我第一次配置时机器人建好了、事件订阅也加了结果在飞书里给机器人发消息一直没反应。排查半天发现应用根本没发布机器人还处于“只有创建者可见”的测试态。所以这一步千万别跳过。2.2 权限清单与开通细节飞书的权限系统非常细机器人能做什么、不能做什么全靠权限开关控制。很多接入问题都是权限漏开导致的。我整理了一份最小可用权限清单照着开基本够用。权限标识作用说明是否必选im:message读取用户发给机器人的单聊消息必选im:message:send_as_bot以机器人身份发送消息必选im:chat:readonly获取群组基础信息强烈建议im:message.group_at_msg读取群组中 机器人 的消息群聊场景必选contact:user.base:readonly读取用户基本信息用于识别发送人可选但建议开在飞书开放平台后台的“权限管理”页面可以按权限标识搜索。比如要开 im:message就在搜索框输入 im:message找到对应权限后点击开通。需要注意的一点是权限开通后不会立刻生效必须通过“版本发布”流程后才会真正授权给应用。你可以在权限管理页面看到每个权限的申请状态如果是“已开通”但应用没发新版实际运行时还是会报权限不足。这里有一个容易踩的坑很多人以为在“权限管理”开了 im:message 就够了结果机器人只能收到消息、不能发消息或者能收单聊消息却收不到群内 消息。原因就是 im:message:send_as_bot 或 im:message.group_at_msg 没有开。我的建议是把上面表格里的权限一次全开了省得后面反复发版。2.3 事件订阅切换到长连接模式这一步是整个接入的核心。在应用详情页左侧找到“事件订阅”默认情况下飞书会让你配置“请求网址”也就是 Webhook 回调地址。我们不用这个改成“使用长连接接收事件”。操作路径是事件订阅页面 → 请求方式配置 → 选择“使用长连接接收事件”。选完之后飞书会生成一个长连接地址OpenClaw 会通过这个地址和飞书保持 WebSocket 连接。你不需要把地址填到任何地方OpenClaw 会自动从飞书 API 获取。接下来在同一个页面添加事件。事件是飞书推送给你的消息类型OpenClaw 要能响应飞书消息必须订阅对应的事件im.message.receive_v1接收消息事件单聊和群聊消息都会触发如果你需要在机器人被拉入群时做处理可以额外订阅 im.chat.member.bot.added_v1可选添加完事件后页面下方会显示“加密策略”相关的配置。飞书支持对事件内容做加密可以用 Encrypt Key 开启也可以不开启。为了减少排查复杂度我建议第一次接入时先不开启加密等链路通了再按需打开。如果打开了加密OpenClaw 配置里必须填写相同的 Encrypt Key否则事件解析会失败。最后回到“凭证与基础信息”页面把下面几个值记下来后面 OpenClaw 配置都要用App ID应用的唯一标识形如 cli_xxxxApp Secret应用密钥形如 xxxxxxxxxx只显示一次忘记就得重置Verification Token在事件订阅页面用于校验事件来源Encrypt Key如果没开加密这个可以为空到这里飞书后台的工作基本完成。但别忘了最后一步创建一个应用版本并发布。在“版本管理与发布”页面新建版本填上版本号和更新说明提交发布。如果是企业自建应用一般管理员审批后就能生效。发布完成后机器人才算真正在飞书里“活了”。3. OpenClaw 侧接入配置关键参数与部署差异飞书侧就绪后回到 OpenClaw 这边。OpenClaw 的 channel消息渠道机制决定了它可以把同一个 Agent 接到不同的 IM 平台上。我们这一步要做的就是新建一个飞书 channel把刚拿到的四个凭证填进去然后启动长连接。3.1 配置文件中的 channel 选择OpenClaw 的配置文件一般放在运行目录或用户目录下常见文件名是 config.yaml 或 openclaw.yaml。不同版本的默认路径可能不同启动时终端日志会打印实际读取的配置文件路径也可以直接用 openclaw config 命令查看。打开配置文件找到 channels 相关段落。OpenClaw 支持的 channel 很多比如 web、cli、telegram、discord、飞书、企业微信等。我们要启用的是飞书channels: feishu: enabled: true app_id: cli_xxxx app_secret: 你的_app_secret verification_token: 你的_verification_token encrypt_key: use_websocket: true如果你的 OpenClaw 版本界面不一样也可以通过交互式命令选择 channel。我试过在终端里输入openclaw channel select然后按提示选 feishu 或飞书它会自动生成对应的配置骨架你再把自己的凭证填进去。相比手动编辑这样更不容易漏字段。选完之后记得重启 OpenClaw让新的 channel 配置生效。3.2 App ID、Secret、Verification Token 的填写逻辑有朋友问为什么有 App ID 和 App Secret 了还要 Verification Token因为三者职责不同。App ID 是飞书用来识别“你是哪个应用”的相当于门牌号App Secret 是用于调用飞书 API 时签名的相当于钥匙Verification Token 是飞书推送事件时附带的校验字符串OpenClaw 拿到事件后会用这个 token 验证事件确实来自飞书防止伪造请求在 WebSocket 长连接模式下Verification Token 的校验依然有效。OpenClaw 每次收到飞书事件都会比对 token不一致会直接丢弃。所以三者的填写必须一字不差尤其是 App Secret复制时注意别带上空格。encrypt_key 那项如果飞书后台没有开启加密留空字符串就行。如果开启了必须把飞书事件订阅页面生成的 Encrypt Key 填进去。第一次接入我建议不开加密避免出现“消息能收到但内容是乱码或解析失败”的情况。填完之后启动 OpenClaw。如果配置正确日志里会出现类似“feishu websocket connected”或者“long connection established”的记录。看到这个就说明 OpenClaw 已经主动和飞书的长连接网关握手成功了。3.3 本地与云端部署的差异点这套方案最大的优点是部署环境几乎不受限制但本地和云端还是有一些细节需要注意。本地部署比如 Windows 或 macOS时OpenClaw 直接前台启动即可。Windows 上如果使用 WSL2 环境有一个已知的坑OpenClaw 启动时可能会提示 could not safely verify the WSL2 environment。这个问题通常和文件系统权限、Docker Desktop 的 WSL2 集成配置有关。如果你遇到这个提示可以先检查 Docker Desktop 的 WSL2 设置是否正确或者把 OpenClaw 的工作目录放到 WSL2 的原生文件系统里而不是 /mnt/c 挂载目录下能规避大部分文件锁和权限问题。云端部署比如云服务器时建议使用 systemd 或 Docker 把 OpenClaw 做成常驻服务。因为长连接有一个特点进程退出连接就断了飞书端会检测到连接断开但不会自动拉起你的进程。所以要让 OpenClaw 开机自启、崩溃自动重启。我自己的做法是写一个简单的 systemd unitExecStart 指向 openclaw 的启动命令Restartalways。防火墙方面由于是 OpenClaw 主动向外发起 WebSocket 连接不需要开放任何入站端口这在安全上也省心很多。云端部署还有一个容易被忽略的问题网络环境可能会主动断开空闲的长连接。如果发现 OpenClaw 运行一段时间后收不到消息但进程还活着多半是长连接被运营商或云平台切断了。OpenClaw 一般自带重连机制但保险起见可以配合守护进程做健康检查比如每分钟探测一次 WebSocket 连接状态发现断开就重启服务。4. 联调测试与高频问题排查实录配置完成不等于能跑联调阶段才是真正出问题的地方。我把自己遇到的几个典型问题和排查思路都整理出来按从高频到低频的顺序排列你如果遇到类似情况可以直接对照。4.1 启动顺序与第一轮消息验证先说启动顺序。飞书后台的配置和应用发布要提前完成OpenClaw 这边最好在飞书应用“已发布”之后再启动 channel否则事件订阅可能还没生效长连接虽然建立了但推不下来消息。启动后的第一轮验证不要急着测复杂对话。先在飞书里找到这个机器人给它发一条“你好”。正常流程是飞书收到消息 → 通过长连接推给 OpenClaw → OpenClaw 的 agent 处理 → 通过 API 回复消息。如果你在 OpenClaw 日志里看到收到了事件但没有最终回复问题大多出在 agent 本身比如模型 API Key 没配、会话超时或者消息被截断了。如果日志里连事件都没收到那就回到飞书后台检查三件事应用是否已发布、事件订阅是否用了长连接模式、im.message.receive_v1 事件是否添加成功。也可以用飞书开放平台自带的“调试”功能模拟一条消息推送到你的应用看看平台侧是否显示投递成功。4.2 高频问题速查表我整理了一个速查表覆盖了我在接入和后续使用中遇到的大部分问题。现象可能原因解决办法OpenClaw 日志出现 agent failed before reply: session file locked (timeout 60000ms)上一次 agent 进程未正常退出会话文件被锁检查是否有残留的 OpenClaw 进程杀掉后删除对应的 session lock 文件再重启机器人能收到消息但不回复模型 API Key 未配置或余额不足检查 OpenClaw 的模型配置确认 qwen/OpenAI 等 provider 的 key 是否有效机器人收不到任何消息应用未发布 / 事件订阅没开长连接 / 权限缺失回到飞书后台按 2.1 到 2.3 检查重点看应用状态和事件订阅方式飞书里输出内容被截断飞书单条消息长度有限制OpenClaw 输出太长在 OpenClaw 配置里启用输出分段或让 prompt 要求 agent 分条发送OpenClaw 启动时提示 could not safely verify the WSL2 environmentWindows WSL2 环境检测异常检查 WSL2 版本和 Docker Desktop 配置工作目录不要放在 /mnt/c长连接状态正常但偶尔不回复网络中断导致 WebSocket 断开重连未触发用守护进程监控 OpenClaw 健康状态断开时自动重启其中agent failed before reply: session file locked 这个问题非常典型。我第一次遇到时很懵表面意思是“agent 在回复之前失败了原因是会话文件锁超时”。说白了就是某个会话被另一个进程占用了OpenClaw 拿不到控制权。最常见的原因是上次运行 OpenClaw 的进程没有彻底退出比如直接在终端按 CtrlC 时进程没被杀干净或者上一次异常崩溃留下了锁文件。排查时用进程管理工具看一下有没有残留的 openclaw 进程有就杀掉然后找到 session 目录下的锁文件删掉再重新启动。如果你是多个服务同时启动也要避免两个进程操作同一个工作目录。飞书输出截断这个问题在热词里也出现了说明不是个例。飞书对单条文本消息有长度限制OpenClaw 在处理长文本回复时如果不做分段很容易被飞书截断。解决办法有两个方向一是调整 OpenClaw 的输出策略开启分段发送二是在 system prompt 里明确告诉 agent回复较长时分成多条消息。我个人更推荐第二种因为模型自己会判断在哪里断句更自然而不是机械地按字数切分。当然如果你只是偶尔跑长文档总结也可以接受截断然后把完整内容生成到在线文档或文件里再把链接发给用户。4.3 几条实操避坑经验除了上面的速查表我再分享几个比较零散的经验都是我实际操作中积累的。第一飞书应用发布后如果机器人还是不响应试着在飞书客户端里退出登录再重新登录。飞书客户端对机器人应用的权限缓存有时不会立刻刷新退出重登能让它重新拉取应用配置。这个方法听着很“玄学”但确实帮我解决过一次“权限都开了却一直无响应”的问题。第二不要在多个终端里同时启动 OpenClaw 指向同一个工作目录。我之前为了调试方便开了两个终端跑同一个配置结果 session 锁冲突不断日志里全是 session file locked。后来规范成“一个工作目录只允许一个 OpenClaw 实例”问题直接消失。第三WebSocket 模式虽然不需要公网但需要 OpenClaw 能够正常访问飞书的服务器。如果你的网络环境有防火墙或代理限制出方向连接长连接可能建立失败。排查时可以在启动日志里看有没有连接被拒绝或超时的记录。这个问题在团队内网环境尤其常见。第四如果你想在群聊里用记得群内要 机器人。飞书的事件推送里群聊普通消息默认不会推给机器人只有 机器人 的消息才会触发事件。这和单聊的机制不同很多人第一次在群里测试时发现机器人没反应其实就是没加 符号。第五日志是最好的老师。不管是飞书侧还是 OpenClaw 侧遇到问题先看日志。OpenClaw 的日志会明确打印出错误原因比如配置文件解析失败、凭证错误、长连接断开等几乎不需要盲猜。飞书开放平台后台的事件订阅页面也有“调试”功能可以看到平台投递事件的记录和状态码两边一对比问题定位很快。最后再分享一个小技巧如果你也遇到了飞书长连接频繁断开的问题除了检查网络还可以看看 OpenClaw 进程是不是被系统休眠或挂起了。笔记本合盖、云服务器内存不足导致进程被 kill都会让长连接悄悄断掉。我的做法是加一个每分钟的定时健康检查探测 WebSocket 是否还活着如果断了就自动拉起 OpenClaw。这套机制跑起来之后机器人基本能做到无人值守。接入成功只是第一步后面真正花时间的是调 prompt、选模型、优化 agent 的工作流。但基础设施稳定了这些迭代才有意义。希望这篇文章能帮你少走一段弯路把 OpenClaw 和飞书的连接一次跑通。
