Skip to main content
Raft 通过本地 Raft CLI 将 OpenClaw 智能体连接到 Raft External Agent。Raft 向 Gateway 网关发送经过身份验证的唤醒提示；随后，智能体使用 Raft CLI 检查和发送消息。仅支持直接聊天（不支持群组）。

​
安装

Raft 是官方外部插件。请在 Gateway 网关主机上安装：
详情：插件

​
前提条件

  • 具有 External Agent 的 Raft 工作区。
  • Raft CLI 安装在 OpenClaw Gateway 网关所在的同一主机上，并且位于服务的 PATH 中。
  • 已登录且已与该 External Agent 关联的 Raft CLI 配置文件。
该插件不存储 Raft 凭据；Raft CLI 将该身份验证信息保存在其自己的配置文件中。

​
配置

在配置中设置配置文件：
对于默认账户，也可以在 Gateway 网关环境中设置 RAFT_PROFILE：
当一个 Gateway 网关连接到多个 Raft External Agent 时，请使用命名账户：
交互式设置会记录同一配置文件：

​
工作原理

Gateway 网关启动时，该插件会：
  1. 在临时端口上打开仅限环回访问的 HTTP 唤醒端点。
  2. 使用该端点和每进程令牌启动 raft --profile <profile> agent bridge。
  3. 仅接受来自本地桥接器、经过身份验证、不含内容且具有重放标识的唤醒提示。
  4. 要求每个唤醒负载中都包含 eventId、attemptId、messageId、delivery_id、 wake_id 或 id 之一。
  5. 根据桥接器事件 ID 对重试的唤醒投递进行 24 小时去重，该机制在 Gateway 网关重启后仍然有效。
  6. 为当前桥接器返回稳定的运行时会话，并为 Raft CLI 协议返回空的活动排空批次。
  7. 为每个已接受的唤醒启动一个串行执行的 OpenClaw 智能体轮次。
桥接器负责 Raft 投递重试和重新连接。OpenClaw 轮次仅接收唤醒通知，而不接收复制的 Raft 消息正文。它使用 CLI 读取待处理消息并发送响应：
Raft 不是推送消息传输方式。OpenClaw 不会通过桥接器自动发回模型的最终文本，因此智能体必须在处理唤醒后使用 Raft CLI。

​
验证

检查 OpenClaw 是否能找到 CLI 且已配置配置文件：
然后向 Raft External Agent 发送消息。Gateway 网关日志应显示 Raft 桥接器启动，随后出现入站唤醒。智能体应使用已配置的 Raft 配置文件检查其待处理消息。

​
故障排查

在 Gateway 网关主机上安装 Raft CLI，并确保服务的 PATH 中可以访问 raft。使用 raft --help 进行验证，然后重启 Gateway 网关。
验证已配置的配置文件处于登录状态，并且属于预期的 Raft External Agent。直接运行 raft --profile <profile> agent bridge 以查看 CLI 诊断信息。
如果智能体未调用 Raft CLI，这是预期行为。唤醒桥接器 不传递消息正文或自动最终回复。检查智能体的工具策略，并确保它可以运行 raft --profile <profile> message check 和 message send。

​
参考资料