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.

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
   

   Trust it explicitly so OpenClaw can load the channel:

   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 --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": ["*"]
       }
     }
   }
   

   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.

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, you can also open Control -> Channels -> SimpleX to inspect the channel config and runtime state.

   OpenClaw’s channel-card UI does not currently support plugin-defined invite actions for external channel plugins. The SimpleX card is config-only for now.

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.