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.
mentionPatterns.mode	Where agent name patterns count as a mention: allow limits pattern matching to the allowIn groups; deny disables it in the denyIn groups.
mentionPatterns.allowIn	SimpleX group ids where agent name patterns count as a mention (used with mode: "allow").
mentionPatterns.denyIn	SimpleX group ids where agent name patterns must not count as a mention (used with mode: "deny").
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.
draftChunk.minChars	Minimum characters before the live draft updates.
draftChunk.maxChars	Maximum characters shown in a single live draft update. The final reply is never truncated.
draftChunk.breakPreference	Where a live draft update trims back to: paragraph | newline | sentence.
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.filesFolder	Path where OpenClaw reads files the external runtime received. Only used when the runtime runs with --files-folder (it then reports file names only, and the plugin joins them to this path). Set it to OpenClaw’s view of the runtime’s files folder — the same path on a shared filesystem, or OpenClaw’s mount of the shared volume across containers. Default: ~/.simplex/files.
connection.outboundFolder	Directory OpenClaw stages outgoing files into so the external runtime can read them on send. Only needed when the runtime doesn’t share a filesystem with OpenClaw (e.g. the runtime runs in a container). OpenClaw writes the file here and passes its path in the send command; if both sides mount the directory at the same path, that’s all you need. Unset = the local file path is passed to the runtime as-is (single-filesystem default).
connection.outboundFolderOnClient	The outboundFolder directory as the runtime sees it, when the two sides mount the shared directory at different paths. When set (with outboundFolder), OpenClaw still writes to outboundFolder but rewrites the directory prefix to this before sending — so no matching/verbatim path is required. No effect without outboundFolder.
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.

draftChunk is OpenClaw’s standard live-draft chunking shape and is optional. When set, it takes precedence over streaming.minChars and streaming.wordBoundary; when unset, those legacy settings and their defaults are unchanged. It only shapes the live in-progress draft — the final reply is always delivered in full and never truncated.

"draftChunk": {
  "minChars": 24,
  "maxChars": 800,
  "breakPreference": "sentence"
}

mentionPatterns scopes where the agent’s name patterns count as a mention, so a bot can stay quiet in some groups and respond to name mentions in others. It refines mention handling only; groupPolicy, groupAllowFrom, and per-group requireMention still decide whether a group is handled at all.

"mentionPatterns": {
  "mode": "allow",
  "allowIn": ["group:42"]
}

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
• draftChunk.minChars, draftChunk.maxChars, and draftChunk.breakPreference
• messageTtlSeconds and filePolicy
• OpenClaw policy and UX settings such as dmPolicy, allowFrom, groupPolicy, groupAllowFrom, mentionPatterns, 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.