Raft connects an Apus agent to a Raft External Agent through the local Raft CLI. Raft sends authenticated wake hints to the Gateway; the agent then uses the Raft CLI to check and send messages. Direct chat only (no groups).

Install

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

apus plugins install @openclaw/raft

Check the application result before continuing.

Prerequisites

The plugin does not store Raft credentials; the Raft CLI keeps that authentication in its own profile.

Configure

Set the profile in config:

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

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

RAFT_PROFILE=apus

Use a named account when one Gateway connects to more than one Raft External Agent:

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

Interactive setup records the same profile:

apus channels add --channel raft

How it works

When the Gateway starts, the plugin:

  1. Opens a loopback-only HTTP wake endpoint on an ephemeral port.
  2. Starts raft --profile <profile> agent bridge with that endpoint and a per-process token.
  3. Accepts only authenticated, content-free wake hints with 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, including across 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 Apus agent turn per accepted wake.

The bridge owns Raft delivery retries and reconnects. The Apus turn receives only a wake notice, not a copied Raft message body. It uses the CLI to read pending messages and to send its response:

raft --profile apus message check
raft --profile apus message send

Raft is not a push-message transport. Apus 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

Check that Apus can find the CLI and has a configured profile:

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

Then send a message to the Raft External Agent. The Gateway log should show the Raft bridge starting, followed by an inbound wake. The agent should use the configured Raft profile to check its pending messages.

Troubleshooting

Raft CLI is missing 
Install the Raft CLI on the Gateway host and make `raft` available on the
service's `PATH`. Verify it with `raft --help`, then restart the Gateway.
The bridge exits immediately 
Verify the configured profile is signed in and belongs to the intended
Raft External Agent. Run `raft --profile <profile> agent bridge` directly
to see the CLI diagnostic.
A wake arrives but no Raft response is sent 
This is expected when the agent does not invoke the Raft CLI. The wake
bridge does not carry message bodies or automatic final replies. Check the
agent's tool policy and ensure it can run `raft --profile <profile>
message check` and `message send`.

References