Guide
Connect Raft to Your AI Agent
Raft calls them External Agents, and both OpenClaw and Hermes can be one. The design is unusual and worth understanding before you set it up, because it explains a behaviour that otherwise looks like a bug.
How This One Works
Most channels hand your agent the message. Raft does not. Instead a small bridge process runs alongside your agent, holds the connection to Raft, and pokes the agent when something happens. The poke carries no message content at all — just enough identifiers to know an event occurred.
The agent then uses the Raft command-line tool to go and read what is waiting, and uses it again to send its reply.
This is deliberate. Message bodies never pass through the connecting layer, so the adapter cannot leak them and holds no Raft credentials — the command-line tool keeps the login in its own profile. The wake notices are checked to make sure they really are content-free, and anything that looks like it is carrying a message body is rejected.
The Consequence Everybody Hits
Because the agent has to actively fetch and send, a reply only happens if the agent actually uses the Raft tool. If your agent's permissions do not let it run that tool, you will see the wake arrive in the logs and no answer will ever appear in Raft.
That is not a broken connection. It is the expected result of an agent that was woken up and had no way to respond. If you are debugging silence, check this before anything else.
What You Need
- A Raft workspace where you can create an External Agent.
- The Raft command-line tool installed on the same machine as your agent, and signed in to that External Agent's profile.
On a hosted instance the second point is the real work: the tool has to be installed inside your instance and logged in there, not on your laptop. Raft shows a setup card when you create the External Agent that walks through installing and logging in.
Once the profile is signed in, configuration is small. On Hermes it is a single setting naming the profile, and the adapter turns itself on when it sees it. On OpenClaw the plugin is installed and pointed at the same profile. Either way you can run more than one, if a single agent serves several Raft workspaces.
What the Bridge Handles for You
Reconnection, retries and delivery guarantees belong to the bridge, not to your agent. It is started and stopped automatically with the agent, listens only on the machine itself, and authenticates with a token generated fresh for each run.
Repeated deliveries of the same event are recognised and dropped for a day, including across restarts, so a retry storm does not turn into your agent answering the same message ten times.
Turns are handled one at a time rather than in parallel.
Scope
This is direct chat only — there are no group conversations on this channel. And it is worth repeating that the agent is not push-replying: nothing your agent says is automatically forwarded to Raft. It has to send, deliberately, through the tool.
Troubleshooting
- The tool is missing. It is not installed in the instance, or not on the path the agent's service can see. Confirm it runs from a plain shell there first.
- The bridge starts and immediately exits. The profile is not signed in, or belongs to a different External Agent than you think. Run the bridge by hand to see what it says.
- A wake arrives, no reply is sent. The agent is not invoking the Raft tool — the case described above. Check its tool permissions.
- Duplicate replies. Should not happen inside the dedupe window; if it does, look for two agents sharing one profile.
Need a Hand?
Contact support from your dashboard and we will get the Raft tool installed and the profile signed in on your instance. The sign-in is yours to complete — we will not log into your Raft account for you.