1. OpenClaw 对接飞书到底解决什么问题OpenClaw 是一个本地运行的 AI 网关工具它能把你常用的各种大模型能力统一封装成聊天渠道飞书就是其中一个渠道。对接完成后你在飞书里给机器人发一条消息OpenClaw 会调用背后的模型生成回复再通过飞书把答案推回给你。整个过程不需要公网服务器不需要备案域名靠的是飞书的长连接机制。适合谁用三类人最合适一是想在飞书群里加一个 AI 助手但不想折腾服务器的开发者二是团队内部想用飞书做知识问答、文档摘要的运营同学三是已经在本地跑 OpenClaw、想把入口从终端搬到飞书的产品经理。你只要有飞书开发者后台的账号权限加上本地 OpenClaw v2.7.9 正常运行就能跟着下面的步骤走通。飞书自建应用对接最容易卡住的地方有三个事件订阅方式选错、权限没开全、App Secret 复制时带了空格。这三个坑我在实测里都踩过下面会逐个给出排查方法。整篇教程按「准备 → 飞书后台配置 → OpenClaw 填参 → 联调验证 → 排错」的顺序展开每一步都有可复制的配置片段。安装包获取方面安卓和苹果分别走对应渠道体积约 45.8MB建议用浏览器自带下载工具下完先核对文件名再解压避免文件损坏导致安装失败。2. OpenClaw 前置准备与飞书自建应用创建2.1 本地环境与安装包确认开始之前先确认两件事。第一本地 OpenClaw 已经装好并且 Gateway 处于在线状态版本建议 v2.7.9 及以上低版本可能没有飞书渠道卡片。第二你有一个飞书开发者平台账号并且具备企业空间或组织资源。个人主体也能创建自建应用但发布版本时企业主体需要管理员审核个人主体一般免审直接上线。安装包下载地址如下安卓和苹果分开安卓安装包https://xiake.yun/api/download/package/17?promoCodeIV4E9B04A80C苹果安装包https://openclaw.ikidi.top/api/download/package/35?promoCodeIV4E9B04A80C下载完成后核对压缩包文件名无误再解压。安装包体积 45.8MB用浏览器自带下载工具能减少文件损坏概率。2.2 创建企业自建应用打开飞书开发者后台 https://open.feishu.cn/app 点击创建企业自建应用。模板可以选空白模板也可以选智能体快捷模板后者会预置一些机器人相关配置省一点事。填写应用名称、简介按需上传图标。图标格式支持 JPG/PNG/SVG/BMP体积控制在 2MB 以内尺寸不小于 240×240px。信息填完点创建。2.3 添加机器人能力进入应用管理页在「应用能力」栏目找到「机器人」选项点击添加。这一步是消息交互的基础没有机器人能力后面的事件订阅配了也收不到消息。2.4 事件订阅改为长连接打开左侧「事件与回调」菜单找到订阅方式设置选定「使用长连接接收事件」不要选服务器回调模式。这是本方案的核心长连接模式下你不需要公网回调域名OpenClaw 本地就能接收飞书推送的事件。2.5 添加消息接收事件在事件列表点击「添加事件」检索并勾选im.message.receive_v1接收消息 v2.0。这个事件是机器人收发消息的核心配置项漏了它机器人就收不到任何消息。2.6 权限开通与批量导入根据页面提示先确认开通事件所需的基础权限逐项核查状态未启用的手动补齐。然后进入「权限管理」页面打开批量导入导出窗口清空原有内容粘贴下面这份完整权限 JSON点击下一步确认新增。权限的数据范围保持默认即可。{ scopes: { tenant: [ aily:message:read, aily:message:write, base:app:copy, base:app:create, base:app:read, base:app:update, base:collaborator:create, base:collaborator:delete, base:collaborator:read, base:dashboard:copy, base:dashboard:read, base:field:create, base:field:delete, base:field:read, base:field:update, base:form:read, base:form:update, base:record:create, base:record:delete, base:record:read, base:record:retrieve, base:record:update, base:role:create, base:role:delete, base:role:read, base:role:update, base:table:create, base:table:delete, base:table:read, base:table:update, base:view:read, base:view:write_only, bitable:app, bitable:app:readonly, board:whiteboard:node:create, board:whiteboard:node:delete, board:whiteboard:node:read, board:whiteboard:node:update, cardkit:card:write, contact:contact.base:readonly, contact:user.base:readonly, contact:user.employee_id:readonly, contact:user.employee_number:read, contact:user.id:readonly, docs:doc, docs:doc:readonly, docs:document.comment:create, docs:document.comment:read, docs:document.comment:update, docs:document.comment:write_only, docs:document.content:read, docs:document.media:download, docs:document.media:upload, docs:document.subscription, docs:document.subscription:read, docs:document:copy, docs:document:export, docs:document:import, docs:event.document_deleted:read, docs:event.document_edited:read, docs:event.document_opened:read, docs:event:subscribe, docs:permission.member, docs:permission.member:auth, docs:permission.member:create, docs:permission.member:delete, docs:permission.member:readonly, docs:permission.member:retrieve, docs:permission.member:transfer, docs:permission.member:update, docs:permission.setting, docs:permission.setting:read, docs:permission.setting:readonly, docs:permission.setting:write_only, docx:document, docx:document.block:convert, docx:document:create, docx:document:readonly, drive:drive, drive:drive.metadata:readonly, drive:drive.search:readonly, drive:drive:readonly, drive:drive:version, drive:drive:version:readonly, drive:export:readonly, drive:file, drive:file.like:readonly, drive:file.meta.sec_label.read_only, drive:file:download, drive:file:readonly, drive:file:upload, drive:file:view_record:readonly, event:ip_list, im:app_feed_card:write, im:chat, im:chat.members:read, im:chat:read, im:message, im:message.group_msg, im:message:send_as_bot, im:message:readonly, im:message:update, sheets:spreadsheet, sheets:spreadsheet:create, sheets:spreadsheet:read, space:folder:create, wiki:node:create, wiki:node:read, wiki:node:update, wiki:space:read ], user: [] } }注意如果只需要基础回复功能可以只开通事件必需权限需要多维表格、文档联动再导入全套。权限导入后数据范围保持默认不要随意改。2.7 发布版本并提取密钥进入「版本管理」栏目新建版本号示例 1.0.0移动端与桌面端默认能力选定机器人填写版本更新备注保存后提交发布。个人主体一般免审核直接上线企业主体需管理员审批。发布成功后返回「凭证与基础信息」页面复制 App ID 和 App Secret 两组参数妥善留存。3. OpenClaw 端可复制配置与参数填写3.1 飞书渠道配置卡片打开 OpenClaw v2.7.9进入「设置 - 聊天配置」找到 Feishu/Lark飞书配置卡片。把上一步复制的 App ID、App Secret 依次填入对应输入框开启渠道启用开关点击页面右上角「保存渠道配置」。如果你习惯用配置文件方式管理OpenClaw 的渠道配置通常落在 settings 类文件里结构类似下面这样路径以你本地实际安装目录为准{ channels: { feishu: { enabled: true, appId: cli_xxxxxxxxxxxxxxxx, appSecret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, connectionMode: websocket, eventTypes: [im.message.receive_v1] } } }注意connectionMode必须是websocket长连接不要写成webhook否则会要求你填公网回调地址。appId和appSecret前后不要有空格这是最常见的失败原因。3.2 三件套对照表无论你用界面还是配置文件飞书渠道接入的核心就是三件套缺一不可配置项来源填写位置常见错误App ID飞书凭证与基础信息页OpenClaw 飞书卡片 appId复制时带了换行App Secret飞书凭证与基础信息页OpenClaw 飞书卡片 appSecret前后有空格Model IDOpenClaw 模型配置渠道绑定的默认模型未绑定导致无回复Model ID 这一项容易被忽略。飞书渠道本身只负责消息收发真正生成回复的是你绑定的模型。如果渠道配好了但机器人不回话先检查模型是否绑定、模型服务是否可用。3.3 保存后重启 Gateway配置保存后建议重启一次 Gateway 服务等待状态变为在线。重启能确保长连接重新建立避免旧连接残留导致事件收不到。4. 联调验证与成功结果确认4.1 飞书内发起第一条消息配置完成后在飞书里搜索你的机器人名称进入单聊窗口发送一条测试消息比如「你好介绍一下你自己」。正常情况下几秒内会收到 AI 回复。4.2 验证事件是否真正到达如果没回复先别急着改配置按这个顺序验证第一步看 OpenClaw 的日志面板确认有没有收到im.message.receive_v1事件。有事件说明飞书侧配置正确问题在模型侧没事件说明长连接没建立或事件没订阅。第二步检查 Gateway 是否在线。离线状态下长连接会断开事件自然收不到。第三步确认应用版本已发布上线。未发布的版本事件订阅不生效。4.3 成功结果的特征跑通后你会看到飞书机器人秒回消息OpenClaw 日志里能看到完整的事件接收和模型调用记录Gateway 状态持续在线。这时候可以进一步测试群聊场景把机器人拉进群它发消息验证群消息事件是否正常。5. 常见报错排查对照5.1 机器人发消息无应答这是最高频的问题。排查清单应用是否发布成功、事件订阅是否选了长连接、是否添加了im.message.receive_v1、App Secret 是否带空格、Gateway 是否在线。逐项核对后重启 Gateway 再测。5.2 报 401 或鉴权失败401 通常意味着 App ID 或 App Secret 不对。回到飞书凭证页面重新复制注意不要复制到多余字符。如果确认密钥无误仍报 401检查应用是否已发布、权限是否已生效。权限变更后需要重新发布版本才能生效。5.3 local proxy failed 或连接超时这类报错多半是本地网络或 Gateway 端口问题。确认 OpenClaw 的本地服务端口没有被占用防火墙没有拦截。长连接模式下不需要公网地址所以不用去配域名或回调 URL。5.4 reading choices 类解析错误如果日志里出现类似reading choices的报错说明模型返回结构不符合预期通常是模型 ID 填错或模型服务返回了非标准格式。检查绑定的 Model ID 是否正确换一个可用模型测试。5.5 OAuth 相关报错OAuth 报错一般出现在权限未开通或应用未授权场景。回到权限管理页确认im:message、im:message:send_as_bot等核心权限已开通然后重新发布版本。提示每次修改权限或事件订阅后都要重新发布版本否则改动不生效。这是很多人卡住的原因。6. 稳定运行与后续接入建议跑通基础消息收发后如果你想让机器人具备更强的模型能力可以在 OpenClaw 里绑定更合适的模型。模型对话调试可以走 https://taotoken.net/api-keys 获取密钥接入文档在 https://taotoken.net/doc 有完整说明。需要长期跑编码或 Agent 类任务的可以看 Coding Plan 方案 https://taotoken.net/coding-plan 。日常维护上建议把飞书渠道配置和权限 JSON 备份一份换机器或重装时直接导入省去重新勾选权限的时间。权限方面基础回复只需事件必需权限涉及多维表格、文档联动的再导入全套避免权限过多带来的管理负担。最后提醒一个实操细节App Secret 在飞书后台可以重置重置后旧密钥立即失效记得同步更新 OpenClaw 里的配置并重启 Gateway。整个对接链路的核心就是「长连接 两个密钥 一个事件」把这三样配对剩下的就是权限和发布版本的细节。