跳到主要内容

飞书

最近更新 2026/10/07

前置条件​

1. 飞书开放平台配置​

  1. 访问 飞书开放平台

  2. 创建企业自建应用（或使用现有应用）

  3. 获取应用凭证：

    • App ID（应用 ID）
    • App Secret（应用密钥）

2. 配置机器人​

在飞书开放平台 → 应用详情 → 应用功能 → 机器人中，开启机器人功能。

3. 配置重定向 URL​

在飞书开放平台 → 应用详情 → 安全设置 → 重定向 URL 中添加：

http://your-domain/agent/api/feishu-oauth/callback

4. 事件与回调​

订阅方式：在飞书开放平台的「事件与回调」中，事件和回调均选择「使用长连接接收」，无需配置公网请求地址。

  1. 事件配置：添加 im.message.receive_v1（接收消息 v2.0），用于接收用户发给机器人的消息、图片和文件。
  2. 回调配置：添加 card.action.trigger（卡片回传交互），用于 AskUserQuestion 问题表单的提交、忽略和继续操作。
  3. 应用权限：必须包含 im:resource（下载用户图片/文件并上传生成文件）和 cardkit:card:write（创建、流式更新和替换交互卡片）。缺少 im:resource 时，文本消息可能正常，但图片读取和生成文件发送会失败。
  4. 保存并发布：权限、事件或回调有变化后，必须在「版本管理与发布」中新建版本并发布，同时确认可用范围包含目标用户；仅保存开发配置不会让已安装版本生效。
提示

验收建议：启动渠道后先确认长连接成功，再依次测试普通文本、图片读取、AskUserQuestion 表单提交以及生成文件原生附件。

5. 应用权限配置​

在飞书开放平台 → 应用详情 → 权限管理中，申请以下权限：

消息相关权限（Bot Token Scopes）：

权限说明
im:message发送消息
im:message.group_at_msg:readonly读取群聊中 @机器人的消息
im:message.group_msg发送群消息
im:message.p2p_msg:readonly读取私信消息
im:message:send_as_bot以机器人身份发送消息
im:message:readonly读取消息
im:resource获取与上传图片或文件资源
cardkit:card:write创建与更新卡片

用户身份权限（User Token Scopes）：

权限说明
contact:user.base:readonly获取用户基本信息（身份验证必需）

权限申请后需要管理员审批。

批量导入：

{

"scopes": {

"tenant": [

"im:message",

"im:message.group_at_msg:readonly",

"im:message.group_msg",

"im:message.p2p_msg:readonly",

"im:message:readonly",

"im:message:send_as_bot",

"im:resource",

"cardkit:card:write"

],

"user": [

"contact:user.base:readonly"

]

}

}

提示

批量导入权限时请额外确认：导入结果必须包含 im:resource 和 cardkit:card:write。如果旧版 JSON 未包含这两项，请在权限管理中补充后重新发布应用版本。

群聊消息分发建议新增权限：tenant:tenant:readonly（获取租户信息）。有此权限时，系统管理在验证渠道后即可识别租户并显示群聊空间；没有此权限不会影响凭证验证和消息收发，但群聊空间需要等目标群第一次 @机器人消息到达后才会被发现。添加权限后请重新发布应用版本，并在渠道管理中点击「重新验证」。

6. 发布应用​

在飞书开放平台 → 应用详情 → 版本管理与发布中，设置应用可见范围&发布应用

选择员工进行授权，仅可见范围内的员工可使用

审核通过后应用可用。

Agent配置​

1. 渠道管理配置​

在系统管理配置：

  1. 登录系统，进入「系统管理」→「Agent 管理」→「渠道管理」

  2. 点击「新建渠道」，选择「飞书」类型

  3. 填写配置信息：

    • 渠道名称：自定义名称（如"飞书机器人"）
    • APP ID & APP Secret

  4. 点击「保存」，系统会自动加密存储配置

  5. 启用渠道（确保「启用」开关打开）

注意：

  • 配置信息会加密存储在数据库中，安全性更高
  • 应用启动时会自动连接所有已启用的飞书渠道（通过 WebSocket 长连接）
  • 修改配置后无需重启服务，立即生效

使用流程​

用户绑定流程​

  1. 用户登录系统
  2. 点击左下角用户头像，打开菜单
  3. 选择"渠道绑定"，在"飞书"下找到要绑定的渠道实例，点击"绑定"按钮
  4. 跳转到飞书授权页面
  5. 用户确认授权
  6. 自动跳转回系统，显示"绑定成功"页面
  7. 关闭授权窗口，原页面自动刷新，菜单中显示"已绑定"状态

用户解绑流程​

  1. 点击左下角用户头像，打开菜单
  2. 选择"渠道绑定"，在"飞书"下找到已绑定的渠道实例，点击"解绑"按钮
  3. 确认解绑操作
  4. 解绑成功，菜单中显示"未绑定"状态

使用手册​

自定义命令​

飞书机器人支持以下命令（所有命令以 / 开头）：

