手把手教你用 OpenClaw 飞书打造专属 AI 机器人先说结论这套组合最大的价值是让你用一个晚上就能把“能对话、能查资料、能跑定时任务、能对接各种工具”的机器人直接搬进飞书工作台里。不去折腾那些需要企业资质、要审批流程的开放平台也能拥有一个完全属于自己的 AI 助手。我前后折腾了两天踩了配置、回调、权限三个大坑最后跑通的时候才意识到OpenClaw 和飞书的配合其实非常简单90% 的时间都浪费在“不知道飞书机器人需要什么格式的响应”上。这篇文章把整个流程拆开揉碎讲清楚从飞书开放平台配置到 OpenClaw 接入再到实际使用场景和排错思路全部是基于我实际跑通过的版本不是抄文档。1. 为什么是 OpenClaw 飞书而不是直接调 API很多朋友一听到“AI 机器人”第一反应是去接大模型的 API然后写个 Web 服务再挂个前端。这个思路本身没有问题但如果你是给团队或者自己用会立刻遇到三件麻烦事服务器要一直开着、轮询和回调要自己写、对话记录和工具调用得自己做状态管理。这些活儿听起来不大真正做起来就是无底洞。OpenClaw 解决的恰恰是后面两件事。它是一个偏“个人代理”形态的工具自带任务编排、工具调用、记忆和定时触发能力。你不需要为它单独维护一套复杂的调度系统也不需要把每次对话的状态塞进数据库它自己会处理。飞书这边负责的是“入口”和“消息触达”同事在群里 机器人或者直接私聊机器人消息会变成 Webhook 推送给 OpenClawOpenClaw 处理完之后再通过飞书的消息接口把回复发回去。1.1 OpenClaw 在我这里的定位我不太建议把它理解成一个“大模型套壳”。从实际使用来看它更像是“一个带手和脚的对话引擎”——它能调用工具、能记住上下文、能定时执行任务、能主动推送结果。举个具体例子我让它每天早上 9 点抓取某个页面的更新摘要然后推到飞书群里这个流程里我没有写一行定时任务代码OpenClaw 内部的调度机制就完成了。如果你之前接触过类似的框架应该知道这类工具最头疼的两块一是怎么把外部系统接进来二是怎么保证对话不跑偏。OpenClaw 对这两块的解法都比较成熟这也是我选它的核心原因后面会展开讲。1.2 飞书在这套方案里的角色飞书这边不需要写后端它充当的是“消息层”用户在飞书里发消息飞书把这个消息通过事件订阅的方式推给你配置的回调地址你的服务也就是 OpenClaw处理完再调用飞书的 API 发消息。整套链路里飞书只负责“传话”真正的 AI 逻辑全在 OpenClaw 那边。所以我们需要准备的实际上只有三样东西一个能跑 OpenClaw 的环境本地电脑也可以但推荐云服务器、一个飞书开放平台账号、以及一个用于接收事件回调的公网可访问地址。第三样是绝大部分人卡住的地方我后面会专门讲怎么处理。2. 从零搭建环境准备和工具选型2.1 环境要求我当前的运行环境是 Ubuntu 22.04 云服务器配置是 2C4G。OpenClaw 本身不算吃资源单独跑一个实例占用内存大约在 300MB 到 500MB 之间但如果后续要接本地模型或者跑一些重型工具内存最好升到 8G。如果你只是想先体验一下用自己电脑的 Docker Desktop 也完全够了后面我从 Docker 方式开始讲。我建议不管你是用云服务器还是本地机器都用 Docker 来跑 OpenClaw理由很简单依赖隔离、升级方便、出了问题可以整个容器删掉重建。OpenClaw 官方提供了镜像拉下来直接跑就行。如果你要修改配置只需要挂载一个目录进去不用动容器内部文件。2.2 飞书应用的创建流程在开始之前先去飞书开放平台open.feishu.cn创建一个“企业自建应用”。注意不要选“商店应用”自建应用适合内部使用权限控制和审核流程都简单得多。创建好之后你会进入应用后台此时需要做下面几件事启用“机器人”能力。在应用的能力配置页里添加“机器人”这样你的应用才有收发消息的资格。配置“事件与回调”。订阅方式选择“推送方式”请求地址填你准备对外开放的 URL就是我们后面要讲的公网地址 /webhook事件选择“接收消息”。获取凭证。在“凭证与基础信息”页面拿到 App ID 和 App Secret这两个后面要填到 OpenClaw 配置里。配置权限。需要开通“读取用户发给机器人的单聊消息”和“给用户发送单聊消息”等权限具体操作路径在“权限管理”页面搜索下面列出的权限词然后开通。这里有一个很多教程不会提醒你的细节飞书的权限分“用户级”和“应用级”你不仅要开通应用权限还必须在“权限管理”里开启“获取用户 user ID”类权限否则 OpenClaw 回复消息时可能拿不到发送者身份导致消息串号或者失败。2.3 把回调地址变成公网地址的三种方式如果你的 OpenClaw 跑在云服务器上那云服务器的公网 IP 加上端口就是公网地址这一步不用额外处理。但如果你是在本地电脑上调试就需要一个内网穿透方案。我试过三种给你做个对比方案稳定性配置复杂度适用场景备注云服务器反向代理高中长期使用、正式环境建议用 Nginx 或 Caddy 转发到本地端口轻量内网穿透工具中低临时调试、本地验证免费版有域名和流量限制适合跑通流程局域网直连高低同办公室内网调试需要飞书回调地址可访问一般不行我最推荐的是直接用云服务器把 Nginx 配好之后回调地址就是https://你的域名/webhook一劳永逸。如果非要在本地调试可以用轻量内网穿透工具但别指望它做生产环境连接不稳定的时候消息会延迟甚至丢失。3. OpenClaw 的配置与启动这一步决定了你后面省不省心3.1 核心配置项详解OpenClaw 支持用配置文件或环境变量来做初始化我建议用环境变量因为容器重启不会丢失而且方便统一管理。最小可行的配置长这样# 飞书应用信息 FEISHU_APP_IDcli_xxxx FEISHU_APP_SECRETyour_app_secret # 飞书回调验证 token FEISHU_VERIFICATION_TOKENyour_verification_token # OpenClaw 的对外访问端口 OPENCLAW_PORT8080先别急着填这几个参数有几个要注意的坑第一FEISHU_APP_SECRET是飞书应用的密钥不是机器人 webhook 的地址。我一开始混淆过以为是飞书群里创建自定义机器人给的那个 Webhook 链接结果配上去一直报“invalid signature”折腾了半小时才发现是拿错了参数。第二FEISHU_VERIFICATION_TOKEN在飞书事件订阅的页面可以查到它用于飞书验证你的回调地址是否属于你自己。有些版本的事件订阅是使用签名校验Encrypt Key你还需要在配置里启用加密并填FEISHU_ENCRYPT_KEY。如果你不启用加密只填 verification token 就能通过但安全性会差一些建议开启。3.2 启动命令和首次验证配置好环境变量之后执行下面的命令启动容器docker run -d \ --name openclaw-feishu \ -p 8080:8080 \ -e FEISHU_APP_IDcli_xxxx \ -e FEISHU_APP_SECRETyour_app_secret \ -e FEISHU_VERIFICATION_TOKENyour_verification_token \ -e OPENCLAW_PORT8080 \ openclaw/feishu-bot:latest这里的镜像名是根据 OpenClaw 官方文档来的如果你本地没有对应镜像可以去它的项目页面看最新版本也可以直接用源码构建。启动之后先不要急着去飞书里发消息先用 curl 测一下回调地址curl -X POST https://你的域名/webhook -H Content-Type: application/json -d {challenge:test,token:your_verification_token}如果配置正确飞书要求回调接口在收到含有challenge字段的请求时原样返回该字段的值。你手动用 curl 模拟一次这样的请求OpenClaw 会返回一个 JSON包含challenge字段就说明回调链路已经通了。这一步能省掉后面大量排错时间。3.3 唯一让人有点懵的响应格式我在最开始提到90% 的时间浪费在“不知道飞书机器人需要什么格式的响应”上这里展开说一下。飞书事件订阅的回调接口不像普通 API 那样“返回一段文本”就行。它有两种工作模式如果启用的是“请求地址”模式飞书会向你的回调地址 POST 一个事件结构体你的服务处理完业务逻辑之后需要返回{code:0}或者其他飞书要求的成功标识告诉飞书“我收到了”。真正的回复内容是通过飞书 API 主动调用发出去的。如果是“长连接”模式飞书和你的服务之间会建立一个 WebSocket不需要暴露公网回调地址但 OpenClaw 需要支持这种模式才能用。大部分第三方机器人框架默认按“主动调用飞书 API”的方式实现OpenClaw 也是。所以你配置好之后看到回调接口返回成功但是飞书里没有收到任何消息不要慌先看两件事第一OpenClaw 的日志里有没有收到事件第二飞书应用的“机器人”是否已经发布并可见自建应用要发布版本之后才会有机器人入口。这里我额外提一个经验飞书自建应用默认是“测试中”状态只有你设置“版本发布”之后应用的机器人才能真正在工作台里被搜索到。很多初学朋友配置完发现飞书里搜不到机器人就是卡在这个地方。路径是应用后台 → 版本管理与发布 → 创建版本 → 提交审核自建应用一般秒过。发布完成后在飞书工作台里搜索你的应用名称就能看到机器人并开始对话了。4. 跑通第一轮对话把 AI 机器人抱进飞书群4.1 私聊机器人的最小验证发布应用之后在飞书工作台里找到刚刚创建的应用机器人点进去发送一条“你好”。正常情况下OpenClaw 的日志里会出现一条消息记录紧接着飞书里会收到回复。如果没反应从下面三处依次排查回调地址对不对在飞书事件订阅页面点“调试”看是否能收到飞书推送的事件。如果提示“URL 不可达”说明公网地址有问题如果提示“验签失败”说明 verification token 或加密密钥不对。权限开没开到权限管理页面确认“读取用户发给机器人的单聊消息”权限已开通并且“应用发布”已成功。OpenClaw 日志有没有报错进入容器查看docker logs -f openclaw-feishu看有没有收到飞书请求。如果连日志都没有大概率是回调地址没配对或者飞书压根没把消息推过来。我第一次跑这一步的时候卡在“验签失败”后来发现是 Nginx 部分把 POST 请求里的 body 吞掉了因为配置了重定向加上X-Forwarded-Proto也没有处理飞书请求到 OpenClaw 时签名校验用的原始 body 已经变了。这个属于环境问题本地没配置 Nginx 的话一般不会遇到。4.2 群聊 机器人的配置要点私聊跑通之后把机器人拉进群聊就是顺理成章的事。群聊需要额外配置两个权限“获取群组信息”和“读取群消息”否则机器人无法识别群里谁 了它。此外在飞书事件订阅的事件列表里需要增加“接收消息群聊事件”的事件才能收到群消息。一个比较实用的细节是OpenClaw 默认只响应“明确 机器人”的消息不会对群里所有聊天都回复这个行为我觉得很合理。如果你想让机器人在群里做更多主动操作比如定时推送不需要依赖用户 直接由 OpenClaw 调用飞书 API 发消息即可这个逻辑走的是主动 API 通道和事件订阅无关。4.3 多轮对话和上下文记忆OpenClaw 对多轮对话的处理方式是内置的。你不需要单独传历史消息它在内部会保留一定轮次的上下文并拼接给大模型。这个在单聊场景下特别省心但有两个注意点上下文长度有限。如果你问的问题特别长或者对话轮次特别多早期的记忆可能会被截断这时候你可以在配置里调整上下文轮数或者加长时间窗口。飞书的“机器人”和普通消息混在一起时OpenClaw 会过滤掉非 消息这个安全性不错但也会导致一个问题如果用户在小群说话但没有 机器人OpenClaw 不知道也不关心不要指望它“暗中观察”。如果你希望机器人能长期记住某类信息比如“我的项目代号是 X”我建议把这些信息写进 OpenClaw 的系统提示词或者记忆文件里而不是依赖对话上下文。对话上下文是短期的记忆文件和系统提示词才是长期的。5. 从“能聊天”到“能干活的 AI 助手”5.1 把定时任务推进飞书群聊天气泡不是这套组合的终点我真正想用的是“定时主动推送”。OpenClaw 支持 cron 类型的定时任务我配置了一个每天早上 9 点抓取某网站更新并推送摘要到飞书群的任务效果很稳定。配置方式大致是在 OpenClaw 的任务设置里添加一条 cron 表达式然后指定要执行的工具和输出群 ID。这里有一个坑飞书群的 ID 不是群名称也不是群链接里的那段字符而是需要在群设置里找到“群 ID”或用飞书开放平台的 API 查询。我一开始直接用群号结果发不出去换成群 ID 之后就好了。我的建议是先做一个“内容型”的定时任务定时抓取、定时提醒这个最不容易出错也最能体现价值。等你熟练之后再让它定时操作一些内部工具或者生成报告那时候你就能体会到为什么大家说“AI 助手不是聊天的是干活的”。5.2 工具调用让 AI 机器人有“手”有“脚”OpenClaw 的强项是工具调用。你可以在飞书里直接跟机器人说“帮我查一下某某网站今天热榜”它会自主调用抓取工具、处理内容然后回复你。这套流程背后其实是“大模型生成工具调用参数 → OpenClaw 执行工具 → 把执行结果拼回上下文 → 模型生成最终回复”。要做到这一步你需要配置两个部分OpenClaw 的工具配置把可用的工具比如网页抓取、搜索、通用查询注册进去。工具的操作权限有些工具涉及发送消息、修改数据建议谨慎授权避免机器人被 一下就执行了危险操作。我自己只开了只读类工具网页抓取、信息检索写操作类一律手动确认。这是因为机器人被 之后就自动执行写操作出问题不容易发现。如果你需要让它执行写操作建议加一个二次确认的提示词比如“你确定要执行吗”让用户确认后机器人再调用工具。5.3 实际使用中的几个场景参考整理几个我实际跑通的、比较务实的使用场景你可以直接抄作业场景实现方式效果每日资讯摘要定时任务 网页抓取工具每天早上在群里收到 3-5 条重点摘要会议纪要助手群聊 机器人 手动投喂文本机器人整理出待办事项和时间点项目进度播报定时任务 内部 API每天固定时间播报进展快捷知识库问答单聊机器人 记忆/检索工具团队内部信息快速检索这些场景的共同点是机器人的“主动性”大于“被动性”不完全依赖用户发消息。想让 AI 机器人在工作流里真正有用就要抓住“主动推送”和“工具调用”这两个点而不是只做问答。6. 排错经验汇总那些文档里不会写清楚的坑6.1 回调验签失败现场还原这是最常见的坑现象是在飞书事件订阅页面点调试提示“验签失败”或者完全没有收到事件。我当时的排查顺序是这样的先看 Nginx 日志确认飞书的请求是不是真的到达了服务器。用 curl 手动模拟飞书请求加上时间戳和签名看 OpenClaw 是否正确处理。把 Nginx 的proxy_pass配置里的proxy_request_buffering off;加上防止 body 被缓冲后改变原始请求。重新生成一次验证 token确保飞书后台保存的和 OpenClaw 里填的是同一个。最后发现问题出在步骤 3OpenClaw 对请求体的签名校验是用原始 body 做的任何一层代理如果修改了 body比如添加了换行、重排了字段都会导致签名不匹配。这个坑在新手阶段特别容易踩因为你很难想到问题会出在一个“透明代理”上。6.2 机器人不回复但日志没有报错这种情况比报错更让人头疼。我遇到过两次一次是自建应用没发布飞书里根本没有机器人入口外部消息也推不过来另一次是权限配置里漏开了“读取单聊消息”事件订阅通过但消息没被处理。处理建议先把应用发布到正式版或者至少发布一个测试版本再检查权限管理里的每一项是否都申请并开通了。飞书开放平台的权限调整很多是“修改后生效”但如果你不开通并发布事件订阅那边不会有完整的消息事件。6.3 消息乱序或者回复串号这个问题我是在对接某一个内部系统时遇到的现象是 A 用户问问题B 用户收到了回复。排查后发现是 OpenClaw 在处理并发时没有把 user ID 作为会话 key导致上下文串了。解决办法是在 OpenClaw 的会话配置里把消息来源chat_id和发送者sender_id一起作为会话标识。这个细节在官方文档里只是轻轻带过但实际使用中非常关键尤其是多用户同时私聊机器人的时候。6.4 本地调试的建议如果你不想买云服务器想在本地先跑通整个流程我建议配合轻量内网穿透工具把本地端口暴露到临时公网域名。但注意这类工具的免费版本通常会有域名有效期限制和访问频率限制只适合验证不适合长期使用。另一个建议是开一个飞书“测试企业”或者“开发版”应用不要在真实企业群里调试。开发版应用可以随便折腾权限和回调地址都可以反复改等确认没问题再迁移到正式环境。7. 配置清单和安全建议最后一部分给出我实际在用的配置参考你可以按照自己的情况改。7.1 一份可参考的最小配置清单配置项值示例说明FEISHU_APP_IDcli_xxxxxxxx飞书应用凭证FEISHU_APP_SECRETxxxxxxxx应用密钥注意保密FEISHU_VERIFICATION_TOKENxxxxxxxx事件订阅的验证 tokenOPENCLAW_PORT8080OpenClaw 服务端口OPENCLAW_CRON0 9 * * *定时任务 cron 表达式示例OPENCLAW_TOOLSweb_fetch,search启用的工具列表示例7.2 安全注意事项我不太建议直接把 App Secret 写进 Docker 启动命令里因为docker inspect能看到完整的环境变量有一定泄露风险。更好的做法是用 secret 文件或容器编排工具比如 docker-compose 的 env_file来加载环境变量并确保服务器上.env文件的权限是 600。回调地址的访问控制也很重要。飞书事件订阅的回调地址最好只接受飞书 IP 的请求或者至少加一层简单的鉴权。OpenClaw 本身会做签名校验但增加一层 Nginx 限制比如只允许飞书官方 IP 段访问会更稳妥。7.3 我踩过的最后一次坑希望对你有帮助就在我准备把这套配置写成文档的时候我突然发现之前设置了一条定时任务把某个群的消息内容摘要自动归档到内部知识库运行了三天都没问题。后来我换了个飞书应用忘记在任务里更新群 ID结果消息一直发不出去日志里也没有明显报错。最后是翻飞书 API 的返回码才发现原来是权限不足。这个教训让我意识到OpenClaw 层面只是调度和调用真正执行飞书消息发送时权限依然要落到飞书应用层面。任何“消息发不出去”的问题第一步永远先看飞书 API 返回的错误码比瞎改配置高效得多。搭建这套系统之后我最大的感受是AI 机器人不应该只是一个聊天窗口它应该能主动帮你盯消息、跑任务、汇总信息。OpenClaw 加飞书的组合把门槛降到了很低——不需要自己写消息服务不需要操心并发会话只要把调度逻辑想清楚就能拥有一个挺称手的效率工具。希望这篇记录能让你少踩几个我踩过的坑。
