飞书开放平台自建应用对接 OpenClaw：App ID 与 App Secret 凭证参数填写详解（含安装包）

1. 飞书自建应用对接 OpenClaw 到底在配什么飞书开放平台自建应用对接 OpenClaw本质上是把飞书当成消息入口把 OpenClaw 当成消息处理与自动化执行的大脑。飞书这边负责创建企业自建应用、开启机器人能力、订阅消息事件、开通权限并发布版本OpenClaw 这边只负责接收两组凭证App ID 和 App Secret。很多开发者第一次做的时候会以为要填一堆回调地址、Token、EncodingAESKey其实 OpenClaw 的飞书渠道走的是长连接模式本地 WebSocket 直接和飞书通信不需要公网域名也不需要服务器回调。所以整篇的重点就落在两个地方飞书侧把应用配置到“可发布、可收消息”的状态OpenClaw 侧把两组凭证准确回填并启用渠道。适合谁看需要在飞书里接入一个能收发消息、能联动文档和多维表格的机器人但手上没有公网服务器、也不想折腾内网穿透的开发者。如果你之前接过企业微信或钉钉机器人会发现飞书这套凭证逻辑更简单但权限和事件这两块更容易漏配漏一个就会出现“保存成功但机器人不回消息”的情况。下面按飞书后台操作、OpenClaw 配置、连通性验证、排错四段展开配置骨架可以直接复制。2. 前置准备OpenClaw 安装包与飞书账号权限在动飞书后台之前先把 OpenClaw 跑起来否则凭证复制出来没地方填。OpenClaw 飞书渠道只需要 App ID、App Secret 两组参数但程序本身要先能正常启动。Windows 整合包获取路径含推广码直接拼在链接里https://xiake.yun/api/download/package/18?promoCodeIV4E9B04A80C苹果系统版本https://openclaw.ikidi.top/api/download/package/35?promoCodeIV4E9B04A80C下载后解压启动确认主界面能打开、Gateway 服务处于运行状态。飞书侧需要你有一个能登录飞书开放平台的账号并且具备可用的企业或团队空间来承载自建应用。个人飞书空间也能创建自建应用发布版本时通常不需要管理员审核企业空间提交版本后要等管理员通过配置才会真正生效。这一点很关键很多人卡在“明明填对了但没反应”其实是版本还在待审核。如果你后续想让机器人调用大模型能力做问答或代码辅助可以提前在 TaoToken 官网了解模型接入方式飞书只负责消息通道模型能力由 OpenClaw 侧配置决定。3. 飞书开放平台侧从创建应用到拿到 App ID / App Secret3.1 创建企业自建应用并添加机器人能力打开飞书开放平台https://open.feishu.cn/app右上角进入开发者后台选择“创建企业自建应用”。填写应用名称、功能描述、图标创建完成后进入应用详情页。左侧找到“添加应用能力”在能力列表里选中“机器人”并添加。没有这一步后面的事件订阅里不会出现消息接收相关事件。3.2 事件订阅选长连接添加 im.message.receive_v1左侧切到“事件与回调”在事件订阅区域点编辑订阅方式选择“使用长连接接收事件”。不要选服务器回调模式OpenClaw 本地部署没有公网地址选错会导致事件推送失败。保存后点“添加事件”搜索“接收”勾选im.message.receive_v1接收消息事件。这个事件是机器人读取飞书消息的核心缺了它机器人就是哑巴。添加时系统会弹权限推荐直接确认开通先把事件依赖的基础权限补齐。3.3 权限批量导入与数据范围如果只做收发消息事件弹窗自带的权限基本够用。但如果你要让 OpenClaw 联动飞书文档、多维表格、云盘、知识库建议直接批量导入完整权限。左侧进入“权限管理”找到“批量导入 / 导出权限”清空默认内容后粘贴下面这段 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: [] } }点下一步确认新增若弹出可访问数据范围保持默认“与应用的可用范围一致”即可。权限不是越多越好但这份清单覆盖了消息、文档、表格、云盘、知识库后续扩展功能不用反复回来补。3.4 发布版本并复制凭证权限和事件配完后进入“版本管理与发布”创建版本版本号写1.0.0或1.0.1移动端和桌面端能力都选机器人更新说明标注事件与权限变更保存后提交发布。个人空间直接生效企业空间等管理员审核。发布完成后回到“凭证与基础信息”复制 App ID 和 App Secret。注意 App Secret 只在特定位置展示复制时不要带前后空格也不要用旧版本遗留的密钥。4. OpenClaw 侧配置config.toml 骨架与凭证回填OpenClaw 的飞书渠道配置可以走图形界面也可以直接改配置文件。图形界面路径是右上角设置 → 聊天配置 → Feishu/Lark 卡片粘贴 App ID、App Secret打开启用开关保存。如果你习惯用配置文件管理下面是一个可复制的config.toml骨架字段名按 OpenClaw 渠道配置逻辑组织[gateway] host 127.0.0.1 port 18789 [channels.feishu] enabled true app_id cli_xxxxxxxxxxxxxxxx app_secret xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx event_mode websocket receive_event im.message.receive_v1几个参数说明event_mode必须是websocket对应飞书后台的长连接模式receive_event保持im.message.receive_v1app_id以cli_开头app_secret是一串较长的字符。改完配置文件后重启 Gateway 服务让配置重新加载。如果你在图形界面填过再改配置文件时注意两边不要冲突以最后一次保存的为准。注意App Secret 属于敏感凭证不要提交到公开仓库也不要在截图里完整暴露。团队协作时建议用环境变量注入而不是硬编码在配置文件里。5. 连通性验证确认机器人真的能收消息配置保存后不要急着在群里 机器人先做两步验证。第一步看 OpenClaw 的 Gateway 日志飞书渠道启用并连接成功后日志里会出现 WebSocket 连接建立、事件订阅相关的记录。如果日志里反复出现重连或鉴权失败说明凭证或事件模式有问题。第二步在飞书里找到这个自建应用机器人发一条私聊消息比如“ping”。正常情况下 OpenClaw 会收到im.message.receive_v1事件并触发处理逻辑。如果你在 OpenClaw 里配置了模型回复机器人会回消息如果只做事件接收日志里能看到消息体。验证时重点看三件事事件是否到达、消息内容是否完整、机器人是否有发送权限im:message:send_as_bot。如果你想让机器人具备模型对话能力可以在 OpenClaw 里接入 TaoToken 的模型对话能力飞书负责把用户消息送进来模型负责生成回复再通过机器人发回飞书。这样一套下来飞书就是入口OpenClaw 是调度层模型是能力层。6. 本篇常见错排查凭证填了但机器人没反应现象一App ID、App Secret 填完保存飞书发消息机器人完全没响应。按顺序核对飞书应用版本是否已发布生效企业空间看管理员是否审核通过事件订阅是否为im.message.receive_v1事件接收模式是否为长连接OpenClaw 保存配置后是否重启了 Gateway复制凭证时是否带了空格或用了旧密钥。这五项里任何一项不对都会表现为“静默无响应”。现象二日志报鉴权失败或 tenant_access_token 获取失败。大概率是 App Secret 复制错误或者应用被停用、密钥被重置过。回飞书“凭证与基础信息”重新复制一次注意不要复制到隐藏字符。现象三机器人能收到私聊但收不到群消息。检查是否开通了im:message.group_msg和im:chat相关权限群消息需要额外权限且机器人要被拉进群。现象四教程没让填公网回调地址是不是漏了。没漏。OpenClaw 飞书渠道走长连接本地 WebSocket 直接和飞书通信不需要公网服务器和回调域名这也是它比服务器回调模式更适合本地部署的原因。现象五权限 JSON 导入后部分权限显示未开通。有些权限需要管理员审批或依赖应用发布状态先完成版本发布再看。如果只是收发消息事件弹窗自带权限就够完整 JSON 是为了后续联动文档和表格。7. 凭证配好之后把飞书机器人接进你的工作流App ID 和 App Secret 填完、渠道启用、消息能通这只是第一步。接下来你可以让 OpenClaw 在收到飞书消息后做更多事调用模型生成回复、读写多维表格、把文档内容拉进来做摘要。如果你需要长期跑编码类或 Agent 类任务可以了解 TaoToken 的 Coding Plan把模型调用额度固定下来避免频繁换 Key。接入过程中如果遇到鉴权或事件订阅报错优先去 TaoToken 的接入文档对照参数再检查飞书后台的事件与权限状态。凭证配置本身不复杂复杂的是飞书侧事件、权限、版本三者必须同时到位。把这三块对齐OpenClaw 的飞书渠道基本一次就能跑通。