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.

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.connectTimeoutMs
• connection.autoAcceptFiles
• 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

Create the service

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.