OpenClaw 接入飞书全攻略：从自建应用到智能体消息收发与表格联动

把 OpenClaw 接进飞书这件事我从一开始就觉得是早晚要做的。单机跑 AI 智能体再爽终究只是自己玩一旦团队日常消息、审批提醒、数据表格全都沉淀在飞书里而 AI 助手还活在命令行和浏览器标签页里这个割裂感会越来越重。这篇指南我打算把从零开始接入飞书的完整路径写清楚飞书开放平台怎么配置、OpenClaw 的 channel 怎么调、消息怎么收发、表格文件怎么推以及我踩过的几个比较隐蔽的坑。不管你是刚把 OpenClaw 跑起来的新手还是已经在本地部署过多个 agent 的老手照着这篇文章走一遍应该都能少走不少弯路。1. 先想清楚让 OpenClaw 上飞书到底要解决什么1.1 OpenClaw 在团队场景里的定位OpenClaw 本质上是一个开源的智能体执行框架它把大模型、工具调用、外部渠道这三层串在一起。你给它接上模型它能做推理给它接上工具它能执行搜索、计算、读写文件给它接上渠道它就能从一个藏在终端里的进程变成团队成员随时可以 一下的助手。前两篇指南已经把安装和基础配置讲完了那时候它还是单机版所有交互都靠命令行或者网页端说实话只适合开发者自娱自乐。一旦落到团队场景需求就变了。团队里不是每个人都有命令行也不是每个人都愿意打开一个网页去问 AI 问题。大家最习惯的动作就是在一个群里 一个机器人然后等它回复。OpenClaw 接入飞书之后这个机器人就有了统一入口它可以回答群里的提问可以把生成的结果整理成飞书消息卡片可以把 CSV、Excel 表格推到群里甚至可以反过来读写飞书多维表格里的业务数据。这才是团队 AI 助手该有的样子。我能想到的典型场景包括运营同学每天让 AI 汇总昨天的数据并生成一张表格发到群里研发同学把发布检查清单交给 AI让它定时提醒产品同学把用户反馈粘贴到多维表格里AI 自动分类打标签。所有这些动作都可以通过飞书这一个入口完成。1.2 为什么选自建应用机器人而不是群自定义机器人飞书里最容易被误用的就是群自定义机器人也就是往群里加一个 Webhook 地址。它有一个致命限制只能主动推送消息接不到用户发来的消息也感知不到 。你想让 AI 像真人一样在群里被 然后回复自定义机器人完全做不到。它适合的场景只有一个单向告警通知比如监控系统往群里扔一条服务挂了的告警。OpenClaw 需要的是双向交互所以必须走企业自建应用这条路。自建应用可以提供完整的机器人能力能接收消息事件、能拿到发送者身份、能调 API 发消息、能上传文件、能操作多维表格。虽然配置步骤比自定义机器人多不少但多出来的每一步都是能力边界。我见过有人图省事先用 Webhook 机器人凑合结果后面每次想做交互功能都卡住最后还得回头重新建应用白白浪费半天时间。另外一个理由是权限可控。自建应用里你可以精确到这个机器人只能读哪些消息、写哪些表格这对企业场景非常重要。自定义机器人一旦拿到 Webhook 地址谁都能往群里发消息出了问题连个审计都做不了。1.3 整条链路长什么样把架构讲清楚后面配置就不会懵。OpenClaw 接飞书之后一次完整的消息交互大概是这样的用户先在飞书群里 机器人或者在私聊里给机器人发一句话。飞书开放平台不会直接把消息推到 OpenClaw而是先触发一个事件通知。如果配置的是事件订阅 Webhook 模式飞书会向 OpenClaw 暴露出来的回调地址发一个 HTTPS 请求如果配置的是长连接模式飞书会把事件通过 WebSocket 长连接推给 OpenClaw。OpenClaw 的 Feishu Channel 模块收到事件后会先做合法性校验然后解析出消息内容、发送者、群 ID 这些信息再交给后面的 Agent 核心去处理。Agent 拿到消息后调用大模型做推理必要时触发工具调用比如查数据库、读文件、调第三方 API。整个过程跑完后OpenClaw 会生成回复内容再通过消息发送接口把结果推回飞书。回复的形式可以是普通文本、富文本、消息卡片也可以先上传一个文件再发一条文件消息。这条链路里最容易出问题的不是 OpenClaw 本身而是飞书侧的事件订阅和权限配置。所以我建议你把这张链路图记在脑子里后面每配一项都想想它在这条链路的哪个位置出了问题时排查起来会快很多。2. 飞书开放平台这边先把手续办齐2.1 创建自建应用并开通机器人能力接入飞书的第一步是到飞书开放平台创建一个企业自建应用。进入开发者后台后选择企业自建应用填应用名称和描述比如团队 AI 助手。创建完成后你会进入应用详情页这里有几个关键信息需要记下来App ID、App Secret这两个值后面配置 OpenClaw 时必填。接下来要开启机器人能力。在应用能力里找到机器人点击启用。这一步做完应用就有了机器人的身份可以在飞书里被搜索到、被拉进群、被 。这里提醒一句应用创建后默认只有你自己能看见和试用想让团队其他人也能用需要发布应用版本并通过审核或者把可用范围设置成全员。我建议开发阶段先用可用范围 仅自己来测试测试通过后再扩大范围。创建应用时还要确定可见范围。这个选项经常被忽略但实际影响很大如果可见范围只包含几个人那么群里的其他人 机器人时会提示机器人不在可用范围内。所以接入团队场景时直接设置为全员可用后续如果担心权限再单独通过机器人能力里的权限配置去限制。2.2 配置事件订阅长连接与 Webhook 怎么选自建应用建好后要给它配置消息接收能力。在应用的事件订阅页面飞书提供两种接收方式长连接和 Webhook 回调。这两种方式我在前面架构里都提到了这里详细说说怎么选。长连接模式是飞书通过 WebSocket 主动把事件推给你的应用不需要你有公网地址也不需要在服务器上开放端口。这个模式对自托管 OpenClaw 的场景特别友好因为大多数人的 OpenClaw 跑在家里 NAS、公司内网服务器或者个人电脑上根本没有公网 IP。如果你用长连接模式整个配置过程只需要在飞书后台订阅事件然后在 OpenClaw 里填入 App ID 和 App Secret它会主动去飞书建立长连接非常简单。Webhook 模式则需要你提供一个公网可访问的 HTTPS 回调地址。飞书服务器会往这个地址发送 POST 请求。如果你的 OpenClaw 已经部署在云服务器上并且有域名和 HTTPS 证书用 Webhook 也完全可以。但要注意飞书会校验回调地址的 URL 有效性配置时必须能快速响应飞书发送的 challenge 验证请求。OpenClaw 内置了回调服务和校验逻辑所以你只需要在 OpenClaw 配置里填好回调路由和加密参数。我的建议很简单本地调试、内网环境、没有域名一律用长连接已经有公网服务器且追求更稳定的生产环境再考虑 Webhook。长连接模式还有一个好处飞书侧会自动维持心跳重连OpenClaw 一旦断线会自动恢复省去很多运维工作。2.3 权限点梳理能少给就少给飞书开放平台的权限模型是所有问题的高发区。每个 API 调用都会校验应用是否申请了对应的权限点哪怕机器人已经启用只要权限点没开调用就报错。接 OpenClaw 时我建议按需开通以下几类权限。第一类是消息权限。收发单聊消息、群聊消息、读取消息内容、发送消息这些都需要对应的权限点。在开发者后台的权限管理里搜索读取用户发给机器人的单聊消息获取群组中所有消息获取与发送单聊、群组消息并开启。第二类是文件权限主要是上传文件、下载文件对应通过接口上传文件读取云空间文件等。第三类是多维表格权限比如查看多维表格编辑多维表格这取决于你是否要让 AI 读写 bitable 数据。这里有一条非常重要的实践经验权限点不是越多越好。你多开一个权限就意味着应用被攻破时的爆炸半径大一圈。我见过有人在群里分享飞书机器人配置时直接给了全部权限后面运维时根本分不清哪些是必要的。我的习惯是先用最小权限集跑通功能缺哪个权限再补哪个。OpenClaw 的日志对权限缺失的报错一般都很明确照着日志补就行。3. 把 OpenClaw 接到飞书从配置到第一条消息3.1 OpenClaw 的 channel 配置入口与参数OpenClaw 的渠道配置一般在主配置文件里路径通常是~/.openclaw/config.yaml或者部署目录下的config/config.yaml不同版本略有差异。打开配置文件你会看到类似channels这样的顶层字段里面可以按渠道名配置多个连接器。接飞书时我们就在这个区块下加一个feishu节点。配置里核心参数有以下几项app_id填飞书应用的 App IDapp_secret填应用密钥encrypt_key填事件订阅里的 Encrypt Key如果启用了加密verification_token填校验 Tokenevent_mode用来指定长连接还是 Webhook。如果选择 Webhook 回调模式还需要配置webhook_path或callback_urlOpenClaw 会在这个路径上启动 HTTP 服务接收飞书事件。这里我建议把敏感配置放到环境变量里不要直接写死在配置文件里。比如FEISHU_APP_ID、FEISHU_APP_SECRET这些环境变量OpenClaw 在读取配置时会优先用环境变量覆盖默认值。这样做的好处有两个一是配置文件可以放心提交到 Git 仓库不泄露密钥二是换环境部署时不用改配置只改环境变量就行。配置好之后重启 OpenClaw 服务观察启动日志。如果一切正常你会看到类似feishu channel connected或websocket connected的日志。如果是长连接模式这里就说明已经和飞书服务器成功建立起连接了。这一步是整个接入过程中最关键的一次验证连不上后面全白搭。3.2 验证连通性向 AI 助手打个招呼服务启动日志正常不代表消息链路就是通的。我第一次接的时候就被这个假象骗过日志显示连接成功但是给机器人发消息完全没有反应。后来排查发现是因为飞书后台事件订阅里没勾选对应的消息事件。所以配置文件只是第一步你还需要在飞书开发后台把需要接收的事件添加到订阅列表里。要接收消息至少要在事件订阅里添加两个事件im.message.receive_v1接收消息和im.message.reply_v1接收消息回复按需添加。添加完事件后把应用保存并发布新版本。开发阶段如果可见范围是仅自己直接保存即可生效如果可见范围较大则需要发布一个应用版本。验证方法很简单在飞书里找到你的机器人先发一条私聊消息。正常情况下OpenClaw 的日志里会打印出收到消息的事件信息随后 AI 的回复会出现在聊天窗口里。这里我建议你先问一个不需要工具调用的简单问题比如你好你是谁先把消息链路跑通再逐步增加复杂任务。很多人在这一步直接让 AI 写代码、查数据库一旦没回就不知道是链路问题还是工具问题排查起来非常被动。3.3 让 AI 理解 指令和群聊上下文私聊消息跑通之后下一步是群聊场景。把机器人拉进一个测试群在群里 它并提问。这里涉及到一个问题OpenClaw 需要能识别消息中是否提到了自己以及提取出真正有效的指令内容。飞书的消息事件负载里会带有mention列表里面包含被 的机器人信息。OpenClaw 的 Feishu Channel 模块会解析这个字段把纯指令文本去掉 部分传给 Agent。你不需要自己手写解析逻辑但需要确认配置里是否开启了仅在被 时响应的模式。如果没开启机器人可能会对群里所有消息都做响应容易造成刷屏也容易被其他机器人的消息带偏。关于上下文上下文OpenClaw 默认会保留会话历史但不同会话之间是隔离的。群聊里它会以chat_id sender_id作为会话维度私聊里以open_id作为维度。这里要特别注意如果你希望机器人在群里对所有人都共享同一个上下文比如它是一个项目助手所有人都问同一个项目的问题可以关闭按发送者隔离改成按群维度共享上下文。具体配置项一般是session_key相关的参数按自己的需求调整即可。4. 进阶玩法不只是聊天还能发表格、写多维表格4.1 让 AI 把结果整理成富文本卡片或表格文件消息收发跑通后你会发现纯文本回复在团队场景里有点不够用。AI 生成一段分析结果如果只是文字阅读体验很差如果是一个数据表直接发 CSV 文件又不够直观。这时候有两个改造方向用消息卡片承载结构化内容或者生成表格文件发到群里。消息卡片是飞书里比较推荐的展示形式。OpenClaw 如果支持interactive消息类型你就可以让 AI 把结果包装成一张卡片包含标题、字段列表、按钮等元素。比如 AI 汇总了三份周报你可以让它把结论放在卡片的头部把关键数据用字段形式列出来重点内容加粗。卡片内容比长文本轻量在移动端飞书里阅读体验尤其好。表格文件则适合数据量大的场景。OpenClaw 可以调用一个本地的表格生成工具把 AI 整理好的结构化数据写成 CSV 或 Excel 文件然后调用飞书上传文件接口im/v1/files拿到file_key之后再调用发送消息接口推送文件消息。我个人的建议是行数少于 50 且不需要二次编辑时用 CSV需要格式、颜色、多 sheet 时用 Excel 库生成 xlsx。飞书本身对 CSV 的预览支持得不错但移动端打开 xlsx 要比 CSV 直观很多。4.2 从问一句答一句到定时任务自动汇报OpenClaw 这类智能体框架的另一个价值是支持定时触发任务。你不需要每次都有人去群里 机器人而是可以设定一个 Cron 表达式让它在每天固定时间自动跑一个工作流把结果推送到指定的飞书群。我实际搭过的一个场景是日报助手每天早上 9 点OpenClaw 自动读取前一天的运营数据调用大模型生成一段摘要再生成一张包含核心指标的表格通过飞书机器人推送到运营群里。整个流程不需要任何人手动触发群成员每天早上打开飞书就能看到结果。实现这个能力关键点有两个。第一是 OpenClaw 的定时任务模块要支持配置目标渠道也就是告诉它任务执行完后消息发到哪个飞书群。这个一般会绑定一个固定的chat_id你可以通过飞书 API 或抓包获取群 ID。第二是任务的输出要做成结构化模板。日报不能每次格式都不一样所以我会在提示词里给 AI 规定输出格式比如必须包含昨日数据、环比变化、今日重点三个部分然后通过模板渲染成消息卡片。这里建议把提示词单独放在一个文件里管理改版时不影响主配置。定时任务上线前一定要先手动跑一遍确认输出格式和推送目标都没问题。我第一次上线日报助手时忘了改推送 chat_id结果日报被推送到一个无关的测试群虽然没造成严重后果但团队里的人都看到了乱七八糟的测试数据印象分掉得很严重。4.3 多维表格联动AI 直接读写业务数据飞书多维表格Bitable是一个很有威力的功能它本质上是轻量级的数据库却又具备在线协作表格的易用性。OpenClaw 如果接入了多维表格 API就能做到很多之前需要人工完成的事情比如把群里不结构化的讨论内容转成表格记录、把 AI 生成的排期写进表格、按条件筛选表格数据并生成报表。操作多维表格的 API 路径是bitable/v1/apps/{app_token}/tables/{table_id}/records需要先获取多维表格的app_token和table_id。这两个值在飞书多维表格的 URL 里可以直接看到。在 OpenClaw 侧我建议把对多维表格的操作封装成一个独立工具让它具备添加记录查询记录更新记录删除记录四个基本方法。封装时要注意参数校验尤其是字段名和字段类型多维表格对类型要求很严格你把数字写成了字符串接口会直接报错。我做过一个比较实用的联动让 AI 每天定时扫描一个用户反馈多维表格把新增的反馈按关键词自动打标签然后生成一份汇总表发到群里。操作流程是先调用查询记录接口按更新时间过滤出新数据再调用大模型做分类和标签提取最后调用更新记录接口把标签写回表格对应字段。整个过程里大模型负责理解语义API 负责读写数据飞书只负责最终展示。这个模式你可以直接复制到很多业务场景里比如客户工单分类、招聘简历初筛、市场线索标签化。5. 踩坑实录输出截断、消息收不到、权限报错5.1 飞书里 AI 输出被截断大概率是这几种原因OpenClaw 在飞书输出容易被截断是搜索热词里反复出现的问题我猜大家遇到的情况都差不多AI 在终端里能完整输出一大段内容但到了飞书里只显示一半或者干脆提示消息过长。这里面其实有三种不同的原因处理方式完全不同但很多人混在一起排查越查越乱。第一种是飞书消息接口本身的长度限制。飞书对单条文本消息的长度限制大约是 150KB一般来说正常回复不会触到这个上限但如果你让 AI 生成了很长的代码或长文档就有可能在发送层被截断。第二种是 OpenClaw 在发送时把消息拆成了多个分段而飞书客户端对连续消息有折叠逻辑看起来像被截断了实际只是展示问题。第三种是最常见的模型输出长度本身就有限制上下文窗口一长AI 在生成过程中就被截断根本轮不到飞书参与。针对第一种和第二种我建议把大段输出改成一个富文本卡片或直接生成文件发送。针对第三种则要检查 OpenClaw 里对模型上下文的设置。平时我会做一些保护措施在工具层对输出做长度检测超过一定阈值就自动触发写成文件并发送的分支同时告诉模型当内容超过预期长度时先给摘要详细内容保存为附件。5.2 事件订阅收不到消息按这个顺序排查收不到消息的问题我免费告诉你一个高效的排查顺序照着这个顺序走基本能在十分钟内定位。第一步看 OpenClaw 日志里有没有收到事件。如果日志里连事件都没有说明飞书的通知根本没到达问题出在订阅或网络链路上。第二步检查飞书后台事件订阅是否真的添加了im.message.receive_v1事件很多人配置了长连接却忘了加事件导致连接虽在但没有任何消息推送进来。第三步检查版本发布状态。开发阶段改的事件在保存并发布之前不会生效如果你只是保存了但没发新版本线上应用跑的还是旧配置。第四步确认应用是否在飞书侧的可用范围内。如果机器人没有被某个成员可见该成员即使拉它进群也无法触发消息事件。第五步检查 Encrypt Key 是否一致。如果事件订阅开启了加密OpenClaw 里的encrypt_key必须和飞书后台完全一致否则解密失败消息会被静默丢弃。按这个顺序排查我还没有遇到过查不出来的情况。反过来你要是东看一眼西看一眼很容易在一个错误方向上耗掉一晚上。5.3 高频报错码速查表接入飞书过程中会遇到不少报错有些报错码一看就知道问题有些则需要查文档。以下是我实际遇到频率比较高的几类整理成一个速查表方便你对照。报错码/现象原因处理办法code10001请求参数错误通常是 App ID 或消息字段格式不对对照 API 文档检查请求体重点看 receive_id、msg_typecode99991661应用没有对应权限点去飞书后台权限管理补齐对应权限并重新发布版本code99991663机器人能力未开启或应用不可用确认应用已启用机器人能力发布状态为可用code230002多维表格字段类型不匹配检查 records 里的字段值和表格列的字段类型是否一致app_ticket 过期获取 tenant_access_token 时缺少 app_ticket检查是否已订阅app_ticket事件并配置好 ticket 缓存事件订阅验证失败回调地址未正确处理 challenge 请求检查 OpenClaw 的回调服务是否正常响应 GET 验证请求长连接频繁断开网络波动或连接数超限检查网络稳定性开启 OpenClaw 的重连机制必要时改用 Webhook 模式这张表不是让你背下来而是遇到类似问题时有个索引。飞书开放平台的错误码体系偶尔会调整所以最终答案请以官方错误码文档为准。但排查思路是不变的先分清是权限问题、参数问题还是网络问题然后对症下药。我在接入 OpenClaw 和飞书的过程中最大的体会是这条链路里 80% 的问题都出在配置同步上。飞书后台改一个配置OpenClaw 这边没重启OpenClaw 改一个参数飞书事件订阅没更新两边各改各的最后链路就断了。所以后来我养成一个习惯每次修改任何一侧的配置后都按改配置 → 重启服务 → 发条测试消息 → 看日志这个循环走一遍确认无误后再继续下一个改动。另一个小技巧是在飞书后台把事件订阅的加密先关掉等整个链路跑通了再开加密否则加密配置一旦有问题你连日志里的事件内容都看不到排查难度会成倍上升。最后如果你准备把这件事做成团队正式功能建议在发布前做一次权限最小化审查把用不到的权限点全部移除这是对自己也是对团队负责。