Raft

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

安装¶

Raft 是官方外部插件。请在 Gateway 主机上安装它：

openclaw plugins install @openclaw/raft

继续之前，请检查应用结果。

前提条件¶

• 一个包含外部代理的 Raft 工作区。
• Raft CLI 已安装在与 OpenClaw Gateway 相同的主机上，并且位于该服务的 PATH 中。
• 一个已登录并关联到该外部代理的 Raft CLI profile。

该插件不存储 Raft 凭据；Raft CLI 会在其自身 profile 中保存该身份验证信息。

配置¶

在配置中设置 profile：

{
  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",
        },
      },
    },
  },
}

交互式设置会记录相同的 profile：

openclaw channels add --channel raft

工作原理¶

Gateway 启动时，该插件会：

1. 在临时端口上打开一个仅限回环的 HTTP 唤醒端点。
2. 使用该端点和每进程 token 启动 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 --profile openclaw message check
raft --profile openclaw message send

验证¶

检查 OpenClaw 能否找到 CLI，并且已配置 profile：

openclaw channels status --probe
openclaw plugins inspect raft --runtime --json

然后向 Raft 外部代理发送一条消息。Gateway 日志应显示 Raft 桥接进程启动，随后出现传入唤醒。代理应使用已配置的 Raft profile 检查其待处理消息。

故障排除¶

参考资料¶

• Raft
• Raft 文档
• Hermes Raft 集成