How It Works

Trace the full message lifecycle from an incoming SimpleX contact through the plugin WebSocket bridge, OpenClaw policy checks, and agent response delivery.

The runtime model is intentionally split: OpenClaw owns routing and policy, this plugin translates channel behavior, and simplex-chat remains a separately managed process with a WebSocket API.

The invite or address link is the access boundary. Once a sender reaches the agent through SimpleX, OpenClaw still applies pairing approval, allowlists, and group policy before that sender can trigger agent work.

1. OpenClaw loads the plugin

   OpenClaw registers the openclaw-simplex channel. For disabled or unconfigured channels, it can use the lightweight setup entry before loading the full runtime entry.

2. The plugin attaches to your SimpleX runtime

   OpenClaw only starts the channel after explicit channels.openclaw-simplex.connection config exists. The plugin then connects to the separately running simplex-chat WebSocket API.

3. Inbound events are normalized

   Incoming SimpleX events are parsed into OpenClaw message context, including peer/group routing, message bodies, media references, reply context, and runtime status updates.

4. Policies are applied

   OpenClaw evaluates DM policy, allowlists, group policy, pairing state, command authorization, and same-chat exec approval authorization. In pairing mode, newly discovered contacts must be approved before they become trusted senders.

5. Replies go back through SimpleX

   Message actions, media sends, polls, edits, deletes, reactions, and group operations are translated back into SimpleX commands and sent through the same WebSocket connection.

OpenClaw does not spawn simplex-chat, does not create a hosted bot identity for this channel, and does not currently expose plugin-defined invite buttons on the external plugin channel card.

What the plugin surfaces

Runtime status

Channel status snapshots, health state, disconnect tracking, and runtime error surfaces.

Multi-account routing

Default-account behavior and per-account overrides under the shared openclaw-simplex channel config.

Message actions

Send, react, poll, edit, delete, upload-file, and group management actions.

Operational helpers

Directory lookups, target resolution, heartbeat readiness, and gateway invite methods for developer-controlled onboarding and automation flows.