把 OpenClaw 接到飞书机器人这件事从开始动工到真正跑顺我前后折腾了差不多一周。回头看最花时间的不是 OpenClaw 本身而是飞书开放平台的权限模型和事件订阅机制——很多设置缺一步整个链路就静默失败日志里干干净净但机器人就是不回话。这篇按我的实操顺序走一遍先在飞书侧把应用建好、权限开对、事件订阅配明白再回头在 OpenClaw 侧把配置逐条填上、把服务拉起来然后从私聊到群聊完整跑通一条最小链路最后把踩过的坑掰开揉碎讲清楚。想在自己团队里做类似集成的同学照着走应该能少走不少弯路。实测下来这个组合做出来的效果接近一个轻量级数字员工机器人能消化群里的 也能处理私聊任务能查资料、能调内部接口还能定时往群里推汇报。这也决定了它适合的人群——有 Linux 和 Docker 基础、想给团队快速搭一个 AI 助理的开发者或者负责团队效率工具的同学。如果你只是想要一个能自动回话的玩具那大可不必上 OpenClaw飞书自带的问答机器人就能满足如果你希望机器人背后有一整套可编程的工具链和任务编排能力那这篇文章就是给你准备的。1. 为什么要把 OpenClaw 塞进飞书里跑1.1 OpenClaw 到底是什么别被名字唬住我第一次看到 OpenClaw 这个名字脑子里蹦出来的是某个开源引擎点进项目页才发现是个挺典型的智能体框架。它做的事可以拆成三块接入大模型、挂载工具、对接即时通讯通道。所谓接入大模型就是 LLM 这一层可以替换闭源商用模型、开源本地模型都能接配置一个 API endpoint 就能换“脑子”。所谓挂载工具是让模型在回答之外还能执行操作比如读写文件、执行命令行、调 HTTP 接口、访问数据库甚至操作浏览器。所谓对接即时通讯通道是把这个能力封装成机器人接到飞书、钉钉、Telegram、Discord 这些 IM 平台上。这三个能力叠在一起 OpenClaw 就不再是个单纯聊天机器人更像一个能完成具体动作的执行器。举个例子同事在群里发一句“把上周的销售数据按区域汇总一下发给我”它可以从接口拉数据、调用脚本做汇总、生成消息卡片再推到群里。整个过程没有人工参与但每一步都有日志可查。1.2 为什么拿飞书当交互层而不是自建一个前端很多人第一反应是既然要做工具为什么不直接做个 Web 页面非要塞进飞书里我实际做完之后的感受是IM 作为交互层有三个天然优势。第一飞书在国内企业里普及度太高了员工天然就在里面不需要额外教大家打开一个新系统、注册一个新账号。第二消息即交互群聊、私聊、、卡片、审批这些都是现成的不用自己实现一套通知和交互组件。第三操作留痕谁在什么时候让机器人做了什么群消息里一翻就有比自建系统的操作日志更自然。劣势也明显IM 不适合承载复杂表单和高频操作。你不可能让用户在一个聊天窗口里填一个十字段的表单也不适合做数据密集型的可视化报表。所以我的定位是飞书上的 OpenClaw 负责那些“几句话能说清楚”、“结果适合用文本或卡片呈现”的任务真正复杂的流程还是留给业务系统。1.3 哪些场景划算哪些场景再怎么接都别扭适合接的场景我总结有三个特征任务触发简单、结果以文本为主、执行过程可以被拆成步骤。典型的有查库存和订单状态、生成日报周报、代码仓库的发布通知、内部知识库问答、定时巡检和告警推送。不适合的也有比如需要多人实时协作编辑的流程、上传下载大文件的操作、复杂权限审批流。这类功能塞进 IM 里会非常别扭机器人只是入口但背后的体验撑不住。建议在项目启动前先明确边界否则后面会不断陷入“这个需求到底要不要做成消息”的纠结中。2. 飞书开放平台侧建应用和开权限的那些细节2.1 创建企业自建应用的前几步登录飞书开放平台的后台在开发者服务里选择创建企业自建应用。这里有个小建议应用名称直接决定机器人显示给同事的名字建议起得直白一点比如“智能助理”或者“Ops 助手”别起那种看起来很酷但没人看得懂的名字。创建完成后在“凭证与基础信息”页面能看到 App ID 和 App Secret。App ID 是cli_开头的字符串App Secret 相当于密码。这两个东西是整个集成的钥匙必须妥善保管特别是 App Secret千万别写进代码仓库也别提交到任何共享文档里。我见过有同事把 Secret 直接贴在群聊里结果被人拿去调接口拉组织架构数据过程相当难看。下一步是在“添加应用能力”里找到“机器人”点添加。这一步会在你的应用下创建一个机器人身份之后用户搜索应用时看到的就是这个机器人。2.2 权限申请清单少一个都白搭飞书的权限模型比较细它不像一些平台那样粗粒度地给“全部权限”而是按能力项逐条申请。我集成的过程中最少需要开通这几项权限标识作用缺少时的现象im:message读取用户发给机器人的消息机器人收不到任何事件im:message:send_as_bot以机器人身份发送消息能收到但无法回复im:message.group_at_msg读取群聊中 机器人的消息私聊正常、群聊不回复im:chat:readonly读取群基础信息无法在群聊中识别群名、群成员这四项是底线。如果你的机器人还要读用户信息、查组织架构再加contact:user.base:readonly之类的权限如果要做定时推送至少要有im:message:send_as_bot并且你要能拿到目标群或用户的chat_id。权限申请后的状态是“已开通”未必代表生效。企业内部自建应用权限修改之后要创建一个新版本并发布发布完成后权限才对目标用户生效。这个细节后面坑了我一次下面会专门讲。2.3 事件订阅长连接还是 Webhook我的选择事件订阅是飞书把“用户发了消息”这个动作推送给你的通道。它有两种模式在“事件与回调”页面里配置。第一种是推模式也就是 Webhook。飞书往你提供的公网 URL 发 POST 请求服务器返回challenge字段完成验证。这种模式要求服务部署在公网可达的 HTTPS 地址上还要处理好证书和网络代理对部署在内网 OpenClaw 来说平添不少麻烦。第二种是长连接模式飞书官方叫“使用长连接接收事件”。OpenClaw 主动和飞书服务器建立 WebSocket 连接事件直接通过这条连接推送下来。优点是不要公网 IP、不要域名、不要 HTTPS 证书内网机器也能稳定收事件缺点是需要保证 OpenClaw 进程长期在线断线后要有重连机制。我的选择很明确长连接。理由很简单OpenClaw 大概率是部署在公司内网服务器上的为了一个回调地址去申请公网域名和证书完全不值得。长连接模式下事件订阅页面只需要添加事件im.message.receive_v1并选择长连接保存即可不需要配置任何回调 URL。2.4 发布版本与可用范围应用建好、权限配好之后还不能直接用。飞书有一个“版本”概念所有配置变更包括权限、机器人信息、事件订阅都要通过“创建版本”并“发布”才能对外生效。企业自建应用一般发布后在管理后台会自动通过但如果你开启了某些审核特性就需要等管理员审批。这里有个容易漏掉的点应用创建后默认的可用范围只有创建者本人。想先在自己和测试群里试用就把应用可用范围设为包含你和测试群成员确认没问题后再扩大到全员。否则就会出现“别人搜不到你的机器人”这种看起来像 bug 实则是配置问题的情况。3. OpenClaw 侧接入配置项逐条拆解3.1 部署形态先用 Docker 把服务拉起来OpenClaw 的部署方式我建议直接用 Docker省去手动装依赖、配环境的麻烦。一个典型的启动命令长这样docker run -d \ --name openclaw \ -p 8080:8080 \ -v /opt/openclaw/config:/etc/openclaw \ -v /opt/openclaw/logs:/var/log/openclaw \ --restart unless-stopped \ openclaw:latest这里把配置文件目录和日志目录都挂到宿主机上方便改配置、查日志。端口 8080 是给管理接口用的如果机器有防火墙记得把端口放通。3.2 飞书通道的配置字段逐项解释OpenClaw 的配置一般集中在config.yaml里。飞书相关的部分大致长这样channels: feishu: enabled: true app_id: cli_xxxxxxxx app_secret: 你的 App Secret mode: websocket # websocket 或 webhook webhook_path: /feishu/callback encrypt_key: allowed_user_ids: [] allowed_chat_ids: []这些字段我逐个说下用途和注意点。app_id和app_secret就是上一节里飞书开放平台给的那两个凭证不用多解释。mode选websocket时对应长连接模式选webhook时 OpenClaw 会启动一个 HTTP 服务路径由webhook_path指定飞书把事件 POST 到这个路径上。encrypt_key是飞书消息加密用的密钥如果你在事件订阅里开启了加密这里必须填一致否则 OpenClaw 解析事件时会直接失败。没开加密就留空。allowed_user_ids和allowed_chat_ids是白名单分别限制哪些用户可以私聊、哪些群可以调用。这是个很重要的安全边界特别是当你给机器人挂了工具之后白名单能挡住大部分乱用。这里要特别提醒不同版本的 OpenClaw 字段名可能有差异有的是mode有的是connection_mode有的是channel_type。配置前先翻一下你下载版本的示例配置别把老教程的字段硬套上去。3.3 启动后怎么确认连接真的成功配置写完服务起来怎么知道真的连上飞书了第一步看启动日志。正常情况下OpenClaw 启动后会出现类似feishu channel started的日志如果用的是长连接模式还会有一条websocket connected。看到这两行说明凭证没问题、事件订阅通道已经建立。第二步在飞书里搜索你创建的应用找到机器人发一条ping。如果一切正常机器人会回复pong。这一步能同时验证事件接收、消息解析、消息发送三个环节。如果没回复不要急着查模型配置先退回到日志看事件到底有没有进来。我的习惯是在正式接模型之前先把 OpenClaw 切到一个最简单的回复模式让机器人把收到的任何文本原样回显。这个模式下链路最短排查最快。通道通了再换回真实模型这样能把“通道问题”和“模型问题”隔离开。这个习惯帮我省了不少时间。4. 从消息到回复最小闭环的完整链路4.1 整个链路是怎么走的用户发消息到机器人这背后经历的东西比想象中多。我拆成六步用户在飞书里给机器人发消息。飞书服务器识别到消息通过长连接或 Webhook 把事件推给 OpenClaw。OpenClaw 解析事件拿到消息内容、发送者、会话 ID。OpenClaw 把消息交给模型模型经过推理或调用工具后生成回复文本。OpenClaw 调用飞书消息发送接口把回复推给对应用户或群。用户在飞书里看到机器人的回复。注意第 2 步和第 5 步是两条不同的链路。接收走事件通道发送走开放平台消息接口中间靠tenant_access_token做身份认证。这个 token 由 App ID 和 App Secret 换来的有有效期OpenClaw 会内部缓存并自动刷新一般不需要手动处理。4.2 事件数据长什么样实际收到的消息事件结构大致是这样{ schema: 2.0, header: { event_type: im.message.receive_v1, event_id: evt_xxx }, event: { message: { message_id: om_xxx, chat_id: oc_xxx, chat_type: p2p, message_type: text, content: {\text\:\ping\} }, sender: { sender_id: { open_id: ou_xxx } } } }这个结构有两个地方特别容易踩坑。第一content字段是 JSON 字符串不是纯文本必须先json.loads再取值。第二chat_type区分是私聊p2p还是群聊group群聊场景下你需要从chat_id发送而私聊场景一般可以直接用用户的open_id。发送消息的调用大致是这个样子curl -X POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_typeopen_id \ -H Authorization: Bearer tenant_access_token \ -H Content-Type: application/json \ -d { receive_id: ou_xxx, msg_type: text, content: {\text\:\pong\} }如果用的是国际版飞书把域名换成open.larksuite.com就行。OpenClaw 里一般有对应的配置项按环境填好即可。4.3 日志怎么读链路通了之后日志是你判断问题位置最重要的依据。OpenClaw 的日志一般分两类一类是通道日志记录事件接收和消息发送的成败另一类是运行时日志记录模型调用和工具执行的过程。我自己的排查习惯是先在通道日志里找事件 ID确认“收到”这件事发生了再在发送日志里找消息返回的code确认“发出去”这件事成功了。如果这两段都有但用户没看到消息那问题大多出在消息内容和接收对象身上。很多时候你以为的“机器人没反应”其实是消息发出去了但投递给了错误的 ID。5. 进阶一点会话记忆、工具调用与主动推送5.1 多轮会话和上下文状态跑通最小闭环之后紧接着的问题就是多轮会话。用户不会总是发一句话就结束更多场景是“帮我查一下 X”“X 的结果里只看华东区的”“再按周维度拆一下”这需要机器人记住前两轮的上下文。OpenClaw 处理会话的方式核心是把会话 ID 和消息序列关联起来。飞书里天然有会话 ID私聊用用户 ID群聊用chat_id可以拿这个作为记忆分组的 key。这样群里的对话不会串到别人头上每个群的上下文互相隔离。上下文不能无限积累否则模型输入很快会被塞满。我一般设置滑动窗口只保留最近几轮对话或者按 token 数量裁剪。具体数值根据模型上下文长度调整比如一个 8K 上下文的模型就只保留最近 20 轮以内的对话。5.2 工具调用的授权姿势OpenClaw 的核心价值在工具调用。你可以给它挂一个内部订单查询接口、数据库只读账号、脚本执行器甚至让它操作浏览器。工具越多权限管理就越重要。我建议按用户维度做分级普通员工只能调用只读类工具管理员可以调用变更类工具敏感操作比如删除数据、重启服务必须二次确认。二次确认的实现也不复杂机器人收到意图后先回一句“确认要执行 XX 操作吗”用户回复确认后再真正执行。这个交互虽然多了一步但能挡住绝大部分误触。5.3 主动推送定时任务怎么写机器人不只是被动响应还可以主动推送。这个特别适合做定时汇报、告警通知和晨报推送。实现方式有两种。一种是用外部 Cron 定时调飞书消息接口把 OpenClaw 当消息发送器用另一种是 OpenClaw 自己内置的调度器在配置里写定时任务。主动推送最麻烦的是拿chat_id。我的经验是让机器人先进群在群里说一句话然后从事件日志里捞这条消息的chat_id之后推送就稳稳的。不要去猜群 ID猜错的概率非常高。推送频率也要克制飞书对主动消息有频控限制超了会被暂时封禁消息能力。宁可少推几次也不要变成骚扰。6. 踩坑实录六个典型问题从根因到解决6.1 回调 URL 校验失败第一次配 Webhook 时飞书后台一直提示校验失败。排查过程是这样的先用curl手动请求回调 URL确认服务本身能通再看响应内容发现返回的不是飞书要求的challenge原文。问题出在 OpenClaw 的配置里回调路径和实际暴露的路径不一致事件请求打到 404 上了。后来干脆切换到长连接模式直接绕开了这个麻烦。如果你一定要用 Webhook记得确认两点URL 必须公网可达、响应必须包含正确的challenge。6.2 私聊正常、群聊就是不回复这个问题的现象很典型机器人私聊能秒回但在群里 它半天没反应。第一反应以为是白名单配置问题查了一圈都没问题最后发现是权限列表里没开im:message.group_at_msg这项权限。更隐蔽的是开通权限后要在飞书后台创建新版本并发布权限才会生效。我当时开通了权限但忘了重新发布结果群聊还是不响应后来重新发布版本才恢复正常。所以排查这类问题时记得把“发布版本”也当做一个检查项。6.3 长连接反复断开、重连长连接模式用了一天后发现日志里有大量断线重连记录每几分钟一次很规律。先怀疑是网络问题后来发现是服务端某条任务线程阻塞把心跳超时拖爆了。排查方法是在日志里找到断连时间点看同一时间有没有正在执行的工具调用或模型请求。如果有基本就是任务阻塞拖垮了心跳。解决办法是给工具调用加上超时上限让它到点就放弃别一直占着线程。6.4 回复消息报 invalid content某次机器人回复长文本时发送接口报了 invalid content 错误。原因是 OpenClaw 往飞书发消息时消息正文必须是 JSON 字符串格式而这个 JSON 字符串里如果有换行或特殊字符没做转义就会被飞书拒掉。这类问题最终的修复都是同一句话content字段必须是合法 JSON 字符串文本内容要先json.dumps再放进content字段别手写字符串拼接。6.5 模型输出太慢表现为“已读不回”机器人像真的读了你消息但一直不回复。查日志发现事件收到了模型调用耗时 40 多秒还没返回飞书那边消息一直在等待状态。原因是大模型在高负载时段推理变慢而飞书 Webhook 模式对响应时间有严格限制超时后这次请求就算失败了。两个解法一是把 OpenClaw 切到长连接模式事件确认响应和业务处理解耦二是把长耗时任务改成异步机器人先回一句“收到稍等”处理完成后主动推结果。6.6 配置改了重启动但行为一点没变有段时间我改了配置文件里的白名单重启容器后测试发现新配置完全不生效。查了很久才发现 Docker 挂载的配置路径写错了我改的是宿主机上的文件但容器实际读的是镜像里自带的旧配置。这类问题的通用排查法是进容器里确认实际读取的配置文件内容和挂载路径是否一致用docker exec看看容器里的文件而不是只看宿主机上改了什么。配置文件的修改一定要先确认它真的是服务实际加载的那一份。7. 生产落地稳定性、安全与扩展7.1 进程守护和优雅重启本地玩和长期跑是两码事。OpenClaw 挂在飞书上同事随时可能发消息进程一挂体验就崩了。部署时我建议容器加--restart unless-stopped让 Docker 自动拉起进程另外配一个健康检查脚本定期检查服务端口和长连接状态。优雅重启也很重要。更新配置时尽量用 Docker 的平滑停止再启动避免直接kill -9。OpenClaw 在长连接模式下重启会带来短暂的消息丢失窗口这是必然的选在低峰时段重启即可。7.2 安全边界机器人能做的事越多安全边界越要画清楚。我的底线是三条第一App Secret 和模型 API Key 绝不进代码库放环境变量或者密钥管理工具里。第二allowed_user_ids必须配置默认拒绝所有用户不如不接。第三敏感工具比如执行命令、删除资源全部二次确认并且把操作日志单独归档方便事后追溯。另外日志里的消息正文可能包含敏感信息推进日志的时候最好做脱敏处理至少把手机号、token 之类的高危字段过滤掉。7.3 扩展方向跑顺一个机器人之后可以继续做的事情不少。比如按部门拆机器人运营一个、研发一个各自挂不同的工具集也可以做多通道聚合同一个 OpenClaw 实例同时接飞书和另一个 IM 平台一套逻辑两边复用。我最后想说的是做这类集成顺序真的很重要。先把通道跑通再上模型最后才上工具每一层单独验证。我第一次直接全都配好结果连问题出在哪都找不到。先把最小的闭环焊死后面所有功能都在这条已验证的链路上叠加你会发现自己省下来的调试时间比想象中多得多。