接入飞书机器人

连接 AI 助手

智能体开发服务平台（AgentWorks）通过飞书应用机器人和长连接接收消息，支持单聊、群聊和流式卡片回复；不需要为 AgentWorks 提供公网事件回调地址。

选择创建方式

有飞书管理员可以完成扫码授权时，优先使用 扫码创建。这个流程由管理员在飞书侧选择创建新应用或使用已有应用，不需要在 AgentWorks 中手动填写 App ID 和 App Secret。

无法使用扫码授权时，再使用手动方式：

创建方式	适用条件	AgentWorks 中的操作
扫码创建	飞书管理员可以扫码并授权新应用或已有应用	填写账号、绑定和聊天策略，选择 生成二维码
手动创建	已有应用凭证，或当前环境无法完成扫码授权	在飞书开放平台完成应用配置，再填写 App ID 和 App Secret

手动准备飞书应用

使用手动创建方式时，在飞书开放平台创建或选择一个企业自建应用，并为应用添加机器人能力。群聊中的自定义 Webhook 机器人不能接收这里需要的交互事件，不能替代应用机器人。

在应用的“凭证与基础信息”中取得 App ID 和 App Secret。只把 App Secret 交给负责配置渠道账号的人员。

手动开通消息和卡片能力

使用手动创建方式时，按照飞书的应用配置说明配置应用身份权限。根据要启用的消息方式开通以下权限：

• im:message.p2p_msg:readonly：读取用户发给机器人的单聊消息。
• im:message.group_at_msg:readonly：在需要群聊时接收群中 @ 机器人的消息。
• im:message:send_as_bot：以应用身份回复消息。
• “创建与更新卡片”：创建并持续更新流式回复卡片。

AgentWorks 会读取通讯录中的用户信息，用于识别审批人员和补充调用方身份。手动接入时，请按飞书获取单个用户信息的要求，开通相应通讯录权限和数据范围。未取得姓名时，调用方显示可以回退到飞书 Open ID；这不表示配置的审批人员已经识别成功。

手动使用长连接订阅事件

手动接入时，需要在飞书侧订阅消息和卡片事件，再发布应用，让目标用户能够使用机器人。

1. 在飞书应用的事件配置中选择“使用长连接接收事件”。
2. 添加 im.message.receive_v1 接收消息事件。
3. 在需要工具确认或输入型中断时，为卡片配置添加 card.action.trigger 回调，并同样使用长连接。
4. 发布应用版本，并确认测试人员或目标组织成员可以使用机器人。

飞书的使用长连接接收事件说明了长连接模式。平台运行环境需要访问飞书公网，但不需要配置 AgentWorks 的公网回调 URL。

创建飞书渠道账号

在 AgentWorks 中创建渠道账号，将飞书应用连接到智能体，并设置哪些用户和群可以使用它。

注意

一个飞书应用只连接一个启用的渠道账号

创建或启用前，先核对已有飞书账号，确保一个 App ID 只对应一个已启用的 AgentWorks 渠道账号。重复连接可能使消息进入非目标账号，并使用错误的绑定目标。发现重复时，先按连接排查步骤处理，再继续创建或启用。

1. 打开 渠道账号。

   打开渠道账号

   也可以从控制台左侧导航进入 渠道账号。

打开页面后，根据准备情况选择扫码创建或手动创建。

扫码创建

扫码流程需要飞书管理员完成授权；授权成功后，渠道账号会自动上线。

1. 选择 扫码创建。

2. 填写 账号名称，选择 绑定模式，并配置单聊、群聊和工具调用显示策略。

   • 实例绑定（agent_id 指向应用实例）：使用已有智能体实例；这里的“应用实例”就是智能体实例。
   • 模板绑定（agent_id 指向 Agent 模板，用户需 /init）：让渠道用户通过 /init 创建专属实例。

   两种方式的差异参见了解绑定模式：使用已有实例还是按用户创建。

3. 选择 生成二维码，让飞书管理员账号扫码。

4. 在飞书侧选择创建新应用或选择已有应用，并完成授权。

   扫码流程会申请通讯录、部门和用户信息权限，包括 contact:contact.base:readonly、contact:department.base:readonly、contact:user.base:readonly、contact:user.email:readonly、contact:user.employee_id:readonly、contact:user.employee_number:read 和 contact:work_city:readonly。

   注意

   已有应用也要检查实际授权

   选择已有应用不会自动补齐过去未授予的权限。配置审批人员后，请确认应用已获得所需权限，并用测试人员完成一次审批。