命令说明示例
/new开启新会话，清除当前会话历史发送 /new
/agent <名称> <消息>给指定名称的 Agent 发消息/agent rhea 你好
/agent <消息>给系统默认 Agent 发消息/agent 你好

说明：

  • 不以 / 开头的消息直接发送给系统默认 Agent
  • Agent 名称必须是用户有权限访问的 Agent
  • 命令参数大小写敏感

群聊消息分发​

群聊消息分发可以让同一个飞书机器人按规则把不同问题交给不同的 Agent 或 Team。一个「群聊空间」对应当前飞书租户，配置对该租户内使用此机器人的群聊生效。只有已绑定 Agentic Engine 账号、并在群里明确 @机器人的成员才能发起任务。

管理员配置​

  1. 确认渠道已启用，应用已发布，并已订阅 im.message.receive_v1 和 card.action.trigger。建议增加 tenant:tenant:readonly，这样系统在验证渠道时即可识别飞书租户；未增加时，需要先在目标群中 @机器人发送一条消息，系统才会发现该群聊空间。
  2. 进入「系统管理 → Agent 管理 → 渠道管理」，在对应飞书渠道上打开「消息分发」。如果存在多个群聊空间，先选择要配置的空间。
  3. 选择默认使用的 Agent/Team。启用群聊分发前必须配置默认项；普通消息没有命中其他规则时会交给它处理。
  4. 按需添加最多 19 条规则。每条规则选择一个 Agent/Team，填写必填的「调用指令」，还可以填写最多 10 个关键词，然后打开该规则的启用开关。
  5. 保存后在群里发送 @机器人 /help 做验收，确认清单中只出现当前用户可使用、且当前可运行的 Agent/Team。
配置项规则
默认 Agent/Team必须配置后才能启用；未指定调用指令、且未命中关键词时使用。
调用指令必填，1～32 个字符；可使用字母、数字、- 和 _，不能使用系统保留命令。大小写以及全角、半角差异不视为不同指令。
关键词可不填；每条规则最多 10 个，每个 2～32 个字符。多个关键词同时命中时优先使用更长的关键词；同长度规则无法唯一判断时回到默认 Agent/Team。
可选范围可选择已启用且可运行的系统/企业 Agent，以及当前企业的 Team；个人 Agent 不会出现在群聊分发候选中。

群聊中的使用方式​

用途示例说明
查看可用能力@机器人 /help
@机器人 能力清单		列出默认项、调用指令和关键词；无权限或当前不可运行的能力不会展示。
指定 Agent/Team@机器人 /analysis 分析本周数据analysis 为管理员配置的调用指令。也可以发送 @机器人 @analysis 分析本周数据。
按关键词分发@机器人 帮我检查埋点方案正文命中某条规则的关键词时，交给对应 Agent/Team；未命中时使用默认项。
取消任务@机器人 /cancel必须整条消息精确发送。任务已输出的正文会保留，并另外收到一条取消确认。
兼容旧写法@机器人 /agent analysis 分析本周数据仍可使用，但新文档推荐直接使用 /analysis。

命令边界：群聊分发不支持 /new；私聊仍支持 /new、/agent 和 /cancel。群聊中的普通新任务必须先 @机器人；只有已有任务正在等待回答时，才可以按机器人提示在原线程或交互卡片中继续回复。

公开上下文与个人数据：系统只使用近期明确 @机器人并实际进入处理的公开群聊轮次作为参考；未 @机器人的普通群消息、其他群、私聊和个人记忆不会混入。历史内容只作为不可信参考，当前这条消息才是本轮指令。

故障排查​

1. 回调 URL 错误​

错误提示：重定向 URL 有误，请联系应用管理员

解决方案：

  • 检查飞书开放平台配置的回调 URL 是否正确
  • 确保协议、域名、端口、路径完全匹配
  • 本地开发注意端口号（如 3000 vs 8686）
  • 如果使用了 NEXT_PUBLIC_BASE_PATH，回调 URL 需要包含该路径

2. 飞书渠道未配置​

错误提示：飞书渠道未配置或未启用

解决方案：

  • 进入「系统管理」→「Agent 管理」→「渠道管理」检查飞书渠道是否存在
  • 确认渠道的「启用」开关已打开
  • 检查 App ID 和 App Secret 是否正确填写
  • 确认应用类型为企业自建应用

3. App Access Token 无效​

错误提示：The app access token passed is invalid

解决方案：

  • 检查渠道管理中的 App ID 和 App Secret 是否正确
  • 确认应用类型（企业自建应用）
  • 检查应用是否已启用

4. 权限不足​

错误提示：权限不足或权限校验失败

解决方案：

  • 在飞书开放平台申请必要的权限
  • 等待管理员审批权限
  • 确认权限已生效

5. 绑定失败​

错误提示：该飞书账号已被其他用户绑定

解决方案：

  • 一个飞书账号只能绑定一个系统用户
  • 如需更换绑定，先在原账号解绑

相关页面与下一步

这篇文档对你有帮助吗？
本页内容