飞书机器人接入 OpenClaw 完整落地部署指南（含安装包）

Asama浅间

65人浏览 · 2026-10-09 09:12:16

Asama浅间 · 2026-10-09 09:12:16 发布

1. 飞书机器人接入 OpenClaw 到底解决什么问题

飞书机器人接入 OpenClaw 这件事，本质上是把本地跑着的 AI 能力塞进飞书的聊天窗口里。你在飞书私聊或者群里 @ 一下机器人，消息通过长连接传到本地 OpenClaw 的 Gateway，Gateway 调用本地模型或者你配置好的模型服务，把结果再回传到飞书。整个过程不需要公网 IP，不需要备案域名，也不需要自己写 webhook 服务。

适合谁？三类人最需要：一是团队已经在飞书里协作，想让 AI 直接进群帮忙查资料、写文案、做表格；二是开发者想拿飞书当入口，测试自己的 Agent 工作流；三是个人用户想用手机飞书远程指挥电脑上的 OpenClaw 干活。OpenClaw 2.7.9 这个版本对飞书渠道的支持已经比较完整，配置项集中在设置里的聊天配置面板，填两组密钥就能跑通。

我实测下来，从零到收到第一条回执，顺利的话 15 分钟以内。卡点通常不在 OpenClaw 本身，而在飞书开放平台的权限勾选和版本发布环节。下面按真实操作顺序拆开讲，每一步都给到可复制的参数和配置片段。

先明确一个概念：飞书这边叫「自建应用」，OpenClaw 这边叫「渠道」。飞书应用负责接收用户消息、把消息推给 OpenClaw；OpenClaw 负责处理消息、把回复发回飞书。两边靠 App ID 和 App Secret 配对。长连接模式下，飞书主动把事件推给 OpenClaw 的长连接客户端，所以你的电脑只要能上网就行，不用做端口映射。

安装包方面，Windows 一键部署包 v2.7.9 压缩包约 45.8MB，解压后直接运行主程序。安卓和苹果版本走的是移动端封装，适合没有 Windows 机器的场景。前置条件就三条：OpenClaw 已部署且 Gateway 在线、有可登录的飞书账号、企业空间需要管理员权限来审核版本。个人空间可以直接发布，省掉审核等待。

2. TaoToken 前置准备与模型接入配置

OpenClaw 本身是个壳，真正干活的是背后接的模型。如果你还没配模型，飞书机器人接进来也只会回「模型未配置」。这里推荐用 TaoToken 做模型接入层，它兼容 OpenAI 风格的接口，OpenClaw 的模型配置里直接填 Base URL 和 Key 就能用。

TaoToken 的 API 地址是 https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 Base URL 填进去。Key 在控制台的 API Keys 页面生成，生成后复制保存，页面刷新就不再完整显示。模型 ID 按你实际要用的填，比如 claude 系列或者 gpt 系列，具体以控制台模型列表为准。

在 OpenClaw 里配置模型的路径是：设置 → 模型配置 → 新增提供商。选 OpenAI 兼容类型，然后填三件套：

{
  "provider": "openai-compatible",
  "base_url": "https://taotoken.net/api",
  "api_key": "sk-你的TaoToken密钥",
  "model_id": "claude-sonnet-4-20250514",
  "timeout": 120
}

这段 JSON 是 OpenClaw 模型配置的字段结构，实际界面里是表单，但字段名一一对应。base_url 末尾不要加斜杠，加了有的版本会拼出双斜杠导致 404。api_key 前后不要有空格，从控制台复制时容易带上换行。

配好模型后，先在 OpenClaw 的对话窗口里发一条测试消息，确认模型能正常回复。这一步很关键，因为飞书渠道只是消息通道，模型不通的话飞书那边表现就是机器人已读不回，排查起来会绕远路。

如果你打算长期跑编码类或者 Agent 类任务，可以了解下 Coding Plan，它针对高频调用做了额度优化。模型对话入口适合先验证模型通不通，API Keys 页面负责生成和管理密钥，接入文档里有各语言的调用示例。这几个入口按需用，别一上来就全开。

TaoToken 在这里的角色是模型网关，不是飞书和 OpenClaw 之间的中转。飞书到 OpenClaw 走的是飞书长连接，OpenClaw 到模型走的是 TaoToken 的 API，两条链路分开，排障时也分开看。

3. 飞书开放平台创建应用与权限配置

打开飞书开放平台开发者后台，地址是 https://open.feishu.cn/app，登录后点「创建企业自建应用」。填应用名称、机器人简介、上传图标，确认创建。创建完进入应用详情页，左侧菜单是后续所有操作的入口。

第一步，添加机器人能力。左侧点「添加应用能力」，在列表里找到「机器人」，点添加。没有这一步，后面的事件订阅里根本看不到消息相关事件。

