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 simplex-chat 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

            +-------------------------+
            |        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

Policy boundary

Access checks stay in OpenClaw through dmPolicy, allowFrom, groupPolicy, pairing state, and command authorization.

Runtime boundary

The plugin connects to a separately running simplex-chat instance over WebSocket instead of spawning or supervising that process.

Account boundary

Account-specific overrides live under channels.openclaw-simplex.accounts, while shared channel config remains at the channel root.

Failure isolation

If the SimpleX WebSocket endpoint is unavailable, this channel reports a runtime error and disconnect state without taking down unrelated OpenClaw channels.

Data flow

1. simplex-chat 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

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