5. 等待页面显示 飞书机器人配置成功。创建的渠道账号会自动上线；打开账号详情检查 绑定目标和 聊天策略。

   按需调整单聊和群聊接收范围。

手动创建

已在飞书开放平台完成应用配置并取得 App ID 和 App Secret 后，可在 AgentWorks 中填写凭证、绑定目标和聊天策略。

1. 在 渠道账号 中选择 新建账号，在 渠道类型 中选择 飞书。

2. 填写 账号名称、应用 ID（凭证）和应用密钥。

3. 选择 绑定模式。

   • 实例绑定（agent_id 指向应用实例）：使用已有智能体实例。
   • 模板绑定（agent_id 指向 Agent 模板，用户需 /init）：让渠道用户通过 /init 创建专属实例。

   两种方式的差异参见了解绑定模式：使用已有实例还是按用户创建。

4. 设置谁可以与机器人单聊。

   禁用单聊 决定是否接收单聊消息；只有未勾选时，单聊允许的发送者 ID 才决定允许哪些人发送消息。按希望的接收范围配置：

   单聊接收范围	禁用单聊	单聊允许的发送者 ID
   只允许指定人员	不勾选	填写这些人的发送者 ID；名单外的发送者会被拒绝
   不通过名单限制发送者	不勾选	留空
   不接收任何单聊消息	勾选	可以保留原名单，名单内的发送者也会被拒绝

   每行填写一个 ID，也可以用英文逗号分隔。生产账号应显式填写经过批准的飞书发送者 ID。

   注意

   禁用单聊时，允许名单暂不生效

   勾选后，即使允许名单仍可编辑，创建或保存配置后也会拒绝所有单聊消息，包括 /init。原名单会保留；取消勾选并保存后，才重新按名单判断。名单为空时，不限制发送者。

   这些设置只控制当前渠道账号的单聊消息，不会绕过飞书自身的访问限制，也不决定群聊是否允许。

5. 设置哪些群可以使用机器人。

   禁用群聊 决定是否接收群聊消息；只有未勾选时，群聊允许的群 ID 才决定允许哪些群。按希望的接收范围配置：

   群聊接收范围	禁用群聊	群聊允许的群 ID
   只允许指定群	不勾选	填写这些群的 ID；名单外的群会被拒绝
   不通过名单限制群	不勾选	留空
   不接收任何群聊消息	勾选	可以保留原名单，名单内的群也会被拒绝

   每行填写一个 ID，也可以用英文逗号分隔。生产账号应显式填写经过批准的群 ID。普通群聊按群 ID 匹配；带有话题 ID 的飞书消息按话题 ID 匹配，只填写所属群 ID 不会自动放行这些话题消息。

   注意

   禁用群聊时，允许名单暂不生效

   勾选后，即使允许名单仍可编辑，创建或保存配置后也会拒绝所有群聊消息，包括群内的 /init。原名单会保留；取消勾选并保存后，才重新按名单判断。名单为空时，不限制群。

   这些设置只控制当前渠道账号的群聊消息，不会绕过飞书自身的权限和消息订阅要求。单聊与群聊分别判断：单聊允许名单不限制群内成员，也不能放行被群聊策略拒绝的消息。

6. 决定是否选择 展示工具调用详情。

7. 按需填写两份审批名单，每行填写一个飞书人员 ID，也可以用逗号分隔。

   字段	谁可以处理审批
   审批人员 ID	名单中的人员可以审批该渠道中其他人发起的任务
   可自我审批人员 ID	名单中的人员只能审批自己发起的任务，不能审批他人的任务
   两份名单都留空	只有任务发起人可以处理自己的审批

   两份名单同时生效。发起人属于审批名单时，本次可能只通知发起人，但其他全局审批人员仍有权处理。

   注意

   配置了名单却无法识别人员时，审批不会放行

   如果两份名单中配置的人员都无法解析为飞书 Open ID，平台不会改为让发起人自行审批，卡片也不会提供可用的审批或作答入口。请检查人员 ID、飞书通讯录权限和数据范围后，再发起新的测试任务。

