Raft External Agent Support via Raft CLI Wake Bridge

Raft links an OpenClaw agent to a Raft External Agent using the local Raft CLI. Authenticated wake hints are sent to the Gateway by Raft; the agent then inspects and delivers messages via the Raft CLI. Only direct chat is supported, not groups.

Install

Raft is an officially supported external plugin. Install it on the Gateway host:

openclaw plugins install @openclaw/raft
openclaw gateway restart

More information: Plugins

Prerequisites

• A Raft workspace containing an External Agent.
• The Raft CLI is present on the same machine as the OpenClaw Gateway, located on the service's PATH.
• A Raft CLI profile that is already authenticated and linked to that External Agent.

Raft credentials are not stored by the plugin; the Raft CLI manages that authentication inside its own profile.

Configure

Define the profile in the configuration:

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

For the default account, RAFT_PROFILE can be set in the Gateway environment instead:

RAFT_PROFILE=openclaw

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

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

The same profile is recorded during interactive setup:

openclaw channels add --channel raft

How it works

Upon Gateway startup, the plugin performs the following actions:

1. Opens a loopback-only HTTP wake endpoint on a temporary port.
2. Launches raft --profile <profile> agent bridge with that endpoint and a per-process token.
3. Only accepts authenticated, content-free wake hints that include a replay identity from the local bridge.
4. Requires one of eventId, attemptId, messageId, delivery_id, wake_id, or id on every wake payload.
5. Deduplicates retried wake deliveries by bridge event ID for 24 hours, surviving Gateway restarts.
6. Returns a stable runtime session for the current bridge and an empty activity-drain batch for the Raft CLI protocol.
7. Starts one serialized OpenClaw agent turn per accepted wake.

The bridge is responsible for Raft delivery retries and reconnections. The OpenClaw turn only receives a wake notification, not a copy of the Raft message body. The CLI is used to read pending messages and send the response:

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

Note

Raft does not function as a push-message transport. OpenClaw does not automatically send the model's final text back through the bridge, so the agent must use the Raft CLI after processing a wake.

Verify

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

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

Next, send a message to the Raft External Agent. The Gateway log should indicate the Raft bridge has started, followed by an incoming wake. The agent should use the configured Raft profile to check its pending messages.

Troubleshooting

Raft CLI is missing

Place the Raft CLI on the Gateway host and ensure raft is accessible on the service's PATH. Verify with raft --help, then restart the Gateway.

The bridge exits immediately

Make sure the configured profile is authenticated and assigned to the correct Raft External Agent. Run raft --profile <profile> agent bridge directly to view the CLI diagnostic.

A wake arrives but no Raft response is sent

This occurs when the agent does not call the Raft CLI. The wake bridge does not carry message bodies or automatic final replies. Review the agent's tool policy and confirm it can execute raft --profile <profile> message check and message send.

References

• Raft
• Raft documentation
• Hermes Raft integration