飞书机器人 | Alephant Documentation

飞书机器人用于在飞书单聊、群聊或应用入口中调用艾维斯能力。上线前应把它当作受控入口来配置：只接收已批准来源的消息，只使用当前用户或群可访问的知识与工具，并让每次回复都能被追踪和审计。

适用场景

场景	建议
团队知识问答	将机器人加入已批准的群，并只绑定该团队可访问的 Agent 或文档集。
内部支持或工单辅助	使用单独的飞书应用和机器人名称，便于运维、日志筛选和权限复核。
项目群助手	为项目群限定知识范围和工具范围，项目结束后下线机器人或移除群访问。
敏感知识问答	先验证用户、群和文档集权限，不把机器人配置成绕过权限的共享代理。

管理边界

项目	建议
入口	使用已批准的飞书企业自建应用、事件订阅和回调地址。
身份	将机器人绑定到明确的艾维斯工作区和 owner，不把机器人当作管理员代理。
响应	仅返回当前用户、群或绑定 Agent 可访问的知识和工具结果。
权限	只开通消息接收所需权限；需要群聊时再补充群消息相关权限。
运维	记录 App ID、回调地址、版本发布时间、密钥轮换和负责人。

配置前检查

开始配置前，请确认：

已准备可供飞书访问的 HTTPS 回调地址。飞书开放平台需要从公网访问该地址。
已登录飞书开放平台，且当前账号可以创建或管理企业自建应用。
飞书客户端与开放平台使用同一租户或账号类型；如果飞书客户端使用个人版，开放平台也应切到对应账号。
已打开艾维斯中的机器人配置页面，方便复制回调 URL 并填写飞书凭据。
已明确机器人允许服务的群、部门、工作区和默认 Agent 或知识范围。

App Secret、Verification Token 和 Encrypt Key 都是敏感信息。只应保存到受保护配置中，不要写入公开文档、Agent 指令、截图、工单或聊天记录。

在飞书开放平台创建应用

进入飞书开放平台后，确认右上角账号属于目标企业或个人租户。若当前账号不正确，先切换账号，再进入开发者后台和企业自建应用页面。

飞书开放平台切换账号并进入企业自建应用页面

进入企业自建应用

打开飞书开放平台，进入开发者后台，在企业自建应用页创建新应用。若已有专用于艾维斯的机器人应用，可以直接进入该应用继续配置。

填写基础信息

填写应用名称、应用描述和图标。建议应用名称与艾维斯中的机器人显示名称保持一致，例如 AIvis 助手 或 产品知识助手，便于管理员和群成员识别。

确认应用状态

创建后检查应用是否出现在企业自建应用列表中。若状态仍为待上线，需要继续完成事件、权限和版本发布配置。

飞书开放平台创建企业自建应用，填写应用名称、描述和图标

配置应用凭证

在飞书应用管理页打开凭证与基础信息，在应用凭证区域复制 App ID 和 App Secret。返回艾维斯机器人配置页面，将它们分别填入：

飞书开放平台凭证与基础信息页面，应用凭证区域展示 App ID 和已隐藏的 App Secret

艾维斯机器人配置页面填写飞书应用 ID 和应用密钥

飞书开放平台	艾维斯配置字段	说明
`App ID`	应用 ID	标识当前飞书企业自建应用。
`App Secret`	应用密钥	用于换取飞书访问令牌。

配置时请注意：

App ID 与 App Secret 必须来自同一个飞书应用。
不要把个人用户 ID、企业 ID、机器人名称或 tenant token 填入应用 ID。
如果重新生成了 App Secret，需要同步更新艾维斯配置；否则机器人可能无法获取访问令牌。
如果页面提示已保存；留空可保留当前值，且没有更换密钥，可以保持密钥字段为空。

配置验证 Token 和加密密钥

在飞书开放平台左侧导航中打开事件与回调，进入加密策略，复制 Verification Token 和 Encrypt Key。回到艾维斯机器人配置页面填写：

飞书开放平台事件与回调的加密策略页面，展示已隐藏的 Verification Token 和 Encrypt Key

飞书开放平台	艾维斯配置字段	说明
`Verification Token`	验证 Token	校验飞书推送的事件或回调请求。
`Encrypt Key`	加密密钥	解密飞书推送的加密消息内容。

填写后确认机器人开关为已启用，并设置一个清晰的显示名称。已保存的 Verification Token 或 Encrypt Key 通常不会明文展示；只有在飞书开放平台重新生成或修改对应值时，才需要重新填写。

艾维斯机器人配置页中已启用机器人，并保存验证 Token 与加密密钥

配置事件和回调地址

在艾维斯机器人配置页面复制系统生成的回调 URL。然后回到飞书开放平台的事件与回调，分别完成两处配置：

艾维斯机器人配置页展示回调 URL 字段，实际地址已遮挡

