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

# 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 <code>2026.5.27</code> or newer
* Node.js <code>22</code> or newer in the OpenClaw plugin host
* a <code>simplex-chat</code> CLI runtime that can expose the WebSocket API

<Steps>
  <Step title="Install SimpleX CLI">
    Install the official <code>simplex-chat</code> CLI:

    ```bash theme={null}
    curl -o- https://raw.githubusercontent.com/simplex-chat/simplex-chat/stable/install.sh | bash
    ```

    Verify the CLI:

    ```bash theme={null}
    simplex-chat -h
    ```

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

      ```bash theme={null}
      curl -o- https://raw.githubusercontent.com/dangoldbj/simplex-chat/install-arch-matrix/install.sh | bash
      ```
    </Note>
  </Step>

  <Step title="Start the SimpleX runtime">
    Start the WebSocket runtime in a separate terminal:

    ```bash theme={null}
    simplex-chat -p 5225
    ```

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

    <Info>
      This is a long-running foreground process. If you want it to start automatically, use the host-managed service examples in <a href="/guide/runtime-setup">Runtime Setup</a>.
    </Info>
  </Step>

  <Step title="Install and enable the plugin">
    Install the plugin in OpenClaw:

    ```bash theme={null}
    openclaw plugins install @dangoldbj/openclaw-simplex
    ```

    Enable it:

    ```bash theme={null}
    openclaw plugins enable openclaw-simplex
    ```

    Trust it explicitly so OpenClaw can load the channel:

    ```bash theme={null}
    openclaw config set plugins.allow "$(
      (openclaw config get plugins.allow --json 2>/dev/null || echo '[]') \
      | jq -c '. + ["openclaw-simplex"] | unique'
    )" --strict-json
    ```
  </Step>

  <Step title="Configure the channel">
    Point OpenClaw at the local SimpleX WebSocket endpoint:

    ```bash theme={null}
    openclaw channels add --channel openclaw-simplex --url ws://127.0.0.1:5225
    ```

    That command writes channel config equivalent to:

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

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

  <Step title="Generate the first invite and verify">
    Confirm the plugin is installed and enabled:

    ```bash theme={null}
    openclaw plugins list
    ```

    ```bash theme={null}
    openclaw plugins info openclaw-simplex
    ```

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

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

    ```bash theme={null}
    openclaw simplex invite create --qr
    ```

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

    In Control UI, you can also open <code>Control -> Channels -> SimpleX</code> to inspect the channel config and runtime state.

    <Note>
      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.
    </Note>
  </Step>
</Steps>

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

```bash theme={null}
openclaw pairing list
```

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

```bash theme={null}
openclaw pairing approve openclaw-simplex <pairingCode>
```

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

For a visual walkthrough, see [Screenshots](/reference/screenshots).

For recurring address links, invite listing, revoke flows, and automation APIs, see [Example Commands](/reference/example-commands) and [Gateway Methods](/reference/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`:

```bash theme={null}
openclaw simplex migrate
```

See [Migration](/guide/migration) for the full checklist and a dry-run option.