跳到主要内容

OpenHex 接入飞书教程

把 Agent Service 接入飞书，团队成员在飞书群里 @机器人 就能对话。全程约 20 分钟，需要飞书管理员权限。

一、接入飞书

前置条件​

  • 飞书管理员账号（能创建应用、发布应用）
  • OpenHex 已发布的 Agent Service（Agent 状态为「已发布」）
  • 飞书企业已开通机器人能力（默认开通）

第 1 步：飞书开放平台创建应用​

  1. 打开飞书开放平台 open.feishu.cn，用管理员账号登录
  2. 左侧菜单 → 开发者后台 → 创建企业自建应用
  3. 填写应用名称（建议与 Agent Service 同名和描述
  4. 创建完成后进入应用详情页

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

验证： 应用出现在「企业自建应用」列表里，状态为「开发中」。

第 2 步：启用机器人能力​

  1. 应用详情页左侧 → 添加应用能力 → 选择「机器人」

  2. 配置机器人信息：名称（客户看到的机器人名）、描述、图标（上传 Logo）

    启用机器人能力界面

验证： 左侧菜单出现「机器人」配置项，显示「已启用」。

第 3 步：获取 App ID 和 App Secret​

  1. 应用详情页 → 凭证与基础信息
  2. 复制 App ID 和 App Secret

获取 App ID 和 App Secret方式

创建成功后凭证页面

凭证与基础信息页，App ID 和 App Secret 位置（红框标注）

第 4步：OpenHex 端填入凭证​

  1. 打开 OpenHex → 进入目标 Agent → 工具栏应用模块→ 添加应用
  2. 选择「飞书」，填入第 3 步获取的 App ID 和 App Secret
  3. 保存

这张图片是OpenHex平台的应用配置界面，对应OpenHex接入飞书教程的相关操作环节。界面右侧可看到已添加的第三方应用「Feishu Bot」，右上角有蓝色的「+ 添加应用」按钮，还有红色框与箭头重点标注该按钮，同时界面右侧边缘的按钮栏里，也有一个被红色框标注的应用管理类按钮。结合文档上下文可知，此界面是接入飞书流程中，选择飞书应用、填入凭证前的操作界面，后续需点击「添加应用」来完成飞书应用的接入配置操作。

图片展示了OpenHex平台Agent设置添加飞书应用配置界面中“添加集成”页面。页面上方有“添加集成”标题，下方有搜索框及“添加自定义集成”按钮。平台应用区域有TikTok、飞书等应用选项，其中飞书应用被红色框突出显示，其下方有“已添加”标识及“已有智能体在用——可以照它复制一份配置”的提示。第三方应用区域列出了多个应用选项。该图片与文档中“第4步：OpenHex端填入凭证”内容相关，用于说明添加飞书应用配置的操作界面情况。

这张图片是OpenHex平台关联飞书的配置界面，对应OpenHex接入飞书流程的配置凭证环节。界面顶部显示“关联飞书”，目标飞书Bot为“Feishu Bot”，当前处于“填写基础信息”步骤，下方明确标注需在飞书后台获取并填入App ID和App Secret两项信息，且对两项信息的作用作出说明。界面底部设有“下一步”按钮，整体呈现配置飞书应用凭证的操作页面。

OpenHex 平台 Agent 设置添加飞书应用配置界面

验证： 渠道列表显示飞书状态为「已配置」，OpenHex 自动生成一个 Webhook URL（下一步要用）。

第 5步：配置事件订阅​

  1. 回到飞书开放平台 → 应用详情页 → 事件与回调
  2. 订阅方式选择「将事件发送至开发者服务器」（Webhook 方式，不要选长连接）
  3. 在「请求地址」中填入 OpenHex 提供的 Webhook URL
  4. 点击「添加事件」→ 搜索并勾选 im.message.receive_v1（接收消息）
  5. 保存

飞书开放平台事件配置界面，按事件类型订阅

OpenHex 配置指南中 Webhook 地址与 im.message.receive_v1 事件订阅步骤

验证： 飞书向 Webhook URL 发送验证请求，OpenHex 自动响应。保存成功且无报错。

第 6 步：开通权限​

  1. 飞书开放平台 → 应用详情页 → 权限管理
  2. 搜索并开通以下核心权限如图，点击「批量开通」
  3. 也可按照需求找到权限一起开通：