在事件配置中，将订阅方式设置为将事件发送至开发者服务器，粘贴回调 URL 并保存。
在回调配置中，将订阅方式设置为将回调发送至开发者服务器，粘贴同一个回调 URL 并保存。

飞书开放平台回调配置页，选择将回调发送至开发者服务器并填写请求地址

事件配置和回调配置是两个不同页签。消息事件通常从事件配置推送；部分交互行为或能力回调从回调配置推送。建议两个位置都填写艾维斯提供的同一个回调 URL。

保存后，两个页签中都应显示已配置的请求地址。如果飞书开放平台保存失败，请先确认回调 URL 使用 HTTPS、可被公网访问，并且艾维斯服务能正确响应飞书的地址校验请求。

飞书开放平台事件配置保存成功，接收消息事件已添加，具体请求地址已遮挡

飞书开放平台回调配置保存成功，具体请求地址已遮挡

添加消息事件与权限

在事件配置页点击添加事件，添加接收消息事件：

im.message.receive_v1

同时在权限管理中开通机器人实际需要的消息权限。只用于单聊时，不要额外开通群消息权限；需要在群聊中响应时，再根据触发方式开通读取群聊中提及机器人消息等权限。

飞书开放平台事件配置页中已添加接收消息事件，并展示所需消息权限

权限审批和事件订阅是两项独立检查。事件已经添加但权限未通过，或权限已通过但应用版本未发布，都可能导致机器人无法收到消息。

创建版本并发布

打开版本管理与发布，点击创建版本，填写版本信息后提交发布。发布完成后检查：

版本状态为已发布。
页面顶部显示当前修改均已发布。
版本详情中的应用能力包含机器人，且状态为已启用。
可用范围符合预期，例如仅部分成员、指定部门或指定企业范围可用。

如果页面提示版本发布后，当前修改方可生效，说明仍有未发布变更。此时即使艾维斯侧配置已经保存，飞书侧也可能不会推送消息或回调。

飞书开放平台版本详情页显示机器人能力已启用，版本状态为已发布

测试机器人

测试前，请先在艾维斯机器人配置页确认：

机器人开关为已启用。
显示名称正确。
应用 ID、应用密钥、验证 Token 和加密密钥已经保存。
回调 URL 与飞书开放平台中的事件、回调地址一致。
绑定的 Agent、知识范围和工具范围符合当前测试场景。

然后在飞书中打开机器人单聊或测试群，发送一条普通问题。配置正确时，机器人应能收到消息并返回回复；实际响应时间取决于网络、模型调用和后端处理耗时。

如果在群聊中测试，请先将机器人添加到目标群，并使用与权限配置匹配的触发方式。例如只开通了群聊中提及机器人的读取权限时，应在群里 @ 机器人后发送问题。

飞书机器人消息收发测试成功

验证访问边界

完成基础回复测试后，再验证治理边界：

使用授权成员发送一个应当能回答的问题，确认机器人返回正确内容。
使用未授权成员、未授权群或无权访问文档集的问题进行测试，确认机器人不会返回敏感数据。
在追踪或请求日志中确认来源平台、用户上下文、绑定 Agent、响应结果和错误信息可审计。
更换 App Secret、Verification Token、Encrypt Key、事件权限或可用范围后，重新发布飞书版本并重复测试。

常见问题排查

现象	优先检查项
飞书开放平台保存回调地址失败	回调 URL 是否为 HTTPS、公网是否可访问、艾维斯服务是否能响应飞书地址校验。
飞书能发送消息，但艾维斯没有收到日志	事件配置是否保存了正确地址、是否添加 `im.message.receive_v1`、最新版本是否已发布。
艾维斯收到回调，但校验失败	`Verification Token` 或 `Encrypt Key` 是否与当前飞书应用一致，复制时是否包含多余空格。
机器人无法获取访问令牌	`App ID` 与 `App Secret` 是否来自同一应用，密钥是否被重新生成后未同步到艾维斯。
单聊可用，群聊无回复	机器人是否已加入群聊，群消息权限是否开通，群聊中是否按权限要求 @ 机器人。
应用列表仍显示待上线	是否已在版本管理与发布中创建并发布新版本。
返回 `403`、`91403` 或资源列表为空	除 API 权限外，还需确认应用版本已发布，并且目标文档、知识库、群聊或其他资源已向该应用授权。

安全与维护建议

仅在艾维斯配置页保存真实密钥，不把密钥写入文档、截图、工单、聊天记录或代码仓库。
密钥疑似泄露时，应在飞书开放平台重新生成，并立即同步更新艾维斯配置。
权限按最小可用范围申请。只需要消息自动回复时，不要额外开通文档、通讯录或管理类权限。
机器人长期不用时，先在艾维斯侧关闭机器人，再在飞书开放平台收回不再需要的权限或下线应用版本。
生产环境建议记录每次飞书应用版本发布的时间、发布人、变更内容和验证结果。