# 飞书接入

配置飞书、完成配对，并验证消息收发。

## 接入后的消息怎样流动

飞书机器人接收消息后，Nexus 根据配对关系把消息交给指定 Agent 与会话，再把结果回复到飞书。需要分别完成应用授权、通道连接和会话配对。

本页介绍 Nexus 的飞书机器人通道。读取飞书云文档需要另外配置连接器，不能因为机器人已经能聊天，就认为它能读取所有云文档。

## 先准备一个可用 Agent

在 Nexus 内给目标 Agent 发一条普通消息，确认模型能回答。然后准备有权创建或管理飞书应用的账号。接入测试先使用自己的私聊，成功后再扩展到工作群。

默认通过 WebSocket 长连接接收事件，Nexus 所在机器需要能访问飞书服务，不要求提供公网回调地址。设备退出或网络断开时，通道不能保持正常在线收发。

## 方式一，通过扫码授权

1. 打开 **能力 → 频道**，进入飞书连接入口。
2. 按页面生成二维码，使用飞书扫描。
3. 在授权页面选择已有应用或创建新应用，检查要授予的权限。
4. 完成授权后返回 Nexus，等待连接结果。
5. 核对应用与账号，再进行私聊配对测试。

扫码完成后不要马上关闭窗口，先看 Nexus 是否确认结果。二维码过期时按页面重新获取；若已在飞书完成授权但 Nexus 结果待确认，先刷新状态，避免重复创建应用。

## 方式二，使用已有应用凭据

已有自建应用时，可在飞书开放平台确认机器人能力、应用可用范围、消息事件和权限，再将 App ID、App Secret 填入 Nexus。

| 字段 | 填写方式 | 什么时候修改 |
| --- | --- | --- |
| App ID | 当前应用的标识 | 改接另一个应用时 |
| App Secret | 与 App ID 属于同一应用的密钥 | 轮换密钥时 |
| 事件配置方式 | 默认 `websocket` | 已准备好回调部署时才改为 `webhook` |
| OpenAPI Base URL | 默认 `https://open.feishu.cn` | 使用明确指定的兼容端点时 |
| 是否在话题中回复 | `true` 或 `false`，默认 `false` | 希望结果留在话题中时 |
| Verification Token | 应用事件验证令牌 | 按事件配置填写 |
| Encrypt Key | 应用事件加密密钥 | 按事件加密配置填写 |

App Secret 与 Verification Token 用途不同，不能互换。普通长连接接入不需要为了填满表单而编造验证或加密字段。

## 应用权限与事件检查

Nexus 的扫码注册流程申请下列应用权限和事件。手动接入时可据此与应用实际设置核对，不要照搬其他产品的大范围权限清单。

| 权限或事件 | Nexus 使用方向 |
| --- | --- |
| `im:message` | 消息访问 |
| `im:message:send_as_bot` | 以机器人身份回复 |
| `im:message.reactions:read` | 读取消息回应 |
| `im:message.reactions:write` | 写入消息回应 |
| `im:resource` | 消息资源访问 |
| `im.message.receive_v1` | 接收入站消息事件 |
| `im.message.reaction.created_v1` | 接收消息回应事件 |

平台中的权限申请、发布与可用范围还要完成对应流程。应用设置存在，不代表当前测试账号已经能使用。外部后台的操作入口以[飞书事件订阅说明](https://open.feishu.cn/document/server-docs/event-subscription-guide/event-subscription-configure-/request-url-configuration-case)为准。

## 长连接和回调如何选择

长连接由 Nexus 主动建立连接，适合没有公网回调入口的桌面或服务器。若使用 `webhook`，需要由部署人员完成公网入口与事件验证；只更改表单值不会自动配置反向代理、证书或平台回调。

第一次接入先用默认长连接验证。不要同时修改传输方式、服务地址和应用凭据，否则很难判断是哪一项导致变化。

## 配对私聊，再测试群聊

从飞书向机器人发一条测试消息，打开 Nexus **能力 → 配对**，找到对应外部用户，将其绑定到目标 Agent 和会话。配对完成后重新发送测试请求。

```text
这是连接测试。请回复“已收到飞书测试”，不要执行其他操作。
```

检查 Nexus 会话中出现同一请求，飞书中收到回复。随后在测试群使用同样流程，核对群本身的绑定；私聊配对不会自动替所有群授权。

开启 **是否在话题中回复** 后，每个新话题需要重新配对。旧话题能回复而新话题无反应时，先检查话题配对，不要先重建整个通道。

## 四种常见故障

### 通道未连接

核对 App ID 和 App Secret 是否属于同一个应用，检查 Nexus 运行机器能否连接飞书。凭据轮换后应同步更新 Nexus。看到旧连接仍在线，也要完成一条新消息的收发测试。

### 通道在线但没有收到消息

检查应用是否对测试账号可用、机器人是否已加入目标群，以及消息接收事件是否配置。再看配对是否对应当前用户、群或话题。先用最短文本测试，避免同时引入附件处理问题。

### Nexus 收到消息却没有完成任务

进入绑定会话，检查模型错误、待答问题和审批卡片。通道负责收发，不能替模型或权限配置解决执行问题。

### Nexus 已完成，飞书没有回复

检查平台发送权限、目标聊天是否有效和通道错误信息。先在飞书查看是否已有消息，再决定重试，避免把网络确认失败变成重复发送。

## 更换应用或长期运行

更换应用后，重新验证账号、私聊、群和话题配对，不把旧应用的外部身份关系当成新应用的关系。持续值守时保持宿主在线，并避免多个实例同时争用同一组通道状态。

配对的管理与撤销见[外部消息配对](/docs/pairing)。涉及读取文档时，继续配置[连接器](/docs/connectors)。