开头约300字 这一两个月我一直在折腾OpenClaw和飞书之间的接入。起因特别朴素白天在飞书里收消息、看表格、接待办到了电脑前又得打开终端敲命令让智能体帮我跑脚本、写文档、同步笔记。两边来回切说实话挺累的。后来我把OpenClaw接到飞书机器人上直接在群里喊一句帮我把这块数据整理成多维表格它就能替我干完一整条链路。所以这篇不是什么官方文档解读就是我实际趟完一遍之后的保姆级接入指南。我会把飞书开放平台侧的申请、权限、事件订阅再到OpenClaw这边的消息收发、Skill封装以及我踩过的坑全部串起来讲。适合打算把智能体接进团队协作工具、又希望从零开始跑通的人也适合已经在用Claude Code/Codex这类终端智能体、想通过飞书随时随地指挥它们干活的玩家。1. 接入前先想清楚三件事OpenClaw、飞书应用和MCP链路1.1 OpenClaw到底是什么适合接飞书吗先说结论OpenClaw 属于社区里很典型的那类终端智能体框架——你在命令行里和它对话它能帮你拆任务、调工具、跑脚本、访问文件还能通过 MCP 协议挂载各种外部服务。简单类比它像一个给大模型装上手脚的壳模型负责想OpenClaw 负责做。OpenClaw 本身不绑定某一家大模型你既可以用云端 API 接入 DeepSeek、GLM、Qwen 这类模型也可以完全用本地模型跑。热词里有人问OpenClaw 只能用接入API的方式使用算力吗其实不是纯本地模型同样能跑通只是对机器配置有要求体验和响应速度会差一些。它适不适合接飞书我的答案是非常合适但前提是你不要指望把飞书变成 OpenClaw 的完整图形界面。飞书这边的定位是前台的指挥入口真正的计算、文件操作、外部请求仍然发生在运行 OpenClaw 的那台电脑或服务器上。飞书负责把一句话指令送进去再把结果以消息、卡片、文件、多维表格链接的形式抛回来。这样你在地铁上用手机就能指挥电脑干活这是最典型的落地场景。1.2 飞书侧的角色从群机器人到开放平台应用飞书机器人其实分两种很多人第一步就混淆了。一种是群聊里添加的自定义机器人本质是一个 Webhook 地址只能单向推消息不能让用户发消息给机器人再等它回复。另一种是企业自建应用里的机器人能力它才是双向的能接收用户消息也能主动发送消息还能调用云文档、多维表格、待办、日历等一堆开放接口。OpenClaw 要接入飞书必须走第二种。具体来说在飞书开放平台创建一个企业自建应用启用机器人能力然后通过事件订阅接收消息。这样用户在会话里 机器人 发消息OpenClaw 侧就能收到并处理。这里有个常见的误区很多人第一时间给群里拉了自定义机器人结果发现自己只能推不能收然后又去搜飞书机器人发送表格发现发是可以发但想要让机器人理解上下文、回复内容依然绕不开自建应用。所以不要省这一步。1.3 连接方式选型为什么我优先走开放API而不是模拟浏览器操作把 OpenClaw 和飞书连起来技术上大概有三条路方案原理优点缺点自建应用 事件订阅 开放API机器人接收消息调用飞书开放接口读写数据官方支持、稳定、可双向、可扩展全量接口需要配置应用权限前期有一定学习成本MCP Server例如 lark-mcp通过标准 MCP 协议把飞书能力挂到 OpenClaw 上让模型直接调用对 OpenClaw 最友好模型自己能决定何时读写表格/文档MCP 工具能力边界取决于服务端实现调试难度偏高模拟浏览器/RPA 操作用自动化工具操控飞书网页或客户端无需开放平台权限极易被风控维护成本高不推荐生产使用我自己实际用的是开放API 少量的 MCP 自定义工具混搭日常的消息收发由自建应用完成而多维表格、云文档、待办这类高频操作我会写几个轻量脚本封装成 OpenClaw 的 Skill让模型按需调用。这样既不会因为 MCP 协议调试卡住又能最快做出一个可用的闭环。后面第三、四章会分别详细讲这两段的实现。2. 飞书开放平台侧的准备自建应用、机器人权限与事件订阅2.1 创建企业自建应用勾对机器人能力打开飞书开放平台后台进入开发者后台选择创建企业自建应用。应用名称我建议起得直白一点比如OpenClaw 助手后面在飞书里搜索应用时不容易搞混。创建完成后第一件事是在应用能力里添加机器人。这一步会生成一个机器人它将以应用名的身份出现在会话中。创建完之后你会在凭证与基础信息里看到 App ID 和 App Secret。App ID 是公开的App Secret 是绝密的谁拿到谁就能冒充你的应用调用接口所以一定要放在配置文件里别提交到 Git 仓库。如果你用本地.env文件管理记得把.env加进.gitignore。这一点看似基础但我见过不止一个人把密钥贴到分享文档里最后被平台安全中心提醒。2.2 权限清单别一上来就 all in很多人一看到权限列表就全部勾选结果发布应用版本时审核变慢甚至因为申请了过多不必要的权限被驳回。更严重的是权限不是勾了就生效需要在权限管理里点击开通然后发布一个应用版本后台审核通过后才会真正生效。按照我的最小闭环需求核心权限其实就这么几类能力域权限标识用途消息收发im:message:send_as_bot机器人主动发送消息消息接收im:message.receive_v1事件接收用户发给机器人的消息云文档docx:document阅读/编辑读取/写入云文档云盘文件drive:drive阅读/编辑下载文件、遍历云盘多维表格bitable:app阅读/编辑读写多维表格待办task:task创建/更新创建飞书待办事项图片/文件素材im:resource发送图片、文件消息如果你只是先跑通消息对话只需要消息相关权限就够。表格、文档、待办这些权限可以等对应的 Skill 写好了再逐个加上去。哪怕后续被审核耽误一两天也比一上来就申请十几项权限被驳回强。2.3 事件订阅用长连接别急着搞公网回调这是整个接入里最容易卡住的一步。飞书开放平台支持两种事件接收方式Webhook 回调你提供一个公网可访问的 HTTPS 地址飞书把事件 POST 过来。要求你的服务器必须在公网而且响应要在几秒内返回否则触发重试。长连接WebSocket应用和飞书服务器之间维持一个长连接飞书把事件主动推到这个连接上。不需要公网 IP不需要配置回调地址非常适合个人电脑或内网环境。我的建议是本地开发阶段直接用长连接。飞书开放平台后台的事件订阅页面请求地址那一栏可以不填改为使用长连接接收事件然后通过飞书 SDK 启动长连接服务。代码实现在第三章会给到。等后面你确实有多人共用、需要部署到云端的时候再切换成 Webhook 回调也不迟。这个选择能帮你省掉一大半回调查验失败的烦恼。2.4 发布版本与自测先把自己加进可用范围在开发者后台的版本管理与发布里你需要创建版本并提交发布。个人开发场景应用可用范围建议先选择仅指定成员或全员但一定记得在自己的账号设置里确认已加入可用范围。如果没有这一步你给机器人发消息时会发现应用不可见或机器人不可用。提交发布后通常几分钟到几小时不等取决于组织管理员设置了什么审批流。第一次可以先把版本描述写清楚比如首次接入OpenClaw仅用于消息测试这样审批人看着也明白。测试时在飞书里直接搜索你的应用找到OpenClaw 助手创建一个私聊会话发一句你好看能否得到回复。如果这一步失败了先回头看事件订阅和权限开通不要急着去调 OpenClaw 的 Skill。3. 打通双向消息让OpenClaw在飞群里干活的核心配置3.1 消息能进来事件订阅到本地Bridge到这一步飞书侧的应用已经能接收消息事件了但事件还只是事件OpenClaw 并不知道有人喊了它。所以我们要写一个本地的 Bridge 服务它的职责是建立飞书长连接 → 收到消息 → 判断是否在喊机器人 → 把有效指令交给 OpenClaw 处理。这里我用 Node.js 写了一个极简版使用的是飞书官方 SDKimport lark from larksuiteoapi/node-sdk; const client new lark.Client({ appId: process.env.FEISHU_APP_ID, appSecret: process.env.FEISHU_APP_SECRET, appType: lark.AppType.SelfBuild, }); async function handleMessage(data) { const { message, sender } data.event; const text message.content; // 消息文本 const chatId message.chat_id; const openId sender.sender_id.open_id; // 只处理 机器人 或私聊消息避免群里所有消息都进来 const isAtBot text.includes(_user_1) || message.chat_type p2p; if (!isAtBot) return; // 交给 OpenClaw 处理拿回回复文本 const reply await askOpenClaw(stripAtMention(text)); // 回发到飞书会话 await client.im.message.create({ params: { receive_id_type: chat_id }, data: { receive_id: chatId, msg_type: text, content: JSON.stringify({ text: reply }), }, }); } client.ws.eventHandler.on(im.message.receive_v1, handleMessage); client.ws.start();这段代码的意图很明确长连接一旦建立飞书会把所有 IM 消息推过来但只有私聊或 到机器人的消息会被处理。askOpenClaw是你自定义的函数可以把清理后的文本通过 stdin 传给 OpenClaw 的命令行也可以调用 OpenClaw 暴露的 HTTP API。我自己用的是命令行方式因为 OpenClaw 本身就支持非交互式输入一条指令进去结果出来非常干净。3.2 多轮对话不能只靠一问一答如果你只做用户发一句模型回一句那用 Webhook 机器人都够了自建应用的意义不大。接入 OpenClaw 的真正价值是让飞书里的对话拥有上下文工具调用长任务执行能力。多轮对话的关键是维护chat_id与会话上下文之间的关系。我在 Bridge 里会在内存中维护一个MapchatId, history[]每次收到新消息就把 OpenClaw 返回的回复追加进历史下次提问时随消息一起传给 OpenClaw。这样飞书用户连续追问时OpenClaw 能记住上一个任务的结果。还有一点非常实用对于执行时间超过 10 秒的任务不要等 OpenClaw 跑完了再回消息否则飞书这边很容易判定无响应。我的做法是收到指令后先立刻回一条收到正在处理稍等然后异步跑任务完成后把结果再推到同一个会话。这就涉及飞书接收消息只代表拿到指令不代表必须同步回复你完全可以在 5 秒后或 1 分钟后再发消息飞书不会拦你。3.3 把OpenClaw的能力暴露成飞书会话里的命令词消息通了之后你会发现一个问题用户不知道该让机器人干什么。OpenClaw 本身是通用智能体你直接发一句帮我写周报它会尝试但如果没有任何约束它可能会随便编一个周报而不是基于你的多维表格数据。我的经验是把能力收敛成命令词。比如在 Bridge 里先做一层简单的命令路由/doc 链接请求读取飞书云文档内容/table 表格链接 追问内容请求读写多维表格/todo 事项 截止时间创建飞书待办/sync 云文档链接把文档下载并同步到本地 Obsidian 库命令词的好处是让用户有预期、让 OpenClaw 不用猜意图也方便后续把每条命令对应到具体 Skill。如果你想保留自由对话就在命令前缀之外把普通文本原样丢给 OpenClaw两条路并行。3.4 手机上的延伸Termux 跑 OpenClaw 是什么体验很多人搜索OpenClaw 安卓部署Termux 安装 OpenClaw 手机版我也试过。在 Termux 里跑 OpenClaw 基本可行安装 Node.js 环境拉相关依赖再把模型 API 配好命令行能正常启动。但说实话手机端的定位更适合做随身工控机轻量文本任务、笔记整理、简单脚本可以跑但如果你的 Skill 涉及大量文件处理或者调用飞书多维表格的批量接口手机的内存和续航会成为瓶颈。如果你确实想用安卓机承载 OpenClaw我建议把 Termux 里的 OpenClaw 当作 Bridge 的处理端而飞书长连接可以跑在同一台手机上也可以跑在电脑上两端通过网络互通。最简单的做法还是让电脑上的 OpenClaw 作为常驻服务手机只作为飞书消息的入口你在地铁上用手机发消息电脑那边处理完再推回到飞书。4. 从聊天到表格与云文档一个可复用的机器人Skill设计4.1 场景拆解用户真实高频用到的四类操作接入跑通后真正让 OpenClaw × 飞书变得有用的是它能处理结构化数据而不只是陪你聊两句。我根据日常使用频率把需求拆成四类收到一堆原始数据让机器人整理成多维表格并把表格链接发回来。在群里直接让机器人发一张表格/进度图它生成消息卡片或文件消息。把飞书云文档/云盘里的文件定时同步到本地 Obsidian 笔记库。把群里的对话沉淀成待办事项自动分配给指定负责人。每一类场景都适合做成一个独立的 OpenClaw Skill而不是全写死在 Bridge 里。Skill 的机制类似于给 OpenClaw 一份说明书工具脚本当一个任务匹配到某个 Skill 时它会自动调用脚本去执行。4.2 让机器人发送表格卡片和文件两条路先回答热词里那个飞书机器人发送表格。飞书机器人发表格其实有两条路第一条路是发消息卡片。在飞书 IM 接口的msg_type里传interactive卡片内容可以是结构化文本。虽然卡片没有原生的表格组件但卡片支持 Markdown 渲染你可以用 Markdown 表格语法把数据渲染成表格。下面是一个最小示例{ msg_type: interactive, card: { elements: [ { tag: markdown, content: | 项目 | 状态 | 负责人 |\n| --- | --- | --- |\n| 接入指南 | 已完成 | 张三 |\n| 云文档同步 | 进行中 | 李四 | } ] } }第二种是直接把数据整理成 Excel/CSV 文件发到会话里。做法是先调用飞书上传素材接口拿到file_key再通过消息接口发送file类型消息。对用户来说收到一个文件比收一张卡片更有可复用性。我在群里发周报时通常先让 OpenClaw 写一个 CSV再发文件消息顺带附一段文字总结。4.3 读写多维表格数据模型和批量更新多维表格是飞书里最像轻量数据库的功能OpenClaw 操作它时首先要理解三个 IDapp_token多维表格的唯一ID、table_id表ID、record_id记录ID。从分享链接里可以解析出来格式通常是https://xxx.feishu.cn/base/{app_token}?table{table_id}view{view_id}。我写了一个简单的通用工具脚本让 OpenClaw 调用它的核心逻辑只有三件事列出表格所有字段让模型知道每一列叫什么、是什么类型。按条件查询记录把结果转成 JSON 供模型阅读。批量新增/更新记录注意飞书接口单批次有数量限制如果数据量很大需要分批写入。热词里有人提到飞书多维表格上下合并其实就是多条记录的字段合并更新用批量更新接口逐个 record_id 更新即可注意别把已有字段覆盖成空值。这个脚本在 OpenClaw 里的 Skill 描述我是这样写的name: feishu_bitable description: 读写飞书多维表格。输入表格链接、操作类型query/create/update和字段数据输出操作结果。 script: python3 skills/feishu_bitable.py parameters: - name: table_url description: 飞书多维表格分享链接 required: true这样模型在看到帮我把这个链接里的表格筛选出未完成项时自动带着链接去调用脚本而不是凭记忆瞎编。4.4 同步飞书云文档到 ObsidianLark Sync思路热词里有lark sync同步飞书云盘到 obsidian。这背后其实是一个高频刚需飞书是协作编辑主场本地笔记库比如 Obsidian是个人知识沉淀主场两边经常不同步。我的实现思路分三步用飞书云盘接口遍历某个文件夹下的所有云文档拿到token和type。对文档类型是docx的调用导出接口把文档内容导出为 Markdown 或 Word。保存到指定的 Obsidian 库目录按文档标题命名并在 YAML frontmatter 里记录飞书文档链接和最近同步时间。# 伪代码实际使用时需要补全 token 刷新与错误处理 import requests def sync_doc(client, file_token, title): # 导出为 markdown resp client.drive.export_file(file_token, md) content resp.bytes with open(f{local_vault}/{title}.md, w, encodingutf-8) as f: f.write(content)这里最值得注意的坑是非 docx 类型的文档比如思维导图、电子表格导出的格式不同不要强统一。我目前只同步 docx 文档多维表格另走 API 导出为 CSV再手动归档。另外飞书的导出动作是异步的导出大文档时不要每个都现场等可以做一个延迟队列导出完成后再下载文件。否则脚本很容易超时。4.5 对接飞书待办把群聊变成任务池最后一个是待办场景。群聊里聊着聊着就容易冒出这个谁跟进一下那个下周三前弄完之类的碎片任务。让 OpenClaw 监听消息、识别待办并自动创建飞书任务是非常自然的能力扩展。飞书待办的开放接口不算复杂创建任务时指定summary任务标题、due截止时间可选指定members负责人。通常一个 Skill 就能搞定# 调用飞书任务接口 curl -X POST https://open.feishu.cn/open-apis/task/v2/tasks \ -H Authorization: Bearer ${FEISHU_TOKEN} \ -H Content-Type: application/json \ -d { summary: 撰写OpenClaw接入飞书的复盘文章, due: {timestamp: 1739404800}, members: [{id: ou_xxx, type: open_id}] }不过我不建议让 OpenClaw 自动把群里每句话都变成待办。群聊里噪声太多我目前的做法是只处理包含明确关键词的消息比如待办跟进下周三前记得等并且在创建前先回一句确认我准备创建一条待办标题是XXX截止时间是XXX确认吗用户回复确认后再真正调用接口。这样既保留自动化又不会误伤。5. 实测中的异常排查权限回调、域名白名单与超时问题5.1 飞书开放平台异常九成出在事件订阅和权限审核上做这类接入一定会在某个时刻遇到飞书返回错误码搜索时满屏都是飞书开放平台异常但对解决实际问题帮助不大。我建议遇到问题先按顺序排查三件事应用版本是否已发布生效、事件订阅是否已启动、对应权限是否在后台开通并审核通过。事件订阅还有一个高频坑长连接模式下如果你在本地启动了 Bridge但电脑休眠或断网连接会静默断开。飞书 SDK 一般有自动重连但有些场景下会卡在半死状态。我跑了几天后总结的经验是给 Bridge 加一个心跳日志每 30 秒打一行并且配合一个看门狗脚本发现长连接断开或心跳停止就自动重启进程。Windows 上如果你用了 OpenClaw Windows Companion 这种方式托管常驻服务同样要留意系统计划任务里仅在用户登录时运行这个选项改成不管用户是否登录都要运行否则重启电脑后机器人就下线了。5.2 权限报错常见错误码与处理对照以下是几个我实际撞过的错误码直接对照处理错误码含义处理方法99991672机器人无权限调用该接口在权限管理里搜索对应权限标识并开通重新发布应用版本99991663应用未发布或不在可用范围检查应用版本发布状态以及当前用户是否在可用范围内99991661事件订阅校验失败确认回调地址可访问长连接模式确认服务已启动99991400参数错误多半是 JSON 格式或必填字段缺失检查接口字段名10003应用被禁用联系管理员看是否有安全策略或频繁调用被封禁排查时最好在 Bridge 里把完整请求和响应日志都打出来不要只看错误码。有时候报的是参数错误实际却是你传了错误的receive_id_type。这类问题看官方文档往往没有直接答案但把串行日志一拉出来问题马上就清楚了。5.3 云文档嵌入自己网站、链接内PDF下载这类外链问题热词里有一堆关于飞书嵌入h5免登录飞书链接内pdf下载怎么把飞书云文档内容嵌到自己网站的问题。这些和 OpenClaw × 飞书接入也有关系因为 OpenClaw 可能会在你自己的网站上展示飞书同步来的内容。飞书云文档的分享逻辑决定了完全匿名免登录嵌入在默认配置下行不通。你如果把一个分享链接直接放进 iframe飞书会基于安全策略拒绝渲染除非你的域名被配置为可信域名而且文档本身的分享范围允许互联网上获得链接的人可阅读。就算这样我实测体验仍然不够顺滑。更稳的做法是让 OpenClaw 在服务端读取文档数据再渲染成自己的 HTML 页面。你只需要在飞书侧给应用加上云文档的阅读权限应用作为服务端程序读取文档完全不需要访客登录飞书。同理飞书链接内 PDF 下载也建议走服务端接口把文件拉下来再提供下载而不是单纯放一个链接。这个思路其实和 4.4 节的 Obsidian 同步是完全一致的都是数据先从飞书取出来再放进你自己的体系。5.4 长任务经常超时怎么办飞书的 Webhook 回调对响应时间有硬性要求如果你用回调模式收到事件后必须在几秒内给出响应否则会重试。长连接模式虽然没有那么严格但你在 Bridge 里如果同步等待 OpenClaw 跑一个复杂的任务仍然会让用户体验变得很差。我的设计原则是所有可能超过 10 秒的请求一律异步化。具体分四步收到消息后立即回一条收到正在处理。把任务塞进本地队列由一个 Worker 进程逐个执行。Worker 调用 OpenClaw 处理任务拿到结果后通过消息接口推回原会话。如果任务失败也在原会话里回一条失败原因而不是静默丢弃。这个异步队列的成本极低代码量不大但能极大提升稳定性。否则你会遇到消息发出去了但一直没回复用户以为机器人死了其实只是 OpenClaw 还在跑。5.5 在群里的体验细节别让机器人被 到崩溃最后分享两个我在群里实测后非常在意的细节。第一如果机器人进了大群一定要在 Bridge 里做消息过滤。默认只处理私聊、以及消息文本中包含 机器人 标识的消息。否则群里任何一个人说话你的 Bridge 都会把文本丢给 OpenClaw大模型 API 的调用量会哗哗涨月底账单很难看。第二OpenClaw 在飞书里的回复不要太长。工作群内消息卡片过长会让刷屏感很强我一般会限制单条回复不超过 500 字如果内容多就改成生成文档或表格链接让用户自己点开看。这两点看着是小事但同事群里有人会因此把你辛苦搭的智能体当成好吵的机器人并举报。我个人实际用下来OpenClaw × 飞书的最小闭环并不复杂一个自建应用、一段长连接 Bridge、两三个 Skill 脚本就能覆盖群里发指令 → 读写表格 → 回复结果这一整套日常动作。真正拉开体验差距的其实是消息过滤、异步队列和权限边界这些容易忽略的细节。最后再分享一个小技巧把所有需要 OpenClaw 执行的确定性动作都用一条斜杠命令开头比如/todo 下周三前完成飞书接入复盘这样你的 Skill 命中率会高很多也不会因为模型自由发挥而把待办标题起得千奇百怪。