1. 项目概述为什么要把OpenClaw接到飞书上先说结论OpenClaw社区里常被误叫成“open claw”原名Clawdbot/Moltbot是一个开源的AI管家项目核心思路是让大模型通过MCPModel Context Protocol模型上下文协议拿到“手”和“眼睛”去操作真实世界里的工具。而飞书恰恰是很多团队日常协作的入口——审批、消息、多维表格、文档、待办全在里面。把OpenClaw接进飞书等于给你的AI助手开了一扇直通工作现场的门它能在飞书群里回消息、读多维表格、写文档记录甚至主动推送提醒。这个组合适合谁两类人最受益。一类是已经在用飞书做日常管理的个人或小团队想让AI帮忙盯着表格变化、自动汇总信息、定时发提醒另一类是技术爱好者想通过MCP协议自己动手搭一套“AI 办公自动化”的中枢但又不想被商业SaaS绑定。我自己是在一个20人左右的团队里试跑的把OpenClaw接上飞书机器人之后最直观的变化就是大家不用再专门跑到某个后台看数据了直接在群里机器人就能拿到汇总结果省掉了大量“帮忙查一下”“帮我发一下”的琐碎对话。先泼一盆冷水网上很多教程把这件事写得特别简单实际做起来坑不少。飞书开放平台的鉴权、事件订阅的校验、MCP服务器的地址互通每一步都有值得注意的细节。尤其如果你是从零开始第一次配置回调地址几乎必踩坑。这篇文章把我从“拿到 OpenClaw 代码”到“飞书群里能正常对话和查表格”的完整过程拆开讲包括每一步的配置参数、为什么这样配置以及我实测中踩过的坑。2. 核心思路拆解OpenClaw 和飞书是怎么“对话”的2.1 OpenClaw 的定位不是聊天机器人是“AI调度中枢”要理解这个项目得先把OpenClaw和普通聊天机器人区分开。普通的飞书机器人本质是一个“消息中转站”你在群里它它把文本发给后端服务后端回个文本完了。但OpenClaw做的事情更接近“AI助手接入真实工具链”的调度中枢。它底层通过MCP协议连接各种工具服务器让模型可以调用函数、读取数据、执行操作。你可以在群里对它说“把多维表格里昨天新增的记录汇总成日报发给我”背后的实际流程是OpenClaw接收到飞书消息把内容交给大模型处理模型判断需要读取多维表格于是通过MCP向飞书发送查询请求飞书开放平台返回表格数据模型整理结果再通过飞书机器人把消息发回群里。这一整套动作里飞书既承担“消息入口”的职责也承担“数据源”的职责。OpenClaw则负责把“理解语言”和“执行动作”中间的那座桥搭起来。2.2 飞书机器人接入的两条技术路线接触飞书开放平台之前你需要先搞清楚它提供两种接入方式自定义机器人Webhook机器人。这是在飞书群里添加的“自定义机器人”只需要一个Webhook地址往这个地址POST一段JSON就能发消息。优点是真的简单5分钟就能跑通缺点也很明显——只能发消息不能收消息更没法读取多维表格内容。它适合做“单向通知”比如定时推送监控告警。自建应用机器人。这才是正路。你在飞书开放后台创建了一个“企业自建应用”给应用开启“机器人”能力然后通过事件订阅接收用户消息通过API主动发消息、读写多维表格。OpenClaw接飞书走的就是这条路。两条路线完全不是一回事我第一次接触时一度以为“能发消息”就等于“接上了”结果调试半天才发现只做了单向通道。如果你想让AI真正参与对话、操作数据直接放弃Webhook机器人老老实实创建自建应用。2.3 消息回传的核心链路回调、长连接与开放接口自建应用机器人接收用户消息飞书开放平台给了两种方式事件订阅Webhook回调飞书把用户消息通过HTTP请求推送到你的服务器地址你的服务器处理后返回响应。需要你有一个公网可达的HTTPS地址。WebSocket长连接长连接模式飞书开放平台支持通过WebSocket建立长连接来接收事件省去公网回调和域名校验的麻烦。开发初期我强烈建议用长连接模式因为不需要配公网HTTPS、不用配域名校验本地就能起服务测试。飞书开放平台已经封装好了长连接服务应用只要配置好事件订阅平台会自动把事件推送到你所建立的WebSocket连接上。等到功能稳定了、想部署到云端长期运行再切换到Webhook回调也不迟。3. 环境准备与前置配置把飞书开放平台“地基”打牢3.1 创建自建应用与开启机器人能力在飞书开放平台open.feishu.cn注意认准域名别进错了后台创建企业自建应用。步骤如下登录开放平台进入“开发者后台”点击“创建企业自建应用”。填应用名称和描述名称建议直白一点比如“AI助理”后面在群里它时显示的就是这个名字。创建完成后进入应用配置页在“添加应用能力”里找到“机器人”开启它。在“凭证与基础信息”页面记下 App ID 和 App Secret。这两个值后面会用到App Secret 只显示一次务必保存好。3.2 配置权限为什么消息和表格权限要分开开通飞书开放平台的权限模型是“一个接口对应一个权限项”你需要哪个API就得在权限管理里开通对应的权限。以我们后续要用的功能为例核心权限有这几项功能所需权限对应的API/能力接收用户发给机器人的消息im:message:readonly等事件订阅中的im.message.receive_v1机器人主动发消息im:messageim/v1/messages发送消息接口读取多维表格记录bitable:app:readonly等bitable/v1/apps/{app_token}/tables/{table_id}/records读写多维表格记录bitable:app记录创建、更新接口在权限管理页面搜索对应的权限并开通。开通后需要重新发布应用版本才会生效。这是新手最容易忽略的点你权限配置好了但没发布版本机器人依然报权限不足。3.3 创建多维表格与获取API调用参数如果你想让OpenClaw能查多维表格需要先准备好一张表并拿到三个关键参数App Token多维表格的标识符在表格URL里能看到。形如https://xxx.feishu.cn/base/{app_token}。Table ID具体某张数据表的ID在表格URL的table参数里。View ID可选视图ID用于指定读取某个视图的数据。这三个参数是后续要通过MCP传给飞书API的关键凭据。我的建议是先手动建一张测试表字段别太多3~5列即可比如“日期、事项、负责人、状态、备注”方便观察读取结果是否正确。4. OpenClaw侧配置让AI真正“长出手脚”4.1 拉取OpenClaw项目并理解目录结构OpenClaw是一个开源项目直接按官方README操作即可。拉取代码后你需要注意两个核心目录/文件环境配置文件存放全局配置包括AI模型对接、外部服务凭证等。MCP服务器配置区用于列出所有可用的MCP服务器及其连接方式。理解这个结构很重要OpenClaw本身不直接实现“读飞书表格”这种能力它是通过MCP服务器去调用外部工具。你需要在MCP配置里声明一个“飞书MCP服务器”并指定它跑在哪个地址上OpenClaw才能找到它。4.2 飞书MCP服务器的两种部署方式我在实践里试过两种部署飞书MCP服务器的方式这里直接对比方式一本地启动HTTP服务适合开发调试。你在本地跑一个飞书MCP服务进程监听某个端口比如 9000然后在OpenClaw的MCP配置里填{ mcpServers: { feishu: { type: http, url: http://localhost:9000/mcp } } }本地模式的优点是日志随手可查、改代码立即生效。缺点是你只能在本地玩飞书平台如果要用Webhook回调方式推事件到你本地则需要内网穿透工具才能让公网访问到你的待调试服务。所以更推荐的调试路径是先用长连接模式接收事件MCP服务作为本地工具被OpenClaw调用。方式二云端函数部署等调试得差不多了可以把飞书MCP服务部署到云函数比如Sealos、Docker容器、轻量服务器等让它跑在一个公网可达的HTTPS地址上。此时OpenClaw无论跑在哪里都能通过网络访问到飞书MCP服务。{ mcpServers: { feishu: { type: http, url: https://your-domain.com/mcp } } }两种方式的OpenClaw侧配置差别不大本质只是把URL从localhost换成公网地址。真正需要留意的反而是飞书侧的凭证注入——MCP服务器处理请求时需要用到前面提到的 App ID 和 App Secret这两个值通过环境变量传入不要写死在代码或配置文件里避免泄露。4.3 飞书开放平台事件订阅配置事件订阅是飞书主动把消息推给我们的通道。在“事件与回调”页面如果你用长连接模式选择“使用长连接接收事件”保存后平台会生成一个长连接请求地址MCP服务启动时会根据 App ID 和 App Secret 去请求建立连接。如果你用Webhook模式需要填一个公网HTTPS回调地址并且要完成URL校验飞书会向该地址发送一个带 challenge 参数的GET请求你需要原样返回 challenge 的值。我建议初期一定先用长连接模式。原因很简单少配置一个公网地址少踩一半的坑。很多教程上来就让你填回调URL结果本地调试时根本收不到任何推送排查半天才发现是公网访问的问题。需要订阅的核心事件是事件说明im.message.receive_v1接收用户发给机器人的消息im.message.reaction_v1消息表情回应可用于交互触发contact.user.updated_v2用户信息变更不是必须看需求其中im.message.receive_v1是必须订阅的否则机器人收不到任何群聊消息。5. 实操过程与核心环节实现跑通“飞书消息 → OpenClaw → 表格查询 → 回复”全链路5.1 环境变量清单与启动顺序整个项目需要至少提供以下环境变量以飞书MCP服务为例变量名含义示例APP_ID飞书自建应用的App IDcli_a1b2c3d4APP_SECRET飞书自建应用的App SecretxxxxxxxxxxxxxxxxFEISHU_APP_TOKEN多维表格的App TokenbascnxxxxxxxxFEISHU_TABLE_ID数据表的Table IDtblxxxxLARK_HOST飞书开放平台域名国内默认可不填https://open.feishu.cn启动顺序也有讲究先启动飞书MCP服务确认它成功连上了飞书长连接、没有报鉴权错误。再启动OpenClaw主程序让它加载MCP服务器配置。最后在飞书群里向机器人发送一条测试消息观察全链路日志。如果先启动OpenClaw、后启动MCP服务OpenClaw在加载MCP工具列表时可能因为服务未就绪而失败导致模型不知道“查表格”这个工具存在后续对话就会出现“AI说自己做不到”的尴尬场景。5.2 关键API参数计算与消息收发细节飞书发送消息的API路径是POST /open-apis/im/v1/messages需要传 receive_id_type 和 receive_id。其中 receive_id_type 有三种常用类型open_id用户的OpenID在事件回调的 payload 里一般能拿到。user_id用户的User ID需要在通讯录里查。chat_id群聊ID机器人所在的群聊用它来定位。实际做群聊机器人时推荐用chat_id。因为用户发给机器人的消息事件里event.message.chat_id字段可以直接拿到回复时原样传回去就行。省去了一堆用户映射关系。发送消息的请求体示例文本消息{ receive_id: oc_xxxxxxxxxxxx, msg_type: text, content: {\text\:\这是机器人发送的消息\} }注意content字段是JSON字符串嵌套的不是直接传JSON对象。我第一次调这个接口时直接传了对象收到参数错误提示后看文档才发现问题。接收事件时飞书推送的消息payload里关键字段的结构大致是{ schema: 2.0, header: { event_type: im.message.receive_v1 }, event: { message: { chat_id: oc_xxxx, content: {\text\:\帮我查一下今天的任务\}, message_type: text }, sender: { sender_id: { open_id: ou_xxxx } } } }MCP服务器拿到content里的文本后转给OpenClaw的大模型去理解模型决定调用哪个工具。5.3 读多维表格的完整调用链OpenClaw在处理“帮我查一下今天的任务”这样的请求时会通过MCP工具去调飞书多维表格API。读取记录的API是GET /open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records关键查询参数page_size每页记录数合理设置为100。filter筛选条件比如按负责人或日期过滤。field_names指定要返回的字段减少数据量加快响应。一个实际可用的filter示例筛选日期字段等于特定值{ filter: { conjunction: and, conditions: [ { field_name: 日期, operator: is, value: [2025-01-20] } ] } }OpenClaw在这里的核心价值是它把用户模糊的自然语言翻译成结构化的filter参数再调用API。比如用户说“看一下昨天张三负责的任务”模型会解析出“日期昨天”“负责人张三”然后组装成上面的查询条件。你不需要为每一种问法单独写逻辑模型替你做了语义解析。5.4 验证链路是否通畅的五步检查法当你配置完不要急着在群里发复杂指令先用最简单的“文本回声”验证链路在群里机器人发送“你好”。观察飞书MCP服务的日志看有没有收到事件推送。观察OpenClaw的日志看模型是否产生了回应。看群里机器人有没有回复。如果以上都通再尝试“帮我查表格里所有记录”。这里有个经验第一次测试时确保机器人和你在同一个群并且你已经把应用发布、机器人能被正常到。很多时候“发消息没反应”不是代码问题而是机器人根本没有进群或者你的方式不对——在飞书里必须用“机器人”触发直接发“你好”机器人是收不到的。6. 常见问题与排查技巧实录6.1 高频问题速查表以下是我在接入过程中真实踩过的问题整理成了速查表现象可能原因排查方式飞书后台保存事件订阅时报“URL无法通过校验”Webhook回调地址无法被公网访问或challenge返回格式错误先用长连接模式绕过公网问题若用回调本地用curl模拟请求验证返回体机器人收不到消息未订阅im.message.receive_v1事件事件订阅配置未生效机器人没在群里检查事件订阅列表重新发布应用版本确认群里能到机器人机器人能收消息但不回复OpenClaw没有正确加载MCP服务器模型接口配置异常查看OpenClaw启动日志确认MCP工具列表里有没有飞书相关工具调用表格API时报“权限不足”未开通bitable:app:readonly权限权限已开通但未发布新版本开放平台“权限管理”里核查重新发布应用版本等待几分钟生效发送消息时提示参数非法content字段不是JSON字符串receive_id_type与传入的ID不匹配用飞书开放平台的API调试台直接测试接口排除代码干扰长连接偶尔断开网络不稳定租户Token过期没有做自动重连检查MCP服务日志里关于long connection的报错实现断线自动重连逻辑6.2 独家避坑心得关于加密、重试与调试关于 Encrypt Key。飞书开放平台在事件订阅配置里有一个“Encrypt Key”选项开启后所有推送的事件都会用该Key做AES加密。如果你不想处理解密逻辑可以不开。但如果你开了一定要注意解密后的JSON才是真正的消息结构不是直接能读的。我在调试时曾因为这个原因日志里看到的全是密文耽误了很长时间。关于事件重试机制。飞书推送事件时如果我们的服务没有在限定时间内正确响应一般是3秒内返回HTTP 200平台会认为推送失败并重试。本地调试时容易遇到处理逻辑里有阻塞操作比如同步调用大模型接口超时导致返回超时飞书就不断重推日志里能看到大量重复事件。解决思路是先快速返回成功响应把消息内容放到异步队列里处理。这是我调试中最大的一个教训。关于多维表格的字段类型。多维表格API返回的字段值格式五花八门。比如“日期”字段返回的是时间戳“人员”字段返回的是数组里包含对象结构“单选”字段返回的是字符串。如果你的AI对返回结果理解不准别怪模型笨先看看API返回的原始JSON确认字段格式是否清晰。必要时在MCP服务里加一层“格式化”逻辑把原始数据整理成更容易理解的文本再交给模型。6.3 调试时的日志规范建议调试这套系统日志就是你的眼睛。强烈建议在飞书MCP服务里对以下三个节点分别输出日志接收原始事件时打印完整的事件ID、消息类型、chat_id。调用飞书API时打印请求的URL、参数脱敏处理App Secret以及响应状态码。返回给OpenClaw时打印最终的工具返回值摘要。这样当AI回答不对时你能快速定位是“没收到消息”“API查不到数据”还是“模型理解错乱”。7. 经验总结与扩展玩法建议7.1 项目跑通后的进一步优化方向全链路跑通之后别急着放松这套系统能扩展的空间比我最初想象的大得多。我在实际使用一个月后沉淀了三个比较有代表性的扩展方向定时任务与主动推送。OpenClaw不仅能“你问我答”还能通过定时触发器主动干活。比如每天早上9点把当天多维表格里的待办事项整理成日报推送到群里。这个实现起来并不复杂给OpenClaw配置一个定时任务让它定时调用飞书MCP的“读取表格”工具再调用“发送消息”工具把结果发到群里。团队反馈说这个功能带来的体验提升比“聊天问答”大得多因为它是主动的、不用等人开口。多机器人分身管理。飞书开放平台允许一个企业应用创建多个机器人吗严格来说是一个自建应用对应一个机器人但你完全可以创建多个自建应用让不同的AI角色用不同的机器人身份出现在群里。比如“数据助理”专注查表格“知识库助手”专注查文档。OpenClaw支持配置多个MCP服务器你可以分别为不同机器人配置不同的工具权限实现职责分离。接入更多飞书能力。飞书开放平台远不止消息和多维表格审批、日历、云文档、待办、通讯录都能通过API操作。OpenClaw的MCP服务器是一个可以不断扩充的工具集合。我自己后续加了“创建待办”和“读取日历”两个工具现在在群里对机器人说“帮我建一个明天下午两点的会议待办”它真的能直接创建到飞书待办里这一步的体验飞跃非常明显。7.2 关于安全与合规的三个提醒把AI接到办公系统里能力越大责任越大。三个安全提醒必须说第一App Secret是最高级别凭证绝对不要提交到Git仓库不要写在客户端代码里。建议用环境变量或密钥管理服务存放。我见过有人把App Secret直接写在MCP配置里然后推到公开仓库第二天整个应用的就可能被外部调用消耗。第二多维表格里的数据往往是团队内部敏感信息。在配置权限时遵循最小权限原则只开通MCP服务真正用到的权限不要顺手全开。事件订阅范围也要克制只订阅必要事件减少数据暴露面。第三AI操作类工具创建待办、修改表格要加“确认机制”。我在实际使用中发现大模型偶尔会误解指令执行了并非用户本意的操作。为避免误操作可以在MCP服务里对写操作增加确认提示或者限定可执行写操作的群聊范围。这一步对生产环境尤其重要。踩过几次坑之后我个人对“OpenClaw接入飞书”这个项目的体会是技术链路本身不复杂复杂的是把“模型能力”和“业务权限”对齐。你让AI做的事情越具体、工具返回的数据越规整它表现就越可靠。反过来如果数据和权限一团乱麻再强的模型也救不回来。所以我的建议是从最小场景起步——接一个机器人、读一张表、回一类问题跑通后再逐步扩大范围。这套思路不仅适用于飞书也适用于任何“AI接入工作流”的实践。