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

​
安装

Raft 是官方外部插件。在 Gateway 网关主机上安装它： 
openclaw plugins install @openclaw/raft
openclaw gateway restart
详情：插件

​
前提条件

  • 一个带有外部智能体的 Raft 工作区。
  • Raft CLI 已安装在与 OpenClaw Gateway 网关相同的主机上，并位于服务的 PATH 中。
  • 一个已经登录并关联到该外部智能体的 Raft CLI 配置文件。
该插件不存储 Raft 凭据；Raft CLI 会将该身份验证保存在自己的配置文件中。

​
配置

在配置中设置配置文件： 
{
  channels: {
    raft: {
      enabled: true,
      profile: "openclaw",
    },
  },
}
对于默认账号，你也可以改为在 Gateway 网关环境中设置 RAFT_PROFILE： 
RAFT_PROFILE=openclaw
当一个 Gateway 网关连接到多个 Raft 外部智能体时，请使用命名账号： 
{
  channels: {
    raft: {
      accounts: {
        support: {
          profile: "support-agent",
        },
        engineering: {
          profile: "engineering-agent",
        },
      },
    },
  },
}
交互式设置会记录相同的配置文件： 
openclaw channels add --channel raft

​
工作原理

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

​
验证

检查 OpenClaw 能否找到 CLI，并且已配置配置文件： 
openclaw channels status --probe
openclaw plugins inspect raft --runtime --json
然后向 Raft 外部智能体发送一条消息。Gateway 网关日志应显示 Raft bridge 启动，随后出现入站唤醒。智能体应使用配置的 Raft 配置文件检查其待处理消息。

​
故障排查

在 Gateway 网关主机上安装 Raft CLI，并让 raft 可通过服务的 PATH 访问。使用 raft --help 验证，然后重启 Gateway 网关。
验证已配置的配置文件已登录，并且属于预期的 Raft 外部智能体。直接运行 raft --profile <profile> agent bridge 查看 CLI 诊断信息。
如果智能体没有调用 Raft CLI，这是预期行为。唤醒 bridge 不携带消息正文，也不会自动发送最终回复。检查智能体的工具策略，并确保它可以运行 raft --profile <profile> message check 和 message send。

​
参考资料