Getting Started

Install simplex-chat, configure the OpenClaw SimpleX plugin, generate your first invite link, and pair your first contact with the agent step by step.

This path gets you from zero to the first invited contact talking to your OpenClaw agent over SimpleX.

Requirements

• OpenClaw 2026.9.3 or newer
• Node.js as required by your OpenClaw release. 2026.9.3 needs >=24.16.0 <25 or >=26.1.0 — Node 22, 23 and 25 are not supported. Check with npm view openclaw engines.node
• a simplex-chat CLI runtime that can expose the WebSocket API

1. Install SimpleX CLI

   Install the official simplex-chat CLI:

   curl -o- https://raw.githubusercontent.com/simplex-chat/simplex-chat/stable/install.sh | bash
   

   Verify the CLI:

   simplex-chat -h
   

   If the official installer picks the wrong Darwin/Linux build for your host, use the temporary arch-matrix installer:

   curl -o- https://raw.githubusercontent.com/dangoldbj/simplex-chat/install-arch-matrix/install.sh | bash
   
2. Start the SimpleX runtime

   Start the WebSocket runtime in a separate terminal:

   simplex-chat -p 5225
   

   Expected result: simplex-chat stays in the foreground and serves the WebSocket API on port 5225.

   This is a long-running foreground process. If you want it to start automatically, use the host-managed service examples in Runtime Setup.

3. Install and enable the plugin

   Install the plugin in OpenClaw:

   openclaw plugins install @dangoldbj/openclaw-simplex
   

   Enable it:

   openclaw plugins enable openclaw-simplex
   

   Only do this if you already maintain an allowlist. plugins.allow is exclusive: when it is unset every plugin is allowed, and setting it to a single entry disables every other plugin — including your model provider. Check first:

   openclaw config get plugins.allow --json
   

   If that prints null, skip this step. The channel loads without it.

   If you do maintain an allowlist, append this plugin to it rather than replacing it:

   openclaw config set plugins.allow "$(
     (openclaw config get plugins.allow --json 2>/dev/null || echo '[]') \
     | jq -c '. + ["openclaw-simplex"] | unique'
   )" --strict-json
   
4. Configure the channel

   Point OpenClaw at the local SimpleX WebSocket endpoint:

   openclaw channels add --channel openclaw-simplex --ws-url ws://127.0.0.1:5225
   

   That command writes channel config equivalent to:

   {
     "channels": {
       "openclaw-simplex": {
         "enabled": true,
         "connection": {
           "wsUrl": "ws://127.0.0.1:5225"
         },
         "dmPolicy": "pairing",
         "allowFrom": ["*"]
       }
     }
   }
   

   Loopback is the default, so --ws-url can be omitted when simplex-chat runs on the same host with -p 5225. For anything else, setup takes the endpoint directly:

   Flag	Use it for
   --ws-url <url>	A runtime at any ws:// or wss:// endpoint
   --ws-host <host> / --ws-port <port>	The same thing, split, when you only need to change one
   --outbound-folder <path>	A runtime with its own filesystem (container/remote), so outbound media can be staged where it can read it
   --allow-unsafe-remote-ws	Plaintext ws:// to a non-loopback host, which is refused without it

   OpenClaw will not start the channel until channels.openclaw-simplex.connection exists. If simplex-chat is not running at that endpoint, OpenClaw will mark the channel disconnected and record the connection error in channel status.

   A plaintext ws:// endpoint on anything but loopback is rejected at setup and again on connect. Prefer wss:// or a private sidecar network; pass --allow-unsafe-remote-ws only when the endpoint is already protected by a private network, firewall, or authenticated TLS proxy.

5. Generate the first invite and verify

   Confirm the plugin is installed and enabled:

   openclaw plugins list
   

   openclaw plugins info openclaw-simplex
   

   Expected result: openclaw-simplex appears in the plugin list, and plugin info shows it as enabled/allowed.

   Create a one-time invite link and terminal QR code:

   openclaw simplex invite create --qr
   

   Expected result: the command prints a SimpleX invite link, and —qr renders a scannable QR code in the terminal.

   In Control UI, the plugin adds its own SimpleX tab under Control. It shows each account’s runtime status, the current address link, and a scannable QR code you can point the SimpleX app at. It also lists anyone waiting on you: pending SimpleX contact requests, and pairing approvals OpenClaw is holding — each with a copy-ready command.

   The tab is read-only. OpenClaw authenticates plugin tabs for reads only, so accepting a request or approving a pairing is done from the command it shows you, not from a button in the page.

   You can still open Control -> Channels -> SimpleX to inspect the channel config and runtime state.

   OpenClaw’s generic channel card still does not support plugin-defined invite buttons for external channel plugins, so the SimpleX card itself stays config-only. The SimpleX tab is where the invite and QR surfaces live.

Pair the first contact

1. Open the invite link in the SimpleX app, or scan the QR code from your terminal.
2. Send a first message to the OpenClaw contact.
3. List pending pairing requests:

openclaw pairing list

4. Approve the request with the pairing code shown by that command:

openclaw pairing approve openclaw-simplex <pairingCode>

5. Send another message in SimpleX and verify the agent responds.

For a visual walkthrough, see Screenshots.

For recurring address links, invite listing, revoke flows, and automation APIs, see Example Commands and Gateway Methods.

Upgrading from an older simplex install

If you are upgrading from an older simplex plugin/channel install, run the migration helper before switching your config and commands to openclaw-simplex:

openclaw simplex migrate

See Migration for the full checklist and a dry-run option.