飞书集成

飞书集成用于把 HiFox Agent 接入飞书。连接后，团队可以在飞书里给 Agent 发消息，Agent 的回复也会回到同一个飞书会话中。

HiFox 当前提供两种接入方式：

飞书智能体：推荐方式。选择一个 Agent 后，通过飞书链接或扫码完成授权，不需要创建自建应用，也不需要填写 App ID / App Secret。

自建机器人：适合需要使用自建飞书应用的团队。需要先完成企业授权，再为每个 Agent 添加一个机器人应用。

如果你只是想快速把 Agent 接入飞书，优先使用飞书智能体。只有在团队明确需要自建机器人应用、统一管理应用发布和审核时，再使用自建机器人方式。

飞书集成能做什么？

飞书集成可以帮助你：

把一个 HiFox Agent 连接成飞书中的智能体或机器人；

在飞书中向 Agent 发送文本消息；

让 Agent 的回复回到飞书会话；

支持图片消息或富文本中的图片，Agent 会在 HiFox 中看到对应附件；

在 HiFox 外部应用集成页查看已连接的飞书智能体、机器人和企业授权状态。

飞书集成更适合临时提问、信息查询、讨论方案或触发轻量工作。如果对话中形成了需要追踪、验收或协作的工作，建议把它落到 HiFox 任务中，再委派给 Agent。

连接前需要准备什么？

准备项	说明
HiFox 组织权限	需要组织 owner 或 admin 来配置飞书集成。
Agent	每个飞书智能体或机器人都需要绑定一个 Agent。没有 Agent 时，先创建 Agent。
飞书账号	使用飞书智能体方式时，需要能在飞书中完成创建和授权。
飞书开放平台权限	只有使用自建机器人方式时需要，用于创建、配置、发布自建应用。

一个 Agent 同一时间只能绑定一个飞书智能体或机器人。已经绑定过的 Agent 不会再出现在可选列表中。

从哪里进入？

进入组织后，打开 外部应用集成，在飞书卡片上点击设置或管理。

飞书卡片会根据当前状态显示不同信息：

状态	含义
设置	还没有配置飞书。
管理	已经配置过飞书，可以继续查看或调整。
企业已连接	自建机器人方式所需的企业授权已通过。
审核中	企业授权应用已提交飞书审核，等待通过。
N 个 Agent 已绑定	已通过飞书智能体方式连接了 N 个 Agent。
N 个机器人已绑定	已通过自建机器人方式连接了 N 个机器人。

打开弹窗后，标题为 连接飞书，可以在 飞书智能体 和 自建机器人 两个方式之间切换。

方式一：连接飞书智能体

飞书智能体是当前推荐方式。它不需要你在飞书开放平台手动创建应用，也不需要填写应用凭证。

操作步骤：

在 连接飞书 弹窗中选择 飞书智能体。

点击 添加飞书智能体。

选择要绑定的 Agent。

点击 打开飞书一键创建，或使用飞书扫码创建。

在飞书中完成创建和授权。

回到 HiFox，等待状态变为已连接。

授权成功后，HiFox 会显示 飞书智能体已连接。之后你可以在飞书里向这个智能体发送消息，消息会进入该 Agent 的会话，Agent 回复后会发回飞书。

如果创建链接过期、在飞书中取消授权，或飞书拒绝了请求，可以重新发起创建流程。

方式二：连接自建机器人

自建机器人方式分为两步：先完成企业授权，再添加机器人。

这种方式适合团队希望使用飞书开放平台里的自建应用，并由企业管理员统一审核、发布和管理。

1. 配置企业授权

企业授权每个组织只需要配置一次。它用于让 HiFox 自动为后续机器人配置权限、事件订阅和回调 URL。

在 自建机器人 页签中，按弹窗提示完成：

在飞书开放平台创建一个自建应用。

进入应用的 凭证与基本信息，复制 App ID 和 App Secret，填写到 HiFox。

进入应用的 安全设置，添加 HiFox 提供的 Redirect URL。

进入应用的 权限管理，用批量导入添加 HiFox 提供的权限 JSON。

在版本管理中提交审核并发布。

回到 HiFox，等待企业授权状态更新。

企业应用提交后可能会显示 审核中。审核状态不会一直在后台刷新；你可以重新打开弹窗，或点击 刷新状态 检查是否已经通过。