8. 在 调用者 ID 字段 中选择业务工具需要的身份标识。

   • 默认使用 默认（渠道用户 ID）。
   • 只有业务工具需要其他标识时，才选择 Open ID、用户名、邮箱或手机号，并用测试用户验证工具实际收到的身份。

   注意

   调用者 ID 不能替代业务系统鉴权

   所选字段缺失时会回退到渠道用户 ID；此设置不改变渠道允许列表。工具应拒绝无法正确映射的身份，不要把缺失的邮箱或手机号当成已验证身份。

9. 保持 未命中的斜杠指令透传给 Agent 关闭。

   该选项默认关闭，未知 /command 返回 /help。只有明确希望模型接收未知斜杠文本，并已评估提示注入和误操作风险时才开启。

10. 选择 创建，然后选择 启用。

调整单聊和群聊接收范围

无论使用扫码还是手动创建，后续都可以选择 编辑渠道账号，按手动创建中的单聊和群聊接收范围调整对应的禁用选项和允许名单，然后选择 保存。两组设置互不影响，可以只提供单聊、只提供群聊，或同时提供两种服务。

验证消息往返

启用后，先确认渠道账号状态变为 在线，再依次验证：

1. 未勾选 禁用单聊 时，让获准的飞书用户向机器人发送单聊消息并收到回复。

2. 未勾选 禁用群聊 时，在获准群中 @ 机器人并收到回复。

   填写了群聊允许名单时，还应确认名单外的测试群被拒绝；需要接收话题消息时，单独在目标话题中验证，不能用普通群聊成功代替。

3. 让机器人生成普通长回复，以及包含多个表格或更长内容的回复。

   • 普通长回复应在同一张飞书卡片中持续更新，而不是只显示一个静态最终消息。
   • 内容超过单张卡片的承载范围时，应出现带有“内容较长，剩余内容将在新卡片中继续展示”和“接上一张卡片继续”提示的续接卡片。确认卡片顺序连续，内容没有缺失或重复。

4. 已启用工具调用详情且模型支持一次返回多个工具调用时，发送需要读取两项互不依赖信息的测试请求。

   飞书卡片应分别显示每个工具调用，每项结果应与相应工具和参数对应，成功或失败状态正确。该测试验证多项调用的展示和结果关联，不验证工具是否同时执行。

5. 使用无副作用的工具请求验证审批规则和人工审批。

   • 验证智能体模板规则的自动批准、自动拒绝和未命中结果。
   • 需要用户补充规则时，让调用在模板中保持未命中，再使用目标用户验证补充规则或人工审批。
   • 对进入人工审批的单项工具调用，分别完成一次允许和一次拒绝。两次测试都应使卡片结束等待、会话返回明确结果，并且 Trace 与 MCP 服务或实际写入的业务系统一致。

   警告

   审批卡片没有明确结果时，不要重复操作

   点击后卡片仍在等待或没有最终回复时，请把结果记为未知，记录账号、会话和发生时间，再核对 Trace 和实际结果并联系平台支持。不要重复点击，也不要重发可能产生副作用的请求；/session fix 只用于恢复会话接收新消息。

6. 主智能体模板已配置子代理且相关实例已更新时，让子代理触发一次需要人工确认的工具调用。

   审批卡片应出现在主智能体会话中。选择 ✅ 允许、⭐ 加白执行 或 ❌ 拒绝 后，智能体实例的 后台任务 应不再停留在 等待审批。

7. 卡片包含一批待审批调用时，核对批量操作的结果。

   • ✅ 全部允许 或 ❌ 全部拒绝：批内所有调用使用同一决定。
   • ⭐ 全部加白执行：批准这一批，但只为其中第一个工具名称添加允许规则。一批调用包含不同工具时，请逐项配置工具权限规则。

8. 使用不同人员验证审批权限。

   • 全局审批人员：确认可以处理其他人发起的审批；未列入名单的人员不能操作。
   • 可自我审批人员：确认可以处理自己的任务，不能处理其他人的任务。
   • 两份名单都为空：确认只有发起人可以操作。
   • 发起人也在名单中：再用另一名全局审批人员测试，确认通知范围不会改变审批权限。

