第5章飞书接入：从0到能@机器人

🎯 本章目标：学完这章，你能在飞书里@AI机器人，让它帮你办事

⏱️ 预计时间：30分钟

📋 前置要求：已完成第3章（安装成功，并在TUI完成bootstrap首轮对话）

本章你将学会什么

在飞书开放平台创建企业应用
获取App ID和App Secret
配置权限（含批量导入JSON）
理解”先发布→再配置→再开长连接”的关键时序
在OpenClaw侧配置飞书渠道
完成配对并验证收发

5.1 为什么第3章让你先Skip Channel

还记得第3章的配置向导吗？我们在Channel那一步选择了Skip。

这不是省略，而是有意为之。

实测经验告诉我们：

先把”TUI里能稳定对话”跑通，确认模型、鉴权、Gateway都正常
再做渠道接入，出错时就能明确判断是”渠道配置问题”还是”基础环境问题”
这种”两段式”路径成功率更高，也更容易排错

如果你已经完成第3章，并且在 TUI 里完成了 bootstrap 初始化，这一章就是你的下一步。

5.2 飞书接入的整体流程

不管你接的是哪家平台，基本都遵循同一条流水线：

平台侧建应用（拿到凭证）
OpenClaw侧配置渠道（openclaw channels add）
启动Gateway并验证收发
配对/白名单放行
再做群聊策略、提及策略和风控

你可以把这5步理解为”固定骨架”。本章先把飞书走通，其他渠道请走补充章或官方渠道文档。

5.3 阶段一：飞书私聊机器人（降低复杂度）

本节按两段走：

第一阶段：飞书私聊机器人可稳定收发
第二阶段：飞书群聊里@机器人可回复

为什么要分两段？

排障时，私聊比群聊简单得多。先确保私聊通，再搞群聊，能大幅降低复杂度。

5.4 Step 1：在飞书开放平台创建应用

5.4.1 打开平台并创建企业应用

打开飞书开放平台：https://open.feishu.cn/app
登录你的飞书账号（需要有企业管理员权限）
点击”创建企业自建应用” （见图5-1）

创建企业应用 图5-1 飞书开放平台创建企业自建应用入口

填写应用信息：
- 应用名称：建议用”AI助手”或”OpenClaw”
- 应用描述：内部使用的AI助手
- 图标：可以上传一个机器人图标

5.4.2 获取App ID与App Secret

创建完成后，进入应用详情页：

点击左侧”凭证与基础信息”
记录以下信息：
- App ID（形如cli_xxxxxxxxxxxxxxxx）
- App Secret（点击”查看”按钮显示）（见图5-2）

获取凭据 图5-2 凭证与基础信息页面中的 App ID / App Secret

⚠️ 重要：App Secret务必保密，不要截图外传，不要发到群里。泄露了别人就能控制你的机器人。

5.4.3 权限配置（批量导入）

这是最容易出错的步骤，仔细跟着做。

点击左侧”权限管理”
点击”批量导入权限”
粘贴以下内容：

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

点击”确定” （见图5-3）

配置权限 图5-3 批量导入权限配置界面

这些权限是做什么的？

权限	作用
im:message:send_as_bot	以机器人身份发送消息
im:message:readonly	读取消息内容
im:message.p2p_msg:readonly	读取私聊消息
im:chat.members:bot_access	访问群成员信息

5.4.4 启用Bot能力

点击左侧”应用能力”
找到”机器人”卡片，点击”启用”
设置机器人名称（建议和应用名称一致）
点击”保存” （见图5-4）

启用 Bot 能力 图5-4 启用机器人能力并保存

5.4.5 首次发布应用（⚠️ 关键步骤！）

切记：这一步必须在开启长连接之前完成！

实测经验：如果还没先发布应用就直接开启”长连接订阅”，通常会持续失败。

发布步骤：

点击左侧”版本管理与发布”
点击”创建版本”
填写版本信息：
- 版本号：1.0.0
- 更新说明：初始版本
点击”保存”
点击”申请发布”
等待企业管理员审批（如果是你自己的企业，通常自动通过）

💡 提示：审批通过后，应用状态会变为”已发布”。这时候才能进行下一步。

发布状态核对（继续前必须满足）：

在“版本管理与发布”页能看到最新版本状态为“已发布”；
如果状态仍是“审核中/草稿”，先不要进入长连接配置。

发布状态核对示意 图5-6 企业应用列表页示意：发布后请回到“版本管理与发布”确认状态为“已发布”

5.5 Step 2：在OpenClaw配置飞书

5.5.1 启用飞书插件

先查看插件列表：

openclaw plugins list

如果存在feishu且状态是disabled，启用它：

openclaw plugins enable feishu

