# Raft

> 通过 Raft CLI 唤醒桥接器支持 Raft 外部智能体

- 网址：https://funcoding.ai/agents/openclaw/channels/raft/
- 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/channels/raft

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

## 安装

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

```bash
openclaw plugins install @openclaw/raft
openclaw gateway restart
```

详情：[插件](https://funcoding.ai/agents/openclaw/tools/plugin/)

## 前提条件

- 具有 External Agent 的 Raft 工作区。
- Raft CLI 安装在 OpenClaw Gateway 网关所在的同一主机上，并且位于服务的
  `PATH` 中。
- 已登录且已与该 External Agent 关联的 Raft CLI 配置文件。

该插件不存储 Raft 凭据；Raft CLI 将该身份验证信息保存在其自己的配置文件中。

## 配置

在配置中设置配置文件：

```json5
{
  channels: {
    raft: {
      enabled: true,
      profile: "openclaw",
    },
  },
}
```

对于默认账户，也可以在 Gateway 网关环境中设置 `RAFT_PROFILE`：

```bash
RAFT_PROFILE=openclaw
```

当一个 Gateway 网关连接到多个 Raft External Agent 时，请使用命名账户：

```json5
{
  channels: {
    raft: {
      accounts: {
        support: {
          profile: "support-agent",
        },
        engineering: {
          profile: "engineering-agent",
        },
      },
    },
  },
}
```

交互式设置会记录同一配置文件：

```bash
openclaw channels add --channel raft
```

## 工作原理

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 读取待处理消息并发送响应：

```bash
raft --profile openclaw message check
raft --profile openclaw message send
```

<div class="callout callout-note">

Raft 不是推送消息传输方式。OpenClaw 不会通过桥接器自动发回模型的最终文本，因此智能体必须在处理唤醒后使用 Raft CLI。

</div>

## 验证

检查 OpenClaw 是否能找到 CLI 且已配置配置文件：

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

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

## 故障排查

<details>
<summary>缺少 Raft CLI</summary>

在 Gateway 网关主机上安装 Raft CLI，并确保服务的 `PATH` 中可以访问
`raft`。使用 `raft --help` 进行验证，然后重启 Gateway 网关。

</details>

<details>
<summary>桥接器立即退出</summary>

验证已配置的配置文件处于登录状态，并且属于预期的
Raft External Agent。直接运行 `raft --profile <profile> agent bridge`
以查看 CLI 诊断信息。

</details>

<details>
<summary>收到唤醒，但未发送 Raft 响应</summary>

如果智能体未调用 Raft CLI，这是预期行为。唤醒桥接器
不传递消息正文或自动最终回复。检查智能体的工具策略，并确保它可以运行
`raft --profile <profile>
message check` 和 `message send`。

</details>

## 参考资料

- [Raft](https://raft.build/)
- [Raft 文档](https://docs.raft.build/welcome/)
- [Hermes Raft 集成](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/raft)