2. 添加机器人

企业授权通过后，就可以为 Agent 添加机器人。

操作步骤：

在飞书开放平台创建一个新的自建应用，作为机器人应用。

在 HiFox 的飞书集成弹窗中点击 添加机器人。

选择要绑定的 Agent。

填写 Bot App ID 和 Bot App Secret。

点击连接。

如果弹出飞书授权窗口，按提示授予“修改应用信息”权限。

等待 HiFox 自动配置机器人能力、权限、事件订阅和回调 URL，并提交发布。

提交后，机器人通常会进入 等待审核 状态。飞书审核通过并完成回调验证后，状态会变为 已连接。

连接后会发生什么？

连接成功后，飞书中的消息会进入 HiFox 对应 Agent 的外部会话。

常见流程是：

用户在飞书里给智能体或机器人发消息；

HiFox 接收飞书事件；

HiFox 找到或创建对应飞书会话；

用户消息写入会话，并触发 Agent 运行；

Agent 生成回复；

回复通过飞书集成发回原会话。

当前重点支持文本消息和图片相关消息。纯图片消息会以“用户发来一张图片”的提示进入会话，并把图片作为附件提供给 Agent 查看。

权限和安全

通常规则是：

组织 owner / admin 可以配置飞书集成、企业授权和机器人；

每个飞书智能体或机器人绑定一个 Agent；

App Secret、Bot App Secret 等凭证会加密保存；

自建机器人方式中，企业授权用于自动配置机器人，不会因为断开企业授权而删除已有机器人；

断开企业授权后，新增机器人和成员授权需要重新完成企业授权。

建议为飞书集成准备权限清晰的管理员账号，并定期检查应用权限和发布状态。不要把 App Secret、Bot App Secret 或其他凭证明文粘贴到任务评论、聊天消息或公开文档中。

常见状态

状态	说明
配置中	HiFox 正在自动配置机器人。
等待审核	已提交飞书审核，审核通过后才可用。
已连接	飞书已完成连接，可以收发消息。
失败	配置失败，需要根据错误提示处理后重试。

自建机器人配置失败时，常见原因包括：机器人应用未开启“机器人”能力、企业授权缺失或失效、Bot App ID / Bot App Secret 不正确，或飞书拒绝了自动配置 / 发布请求。

常见问题

应该选飞书智能体还是自建机器人？

如果目标是尽快让 Agent 在飞书中可用，选飞书智能体。它不需要填写凭证，也不需要你手动配置飞书开放平台应用。

如果团队需要自建应用、企业审核、应用可见性或更严格的平台管理，再选自建机器人。

为什么没有可选 Agent？

可能还没有创建 Agent，或者所有可用 Agent 都已经绑定了飞书智能体或机器人。一个 Agent 只能绑定一个飞书入口。

自建机器人为什么一直在审核中？

飞书应用发布需要经过飞书侧审核。HiFox 不会持续后台轮询审核结果；可以重新打开飞书集成弹窗，或点击刷新状态检查。

断开企业授权会影响已有机器人吗？

不会直接影响已有机器人。但新增机器人，以及后续需要企业授权的成员授权流程，需要重新完成企业授权。

收不到飞书消息怎么办？

先检查机器人状态是否为已连接，再确认飞书应用已经发布、事件订阅和回调 URL 已生效。如果使用自建机器人，还要确认 Bot App ID / Bot App Secret 正确，且机器人能力已经开启。

飞书消息会变成 HiFox 任务吗？

不会自动变成任务。飞书集成连接的是 Agent 外部会话，适合对话和轻量协作。需要跟踪状态、负责人、评论和验收标准的工作，建议手动创建 HiFox 任务，再委派给 Agent。

飞书集成能做什么？#

连接前需要准备什么？#

从哪里进入？#

方式一：连接飞书智能体#

方式二：连接自建机器人#

1. 配置企业授权#

2. 添加机器人#

连接后会发生什么？#

权限和安全#

常见状态#

常见问题#

应该选飞书智能体还是自建机器人？#

为什么没有可选 Agent？#

自建机器人为什么一直在审核中？#

断开企业授权会影响已有机器人吗？#

收不到飞书消息怎么办？#

飞书消息会变成 HiFox 任务吗？#