💡 提示：官方文档也给出openclaw plugins install @openclaw/feishu。但结合本书的实测，优先启用内置插件更稳定。

5.5.2 交互式添加Channel

运行命令：

openclaw channels add

按提示完成配置：

问题1：选择渠道类型

? Select channel type:
❯ Feishu/Lark (飞书)
  Telegram
  WebChat
  ...

选择Feishu/Lark (飞书)

问题2：输入App ID

? Enter Feishu App ID: cli_xxxxxxxxxxxxxxxx

粘贴你在5.4.2获取的App ID

问题3：输入App Secret

? Enter Feishu App Secret: [粘贴Secret]

粘贴你在5.4.2获取的App Secret（粘贴时不显示字符，这是正常的）

问题4：选择飞书域名

? Which Feishu domain?
❯ feishu.cn (国内版)
  ...

国内用户选feishu.cn

问题5：群聊策略

? Group chat policy:
❯ disabled (先不通群聊)
  enabled

先选disabled，等私聊通了再开群聊。

问题6：需要mention才回复？

? Require mention in group chats?
❯ yes (群里需要@才回复)
  no

选yes，避免机器人在群里乱说话。

5.5.3 验证配置

配置完成后，查看Channel列表：

openclaw channels list

应该显示：

NAME    TYPE    STATUS
feishu  feishu  configured

5.6 Step 3：开启事件订阅（长连接）

5.6.1 关键时序（⚠️ 血的教训）

正确的时序是：

✅ 飞书侧：创建应用 → 配置权限 → 发布应用
✅ OpenClaw侧：channels add配置渠道
✅ OpenClaw侧：启动Gateway
✅ 飞书侧：开启事件订阅（长连接）并保存
✅ 飞书侧：确认订阅事件已添加并保存

如果顺序错了，长连接会订阅失败，表现为”消息发出去，机器人没反应”。

5.6.2 启动Gateway

openclaw gateway start

确认输出：

✓ Gateway started on http://127.0.0.1:18789

5.6.3 在飞书平台开启事件订阅

回到飞书开放平台
点击左侧”事件与回调”
在”事件订阅方式”中，选择”长连接” （见图5-5）

配置事件订阅 图5-5 事件与回调页面：开启长连接订阅

点击”保存”

5.6.4 添加事件订阅并保存

在”订阅事件”区域，点击”添加事件”：

搜索im.message.receive_v1
勾选并确认添加

这个事件表示”收到消息时通知我”。

操作提醒：在飞书“长连接”模式下，这里不需要你手动填写回调 URL；重点是“长连接已开启 + 事件已添加 + 已保存”。

5.7 Step 4：配对与放行

5.7.1 私聊机器人触发配对

在飞书里：

搜索你的机器人名称
进入私聊界面
发送任意消息，比如”你好”

这时候消息还到不了 OpenClaw，因为需要先“配对”。

在默认 dmPolicy: pairing 下，机器人会在飞书私聊里直接回一条配对提示，里面包含一段配对码（Pairing code）。

这就是对用户最直观、最容易拿到 code 的路径。

5.7.2 方式A（推荐）：直接用私聊里的配对码批准

让用户把飞书私聊里看到的 Pairing code 发给管理员（或你自己复制）。

然后在终端执行：

openclaw pairing approve feishu <CODE>

操作提醒：<CODE> 要替换成你刚看到的真实配对码，别把尖括号一起复制进去。

例如：

openclaw pairing approve feishu A1B2C3D4

（把 A1B2C3D4 替换成飞书私聊里看到的真实配对码）

5.7.3 方式B（备选）：在OpenClaw里查配对请求

如果你没看到私聊里的 code，或者想二次核对，再在终端运行：

openclaw pairing list feishu

应该显示：

Code      ID          Meta        Requested
A1B2C3D4  ou_xxx...   {...}       2026-02-18T10:10:00.000Z

再执行批准：

openclaw pairing approve feishu A1B2C3D4

（把 A1B2C3D4 换成上一步看到的真实配对码 Code）

5.7.4 验证私聊

回到飞书，再次发送消息：

你好，请介绍一下你自己

期望结果：机器人回复消息！

5.8 Step 5：开启群聊（可选）

私聊通了之后，可以开启群聊功能。

5.8.1 修改Channel配置

openclaw channels add --channel feishu

修改：

groupChat: enabled
requireMention: true

5.8.2 把机器人拉进群

在飞书里创建一个群
点击”添加机器人”
搜索你的机器人名称
添加进群（见图5-7）

机器人能力启用状态示意 图5-7 群聊接入前置条件：应用内机器人能力已启用（群内“添加机器人”入口在飞书客户端）

5.8.3 群里@机器人测试

在群里发送：

@AI助手 你好