最近在折腾智能体项目时我把 OpenClaw 接入了飞书这事的完整链路其实比网上大多数教程写的要长不少。很多人卡在第一步——去飞书开放平台创建应用然后就不知道该干什么了还有人以为必须搞一台公网服务器、配好 Webhook 才能收消息结果在域名和反向代理上耗了好几天。我这篇直接给你一条最省心的路在飞书开放平台创建企业自建应用开通机器人和消息权限再用 OpenClaw 自带的 WebSocket 模式连接全程不需要公网 Webhook本地跑和云端跑都行。整个过程踩了不少坑尤其是 WSL2 环境校验、会话文件锁、飞书消息截断这几个点我会把排查思路和解决办法一起写清楚。这个方案适合谁想在自己电脑或云服务器上跑一个能接入飞书的 AI 助手又不愿意折腾内网穿透和公网回调地址的人也适合已经玩过 OpenClaw、但对飞书接入细节还不熟的人。我会把从创建应用到最终跑通的每一步都拆开讲也会解释为什么 WebSocket 模式是这个场景下的最优解。1. 方案选型为什么优先走 WebSocket而不是公网 Webhook1.1 Webhook 的痛点飞书开放平台最传统的事件回调方式就是你在平台上填一个公网可访问的 HTTPS 地址飞书服务器在用户给机器人发消息时把事件内容 POST 到这个地址上。这个模式看起来简单但对你本地的开发环境非常不友好。你的电脑通常在 NAT 后面没有公网 IP飞书的请求根本到不了你本机就算你有一台云服务器也得给那个端口配 HTTPS 证书、做反向代理、管理安全组规则有时候还要处理域名备案问题。这些活加起来已经足够劝退大部分只是想试试机器人功能的人了。更麻烦的是Webhook 地址是写死在飞书开放平台里的一旦你的服务器 IP 变了、端口换了或者你想从本地切到云端运行就要去平台后台重新配置回调地址改完还要等配置生效。这种“配置中心化”的方式对一个经常改部署位置的个人项目来说实在太笨重。1.2 WebSocket 模式的工作原理WebSocket 和 Webhook 最大的区别在于连接方向。Webhook 是飞书服务器主动来访问你的服务而 WebSocket 模式是让 OpenClaw 作为客户端主动去连接飞书的网关服务器建立一条长连接。连接建立之后飞书收到用户消息只需要沿着这条已有的连接把事件推下来就行完全不需要知道你的服务器地址在哪里。打个比方Webhook 就像你留了个门牌号快递员飞书消息要上门送件前提是你这个地址必须能被找到WebSocket 则像你自己去快递站取了个号然后坐在那里等叫号快递站飞书网关有包裹了直接递给你你身在何处它根本不用关心。只要你的机器能访问外网就能稳定收到消息。WebSocket 本身基于 TCP先通过 HTTP 完成握手再升级为全双工通信。OpenClaw 里的 WebSocket 模式实际上是把飞书开放平台提供的长连接 SDK 封装好了你只需要配置应用凭证和模式它会自动建立、维护、重连这条连接比自己去写长连接管理省太多事了。这就意味着不管你是在家里的笔记本电脑上跑还是在云服务器上跑配置几乎完全一样不需要额外开端口也不需要改防火墙策略。对个人项目来说这种“零暴露”的模式在安全性上也更让人放心。2. 飞书开放平台企业自建应用创建与权限开通2.1 创建企业自建应用这一步是整个接入的地基。打开飞书开放平台open.feishu.cn登录后进入开发者后台选择“创建企业自建应用”。这里要特别提醒一句自建应用和商店应用是两码事自建应用只服务于你自己的企业组织审核流程短、权限申请更灵活最适合个人开发和内部小范围使用。填应用名称的时候建议直接起一个像机器人名字一样的名称比如“我的助理”“小助手”之类因为这个名字会直接显示在飞书聊天列表里用户看到的就是它。应用描述随便写不影响功能。创建完成后页面上会出现两个关键字段App ID 和 App Secret。App ID 相当于应用的用户名App Secret 相当于密码。这两个值是在 OpenClaw 里配置飞书通道的核心凭证绝对不能泄露到公开的代码仓库里。我见过有人图省事直接把 App Secret 贴到 GitHub 上结果机器人被别人接管消息内容和对话记录全部可被读取这是很严重的安全事故。2.2 开通机器人并配置消息权限创建完应用后先别急着去写配置得先把这个应用变成一个“机器人”。在应用的功能区域找到“机器人”入口点击启用。然后在“权限管理”里把消息相关的权限都打开。根据我实际测试的经验核心需要的权限至少有这几个权限代码作用说明im:message读取用户发给机器人的单聊消息im:message:send_as_bot以机器人的身份发送消息im:message.p2p_msg_read读取单聊消息内容im:chat:readonly读取群聊基础信息用于群内使用im:resource读取消息中的图片、文件资源处理附件时用得上这里有个很容易忽略的细节很多人在权限管理里开了im:message却漏掉了im:message:send_as_bot结果机器人能收到消息但发不出去或者只读不回。建议在权限页面里把“机器人”相关的权限全部勾选不用吝啬。自建应用的权限开通后通常不需要像商店应用那样走重新上架审核但个别权限会有几秒到几分钟的生效延迟如果马上测试发现没效果等一下再试。2.3 事件订阅与连接方式选择权限只是基础要让 OpenClaw 能感知“用户发了消息”这件事还得配置事件订阅。进入“事件与回调”页面找到“事件订阅”然后添加事件。这里最关键的事件是im.message.receive_v1中文名叫“接收消息”。不加这个事件机器人就像一部没开铃声的手机别人发消息过来你不知道自然也就不会有任何回复。添加事件时飞书会要求你填写“请求地址”也就是 Webhook 回调地址。很多教程在这里就卡住了以为必须填一个真实可访问的公网地址。实际上当我们准备用 WebSocket 长连接模式时这个地址可以随便填一个合法 URL 占位比如https://example.com/webhook只要格式合法就行因为后续的消息根本不走这个地址。但这里有一个关键选择在“事件订阅”页面连接方式要选“长连接”而不是“Webhook”。选了长连接之后飞书平台会通过 SDK 在你的客户端和飞书网关之间建立持久连接你填的那个请求地址就彻底成了摆设。这个地方如果选错了即使你填了合法地址OpenClaw 也会因为收不到回调而没有任何反应。配置完成后飞书开放平台的后台会有“调试”功能可以模拟一条消息推送到你配置的连接上。我的建议是在真正启动 OpenClaw 之前先用这个调试功能确认事件订阅配置正确能省掉后面大量的排查时间。3. OpenClaw 部署与核心配置3.1 安装 OpenClawOpenClaw 的安装方式有几种官方推荐的方式是针对不同平台的脚本安装。Linux 和 macOS 可以直接在终端执行安装命令curl -fsSL https://openclaw.ai/install.sh | bash但 Windows 用户要特别小心原生 PowerShell 或 cmd 环境下的支持非常有限。我在第一次安装时就在 Windows 原生命令行里试过结果直接报了could not safely verify the WSL2 environment一脸懵。后来才明白OpenClaw 依赖 WSL2 提供的 Linux 环境所以正确的做法是先在 Windows 上装好 WSL2 和 Ubuntu 发行版然后在 Ubuntu 终端里执行安装命令。如果你还没装 WSL2可以在管理员权限的 PowerShell 里执行wsl --install装完默认发行版之后再执行wsl --set-default-version 2确保用的是 WSL2然后重启电脑。重启后进入 Ubuntu 终端再跑前面的安装脚本这次基本就顺了。安装过程中脚本会拉取一堆依赖如果你的网络环境一般可能会有一些超时重试耐心等就行。装好之后可以执行openclaw --version确认安装成功。3.2 配置飞书 Channel 与 WebSocket 连接OpenClaw 安装完成后会生成一个配置文件一般位于~/.openclaw/config.yaml也可能因为版本不同路径略有差异。这个文件是 OpenClaw 的全局配置控制着启用哪些渠道、使用什么模型、怎么管理会话等。我们需要在配置里添加一个飞书 channel。一个典型的配置片段长这样channels: feishu: enabled: true app_id: cli_xxxxxxxxxxxx app_secret: 你的AppSecret mode: websocketapp_id和app_secret对应你在飞书开放平台创建应用时得到的两个值mode必须写成websocket。这个字段特别关键如果你不写或者误写成 webhookOpenClaw 会尝试启动一个本地 HTTP 服务来接收飞书推送然后因为你的本机没有公网地址而陷入瘫痪日志里反复报连接失败。配置保存后启动 OpenClawopenclaw start如果配置正确日志里会出现类似Feishu channel connected或者长连接建立成功的信息。看到这个日志就说明你的 OpenClaw 已经成功连上飞书的网关接下来就可以去飞书里找机器人聊天了。如果你想把 App Secret 从配置文件里挪出来用环境变量管理OpenClaw 也支持。比如export FEISHU_APP_IDcli_xxx export FEISHU_APP_SECRET你的AppSecret然后在配置文件里引用环境变量。这种方式在部署到云服务器或者和团队协作时更安全不会因为一个配置文件泄露导致整个应用暴露。3.3 Channel 选择与多 Agent 调度OpenClaw 本身是一个支持多平台的 Agent 框架除了飞书之外Discord、Telegram、Slack 等渠道也都能接。当你只在配置里启用了飞书一个 channel 时事情很简单默认就走飞书。但如果你同时配置了多个渠道启动 Agent 时就必须显式指定 channel否则消息可能走错地方或者 Agent 不知道监听哪个渠道。启动时指定 channel 的命令大致是openclaw run --channel feishu有些交互式版本支持在运行时用/channel feishu切换。我建议把 channel 选择和会话隔离放在一起考虑。比如你在 Web 端调试 OpenClaw同时又想让它响应飞书消息最好给不同的入口分配不同的 session避免两个入口同时在同一个会话上操作导致出现锁冲突。这个细节我在后面讲常见问题时还会再展开但这里先埋个伏笔多 channel 环境下务必关注消息从哪条线进来、回复从哪条线出去。4. 接通后的实操验证与细节打磨4.1 验证机器人收发消息配置全部就绪后在飞书里搜索你的应用名称找到机器人先发一条“你好”试一下。正常情况下用户消息会通过长连接推送到 OpenClawAgent 开始处理然后把回复通过机器人发回聊天窗口。整个链路看起来是瞬时的但实际上涉及的是飞书服务器收到消息 → 推送给开放平台网关 → 网关把事件通过 WebSocket 连接发给 OpenClaw → OpenClaw 里 Agent 处理 → 调用飞书 API 以机器人身份发送回复。任何一个环节出问题都会表现为“消息石沉大海”。遇到这种情况优先按照下面三个顺序排查事件订阅里有没有添加im.message.receive_v1并且连接方式确实选的是“长连接”。权限管理里有没有im:message和im:message:send_as_bot没有的话机器人只能收不能发。OpenClaw 启动日志里有没有报错比如鉴权失败、连接断开、session 异常等。如果你不想等真实用户消息来验证飞书开放平台的事件订阅调试工具可以直接推送测试事件这个功能用来排查接入问题非常高效。4.2 飞书输出截断与长文本处理运行了一段时间后我遇到最烦的问题就是消息截断。飞书对单条机器人消息有长度限制虽然具体数值在不同协议版本里略有差异但实际使用中一旦 Agent 生成很长的回答超过限制的那部分会被直接吞掉看起来就像 AI 只回答了一半非常影响体验。要解决这个问题我试过三种方式第一种是在 OpenClaw 的配置里开启长文本自动分段让长消息按段落拆成多条发送。这个方案能保住内容完整性但问题是飞书聊天窗里会连续弹好几条消息阅读起来比较割裂。第二种是在给 Agent 的 Prompt 里明确加上一条规则“回答尽量精炼如果内容超过 2000 字必须分点总结不要一次性输出长段落。”这个方法我从实际效果来看最推荐因为它从源头控制住了 Agent 的输出长度回复变得简洁也符合聊天工具的使用习惯。具体怎么加取决于你用的模型和 Prompt 模板但核心逻辑就是告诉 Agent“飞书有长度限制别啰嗦”。第三种是用飞书的富文本卡片消息来承载长内容。卡片消息比纯文本消息能承载更多内容展示上也更美观但配置起来更复杂适合对展示效果有要求的场景。如果你只是想把消息收下来前两种足够了。4.3 会话文件管理OpenClaw 会把每个会话的状态保存在本地文件中包括对话历史、Agent 的状态、临时变量等。这个设计本身没什么问题但在实际操作中会踩一个很典型的坑如果你上一次进程没有正常退出或者有两个进程同时在操作同一个 session启动时可能报agent failed before reply: session file locked (timeout 60000ms)。这个错误的含义是会话文件被锁住了等待了 60 秒仍然没有拿到锁于是直接放弃处理。我第一次遇到这个报错时第一反应是 OpenClaw 崩了后来才发现是之前的旧进程还活着占着同一个 session 的锁不放。解决办法很简单# 1. 查看是否有旧 OpenClaw 进程 ps aux | grep openclaw # 2. 如果没有正在运行的任务直接停掉旧进程 kill pid # 3. 删除对应的锁文件 rm -f ~/.openclaw/sessions/session_id.lock核心教训是OpenClaw 不允许两个进程同时操作同一个会话。如果你要把 OpenClaw 部署成多个实例务必给每个实例分配不同的 session id避免并发抢锁。5. 常见问题与排查实录5.1 WSL2 环境校验失败could not safely verify the WSL2 environment这个报错基本只出现在 Windows 上。通常有两种原因一是在原生命令行里执行安装脚本二是虽然装了 WSL但默认版本是 WSL1。解决办法是在 PowerShell 里执行wsl --set-default-version 2然后重启 WSL。如果还没有安装任何发行版先wsl --install安装 Ubuntu。装完之后在 Ubuntu 终端里执行安装脚本这个报错就不会再出现。5.2 session file locked 的更深层排查前面提到过 session 锁的问题这里我再补充一个典型的并发场景。有时候你不是故意跑多个进程而是 Web 管理界面和后端服务共用同一个 session。OpenClaw 自己的一些内置工具也会持有 session 锁比如后台定时任务、自动保存。当你在 Web 界面调试时刚好触发了后台任务就可能撞上车。这时候即使你重启进程锁文件也不一定马上释放删除 .lock 文件反而是最干净的办法。另外如果你在分布式环境里跑 OpenClaw千万别让多个节点共享同一个存储目录下的 session 文件否则不仅会锁冲突还会出现对话历史互相覆盖的问题。给每个节点配置独立的 session 目录才是避免这一系列问题的根本方案。5.3 用 Postman 验证 WebSocket 连接很多人配置完飞书通道后想在不启动 OpenClaw 的情况下先用 Postman 验证一下 WebSocket 能不能通。Postman 确实支持 WebSocket 请求可以新建一个 WebSocket 类型的请求输入地址后手动发送消息。但要注意飞书长连接模式使用的是开放平台 SDK 内部协议连接地址和握手信息是 SDK 动态生成的不是简单的wss://地址拿 Postman 发一条消息就能测通。Postman 更适合去验证你自己开发的 WebSocket 服务或者当 OpenClaw 接入自定义 WebSocket 网关时做调试。对于接飞书这种事正确做法只有一条启动 OpenClaw看它的日志输出。5.4 其它值得注意的小坑不要把 App Secret 写死在公开仓库里。哪怕只是一个临时的测试项目只要推送到 GitHub 上就默认已经泄露了。建议用环境变量或密钥管理工具。事件订阅回调地址如果后来切换到 Webhook 模式必须把它改成真正可访问的公网地址否则事件推送会失败而且失败日志只出现在飞书后台你本地看不到任何提示。长连接模式下偶发的事件重复投递是正常的。OpenClaw 一般会做消息去重但如果你的 Agent 被设计成会写数据库、发通知之类的操作建议在业务层也做一次幂等处理防止同一条用户消息触发两次动作。6. 多平台部署与后续扩展6.1 从本地迁移到云端如果你在本地已经跑通了飞书接入想把它迁到云服务器上长期运行恭喜你这个过程中最难受的部分已经被 WebSocket 模式消除了。你不需要在云服务器的安全组里开任何入站端口也不需要为飞书回调单独配置 HTTPS 证书。只需要在云服务器上安装 OpenClaw把同一份配置文件复制过去注意用环境变量管理密钥然后启动即可。这里有一个部署细节云服务器上的 OpenClaw 要想稳定运行建议用 systemd 服务或者容器来托管保证进程异常退出后能自动重启。不然一次内存抖动就会让你整个机器人失联。6.2 多渠道统一接入OpenClaw 的 channel 机制决定了它天生适合做多渠道聚合。飞书、Discord、Telegram 等平台可以同时配置。每个渠道独立建立自己的长连接互不干扰。当你的 Agent 被多个渠道触发时OpenClaw 会按照会话和渠道的对应关系去路由回复不会交叉串线。但正如我在 3.3 节里强调的多 channel 场景下一定记得在启动 Agent 时指定 channel否则消息去向可能出问题。我个人的部署习惯是给飞书单独跑一个 Agent 实例给 Web 端和调试环境各分配一个独立 session这样既避免会话锁冲突也方便把线上用户消息和开发调试消息彻底隔离。6.3 OpenClaw 与其它 Agent 框架的取舍最近总有人拿 OpenClaw 和 WorkBuddy 这类工具做对比。从我自己的使用感受来看OpenClaw 的优势在于 channel 接入体系完整、长连接支持成熟、配置灵活尤其是对飞书这种国内办公工具的适配做得不错这对国内开发者来说价值很大。WorkBuddy 这类产品更偏商业化和开箱即用但灵活性弱一些。如果你喜欢自己控制一切OpenClaw 是更合适的选择如果你要的是零配置的托管体验那可以考虑 WorkBuddy。当然这个领域变化很快选型时还是要结合自己的实际场景。把 OpenClaw 接上飞书之后我自己最直观的感受是本地跑一个 AI 助手这件事终于不再需要“把服务暴露到公网”这种高风险操作了。整个链路里飞书开放平台负责身份和消息通道OpenClaw 负责 Agent 能力和会话管理WebSocket 像一条稳定的私人管道把两端安静地连起来。之后你要是想扩展更多渠道或者把 Agent 从本地搬到云服务器只需要改一下 channel 配置几乎不用动其他代码。最后再分享一个小技巧配置完飞书通道后先用单聊测试跑通之后再拉进群里因为群聊里涉及 机器人和消息权限报错信息更隐蔽单聊验证通过能帮你排除掉 80% 的接入问题。