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 ID，app_secret填应用密钥，encrypt_key填事件订阅里的 Encrypt Key（如果启用了加密），verification_token填校验 Token，event_mode用来指定长连接还是 Webhook。如果选择 Webhook 回调模式，还需要配置webhook_path或callback_url，OpenClaw 会在这个路径上启动 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 高频报错码速查表

接入飞书过程中会遇到不少报错，有些报错码一看就知道问题，有些则需要查文档。以下是我实际遇到频率比较高的几类，整理成一个速查表方便你对照。

这张表不是让你背下来，而是遇到类似问题时有个索引。飞书开放平台的错误码体系偶尔会调整，所以最终答案请以官方错误码文档为准。但排查思路是不变的：先分清是权限问题、参数问题还是网络问题，然后对症下药。

我在接入 OpenClaw 和飞书的过程中，最大的体会是：这条链路里 80% 的问题都出在配置同步上。飞书后台改一个配置，OpenClaw 这边没重启；OpenClaw 改一个参数，飞书事件订阅没更新；两边各改各的，最后链路就断了。所以后来我养成一个习惯：每次修改任何一侧的配置后，都按"改配置 → 重启服务 → 发条测试消息 → 看日志"这个循环走一遍，确认无误后再继续下一个改动。另一个小技巧是，在飞书后台把事件订阅的加密先关掉，等整个链路跑通了再开加密，否则加密配置一旦有问题，你连日志里的事件内容都看不到，排查难度会成倍上升。最后，如果你准备把这件事做成团队正式功能，建议在发布前做一次权限最小化审查，把用不到的权限点全部移除，这是对自己也是对团队负责。