消息通道
飞书接入
配置飞书、完成配对，并验证消息收发。
接入后的消息怎样流动
飞书机器人接收消息后，Nexus 根据配对关系把消息交给指定 Agent 与会话，再把结果回复到飞书。需要分别完成应用授权、通道连接和会话配对。
本页介绍 Nexus 的飞书机器人通道。读取飞书云文档需要另外配置连接器，不能因为机器人已经能聊天，就认为它能读取所有云文档。
先准备一个可用 Agent
在 Nexus 内给目标 Agent 发一条普通消息，确认模型能回答。然后准备有权创建或管理飞书应用的账号。接入测试先使用自己的私聊，成功后再扩展到工作群。
默认通过 WebSocket 长连接接收事件，Nexus 所在机器需要能访问飞书服务，不要求提供公网回调地址。设备退出或网络断开时，通道不能保持正常在线收发。
方式一，通过扫码授权
- 打开 能力 → 频道，进入飞书连接入口。
- 按页面生成二维码，使用飞书扫描。
- 在授权页面选择已有应用或创建新应用，检查要授予的权限。
- 完成授权后返回 Nexus，等待连接结果。
- 核对应用与账号，再进行私聊配对测试。
扫码完成后不要马上关闭窗口，先看 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 | 接收消息回应事件 |
平台中的权限申请、发布与可用范围还要完成对应流程。应用设置存在，不代表当前测试账号已经能使用。外部后台的操作入口以飞书事件订阅说明为准。
长连接和回调如何选择
长连接由 Nexus 主动建立连接，适合没有公网回调入口的桌面或服务器。若使用 webhook，需要由部署人员完成公网入口与事件验证；只更改表单值不会自动配置反向代理、证书或平台回调。
第一次接入先用默认长连接验证。不要同时修改传输方式、服务地址和应用凭据，否则很难判断是哪一项导致变化。
配对私聊，再测试群聊
从飞书向机器人发一条测试消息，打开 Nexus 能力 → 配对，找到对应外部用户，将其绑定到目标 Agent 和会话。配对完成后重新发送测试请求。
这是连接测试。请回复“已收到飞书测试”，不要执行其他操作。
检查 Nexus 会话中出现同一请求，飞书中收到回复。随后在测试群使用同样流程，核对群本身的绑定；私聊配对不会自动替所有群授权。
开启 是否在话题中回复 后，每个新话题需要重新配对。旧话题能回复而新话题无反应时，先检查话题配对，不要先重建整个通道。
四种常见故障
通道未连接
核对 App ID 和 App Secret 是否属于同一个应用，检查 Nexus 运行机器能否连接飞书。凭据轮换后应同步更新 Nexus。看到旧连接仍在线，也要完成一条新消息的收发测试。
通道在线但没有收到消息
检查应用是否对测试账号可用、机器人是否已加入目标群，以及消息接收事件是否配置。再看配对是否对应当前用户、群或话题。先用最短文本测试，避免同时引入附件处理问题。
Nexus 收到消息却没有完成任务
进入绑定会话，检查模型错误、待答问题和审批卡片。通道负责收发，不能替模型或权限配置解决执行问题。
Nexus 已完成，飞书没有回复
检查平台发送权限、目标聊天是否有效和通道错误信息。先在飞书查看是否已有消息，再决定重试，避免把网络确认失败变成重复发送。
更换应用或长期运行
更换应用后，重新验证账号、私聊、群和话题配对，不把旧应用的外部身份关系当成新应用的关系。持续值守时保持宿主在线，并避免多个实例同时争用同一组通道状态。