野火IM与AI对接开发说明
野火IM与AI的对接主要通过机器人（Robot）来完成。本文说明机器人的基本概念、对接架构，以及在AI场景下的常用能力。
本文中AI泛指大模型、AI Agent等人工智能服务；涉及具体执行任务的实体时，使用Agent来表述。
1. 什么是野火机器人
准确地说，野火机器人是虚拟用户的双向沟通能力：
- 机器人是IM系统中的一种特殊用户，由后端服务控制，拥有自己的身份（昵称、头像等），可以像普通用户一样出现在会话和群组中。
- 沟通是双向的：Agent服务可以主动给用户发消息；用户发给机器人的消息也会通过回调地址推送给Agent服务处理。
- 每个机器人有独立的ID和密钥（AK/SK），所有接口调用都需要签名鉴权，权限可控、可随时收回。
机器人通过 Server API 创建，之后Agent服务通过 Robot API 与IM服务交互。Java开发者可以直接使用 Server SDK，其中封装了RobotService的全部方法。
2. 对接架构
2.1. 直连模式
Agent服务暴露一个HTTP回调地址，IM服务把用户消息推送到该地址，Agent服务再通过Robot API（80端口）回复。此模式要求Agent服务部署在IM服务可达的网络中（同一内网或具有公网地址）。
2.2. 机器人网关模式（robot-gateway）
如果Agent服务处在内网，可以使用机器人网关解决网络穿透问题：
┌───────────────┐ WebSocket ┌──────────────┐ HTTP回调/Robot API ┌─────────┐
│ Agent服务/客户端│ ←────────→ │ 机器人网关 │ ←─────────────────→ │ IM服务 │
└───────────────┘ (8884) └──────────────┘ (8885) └─────────┘
- Agent服务作为客户端通过WebSocket主动连出到网关，无需公网IP，即可与IM服务双向通信。
- 网关支持多机器人同时接入、动态鉴权、心跳保活与自动重连，提供Java和JS版本的客户端SDK。
- 网关内置机器人工厂（BotFather）功能，用户在IM客户端内通过聊天命令（
/create、/list等）即可在线创建和管理机器人，创建后自动下发机器人ID、密钥和网关连接地址。 - 网关仓库中还提供了多种AI平台的现成对接插件：OpenClaw适配器、DeepSeek Harness（dsh）插件、Hermes桥接、Claude Code桥接（cc-connect）等，多数场景可以拿来即用。
另外，还提供了野火机器人MCP服务，把机器人API封装成MCP工具，Agent可以像调用工具一样发消息、管理群组。
3. AI对接的常用能力
3.1. 双向消息交互
用户消息通过回调推送给Agent服务；Agent服务通过 /robot/message/send 发送消息、通过 /robot/message/reply 回复指定消息。支持文本、图片、语音、视频、文件等各类消息。
3.2. 流式消息回复
对接大模型时，回复内容是逐步生成的。野火IM内置了流式消息类型，可以让用户看到Agent"正在打字"的效果：
- 流式内容正在生成消息（类型14）：持续下发同一个流ID（streamId）的全量文本，客户端在同一个气泡中实时刷新。
- 流式文本取消消息（类型20）：生成无产出或失败时发送，客户端按streamId删除对应的生成中/已生成消息，自身不落库。
- 流式内容生成完成消息（类型15）：生成结束后下发，把气泡内容"定稿"。
前两种消息均为透传消息（persistFlag=4），不产生冗余的历史记录。详见内置消息内容。
3.3. 机器人在线状态
机器人可以设置自己的在线状态（如通过网关调用 /robot/set_online），用户在客户端上就能看到AI助手是否在线，避免向离线的AI助手提问。在线状态的展示需要客户端开启在线状态功能。
3.4. 会话级用户设置
机器人可以通过 /robot/conversation/user_setting 修改会话级用户设置（单聊和群聊都支持），请求参数为会话、类型（type）和值（value）：
- 群聊：设置会写入到群内所有成员（机器人本身除外）的用户设置中，设置的key带有会话信息，天然按会话隔离。
- 单聊：设置会写入到对方用户的用户设置中。
- 权限约束：该类型的设置（会话级用户设置scope）只允许机器人写入，普通客户端无权修改，避免数据被篡改。
- 可扩展性：type可以自定义，业务方可以为不同的Agent状态定义不同的类型；value为字符串，可以存放任意内容（如JSON）。用户设置会自动实时同步到用户的所有端。
客户端读取当前用户关于该会话的用户设置，即可拿到机器人写入的内容。AI场景下可以用它来动态显示Agent的状态和进度，例如"思考中"、"正在检索资料"、"任务执行 60%"等。关于用户设置的更多说明请参考用户设置。
3.5. 自定义消息与交互界面
机器人可以发送自定义消息，在客户端注册对应的消息内容类型后，可以渲染成各种样式：
- 各类卡片（任务卡片、审批卡片、结果展示卡片等）；
- 带按钮的选择界面，用户点选后机器人收到回调继续处理。
配合群聊中"发给指定用户"（toUsers）的能力，还可以实现只有提问者可见的交互卡片。
3.6. 更新消息内容
机器人可以通过 /robot/message/update 更新已发送的消息内容。典型用法：先发送一条"任务处理中"的消息，任务状态变化时原地更新这条消息（进行中 → 完成/失败），避免刷屏。注意：更新消息功能需要专业版IM服务，机器人只能更新自己发送过的消息。
3.7. 群组管理
机器人拥有完整的群组操作能力：建群、拉人、踢人、设置管理员、修改群信息等。可以让Agent自动为任务建群、邀请相关人员、在任务结束后解散群组。
3.8. 频道（订阅式广播）
频道类似微信公众号，是基于订阅关系的一对多广播（用户可以关注或取消关注）。频道的owner可以是机器人，这样Agent就可以管理和运营自己的频道：
- 适用于订阅式广播场景，比如AI每日摘要、资讯推送、系统公告等。
- 甚至可以做全局公众号，面向系统内所有用户发布内容。
- 与机器人形成互补：订阅广播用频道，双向交互用机器人。
频道的概念请参考频道，接口请参考Channel API。
3.9. 音视频通话与会议
机器人可以以虚拟用户的身份参与到音视频通话和会议中。结合语音流处理能力，未来可以实现AI与用户实时音视频交互的场景。
4. 推荐实践
4.1. 用群组对应Agent的项目空间
Agent平台普遍有"项目空间（Workspace/Project）"的概念，推荐用群组来承载：
- 群即空间，群成员是空间成员（人 + 机器人/Agent），群消息历史即空间共享上下文，会话级用户设置即空间配置和状态。
- 配合机器人的群组管理能力，可以让Agent按任务动态建群、邀请相关的人和Agent加入、任务结束后解散，对应Agent工作流中"为每个任务开一个空间"的模式。
需要注意，群组没有真正的"工作目录"，Agent项目空间中的文件资源需要用群文件、自定义消息等来承载，两者不是完全等价的。
4.2. 多Agent协作（Agent与Agent对话）
机器人本质上是普通用户身份，因此Agent之间也可以像人一样对话，天然支持多Agent协作：
- 把多个机器人拉进同一个群，Agent A发出的消息会通过回调推送给Agent B的服务，B处理后再回复，A同样可以收到，形成Agent之间的对话链路。
- 群组作为协作空间，对话过程对人类成员完全可见、可追溯，人可以随时介入、纠正或接管，这比Agent之间私下的API调用更透明。
- 可以用
@或自定义消息卡片来指定任务的接收方，配合会话级用户设置同步各Agent的分工和状态。
需要注意防止死循环：Agent互相触发可能无限对话下去，Agent服务侧需要做收敛控制，比如不响应其他机器人的消息、只在被@时响应、限制连续对话轮次等。另一个推荐的做法是让Agent支持流式取消消息（类型20）：Agent收到消息开始生成回复后，如果判断这条消息不需要回复（比如来自其他机器人、对话已收敛），直接发送取消消息，客户端会按streamId删除对应的生成中消息且不落库，相当于"想了想决定不说了"，不会在会话中留下任何痕迹。
4.3. 用会话线路（line）区分Agent会话
野火会话有一个线路（line）属性，用于过滤和区分会话。可以为Agent会话选一个单独的线路值（比如1），机器人发送消息时把会话的line设置为该值：
- 客户端既可以按line把Agent会话和普通会话一起显示，也可以分开单独显示（比如一个独立的"AI助手"入口）。
- 针对该线路的会话可以做特殊处理，比如启用流式消息刷新、渲染AI专用卡片、关闭已读回执等。
4.4. 设计交互卡片和进度状态
- 简单结果用普通消息回复；需要用户选择或确认的，用自定义消息渲染成交互卡片，用户操作后机器人收到回调继续处理。
- 长任务先回复一条"处理中"消息，过程中用更新消息接口原地刷新状态（进行中 → 完成/失败），避免刷屏。
- 需要向会话内所有成员同步Agent的状态/进度时，使用会话级用户设置接口，客户端在会话界面读取展示。
4.5. 上下文记忆
Robot API只负责消息的收发，不提供历史消息查询，上下文记忆需要自行解决，两种方案：
- Agent服务自己保存所有回调收到的消息，按会话组织，调用大模型时拼入上下文。
- 在robot-gateway中按机器人和会话维度存储消息，Agent按需向网关查询。这样上下文存储集中在网关，多个Agent服务实例可以共享。
无论哪种方案，发往大模型前都要做上下文窗口的裁剪或摘要，群聊场景尤其要注意。
4.6. 状态指示
建议多种状态手段双管齐下，让用户清楚感知Agent的工作状态：
- 输入提示（"对方正在输入"）：Agent收到消息开始处理时展示。
- 流式生成中：回复内容开始生成后，用流式消息（类型14/15）实时刷新气泡。
- 会话级用户设置：展示更精细的状态，比如"思考中"、"执行工具"、"运行完成"等，客户端在会话界面读取展示。
4.7. 媒体处理
- 发送：Agent可以把生成的图片、语音、文件等通过对应的媒体消息类型发送给用户。
- 接收：用户消息中的图片、语音、文件等媒体内容，Agent服务可以下载下来处理（比如语音先转文字再交给大模型）。
5. 安全与合规
- 凭证安全：robotId/secret是机器人的全部权限凭证，所有接口调用都靠它签名（同时带时间戳防重放），务必妥善保管。目前robotId/secret保存在Agent本地，如果想要提高安全性，可以改造认证方式：把secret保存在robot-gateway侧，Agent本地不保存secret，改为通过临时验证获取cookie/token后再连接网关。
- 权限边界：机器人只有普通用户的权限，权限可控、可随时收回。注意不要把管理API（
/admin/）暴露给Agent，管理API权限过大，一旦泄露风险很高。 - 内容合规：AI生成的内容需要符合相关法律法规，建议对Agent的输入和输出做审核，可以结合IM服务的敏感词等能力。开发运营社交类应用也要注意合规要求，请参考开发运营社交软件也要遵守法律。
6. 持续演进
野火IM的连接能力是分步演进的：人和人的连接是IM的本职；机器人（虚拟用户的双向沟通能力）打通了服务和人的连接。进入AI时代，连接的主体从"人"扩展到"Agent"，接下来要完善的是三类连接：
- 人和Agent：让用户像与人聊天一样和AI助手协作，并实时感知Agent的工作状态——本文介绍的流式回复、交互卡片、会话级用户设置等能力都服务于这个目标。
- 服务和Agent：现有系统可以用消息通知Agent，让Agent实时感知到现有服务的状态。
- Agent和Agent：机器人本质上是普通用户，Agent之间可以在群组中像人一样对话和协作，过程对人可见、可介入、可接管。更多思考请参考Agent通信的未来。
野火会持续推进，满足客户需求，更好地支撑AI应用的落地。
7. 参考文档
- 如何正确地理解机器人
- Robot API接口
- Channel API接口
- 内置消息内容
- 自定义消息内容
- 野火机器人MCP服务简介
- 野火IM x OpenClaw打造你的私有化AI助手
- 野火IM × Hermes：把企业即时通讯接入AI Agent时代