Configuration

Complete reference for every OpenClaw SimpleX channel configuration field including connection settings, DM and group policies, and multi-account setup.

The plugin reads configuration from channels.openclaw-simplex.

Minimal config

{
  "channels": {
    "openclaw-simplex": {
      "enabled": true,
      "connection": {
        "wsUrl": "ws://127.0.0.1:5225"
      }
    }
  }
}

Single-account config

If accounts is not set, the root channels.openclaw-simplex object acts as the default account config.

{
  "channels": {
    "openclaw-simplex": {
      "enabled": true,
      "name": "SimpleX",
      "actions": {
        "reactions": true,
        "polls": true
      },
      "reactionLevel": "minimal",
      "dmPolicy": "pairing",
      "allowFrom": ["*"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": [],
      "mediaMaxMb": 5,
      "connection": {
        "wsUrl": "ws://127.0.0.1:5225",
        "connectTimeoutMs": 15000
      }
    }
  }
}

Multi-account config

If accounts is set, each account entry can override the shared root config. This is the model to use when different SimpleX identities or runtimes should map to different OpenClaw channel accounts.

{
  "channels": {
    "openclaw-simplex": {
      "enabled": true,
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "connection": {
        "wsUrl": "ws://127.0.0.1:5225"
      },
      "accounts": {
        "ops": {
          "name": "Ops",
          "enabled": true,
          "reactionLevel": "extensive",
          "allowFrom": ["alice", "bob"],
          "connection": {
            "wsUrl": "ws://127.0.0.1:7777"
          }
        }
      }
    }
  }
}

Field reference

Field	Meaning
enabled	Master toggle for the channel or account.
name	Optional display name for an account.
actions.reactions	Enable or disable agent reaction actions for this channel/account.
actions.polls	Enable or disable poll-style message actions for this channel/account.
reactionLevel	Agent reaction behavior: off | ack | minimal | extensive.
dmPolicy	Direct-message policy: open | allowlist | pairing | disabled. Effective default: pairing.
allowFrom	DM allowlist entries.
dmHistoryLimit	Optional per-DM history limit.
dms	Per-DM config overrides using OpenClaw’s shared DM config schema.
groupPolicy	Group-message policy: open | allowlist | disabled.
groupAllowFrom	Group allowlist entries.
groups.<groupId>.requireMention	Whether a group message must mention the bot before it is handled.
groups.<groupId>.tools	Per-group tool policy using OpenClaw’s shared tool policy schema.
mediaMaxMb	Maximum accepted/uploaded media size in MB.
markdown	Markdown rendering config from OpenClaw’s shared channel schema.
blockStreaming	If true, buffer the response instead of streaming partial output.
blockStreamingCoalesce	Optional response coalescing behavior for blocked streaming.
connection.mode	Connection mode. Only external is supported.
connection.wsUrl	WebSocket URL for the running simplex-chat WebSocket API. If set, this wins over wsHost/wsPort.
connection.wsHost	Optional host fallback when wsUrl is not set. Default: 127.0.0.1.
connection.wsPort	Optional port fallback when wsUrl is not set. Default: 5225.
connection.autoAcceptFiles	Whether incoming file transfers should be auto-accepted by the SimpleX runtime.
connection.connectTimeoutMs	WebSocket connection timeout in milliseconds.
accounts.<accountId>	Per-account overrides for the same schema.

A channel/account is considered configured only when connection.wsUrl, connection.wsHost, or connection.wsPort is present. If none of those are set, OpenClaw will not treat the channel as startup-ready.

What belongs in plugin config vs runtime startup

This plugin talks to an already running external simplex-chat process. That means the OpenClaw config only models settings the plugin can truthfully use at runtime.

Good fit for plugin config

• connection.wsUrl, wsHost, wsPort
• connection.connectTimeoutMs
• connection.autoAcceptFiles
• OpenClaw policy and UX settings such as dmPolicy, allowFrom, groupPolicy, actions, and reactionLevel

Intentionally not mirrored into plugin config

These are primarily simplex-chat startup or environment flags, so they belong in the host-managed service command line, not in channels.openclaw-simplex:

• transport/bootstrap: —server, —xftp-server, —socks-proxy, —socks-mode, —host-mode, —required-host-mode, —smp-proxy, —smp-proxy-fallback, —smp-web-port
• local process/file layout: -d/—database, -k/—key, —files-folder, —temp-folder, —log-file
• runtime process behavior: —device-name, —maintenance, —mute, —mark-read, —reactions, —create-bot-display-name

Those flags can still be valuable, but the right place to set them is the supervised simplex-chat service definition described in Runtime Setup.