Raft External Agent Support via the Raft CLI Wake Bridge

Raft links an OpenClaw agent to a Raft External Agent by way of the local Raft CLI. Authenticated wake hints travel from Raft to the Gateway, after which the agent checks and sends messages through the Raft CLI. Chat is one-to-one only; groups are not supported.

Install

Raft ships as an official external plugin. Put it on the host running the Gateway:

openclaw plugins install @openclaw/raft

Before moving on, review the application result.

Prerequisites

• A Raft workspace containing an External Agent.
• The Raft CLI present on the same host as the OpenClaw Gateway, running under the service's PATH.
• A Raft CLI profile already signed in and tied to that External Agent.

No Raft credentials are kept by the plugin; authentication lives in the Raft CLI's own profile.

Configure

Point config at the profile:

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

Alternatively, for the default account, place RAFT_PROFILE in the Gateway environment:

RAFT_PROFILE=openclaw

When a single Gateway talks to multiple Raft External Agents, use a named account:

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

The interactive setup stores the same profile:

openclaw channels add --channel raft

How it works

On Gateway startup, the plugin does the following:

1. Binds a loopback-only HTTP wake endpoint to an ephemeral port.
2. Launches raft --profile <profile> agent bridge with that endpoint plus a per-process token.
3. Admits only authenticated, content-free wake hints carrying a replay identity from the local bridge.
4. Demands one of eventId, attemptId, messageId, delivery_id, wake_id, or id on each wake payload.
5. Deduplicates retried wake deliveries by bridge event id for 24 hours, surviving Gateway restarts as well.
6. Hands back a stable runtime session for the current bridge and an empty activity-drain batch for the Raft CLI protocol.
7. Begins one serialized OpenClaw agent turn for every wake it accepts.

Retries and reconnects for Raft delivery belong to the bridge. What the OpenClaw turn gets is a wake notice alone, never a copied Raft message body. Reading pending messages and sending a reply both happen through the CLI:

raft --profile openclaw message check
raft --profile openclaw message send

Note

Raft does not work as a push-message transport. The model's final text is never sent back through the bridge automatically by OpenClaw, so after handling a wake the agent has to use the Raft CLI.

Verify

Confirm OpenClaw can locate the CLI and that a profile is configured:

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

Next, message the Raft External Agent. The Gateway log ought to show the Raft bridge starting, then an inbound wake. The agent should check its pending messages using the configured Raft profile.

Troubleshooting

Raft CLI is missing

Put the Raft CLI on the Gateway host and expose raft under the service's PATH. Confirm with raft --help, then restart the Gateway.

The bridge exits immediately

Make sure the configured profile is signed in and belongs to the intended Raft External Agent. Run raft --profile <profile> agent bridge on its own to inspect the CLI diagnostic.

A wake arrives but no Raft response is sent

This happens when the agent never calls the Raft CLI. Message bodies and automatic final replies are not carried by the wake bridge. Review the agent's tool policy and confirm it is allowed to run raft --profile <profile> message check and message send.

References

• Raft
• Raft documentation
• Hermes Raft integration