> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # 飞书机器人 > 配置飞书机器人接入群聊或应用，并控制消息、权限和知识访问边界。 飞书机器人用于在飞书单聊、群聊或应用入口中调用艾维斯能力。上线前应把它当作受控入口来配置：只接收已批准来源的消息，只使用当前用户或群可访问的知识与工具，并让每次回复都能被追踪和审计。 ## 适用场景 | 场景 | 建议 | | --------- | ----------------------------------- | | 团队知识问答 | 将机器人加入已批准的群，并只绑定该团队可访问的 Agent 或文档集。 | | 内部支持或工单辅助 | 使用单独的飞书应用和机器人名称，便于运维、日志筛选和权限复核。 | | 项目群助手 | 为项目群限定知识范围和工具范围，项目结束后下线机器人或移除群访问。 | | 敏感知识问答 | 先验证用户、群和文档集权限，不把机器人配置成绕过权限的共享代理。 | ## 管理边界 | 项目 | 建议 | | -- | ------------------------------------- | | 入口 | 使用已批准的飞书企业自建应用、事件订阅和回调地址。 | | 身份 | 将机器人绑定到明确的艾维斯工作区和 owner，不把机器人当作管理员代理。 | | 响应 | 仅返回当前用户、群或绑定 Agent 可访问的知识和工具结果。 | | 权限 | 只开通消息接收所需权限；需要群聊时再补充群消息相关权限。 | | 运维 | 记录 App ID、回调地址、版本发布时间、密钥轮换和负责人。 | ## 配置前检查 开始配置前，请确认： 1. 已准备可供飞书访问的 HTTPS 回调地址。飞书开放平台需要从公网访问该地址。 2. 已登录[飞书开放平台](https://open.feishu.cn/app)，且当前账号可以创建或管理企业自建应用。 3. 飞书客户端与开放平台使用同一租户或账号类型；如果飞书客户端使用个人版，开放平台也应切到对应账号。 4. 已打开艾维斯中的机器人配置页面，方便复制回调 URL 并填写飞书凭据。 5. 已明确机器人允许服务的群、部门、工作区和默认 Agent 或知识范围。 `App Secret`、`Verification Token` 和 `Encrypt Key` 都是敏感信息。只应保存到受保护配置中，不要写入公开文档、Agent 指令、截图、工单或聊天记录。 ## 在飞书开放平台创建应用 进入飞书开放平台后，确认右上角账号属于目标企业或个人租户。若当前账号不正确，先切换账号，再进入**开发者后台**和**企业自建应用**页面。 ![飞书开放平台切换账号并进入企业自建应用页面](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/74390154d42ccbb00126dda86e5eae00dfc8faad95517b43ac7b3d059cf3ef24/assets/aivis/feishu-bot/open-custom-apps.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260908%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260908T152038Z&X-Amz-Expires=604800&X-Amz-Signature=8e0730ee698e2333890545878a8255e41ca716e76da4dd1f5f40071996be3a72&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) #### 进入企业自建应用 打开飞书开放平台，进入**开发者后台**，在**企业自建应用**页创建新应用。若已有专用于艾维斯的机器人应用，可以直接进入该应用继续配置。 #### 填写基础信息 填写应用名称、应用描述和图标。建议应用名称与艾维斯中的机器人显示名称保持一致，例如 `AIvis 助手` 或 `产品知识助手`，便于管理员和群成员识别。 #### 确认应用状态 创建后检查应用是否出现在企业自建应用列表中。若状态仍为**待上线**，需要继续完成事件、权限和版本发布配置。 ![飞书开放平台创建企业自建应用，填写应用名称、描述和图标](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/2c56ebf6a86ebaecb1ec11f4613e27edc903ac072e78a9c5714e2f09c77cb23c/assets/aivis/feishu-bot/create-app.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260908%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260908T152038Z&X-Amz-Expires=604800&X-Amz-Signature=5943786be9b016957d3752fa3a1f91a02793e7cd62b1b1de407e26fab4cb3e81&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) ## 配置应用凭证 在飞书应用管理页打开**凭证与基础信息**，在**应用凭证**区域复制 `App ID` 和 `App Secret`。返回艾维斯机器人配置页面，将它们分别填入： ![飞书开放平台凭证与基础信息页面，应用凭证区域展示 App ID 和已隐藏的 App Secret](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/79e2a2be8cac98583946e2222ecac864cfa36d5ba86d2c19e37dd25a464964bd/assets/aivis/feishu-bot/app-credentials.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260908%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260908T152038Z&X-Amz-Expires=604800&X-Amz-Signature=66c88f278a4248519652aa0ed74c139d72b23d3d9b11024f554ec4d23aa30909&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) ![艾维斯机器人配置页面填写飞书应用 ID 和应用密钥](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/a1d8fbbcfc5565642bbb80d00d3d8e7c6f97a9347dccd7a75be44828ade45ebe/assets/aivis/feishu-bot/aivis-app-credentials.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260908%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260908T152038Z&X-Amz-Expires=604800&X-Amz-Signature=b02461da93ba557b6836a960fffd8fd1d7dcc035926a3ddc35ecdfd0fd75e4ad&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) | 飞书开放平台 | 艾维斯配置字段 | 说明 | | ------------ | ------- | ------------- | | `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](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/2c25ce2a22ac4caa8b4a6776523d90b8950f3cc3cc06cbb5bdc46322c42b8043/assets/aivis/feishu-bot/encryption-strategy.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260908%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260908T152038Z&X-Amz-Expires=604800&X-Amz-Signature=af243ed0eacfb306cdd29661de2e9c8d94d13c8cc8d2290e8e803b558c11d1be&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) | 飞书开放平台 | 艾维斯配置字段 | 说明 | | -------------------- | -------- | --------------- | | `Verification Token` | 验证 Token | 校验飞书推送的事件或回调请求。 | | `Encrypt Key` | 加密密钥 | 解密飞书推送的加密消息内容。 | 填写后确认机器人开关为**已启用**，并设置一个清晰的显示名称。已保存的 `Verification Token` 或 `Encrypt Key` 通常不会明文展示；只有在飞书开放平台重新生成或修改对应值时，才需要重新填写。 ![艾维斯机器人配置页中已启用机器人，并保存验证 Token 与加密密钥](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/01e8b5eb1786b0620205992abb8c7fa6c6ea89a9660d509a44565b56180a2de1/assets/aivis/feishu-bot/aivis-bot-security-fields.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260908%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260908T152038Z&X-Amz-Expires=604800&X-Amz-Signature=a554f1434ebdf2656d44e16f855259b0999616f354b2875f65d3bfcd6090e9d3&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) ## 配置事件和回调地址 在艾维斯机器人配置页面复制系统生成的**回调 URL**。然后回到飞书开放平台的**事件与回调**，分别完成两处配置： ![艾维斯机器人配置页展示回调 URL 字段，实际地址已遮挡](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/cc022c74a4eb8e4a8ae9de0bb141780c2b333c17916597b7a54470edcace8868/assets/aivis/feishu-bot/aivis-callback-url.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260908%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260908T152038Z&X-Amz-Expires=604800&X-Amz-Signature=22086d1208173eecc045f5662c7bd7a2abbbc87348a55d2e6672947ae7c73cfb&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) 1. 在**事件配置**中，将订阅方式设置为**将事件发送至开发者服务器**，粘贴回调 URL 并保存。 2. 在**回调配置**中，将订阅方式设置为**将回调发送至开发者服务器**，粘贴同一个回调 URL 并保存。 ![飞书开放平台回调配置页，选择将回调发送至开发者服务器并填写请求地址](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/5f0554136dfcbc94b938e36eab684f24e982da83b1b10bbfeff5eabc80fcac48/assets/aivis/feishu-bot/callback-configuration.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260908%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260908T152038Z&X-Amz-Expires=604800&X-Amz-Signature=8a47beac472d50c8b821c18067b608274d2077b28a8ac1c4418494449aaab3df&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) **事件配置**和**回调配置**是两个不同页签。消息事件通常从事件配置推送；部分交互行为或能力回调从回调配置推送。建议两个位置都填写艾维斯提供的同一个回调 URL。 保存后，两个页签中都应显示已配置的请求地址。如果飞书开放平台保存失败，请先确认回调 URL 使用 HTTPS、可被公网访问，并且艾维斯服务能正确响应飞书的地址校验请求。 ![飞书开放平台事件配置保存成功，接收消息事件已添加，具体请求地址已遮挡](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/7f9b6626febc30c96b9ada97c51327ad52031357490258e69b05e1d9f1617933/assets/aivis/feishu-bot/event-configuration-saved.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260908%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260908T152038Z&X-Amz-Expires=604800&X-Amz-Signature=52b19cb991f7fe73b024fb57f638eb213314f47118c23c77e606fd499178629d&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) ![飞书开放平台回调配置保存成功，具体请求地址已遮挡](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/112fe7f4d88037cf5ed199f1ea599b8c8fd18192c21478a2daf73777c21e5438/assets/aivis/feishu-bot/callback-configuration-saved.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260908%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260908T152038Z&X-Amz-Expires=604800&X-Amz-Signature=036f6233b81b88359a238a37c53b0f2b74d263e9f1a1a9abd5599f0c01acdab3&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) ## 添加消息事件与权限 在**事件配置**页点击**添加事件**，添加**接收消息**事件： ```text im.message.receive_v1 ``` 同时在**权限管理**中开通机器人实际需要的消息权限。只用于单聊时，不要额外开通群消息权限；需要在群聊中响应时，再根据触发方式开通读取群聊中提及机器人消息等权限。 ![飞书开放平台事件配置页中已添加接收消息事件，并展示所需消息权限](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/fa690ed3039fe9f011ac47edca42e2be0b09d60e5a205c454ba673af71c8ca4d/assets/aivis/feishu-bot/message-event.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260908%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260908T152038Z&X-Amz-Expires=604800&X-Amz-Signature=4b0632f79e2925d3e4c543f3074282f1598ae14294e0722da33aa9204f951e7e&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) 权限审批和事件订阅是两项独立检查。事件已经添加但权限未通过，或权限已通过但应用版本未发布，都可能导致机器人无法收到消息。 ## 创建版本并发布 打开**版本管理与发布**，点击**创建版本**，填写版本信息后提交发布。发布完成后检查： * 版本状态为**已发布**。 * 页面顶部显示**当前修改均已发布**。 * 版本详情中的应用能力包含**机器人**，且状态为**已启用**。 * 可用范围符合预期，例如仅部分成员、指定部门或指定企业范围可用。 如果页面提示**版本发布后，当前修改方可生效**，说明仍有未发布变更。此时即使艾维斯侧配置已经保存，飞书侧也可能不会推送消息或回调。 ![飞书开放平台版本详情页显示机器人能力已启用，版本状态为已发布](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/c6d85ef2602d13493bcdbc8c83d4c682fa4dc4311269ed19c03ff507289ca4db/assets/aivis/feishu-bot/release-details.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260908%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260908T152038Z&X-Amz-Expires=604800&X-Amz-Signature=2c6acf243da20fa70117882de0779848c5f5f73a8cf4d9324855600337c50fbb&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) ## 测试机器人 测试前，请先在艾维斯机器人配置页确认： 1. 机器人开关为**已启用**。 2. 显示名称正确。 3. 应用 ID、应用密钥、验证 Token 和加密密钥已经保存。 4. 回调 URL 与飞书开放平台中的事件、回调地址一致。 5. 绑定的 Agent、知识范围和工具范围符合当前测试场景。 然后在飞书中打开机器人单聊或测试群，发送一条普通问题。配置正确时，机器人应能收到消息并返回回复；实际响应时间取决于网络、模型调用和后端处理耗时。 如果在群聊中测试，请先将机器人添加到目标群，并使用与权限配置匹配的触发方式。例如只开通了群聊中提及机器人的读取权限时，应在群里 @ 机器人后发送问题。 ![飞书机器人消息收发测试成功](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/a24c5652da370938a698cbddee79487b436d8980bf5433728416fc23764a5699/assets/aivis/feishu-bot/feishu-bot-test.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260908%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260908T152038Z&X-Amz-Expires=604800&X-Amz-Signature=b823997c1d5f81a4c74d24fdb8d8fc8b6d0e1af2acae5a7c374972203512682d&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) ## 验证访问边界 完成基础回复测试后，再验证治理边界： 1. 使用授权成员发送一个应当能回答的问题，确认机器人返回正确内容。 2. 使用未授权成员、未授权群或无权访问文档集的问题进行测试，确认机器人不会返回敏感数据。 3. 在追踪或请求日志中确认来源平台、用户上下文、绑定 Agent、响应结果和错误信息可审计。 4. 更换 `App Secret`、`Verification Token`、`Encrypt Key`、事件权限或可用范围后，重新发布飞书版本并重复测试。 ## 常见问题排查 | 现象 | 优先检查项 | | ------------------------ | ------------------------------------------------------------- | | 飞书开放平台保存回调地址失败 | 回调 URL 是否为 HTTPS、公网是否可访问、艾维斯服务是否能响应飞书地址校验。 | | 飞书能发送消息，但艾维斯没有收到日志 | **事件配置**是否保存了正确地址、是否添加 `im.message.receive_v1`、最新版本是否已发布。 | | 艾维斯收到回调，但校验失败 | `Verification Token` 或 `Encrypt Key` 是否与当前飞书应用一致，复制时是否包含多余空格。 | | 机器人无法获取访问令牌 | `App ID` 与 `App Secret` 是否来自同一应用，密钥是否被重新生成后未同步到艾维斯。 | | 单聊可用，群聊无回复 | 机器人是否已加入群聊，群消息权限是否开通，群聊中是否按权限要求 @ 机器人。 | | 应用列表仍显示**待上线** | 是否已在**版本管理与发布**中创建并发布新版本。 | | 返回 `403`、`91403` 或资源列表为空 | 除 API 权限外，还需确认应用版本已发布，并且目标文档、知识库、群聊或其他资源已向该应用授权。 | ## 安全与维护建议 * 仅在艾维斯配置页保存真实密钥，不把密钥写入文档、截图、工单、聊天记录或代码仓库。 * 密钥疑似泄露时，应在飞书开放平台重新生成，并立即同步更新艾维斯配置。 * 权限按最小可用范围申请。只需要消息自动回复时，不要额外开通文档、通讯录或管理类权限。 * 机器人长期不用时，先在艾维斯侧关闭机器人，再在飞书开放平台收回不再需要的权限或下线应用版本。 * 生产环境建议记录每次飞书应用版本发布的时间、发布人、变更内容和验证结果。 ## 相关页面 * [智能体](/aivis/agents/agents) 介绍如何配置可被机器人调用的 Agent。 * [用户、群组与角色](/aivis/governance/users-and-groups) 介绍访问边界如何应用到成员和群组。 * [追踪](/aivis/governance/tracing) 介绍如何审计机器人请求。 * [飞书知识连接器](/aivis/knowledge/connectors/feishu) 介绍如何索引飞书知识空间。