> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw-simplex.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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..requireMention` | Whether a group message must mention the bot before it is handled. |
| `groups..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:` and `!`. 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.` | 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](/guide/runtime-setup).