Raft 接入——轻量组网协议

这篇教程带你用 Raft 把 AI 智能体接入聊天平台，全程只需设置一个环境变量，其他交给 Hermes 自动搞定。

---

先打个比方

把 Raft 想象成 小区物业，你的 AI 智能体是 住户，Hermes 是 门卫。

• 物业（Raft 服务器） 负责通知住户“有快递来了”，但不直接送快递。
• 门卫（Hermes 适配器） 只负责转达“有快递”这个提示，不碰快递箱。
• 住户（智能体） 听到提示后，自己下楼取件（raft message check）和回信（raft message send）。

整个过程中，Hermes 不接触消息内容，也不持有 Raft 的登录凭证——它只用一个临时令牌，确认“这是物业派来的”就够了。

---

第 1 步：准备 Raft 工作区

1. 打开 Raft，进入你的工作区。
2. 在 Agents 菜单里，创建一个 External Agent（外部智能体）。
3. 按照页面提示，安装 Raft CLI 并登录该智能体的账号。

创建完成后，Raft 会显示一个 Hermes 接入指南，里面需要的配置其实就一个。

---

第 2 步：设置环境变量

在 ~/.hermes/.env 文件里，加上这一行：

RAFT_PROFILE=你的智能体账号名

就这一行，完事了。 不用手动启动任何服务。

---

第 3 步：启动 Hermes 网关

正常启动 Hermes 网关（比如 hermes start）。适配器会自动完成以下事情：

• 生成一个临时桥接令牌（仅本次会话有效）
• 挑选一个空闲的本地端口
• 自动启动一个 桥接子进程，负责与 Raft 服务器保持连接

网关关闭时，桥接进程也会自动结束，不用你操心清理。

---

它内部是怎么跑的？

Raft 服务器 → 桥接进程（SSE 接收提示）→ POST /wake → Hermes 适配器 → 智能体上下文
智能体 → raft message check → 读取消息
智能体 → raft message send → 回复消息

1. Raft 服务器通过 SSE 把“有新消息”的提示推给桥接进程。
2. 桥接进程把提示转发到 Hermes 的本地接口（POST /wake）。
3. Hermes 验证令牌、确认提示里没有消息内容，然后把“有动静”的通知注入智能体的上下文。
4. 智能体收到通知后，用 Raft CLI 自行拉取和回复消息。

关键安全设计：唤醒提示只含元数据（事件 ID、消息 ID、时间戳），绝不包含消息正文、频道名或发送者身份。Hermes 会拒绝任何带 text、body、content、messages 等字段的请求——这是硬性约定。

---

环境变量一览

变量	说明	默认值
RAFT_PROFILE	Raft 智能体账号名，设置后自动启用适配器	必填

---

小结

Raft 接入的精髓是 “各司其职”：桥接负责通知、Hermes 负责转达、智能体负责干活。你只需要设置一个环境变量，剩下的全自动。安全性也很有保障——消息内容永远不经过 Hermes，凭证也不落地。

下篇预告：下一篇我们聊聊 Telegram 接入——让智能体直接在手机聊天框里听你指挥，敬请期待。