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

# Runtime Setup

> Configure simplex-chat as a persistent systemd or launchd service, set the WebSocket endpoint, and connect multiple SimpleX accounts to OpenClaw.

Use this page after the first setup is already working and you want to make the SimpleX runtime persistent or split multiple accounts across separate runtimes. For the first install and pairing flow, start with [Getting Started](/guide/getting-started).

## Keep `simplex-chat` running

If you want the SimpleX runtime to start automatically on login or machine boot, let the host OS supervise it and keep OpenClaw focused on the channel connection itself.

The plugin CLI can generate and install a host service for the current machine:

```bash theme={null}
openclaw simplex runtime service install
```

The service helper auto-detects <code>systemd --user</code> on Linux, <code>launchd</code> on macOS, and SysV init as a Linux fallback. It prints the generated service file and next commands first, and it asks for interactive approval before writing files. It prints supervisor commands for the operator to run instead of executing them from the plugin. Use <code>--provider systemd</code>, <code>--provider launchd</code>, or <code>--provider sysvinit</code> to override detection.

Common install options:

```bash theme={null}
openclaw simplex runtime service install \
  --port 5225 \
  --simplex-chat-path ~/.local/bin/simplex-chat \
  --device-name "OpenClaw SimpleX" \
  --files-folder ~/.simplex/files \
  --temp-folder ~/.simplex/tmp
```

Use <code>--dry-run</code> with <code>install</code> to print the plan without writing files.

The repo also ships deployment templates under <code>examples/</code>:

* <code>examples/docker-compose.sidecar.yml</code>: OpenClaw plus a private <code>simplex-chat</code> sidecar network.
* <code>examples/systemd/simplex-chat.service</code>: hardened user service template.
* <code>examples/caddy/Caddyfile</code>: TLS/auth proxy example for exceptional remote WebSocket access.

## Decide which settings go where

Use this rule:

* put OpenClaw channel behavior in <code>channels.openclaw-simplex</code>
* put <code>simplex-chat</code> process startup flags in the supervised service command line

Plugin-side settings:

* <code>connection.wsUrl</code>
* <code>connection.allowUnsafeRemoteWs</code>
* <code>connection.connectTimeoutMs</code>
* <code>connection.autoAcceptFiles</code>
* <code>streaming.nativeTransport</code> and related live-reply throttling fields
* <code>messageTtlSeconds</code> and <code>filePolicy</code>
* <code>dmPolicy</code>, <code>allowFrom</code>, <code>groupPolicy</code>

Runtime-side startup flags:

* relay and proxy selection: <code>--server</code>, <code>--xftp-server</code>, <code>--socks-proxy</code>, <code>--host-mode</code>, <code>--smp-proxy</code>
* local storage/layout: <code>--database</code>, <code>--files-folder</code>, <code>--temp-folder</code>, <code>--log-file</code>
* runtime process behavior: <code>--device-name</code>, <code>--maintenance</code>, <code>--mute</code>, <code>--mark-read</code>

### Manual service files

The CLI helper above is the preferred path. These examples show what it writes and are useful when you want to manage the service definition yourself.

<Tabs>
  <Tab title="Linux">
    ```bash theme={null}
    mkdir -p ~/.config/systemd/user
    cat > ~/.config/systemd/user/simplex-chat.service <<'EOF'
    [Unit]
    Description=SimpleX Chat WebSocket Runtime
    After=network-online.target

    [Service]
    ExecStart=%h/.local/bin/simplex-chat -p 5225 --device-name "OpenClaw SimpleX" --files-folder %h/.simplex/files --temp-folder %h/.simplex/tmp
    Restart=on-failure
    RestartSec=5

    [Install]
    WantedBy=default.target
    EOF
    ```

    <Note>
      Adjust the <code>ExecStart</code> path if <code>simplex-chat</code> is installed somewhere other than <code>%h/.local/bin/simplex-chat</code>. The extra flags above are examples of runtime-owned settings that do not belong in OpenClaw channel config.
    </Note>
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    mkdir -p ~/Library/LaunchAgents
    cat > ~/Library/LaunchAgents/ai.openclaw.simplex-chat.plist <<'EOF'
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
      <dict>
        <key>Label</key>
        <string>ai.openclaw.simplex-chat</string>
        <key>ProgramArguments</key>
        <array>
          <string>/usr/local/bin/simplex-chat</string>
          <string>-p</string>
          <string>5225</string>
          <string>--device-name</string>
          <string>OpenClaw SimpleX</string>
          <string>--files-folder</string>
          <string>/Users/YOUR_USER/.simplex/files</string>
          <string>--temp-folder</string>
          <string>/Users/YOUR_USER/.simplex/tmp</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>KeepAlive</key>
        <true/>
      </dict>
    </plist>
    EOF
    ```

    <Note>
      Adjust <code>/usr/local/bin/simplex-chat</code> if the binary is installed elsewhere on your system, and replace <code>YOUR\_USER</code> in the folder paths.
    </Note>
  </Tab>
</Tabs>

### Start it

<Tabs>
  <Tab title="Linux">
    ```bash theme={null}
    systemctl --user daemon-reload
    systemctl --user enable --now simplex-chat.service
    ```
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.simplex-chat.plist
    launchctl kickstart -k gui/$(id -u)/ai.openclaw.simplex-chat
    ```
  </Tab>
</Tabs>

### Check status

<Tabs>
  <Tab title="Linux">
    ```bash theme={null}
    systemctl --user status simplex-chat.service
    ```

    Expected result: the service status should be <code>active (running)</code>.
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    launchctl print gui/$(id -u)/ai.openclaw.simplex-chat
    ```

    Expected result: the launch agent should appear under that label and report a running PID.
  </Tab>
</Tabs>

## Common startup flag patterns

These are reasonable patterns to consider when you run <code>simplex-chat</code> as an external service:

* fixed local identity label:
  <code>--device-name "OpenClaw SimpleX"</code>
* explicit file locations:
  <code>--files-folder \~/.simplex/files --temp-folder \~/.simplex/tmp</code>
* custom relay policy:
  <code>--server "smp1.example.com smp2.example.com" --xftp-server "xftp1.example.com"</code>
* SOCKS/Tor routing:
  <code>--socks-proxy :9050 --host-mode onion --required-host-mode</code>
* stricter message routing:
  <code>--smp-proxy always --smp-proxy-fallback no</code>

<Warning>
  Do not copy every CLI flag into the service blindly. Flags such as proxy mode, relay selection, maintenance mode, and custom database paths materially change runtime behavior and should be chosen deliberately for your deployment.
</Warning>

## Maintenance mode

If you need to bring up the runtime without immediately serving chat traffic, run it with <code>--maintenance</code> and start chat manually inside the runtime later.

This is a <code>simplex-chat</code> operational mode, not an OpenClaw channel config field, so it belongs in the service command only when you intentionally want that behavior.

## Remote WebSocket endpoints

Prefer loopback, a private sidecar network, or <code>wss\://</code> with access controls. Plaintext <code>ws\://</code> endpoints on non-loopback hosts are blocked by default because the WebSocket API controls the SimpleX runtime.

Only set <code>connection.allowUnsafeRemoteWs: true</code> when that endpoint is protected by a private network, firewall, or authenticated TLS proxy.