第二步，配置事件订阅。左侧进「事件与回调」→「事件配置」，订阅方式选「使用长连接接收事件」。这个选项是省掉公网回调地址的关键，选完保存。然后点「添加事件」，搜索 im.message.receive_v1，勾选「接收消息」。弹窗会提示开通配套权限，点确认，单聊和群聊 @ 的权限会自动带上。

第三步，批量导入权限。左侧进「权限管理」，点「批量导入/导出权限」，清空原有内容，粘贴下面这段完整 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: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": []
  }
}

粘贴后点导入，页面会列出所有待开通权限，确认无误后提交。这段 JSON 覆盖了消息收发、云文档、多维表格、通讯录读取等常用能力，后续想让机器人操作表格或文档就不用再回来补权限。

第四步，发布版本。左侧进「版本管理与发布」，点「创建版本」，版本号填 1.0.0，移动端和桌面端默认勾选机器人能力，填版本备注后保存。个人飞书空间直接点发布即可生效；企业空间需要管理员在管理后台审核，审核通过才生效。这一步没做，前面配得再对，机器人也不会回消息。

4. 密钥填写与本地启动验证

回到应用详情页的「基础信息」，找到 App ID 和 App Secret，分别复制。App Secret 点显示后复制，离开页面再回来需要重新显示。

打开 OpenClaw，点右上角设置，进「聊天配置」，找到 Feishu/Lark 选项。把 App ID 和 App Secret 分别粘贴到对应输入框，打开渠道开关，保存。保存后 OpenClaw 会尝试建立长连接，Gateway 日志里能看到连接状态。

这里给一份 OpenClaw 配置文件里飞书渠道的字段结构，方便你对照检查：

[channels.feishu]
enabled = true
app_id = "cli_xxxxxxxxxxxxxxxx"
app_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
connection_mode = "websocket"
event_types = ["im.message.receive_v1"]

connection_mode 必须是 websocket，对应飞书那边的「长连接接收事件」。event_types 里至少要有 im.message.receive_v1，少了这个事件，消息进不来。

保存后重启 Gateway 服务。Windows 下如果是一键包，托盘图标右键有「重启服务」；命令行启动的话 Ctrl+C 停掉再重新运行。重启后看日志，出现类似 feishu websocket connected 的字样就说明长连接建立成功。

验证动作：在飞书里搜索你创建的应用名称，进入私聊窗口，发一条「你好」。OpenClaw 的对话窗口应该同步出现这条消息，模型处理后回复会回到飞书私聊。如果群里测试，把机器人拉进群，@ 它发消息，同样能收到回复。

成功回执的标志是飞书里机器人回复了内容，同时 OpenClaw 日志里有 message sent 记录。两个都对上，接入就算完成。只飞书收到回复但日志没有，可能是缓存；只日志有但飞书没收到，检查权限里 im:message:send_as_bot 是否开通。

5. 常见报错排查对照

机器人收不到消息：先看飞书应用是否已发布生效，未发布的版本事件不会推送。再看事件订阅是不是长连接模式，webhook 模式在本地环境收不到。然后检查 App ID 和 App Secret 有没有多余空格，从飞书复制时容易带上。最后重启 Gateway，配置改动后不重启不生效。

报错 401 unauthorized：模型侧密钥问题。检查 TaoToken 的 API Key 是否有效、是否过期、base_url 是否写成 https://taotoken.net/api 且末尾无斜杠。如果 OpenClaw 日志里出现 401 且伴随 reading choices，说明请求发出去了但鉴权失败，重点查 Key。

local proxy failed：本地网络到模型服务的连接问题。检查本机是否能正常访问外网，防火墙是否拦截了 OpenClaw 的出站请求。这种情况和飞书渠道无关，是模型链路的问题，先把模型对话调通再回来看飞书。

OAuth 相关报错：飞书应用权限未开通完整。回到权限管理页面，确认批量导入的权限全部处于「已开通」状态，有「待开通」的重新提交。企业空间还要确认管理员已审核通过版本。

仅单聊可用、群聊无响应：群组权限没开全。检查 im:chat、im:chat:read、im:message.group_msg 这几个权限是否开通，补开后重新发布版本。群聊里机器人需要被 @ 才会触发，直接发消息不 @ 默认不响应。

长连接频繁断开：检查本机网络稳定性，长连接对网络抖动敏感。OpenClaw 一般有自动重连，日志里看到 reconnecting 属正常。如果一直连不上，确认飞书应用的事件订阅模式没被改回 webhook。

排查顺序建议：先确认模型链路通（本地对话能回复），再确认飞书应用已发布，再确认事件订阅是长连接，最后确认密钥无空格。按这个顺序走，基本不会绕圈。