> ## 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.

# Architecture

> Understand the runtime boundaries between OpenClaw, the SimpleX channel plugin, and the external simplex-chat process including their responsibilities.

The architecture is built around one rule: OpenClaw should enforce policy and route messages, but it should not own the <code>simplex-chat</code> process lifecycle for this plugin.

That separation keeps the channel implementation explicit, makes host-level supervision a deployment choice, and avoids hiding the network/runtime boundary inside plugin startup code.

## High-level diagram

```text theme={null}
            +-------------------------+
            |        OpenClaw         |
            |  (agent + router/core)  |
            | - policy enforcement    |
            +------------+------------+
                         |
                         | channel plugin API
                         v
            +-------------------------+
            | @dangoldbj/openclaw-    |
            |        simplex          |
            | - inbound monitor       |
            | - outbound translation  |
            | - account/runtime state |
            +------------+------------+
                         |
                         | WebSocket API
                         v
            +-------------------------+
            |   SimpleX CLI Runtime   |
            |      (simplex-chat)     |
            +------------+------------+
                         |
                         | network
                         v
            +-------------------------+
            |      SimpleX Network    |
            +-------------------------+
```

## Boundaries

<Columns cols={2}>
  <Card title="Policy boundary" icon="shield">
    Access checks stay in OpenClaw through <code>dmPolicy</code>, <code>allowFrom</code>, <code>groupPolicy</code>, pairing state, and command authorization.
  </Card>

  <Card title="Runtime boundary" icon="server">
    The plugin connects to a separately running <code>simplex-chat</code> instance over WebSocket instead of spawning or supervising that process.
  </Card>
</Columns>

<Columns cols={2}>
  <Card title="Account boundary" icon="users">
    Account-specific overrides live under <code>channels.openclaw-simplex.accounts</code>, while shared channel config remains at the channel root.
  </Card>

  <Card title="Failure isolation" icon="triangle-alert">
    If the SimpleX WebSocket endpoint is unavailable, this channel reports a runtime error and disconnect state without taking down unrelated OpenClaw channels.
  </Card>
</Columns>

## Data flow

1. <code>simplex-chat</code> emits events through its WebSocket API.
2. The plugin monitor parses those events into OpenClaw channel context.
3. OpenClaw applies policy checks and runs the agent.
4. The plugin translates replies, live text updates, edits, reactions, media sends, and group actions back into SimpleX commands.

## Implementation surfaces

* <code>src/channel/events/simplex-monitor.ts</code>: inbound SimpleX event monitoring, reconnect handling, parsing, and message normalization.
* <code>src/channel/messaging/simplex-send.ts</code> and <code>src/channel/messaging/simplex-outbound.ts</code>: outbound message delivery, optional SimpleX-native live text replies, and reply translation.
* <code>src/actions/actions.ts</code>, <code>src/actions/message-actions.ts</code>, and <code>src/actions/group-actions.ts</code>: shared OpenClaw message actions such as upload-file, reactions, polls, edits, deletes, and group operations.
* <code>src/simplex/runtime/ws-client.ts</code> and <code>src/simplex/runtime/transport.ts</code>: WebSocket transport and command execution.
* <code>channels.openclaw-simplex</code> and <code>channels.openclaw-simplex.accounts</code>: shared and per-account runtime config.