# 飞书配置指南

## 你可以用它做什么

通过飞书应用提供业务能力，或接收飞书事件触发 MOI。应用调用和事件接收需分别验证。

## 配置前准备

让飞书应用管理员准备企业应用，在开放平台获取 App ID、App Secret，并按需要申请接口权限和发布应用。准备事件配置中的 Verification Token；加密事件还需要 Encrypt Key。官方页面依赖登录/动态内容，本指南的 MOI 必填项以本地表单为准。

需要能够在当前 MOI 工作区创建或编辑工具配置。若没有入口或提示无权操作，请联系工作区管理员，不要借用他人的账号。

## 配置页面


```{figure} /assets/images/agents/guide-5-hd/14-feishu-message-form.png
:alt: 飞书消息发送配置：App ID、App Secret 与 Verification Token 来自同一个应用。
:class: agent-guide-image
:figclass: agent-guide-shot

飞书消息发送配置：App ID、App Secret 与 Verification Token 来自同一个应用。
```

## 在 MOI 中操作

1. 进入工具市场的飞书，按需求选择应用能力或事件能力。
2. 创建实例，填写同一应用的 App ID、App Secret 和 Verification Token。事件加密时再填 Encrypt Key。
3. 保存实例并测试连接；按需求在智能体工具配置中绑定该实例。
4. 需要接收事件时，从实例详情复制 MOI 回调 URL，在飞书事件订阅中配置请求地址并完成校验。
5. 订阅所需事件，确认应用的接口权限、发布状态和可用范围，再在 MOI 配置事件路由目标。

## 字段怎么填写

| 字段 | 何时需要 | 填写说明 |
| --- | --- | --- |
| 实例名称 | 必填 | 例如「团队飞书助手」。 |
| App ID / App Secret | 必填 | 来自同一个飞书应用，不能混用不同应用的凭证。 |
| Verification Token | 当前两个能力入口均必填 | 来自事件配置；即使只选应用能力，当前 MOI 表单也要求填写。 |
| Encrypt Key | 事件入口可选 | 启用事件加密时填写匹配值，否则留空。 |

## 让智能体实际使用

回到目标智能体详情，在工具区域检查对应能力是否已绑定；提供实例选择时，核对目标连接。具体步骤见[绑定并验证工具](../bind-tools.md)。

应用调用先对测试资源执行一个已授权的只读操作。事件接收则在测试群或测试资源产生一次指定事件，检查飞书投递与 MOI 目标任务；不要以 App Secret 测试通过代替事件成功。

验收时逐项确认：

- [ ] 保存成功，重新打开后配置仍存在。
- [ ] 测试连接返回成功，而不是只有「已配置」标签。
- [ ] 对话的工具调用记录显示实际调用，结果与目标平台一致。
- [ ] 如启用事件接收，还验证了事件投递和正确目标触发。

## 常见问题

| 现象 | 检查方法 |
| --- | --- |
| 应用认证失败 | 核对 App ID 与 Secret 是否同属一个应用。 |
| 操作无权限 | 请应用管理员核对已申请且已生效的权限及应用可用范围。 |
| 回调校验失败 | 核对公网 URL、Verification Token、加密设置以及 MOI 服务可达性。 |

## 凭证维护与安全

只在 MOI 的敏感字段中输入 Key、Token、密码或私钥，不要放进提示词、截图、Issue 或 Git 仓库。配置更换前先确认有哪些智能体使用该实例；更换后重新测试，再验证一次实际任务。若凭证泄露，应到提供方撤销并生成新凭证。删除或停用配置会影响依赖它的调用，请先确认影响范围。

## 资料与核对范围

- [飞书事件订阅官方入口](https://open.feishu.cn/document/server-docs/event-subscription-guide/event-subscription-configure-/request-url-configuration-case)。外部控制台菜单可能随版本变化；以提供方页面为准。
- 接入范围与资料依据见[指南说明](index.md#tool-configuration-sources)。
- [返回工具配置指南目录](index.md)。