1+---
2+summary: "Raft External Agent support through the Raft CLI wake bridge"
3+read_when:
4+ - You want to connect OpenClaw to a Raft workspace
5+ - You are configuring a Raft External Agent
6+ - You are debugging Raft wake delivery
7+title: "Raft"
8+sidebarTitle: "Raft"
9+---
10+11+Raft support connects an OpenClaw agent to a Raft External Agent through the local
12+Raft CLI. Raft sends authenticated wake hints to the Gateway. The agent then uses
13+the Raft CLI to check and send messages.
14+15+## Install
16+17+Raft is an official external plugin. Install it on the Gateway host:
18+19+```bash
20+openclaw plugins install @openclaw/raft
21+openclaw gateway restart
22+```
23+24+Details: [Plugins](/tools/plugin)
25+26+## Prerequisites
27+28+- A Raft workspace with an External Agent.
29+- The Raft CLI installed on the same host as the OpenClaw Gateway.
30+- A Raft CLI profile that is already signed in and associated with that External Agent.
31+32+The plugin does not store Raft credentials. The Raft CLI keeps that authentication
33+in its own profile.
34+35+## Configure
36+37+Set the profile in config:
38+39+```json5
40+{
41+ channels: {
42+ raft: {
43+ enabled: true,
44+ profile: "openclaw",
45+ },
46+ },
47+}
48+```
49+50+For the default account, you can instead set `RAFT_PROFILE` in the Gateway
51+environment:
52+53+```bash
54+RAFT_PROFILE=openclaw
55+```
56+57+Use a named account when one Gateway connects to more than one Raft External Agent:
58+59+```json5
60+{
61+ channels: {
62+ raft: {
63+ accounts: {
64+ support: {
65+ profile: "support-agent",
66+ },
67+ engineering: {
68+ profile: "engineering-agent",
69+ },
70+ },
71+ },
72+ },
73+}
74+```
75+76+The interactive setup flow records the same profile:
77+78+```bash
79+openclaw channels setup raft
80+```
81+82+## How It Works
83+84+When the Gateway starts, the plugin:
85+86+1. Opens a loopback-only HTTP wake endpoint on an ephemeral port.
87+2. Starts `raft --profile <profile> agent bridge` with that endpoint and a
88+ per-process token.
89+3. Accepts only authenticated, content-free wake hints with a replay identity from the local bridge.
90+4. Requires one of `eventId`, `attemptId`, `messageId`, `delivery_id`, `wake_id`, or `id`.
91+5. Deduplicates recent retried wake deliveries by bridge event id, including across Gateway restarts.
92+6. Starts one serialized OpenClaw agent turn for each accepted wake.
93+94+The bridge owns Raft delivery retries and reconnects. The OpenClaw turn receives
95+only a wake notice, not a copied Raft message body. It uses the CLI to read
96+pending messages and to send its response:
97+98+```bash
99+raft --profile openclaw message check
100+raft --profile openclaw message send
101+```
102+103+<Note>
104+Raft is not a normal push-message transport. OpenClaw does not automatically
105+send the model's final text back through the bridge, so the agent must use the
106+Raft CLI after processing a wake.
107+</Note>
108+109+## Verify
110+111+Check that OpenClaw can find the CLI and has a configured profile:
112+113+```bash
114+openclaw channels status --probe
115+openclaw plugins inspect raft --runtime --json
116+```
117+118+Then send a message to the Raft External Agent. The Gateway log should show the
119+Raft bridge starting, followed by an inbound wake. The agent should use the
120+configured Raft profile to check its pending messages.
121+122+## Troubleshooting
123+124+<AccordionGroup>
125+ <Accordion title="Raft CLI is missing">
126+Install the Raft CLI on the Gateway host and make `raft` available on the
127+service's `PATH`. Verify it with `raft --help`, then restart the Gateway.
128+ </Accordion>
129+ <Accordion title="The bridge exits immediately">
130+Verify the configured profile is signed in and belongs to the intended
131+Raft External Agent. Run `raft --profile <profile> agent bridge` directly
132+to see the CLI diagnostic.
133+ </Accordion>
134+ <Accordion title="A wake arrives but no Raft response is sent">
135+This is expected when the agent does not invoke the Raft CLI. The wake
136+bridge does not carry message bodies or automatic final replies. Check the
137+agent's tool policy and ensure it can run `raft --profile <profile> message
138+check` and `message send`.
139+ </Accordion>
140+</AccordionGroup>
141+142+## References
143+144+- [Raft](https://raft.build/)
145+- [Raft documentation](https://docs.raft.build/welcome/)
146+- [Hermes Raft integration](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/raft)
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。