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.

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:

openclaw simplex runtime service install

The service helper auto-detects systemd —user on Linux, launchd 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 —provider systemd, —provider launchd, or —provider sysvinit to override detection.

Common install options:

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 —dry-run with install to print the plan without writing files.

The repo also ships deployment templates under examples/:

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

Decide which settings go where

Use this rule:

• put OpenClaw channel behavior in channels.openclaw-simplex
• put simplex-chat process startup flags in the supervised service command line

Plugin-side settings:

• connection.wsUrl
• connection.allowUnsafeRemoteWs
• connection.connectTimeoutMs
• connection.autoAcceptFiles
• streaming.nativeTransport and related live-reply throttling fields
• messageTtlSeconds and filePolicy
• dmPolicy, allowFrom, groupPolicy

Runtime-side startup flags:

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

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.

Linux

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

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

macOS

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

Adjust /usr/local/bin/simplex-chat if the binary is installed elsewhere on your system, and replace YOUR_USER in the folder paths.

Start it

Linux

systemctl --user daemon-reload
systemctl --user enable --now simplex-chat.service

macOS

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.simplex-chat.plist
launchctl kickstart -k gui/$(id -u)/ai.openclaw.simplex-chat

Check status

Linux

systemctl --user status simplex-chat.service

Expected result: the service status should be active (running).

macOS

launchctl print gui/$(id -u)/ai.openclaw.simplex-chat

Expected result: the launch agent should appear under that label and report a running PID.

Common startup flag patterns

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

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

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.

Maintenance mode

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

This is a simplex-chat 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 wss:// with access controls. Plaintext ws:// endpoints on non-loopback hosts are blocked by default because the WebSocket API controls the SimpleX runtime.

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