9. 保持未知斜杠透传关闭，发送虚构未知命令，确认返回命令帮助。

   如业务批准开启，保存后再发送另一条无副作用的虚构命令，确认收到 Agent 回复，并在对应智能体实例中找到新的 Trace。开关显示为开启但缺少回复或 Trace 时，请恢复为关闭并联系平台支持。

10. 发送 /help，核对可用系统命令。

    命令含义和安全边界参见管理渠道会话和斜杠命令。/trust * 会为当前用户增加所有工具的宽泛自动审批规则，不应在生产中使用。

消息往返验证成功后，需要核对绑定目标、定位渠道会话、检查用户路由或维护定时任务时，参见创建账号后继续管理消息、用户和任务。

排查连接与回复问题

未得到预期回复时，按看到的现象检查：

• 账号保持离线：检查 App ID、App Secret、应用版本、机器人能力、事件订阅和平台到飞书的公网连接。

• 收到消息但无法回复：检查发送消息和卡片权限。

• 卡片显示正在重试：平台仍在处理同一次任务，等待后续结果即可，不要重发原消息。需要结束任务时发送 /stop；容错设置见配置超时、重试和备用模型。

• 审批或提问卡片不能操作：先确认任务是否已失败或取消；任务已结束时，不要再回复旧卡片。任务仍在等待时，检查两份审批名单中的人员 ID、通讯录权限和数据范围。

• 飞书卡片显示运行失败：记录用户、时间和智能体实例，到 Trace 和相关运行记录定位模型、工具、权限或外部服务问题。不要连续重试可能有副作用的请求；参见处理渠道中的运行错误和审批。

• 发现同一 App ID 有重复连接，或消息进入非目标账号：停止发送测试消息，只保留一个账号启用，刷新后确认其他账号保持离线。

  无法确认旧连接已经停止时，先联系平台支持。确认完成后，再用 /help 和一条无副作用消息核对账号、用户绑定和智能体实例。消息仍进入非目标绑定时，停用相关账号并联系平台支持。

验证模板绑定和 /init

模板绑定不会在创建渠道账号时批量创建实例。按照以下步骤确认测试用户已经获得专属智能体实例：

1. 使用尚未初始化的测试用户发送：

   /init

2. 如果智能体模板开放了必填参数，按照机器人返回的参数名再次发送：

   /init CUSTOMER_ID=customer-001 REGION=cn-east

3. 打开 AgentWorks 控制台的 渠道账号，进入目标飞书账号的 用户绑定。

   打开渠道账号

4. 确认测试用户指向新创建的智能体实例。

5. 让同一用户发送普通消息，确认消息继续进入该实例；再次发送 /init 应返回已经初始化的提示。

需要从专用测试应用开始，使用两位测试用户验证按用户开通和配置个人工作助手、长回复、解绑和重新初始化时，参见构建按用户开通的飞书个人工作助手。需要把统一维护的制度资料一起交付到飞书时，参见构建共享制度知识的飞书员工服务助手。

轮换 App Secret

每个渠道账号保存一组飞书凭证。修改凭证会中断旧连接并使用新凭证重新连接，因此需要按有短暂中断的轮换安排维护窗口。

1. 选择业务低峰期并记录当前账号、绑定目标和允许列表。
2. 在飞书侧生成或取得新 Secret，但先不要撤销仍在使用的凭证。
3. 选择 编辑，同时填写 应用 ID（凭证）和新的应用密钥，然后选择 保存。
4. 等待账号重新变为 在线，并完成一次单聊或群聊往返。
5. 确认卡片更新和 /init 路径仍然正常。
6. 再在飞书侧撤销旧 Secret。

如果保存后无法上线，恢复仍有效的旧凭证，重新检查连接，再安排下一次轮换。

停用或删除渠道账号

临时停止或永久删除机器人渠道账号时，先选择 停用并确认状态已经变为 已停用。停用会断开长连接，但不会删除智能体模板、智能体实例、会话或模板绑定产生的用户实例。

永久移除前，先记录并处理用户绑定、专属智能体实例和外部飞书应用，再选择 删除。删除 AgentWorks 渠道账号会停止对应渠道连接，但不会删除飞书开放平台中的应用。

本页记录的飞书渠道流程以文本消息为支持范围。只有在目标租户中使用真实测试账号确认目标文件类型可用后，才把图片、音频或文件输入纳入业务验收。