本页内容
本页内容
开发者和自托管
Raft
Raft 通过本地 Raft CLI 将 OpenClaw 代理连接到 Raft 外部代理。 Raft 向网关发送经过身份验证的唤醒提示;然后,代理使用 Raft CLI 检查并发送消息。仅直接聊天(无群组)。
安装
Raft 是一个官方外部插件。在 Gateway 主机上安装它:
在继续之前检查 申请结果。
先决条件
- 一个带有外部代理的 Raft 工作区。
- Raft CLI 已安装在与 OpenClaw Gateway 相同的主机上,并且位于该服务的
PATH中。 - 一个已登录并且已关联到该外部代理的 Raft CLI 配置文件。
该插件不会存储 Raft 凭据;Raft CLI 会在其自己的配置文件中保留该身份验证信息。
配置
在配置中设置配置文件:
对于默认帐户,您可以在网关环境中设置 RAFT_PROFILE:
当一个网关连接到多个 Raft 外部代理时,使用指定帐户:
交互式设置会记录相同的 profile:
工作原理
当 Gateway 启动时,插件会:
- 在一个临时端口上打开仅限 loopback 的 HTTP 唤醒端点。
- 使用该端点和一个按进程分配的 token 启动
raft --profile <profile> agent bridge。 - 仅接受来自本地 bridge 的经过身份验证、无内容的唤醒提示,并带有重放标识。
- 每个唤醒负载都必须包含
eventId、attemptId、messageId、delivery_id、wake_id或id中的一个。 - 通过 bridge 事件 id 对重试的唤醒投递进行去重,保留 24 小时,包括 Gateway 重启期间。
- 为当前 bridge 返回一个稳定的运行时会话,并为 Raft CLI 协议返回一个空的活动排空批次。
- 每次接受到唤醒时,启动一个序列化的 OpenClaw agent turn。
bridge 负责 Raft 投递重试和重新连接。OpenClaw turn 只接收唤醒通知,而不会接收复制过来的 Raft 消息正文。它使用 CLI 来读取待处理消息并发送响应:
验证
检查 OpenClaw 是否能找到 CLI,并且是否已配置 profile:
然后向 Raft External Agent 发送一条消息。Gateway 日志应显示 Raft 桥接启动,随后出现一个入站唤醒。该代理应使用已配置的 Raft profile 来检查其待处理消息。
故障排查
Raft CLI失踪了
在 Gateway 主机上安装 Raft CLI,并使 raft 在该服务的 PATH 中可用。使用 raft --help 验证,然后重启 Gateway。
桥立即退出
验证所配置的 profile 已登录,并且属于目标 Raft External Agent。直接运行 raft --profile <profile> agent bridge 以查看 CLI 诊断信息。
唤醒到达但未发送 Raft 响应
当代理不调用 Raft CLI 时,这是预期的。唤醒桥不携带消息体或自动最终回复。检查代理的工具策略并检查其是否可以运行raft --profile <profile> message check和message send。