如果希望机器人不被 @ 也能接收群里所有消息，换成 im:message.group_msg（获取群组中所有消息）。其余权限按需添加。

**验证：**权限列表中上述权限状态为「已开通」。

该图片展示的是OpenHex接入飞书流程的第3步“配置权限”页面，当前处于配置飞书应用权限的环节。页面内列有多项核心飞书权限选项，且已勾选对应权限，包含查看、评论、编辑和管理多维表格（bitable）、查看群组中用户@机器人消息（im.group_at）、查看和知道知识库（wiki:wiki）等权限，同时提供了“复制导入JSON”的按钮，用户完成权限配置后可点击“下一步”继续流程，此页面对应教程中开通飞书权限的操作步骤。

飞书权限

第 7 步：发布应用​

  1. 飞书开放平台 → 应用详情页 → 版本管理与发布
  2. 点击「创建版本」→ 填写版本号（如 v1.0.0）和更新说明
  3. 提交发布 → 管理员审核
  4. 审核通过后，应用状态变为「已发布」

图片展示的是飞书开放平台的版本管理与发布页面。页面左侧有导航栏，右侧上方显示版本号为1.0.2，版本状态为“已发布”，并有发布人、发布通知时间等信息。页面下方有“更新版本”“发布记录”“日志检索”“应用质量看板”等选项。该图片与文档中“第7步：发布应用”内容相关，用于说明在飞书开放平台发布应用后，版本状态显示为“已发布”的情况，是验证应用发布成功的依据。

版本管理与发布页面，版本状态为已发布

**验证：**版本状态显示「已发布」，企业成员可在飞书中搜索到机器人。

第 8 步：测试​

  1. 在飞书中搜索你的机器人名称
  2. 创建一个飞书群，把机器人拉进群
  3. 在群里 @机器人 发一条消息：「你好」
  4. 观察 Agent Service 是否正常回复

验证： 机器人正常回复（内容与演练场一致）、回复速度 10-20秒以内、OpenHex 会话管理能看到这条记录。

说明
群里自己会判断要不要回 —— 群里可以正常聊天，不会被打扰
私聊每条都回，不用 @
发图片 / 文件支持。可以先发图，再单独 @ 它提问，两条会被合起来理解
话题回复在群里对着它的回复开话题，这个话题就是一个独立会话，上下文互不串
和网页端的关系同一个 Agent、同一套知识与技能，但会话各自独立
积分与网页端一致，从 Agent 拥有者账户扣除

上线检查清单​

  • 飞书开放平台应用已发布（状态为「已发布」，不是「开发中」）
  • 可用范围已设为「全部成员」（或指定部门）
  • OpenHex 端飞书渠道显示「已配置」
  • 事件订阅 URL 配置正确，订阅方式为 Webhook
  • 已开通 im:message + im:message.group_at_msg:readonly 等权限
  • 已订阅 im.message.receive_v1 事件
  • 在飞书群 @机器人 能正常对话
  • 不同群、不同人的会话互不干扰
  • OpenHex 会话管理里能看到飞书渠道的会话数据

常见问题​

@机器人 没反应

依次检查：① 飞书应用是否已发布（不是「开发中」）；② 可用范围是否包含当前用户；③ 事件订阅 URL 是否正确、im.message.receive_v1 是否勾选；④ OpenHex 端 App ID 和 App Secret 是否正确（逐字核对，注意末尾空格）；⑤ 在 OpenHex 后台点「测试连接」。

机器人回复内容不对

不是飞书的问题，是 Agent Service 配置的问题。去 OpenHex 试一试测试同样的消息，不一致则检查知识库。

飞书发布审核不通过

检查三个权限是否全部开通；检查应用名称和描述是否合规；联系飞书管理员确认审核状态。

机器人只能私聊，群里不回复

依次检查：① im:message.group_at_msg:readonly 权限是否已开通（这是接收群 @消息的必要权限）；② 机器人是否已被拉进目标群（群设置 → 群机器人 → 确认机器人在列表中）；③ 事件订阅 im.message.receive_v1 是否生效；④ 群里是否确实 @了机器人（仅接收 @消息模式下，不 @不会触发

后续​

接入飞书后，Agent Service 的对话数据会自动出现在 OpenHex 的联系人与会话管理中，你可以跟其他渠道（网页、微信、嵌入）的数据一起看，统一管理。

最后更新：2026-09-08