> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw-simplex.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 <code>simplex-chat</code> 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.

<Steps>
  <Step title="OpenClaw loads the plugin">
    OpenClaw registers the <code>openclaw-simplex</code> channel. For disabled or unconfigured channels, it can use the lightweight setup entry before loading the full runtime entry.
  </Step>

  <Step title="The plugin attaches to your SimpleX runtime">
    OpenClaw only starts the channel after explicit <code>channels.openclaw-simplex.connection</code> config exists. The plugin then connects to the separately running <code>simplex-chat</code> WebSocket API.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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. When <code>streaming.nativeTransport</code> is enabled for the account, assistant text previews use SimpleX live messages and the final text edits that same message in place.
  </Step>
</Steps>

<Note>
  SimpleX-native live replies are opt-in and text-only. Media, polls, and explicit action sends continue to use normal delivery, and failed live updates fall back to normal sends.
</Note>

<Note>
  OpenClaw does not spawn <code>simplex-chat</code>, 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.
</Note>

## What the plugin surfaces

<Columns cols={2}>
  <Card title="Runtime status" icon="activity">
    Channel status snapshots, health state, disconnect tracking, and runtime error surfaces.
  </Card>

  <Card title="Multi-account routing" icon="users">
    Default-account behavior and per-account overrides under the shared <code>openclaw-simplex</code> channel config.
  </Card>
</Columns>

<Columns cols={2}>
  <Card title="Message actions" icon="send">
    Send, react, poll, edit, delete, upload-file, and group management actions.
  </Card>

  <Card title="Operational helpers" icon="bolt">
    Directory lookups, target resolution, heartbeat readiness, and gateway invite methods for developer-controlled onboarding and automation flows.
  </Card>
</Columns>