消息渠道接入
将 Agent 或 Assistant 接入外部消息平台时，需要配置平台授权、消息路由、应用或机器人权限及凭据。
打开控制台 → 触发配置 → 新建触发配置，即可查看当前 AstraBox 部署中已安装的消息平台。每个已安装的适配器都会提供对应的设置入口和配置字段。
| 层级 | 职责 |
|---|---|
| 消息平台 | 管理应用或机器人身份、权限设置和事件订阅。 |
| 消息平台适配器 | 维持消息产品连接，并把连接状态、消息和事件转换为统一协议。 |
| AstraBox | AstraBox 保存消息平台触发配置及其只写凭据，将每个外部会话映射到 Session，并记录任务处理与回复投递状态。 |
平台授权与消息路由
AstraBox 的消息平台触发配置有三个独立的配置维度：
| 维度 | 解决的问题 | 配置方式 |
|---|---|---|
| 平台授权 | 应用或机器人如何获得收发消息的权限。 | 消息平台提供的凭据和设置。 |
| 消息路由 | 某条上行消息应使用哪个 Agent 或 Assistant，以及哪个 Session。 | 触发配置选定的目标，以及平台提供的外部会话。 |
| 执行身份 | 由哪个 AstraBox 账号执行并拥有对话。 | Agent 触发配置的消息执行身份；Assistant 触发配置固定使用归属用户的账号。 |
消息平台凭据用于授权应用或机器人连接，不会把消息参与者认证为 AstraBox 用户。执行账号由配置的消息执行身份决定：Agent 触发配置在适配器支持时默认使用 Agent 创建者，该 Agent 的创建者、指定管理员和平台管理员可以选择其他受支持的模式；Assistant 触发配置始终使用归属用户的账号。应按目标用户范围设置机器人的可见性和平台权限；只希望部分账号能使用时，在允许的发送者中列出这些账号。
接入消息平台
所有已安装的消息平台都采用相同流程：
- 创建触发配置： 打开控制台 → 触发配置 → 新建触发配置，选择 Agent 或 Assistant，再选择消息平台。
- 创建应用或机器人： 使用 AstraBox 表单链接的官方开发者控制台。
- 配置权限和事件： 允许应用或机器人接收目标消息并发送回复。按照平台要求选择长连接或 Webhook 等连接方式。
- 填写凭据： 完成 AstraBox 显示的字段并创建触发配置。字段由已安装的适配器定义，凭据只允许写入。
- 按页面提示完成回调配置： 如果触发配置详情页显示回调地址，将其复制到消息平台的事件或 Webhook 设置中。把应用或机器人加入目标会话，然后发送消息。
使用回调的接入方式依赖创建触发配置时显示的 AstraBox 公网地址。如果该地址发生变化，请先在消息平台中更新回调地址，再继续接收消息。
消息路由
固定 Agent 或 Assistant
每个消息平台触发配置都属于一个 Agent 或一个 Assistant。该触发配置接收的所有上行消息都由所选目标处理。Assistant 的触发配置只能由其归属用户管理，并且始终以归属用户身份运行，参见 Assistant。
允许的发送者
允许的发送者列出触发配置接收哪些账号的消息，每行一个，原样使用所选适配器显示的发送者格式和示例。例如，Satori 的 Telegram 适配器使用 telegram:123456789；Generic JSON webhook 使用请求中的 sender 原值，如 user123。不要自行添加或删除平台前缀。
列表为空时接收平台投递的所有账号。列表不为空时，列表之外账号的消息会被忽略：不会开始任何工作，也不会作为上下文进入之后的回复。Assistant 的触发配置必须列出归属用户的账号，因为机器人的私聊对任何找到它的人都开放。
发往会话的不只是回复。Agent 程序之后在这次会话中主动产生的内容，例如定时任务的结果或完成的后台任务，也会投递到这里。
消息执行身份
消息执行身份决定触发配置的消息以哪个 AstraBox 账号执行。该账号拥有这些对话、提供对话所用的连接器，并能在控制台中看到它们。该 Agent 的创建者、指定管理员和平台管理员可以修改：
| 设置 | 消息的执行账号 |
|---|---|
| Agent 创建者 | 创建该 Agent 的账号。适配器支持此模式时的默认设置。 |
| 指定的一个账号 | 在执行账号用户 ID中填写的身份提供商用户 ID。 |
| 每位发送者关联的账号 | 平台管理员在触发配置页面的关联账号中为该发送者关联的账号。 |
Assistant 的触发配置固定使用归属用户的账号，不能选择其他执行模式。
Agent 管理者可以选择本人的执行账号；指定他人账号仍需平台管理员。修改执行策略不会授予发送者的个人账号或连接器权限。账号关联仍由平台管理员管理，适配器的模式限制以及部署安装的执行身份校验继续生效。API 客户端通过 GET /api/v1/channel-providers?agent_id=<id> 读取该 Agent 的编辑能力；不能管理该 Agent 的调用者收到 404。
选择“每位发送者关联的账号”时，即使在同一个群里，每位发送者也各自拥有与 Agent 的对话，Agent 的访问设置对每个关联账号生效。出现以下情况时，AstraBox 会告知发送者消息未被回复的原因，绝不会以其他人的身份回复：
- 发送者没有关联账号；
- 关联账号无权使用该 Agent；
- 消息回复的是其他账号的对话，或点击了该对话中的按钮。
有些平台的工作属于具体的人，因此只能以关联账号执行；这类平台的触发配置不提供其他设置。
Agent 何时回应
回应策略决定 Agent 回应群组中的哪些消息。Agent 不回应的消息会保留为上下文，并在 Agent 回应下一条消息时一并引用给它。
| 策略 | 回应的消息 |
|---|---|
全部回应（all） | 每条消息 |
仅被提及时回应（mentions） | 私信、提及 Agent 的消息，以及对 Agent 的回复 |
参与后由模型判断（participated） | 同 mentions；在 Agent 已经回应过的话题中，还会由模型判断每条普通消息 |
由模型主动判断（proactive） | 同 mentions；还会由模型判断每条普通消息 |
后两种策略由模型判断，依据是触发配置中的判断指令，它说明 Agent 何时应该发言。这两种策略需要标题模型，或部署安装的回应判断器；参见消息平台回应判断器。
会话映射
平台授权完成后，消息路由流程如下：
- 用户在私聊、群组、频道或话题中发送消息。
- 适配器验证并规范化平台事件。
- AstraBox 持久记录这条平台消息，避免重复投递导致 Agent 执行两次。
- 稳定的外部会话标识用于为所选 Agent 或 Assistant 创建或复用 Session。
- Agent 处理消息，AstraBox 记录向消息平台投递回复的结果。
私聊、群组、频道和话题使用消息平台提供的稳定标识。这些标识与 AstraBox 的身份认证和资源所有权相互独立。
消息平台触发配置绑定的 Agent 或 Assistant 创建后不能更换。如需将平台连接交给其他目标，请创建新的触发配置。
图片与文件
参与者随消息发送的图片和文件会随这条消息一起交给 Agent，回复引用为上下文的更早消息里的文件也一样。每个文件写进会话工作区的 uploads/{输入 id}/{文件名}，消息里会写明这些路径。Agent 的引擎接受图片输入、且文件是 PNG、JPEG、GIF 或 WebP 时，图片还会作为图片交给模型；否则 Agent 只把它当作文件收到。一条消息最多 10 个文件，每个不超过 25 MiB。
AstraBox 按 Satori 代理规则，通过送来这条消息的适配器读取文件：只读适配器自己的 internal: 链接，或适配器登记过前缀的链接（Discord 为其 CDN）。读不到或超过上限的文件不会被静默丢弃：消息会告诉 Agent 哪个文件没能取回以及原因。音频和视频仍以链接形式留在消息正文里。
提问与审批
Agent 在继续之前需要提问或请求审批时，会话会收到到此为止的回复，后面跟着问题及编号选项。参与者可以用以下任一方式作答：
- 在 Telegram 和 Discord 上点击选项按钮。
- 回复问题所在的消息，写上选项编号；问题允许时也可以直接写自己的答案。
- 只发送选项编号；可多选时用逗号分隔多个编号。
随后 Agent 会继续同一个任务，并发出后续回复。包含多个问题的表单会逐个提问。发送其他任何消息都表示参与者不再作答：AstraBox 会停止正在等待的任务，并把这条消息作为新请求处理。作答和点击按钮仍需通过触发配置的发送者及执行账号检查；使用关联账号模式时，参与者不能替其他账号的对话作答。
凭据接入
在对应开发者平台创建应用或机器人、配置必要权限并取得凭据，然后在新建触发配置中填写。所选适配器会提供准确的非敏感设置和只写凭据字段。
凭据只在创建或更新消息平台触发配置时写入，绝不会明文回显。替换凭据时，会替换该适配器要求的完整凭据集合。
配置应用或机器人
创建应用或机器人
从 AstraBox 表单打开官方开发者控制台。创建应用或机器人，并为这个消息平台触发配置分配独立身份。
配置权限和事件
只授予 Agent 处理目标会话所需的消息和事件权限。启用平台要求的事件订阅和连接方式。
发布或启用应用
按照消息平台要求发布或启用应用。将可见范围设为目标组织、工作区、群组或用户，再把机器人加入需要接收消息的位置。
获取凭据
复制 AstraBox 表单要求的凭据。对于使用回调的连接，请先创建触发配置，再登记详情页显示的回调地址。