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",
      "contextVisibility": "allowlist",
      "allowFrom": ["*"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": [],
      "mediaMaxMb": 5,
      "messageTtlSeconds": 86400,
      "streaming": {
        "nativeTransport": false,
        "throttleMs": 2000,
        "minChars": 24,
        "wordBoundary": true
      },
      "filePolicy": {
        "autoAccept": true,
        "maxSizeMb": 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",
          "contextVisibility": "allowlist",
          "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.
contextVisibility	OpenClaw supplemental context visibility mode for the channel/account: all | allowlist | allowlist_quote. Use this when you want tighter control over what extra context the channel may expose to agent runs.
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.
streaming.nativeTransport	Enables SimpleX-native live assistant text replies. Disabled by default so intermediate assistant text is not exposed unless explicitly enabled.
streaming.throttleMs	Minimum delay between SimpleX live message edits. Default: 2000.
streaming.minChars	Minimum added characters before a SimpleX live message update is sent. Default: 24.
streaming.wordBoundary	Prefer live updates at word boundaries. Default: true.
messageTtlSeconds	Optional SimpleX message time-to-live applied to outbound text, media, poll, action, and reply sends for this account.
filePolicy.autoAccept	Preferred file auto-accept setting. If omitted, the legacy connection.autoAcceptFiles setting is used.
filePolicy.maxSizeMb	Operator-facing receive-side file size policy for diagnostics.
experimentalChannels	Enables capability-gated parsing for SimpleX channel-like targets such as channel:<id> and !<id>. This does not claim full SimpleX Channels support.
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.allowUnsafeRemoteWs	Allow plaintext remote WebSocket endpoints. Keep this false unless the endpoint is protected by a private network, firewall, or authenticated TLS proxy.
connection.autoAcceptFiles	Whether incoming file transfers should be auto-accepted by the SimpleX runtime.
connection.connectTimeoutMs	WebSocket connection timeout in milliseconds.
connection.commandTimeoutMs	Default SimpleX WebSocket command timeout in milliseconds.
connection.directoryTimeoutMs	Shorter timeout for advisory contact and group directory lookups.
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.

SimpleX-native live replies apply only to assistant text previews and final text. Media, polls, and explicit message actions continue to use normal SimpleX sends. If a live update fails or a payload contains media, the plugin falls back to normal delivery.

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.allowUnsafeRemoteWs
• connection.connectTimeoutMs, connection.commandTimeoutMs, and connection.directoryTimeoutMs
• connection.autoAcceptFiles
• streaming.nativeTransport, streaming.throttleMs, streaming.minChars, and streaming.wordBoundary
• messageTtlSeconds and filePolicy
• OpenClaw policy and UX settings such as dmPolicy, allowFrom, groupPolicy, contextVisibility, 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.