Skip to main content
Most failures fall into one of three buckets: the plugin is not trusted/enabled, OpenClaw cannot reach the external simplex-chat WebSocket endpoint, or policy settings are correctly rejecting a sender you expected to allow.
Two common mistakes: simplex-chat is listening on one port but wsUrl points to another, or dmPolicy: “pairing” is enabled but the sender has not been approved yet.

​
Plugin not listed

First check:
Then inspect the plugin entry directly:
What to verify:
  • the package is installed in the same runtime environment where OpenClaw is running
  • plugins.allow includes openclaw-simplex — but only if you use an allowlist at all. When plugins.allow is unset, every plugin is allowed and nothing needs adding; setting it to a single entry would disable every other plugin.
  • the plugin is enabled
  • OpenClaw has been restarted after any manual config or install changes
If the package is installed but not allowlisted, OpenClaw may still refuse to load it.

​
Channel fails to start

What to check first: simplex-chat must be running on the same WebSocket endpoint that channels.openclaw-simplex.connection.wsUrl points to. Start the runtime manually if needed:
Then verify the configured channel endpoint:
What to verify:
  • channels.openclaw-simplex.connection exists
  • wsUrl matches the port where simplex-chat is actually listening
  • if you use wsHost/wsPort instead, those values match the runtime endpoint
  • if you point at a plaintext non-loopback ws:// endpoint, either move it behind loopback/private networking or explicitly set connection.allowUnsafeRemoteWs
  • channel status shows the latest connection error if the WebSocket handshake fails
For persistent startup, run simplex-chat under a host-managed service. See Runtime Setup.

​
Channel shows Running No or Connected No

If the channel is configured but not connected, check the runtime boundary first:
  • Configured Yes means OpenClaw has enough channel config to attempt startup.
  • Running No means OpenClaw does not currently have a running channel runtime for that account.
  • Connected No means the plugin is not connected to the configured simplex-chat WebSocket endpoint.
The plugin reconnects after an unexpected SimpleX WebSocket disconnect or runtime restart, but the restarted runtime must come back on the same configured endpoint. If the card stays disconnected, verify the service logs, port binding, and connection.wsUrl.

​
Inbound messages dropped

If messages arrive in SimpleX but the agent does not answer, check policy first:
  • dmPolicy: “pairing” means a newly discovered contact must be approved before responses start
  • dmPolicy: “allowlist” means the sender must match allowFrom
  • group traffic may be blocked by groupPolicy or groupAllowFrom
  • if the account requires mentions in groups, a group message without the bot mention will be ignored
  • SimpleX group counts in runtime diagnostics are advisory directory probes; group links and group message delivery can work even when /_groups reports an empty list.
  • If a poll action is delivered successfully but OpenClaw logs an incomplete turn, check the tool result first. A poll-only model turn can be delivered as a tool action without a separate final text reply.
List pending pairing requests:
Approve a sender if needed:

​
Invite methods failing

Invite commands and gateway methods require more than plugin installation: the channel account must be configured, enabled, and connected to a live simplex-chat runtime. Use the plugin CLI first:
If that fails:
  • confirm the account’s connection.wsUrl points at a running runtime
  • check whether the channel account is enabled
  • inspect the latest channel status/runtime error in OpenClaw
  • run openclaw simplex runtime status or openclaw simplex runtime doctor for the active account
  • if you are automating through gateway methods, verify the same account works through the plugin CLI first

​
Media issues

  • media URLs must be reachable from the OpenClaw host, not just from the client that sent the command
  • check the configured size limit (mediaMaxMb)
  • if received photos or files reach the agent without their contents and the gateway log shows SimpleX inbound media staging failed with EPERM, the runtime is saving files somewhere OpenClaw may not read, usually ~/Downloads because it was started without --files-folder. Restart it with --files-folder ~/.simplex/files --temp-folder ~/.simplex/tmp, or set connection.filesFolder to match a folder of your choice
  • verify the source URL returns a usable content type and file payload
  • if a specific message action fails, retry with a small known-good file first to separate transport issues from size/type issues

​
Useful diagnostic commands

Start the runtime in the foreground and watch connection behavior directly:
List installed plugins:
Inspect this plugin’s enable/allow state:
Write the channel endpoint config explicitly:
Show runtime status:
Run runtime diagnostics:
In a terminal this prints a readable summary; it exits non-zero when the runtime is unhealthy, so it can gate a script or CI step:
Every SimpleX command prints a human-readable summary on a terminal and raw JSON when redirected or piped, so existing automation is unaffected. Pass —json to force JSON in a terminal. Run the runtime doctor again after enabling SimpleX-native live replies with streaming.nativeTransport. The doctor reports advisory capability probe states from the active WebSocket runtime, but it does not spawn, supervise, or manage simplex-chat. The top-level openclaw doctor also probes each configured SimpleX account’s runtime, so an unreachable WebSocket, a missing user profile, or an unsafe remote endpoint is reported alongside the static config checks. The probe is bounded and never fails the run. Set OPENCLAW_SIMPLEX_DOCTOR_SKIP_RUNTIME_PROBE=1 to skip it, which is useful in CI or when auditing config offline:
openclaw doctor also reports pre-1.0 config left over from the simplex era — a channels.simplex section, or managed-runtime fields such as managed, cliPath, or a top-level wsUrl — and repairs them under its fix command. List pending SimpleX contact requests:

​
Where to inspect errors

  • In Control UI, open the SimpleX tab under Control. Each configured account shows its WebSocket endpoint, connection state, runtime version, whether a user profile is active, and any transport security warnings. An unreachable runtime renders as an offline card rather than an error. The tab also lists pending contact requests and pairing approvals, each with the command that acts on it — a queue that is otherwise only visible from the CLI. Pending contact requests stay listed even while the runtime is down, because they are read from the plugin’s own store rather than the runtime. That store is kept in OpenClaw’s plugin state, so both queues also survive a gateway restart; disabling or removing the plugin clears them.
  • In Control UI, open Control -> Channels -> SimpleX and inspect the channel status and connection state.
  • Use openclaw plugins info openclaw-simplex to verify plugin enable/allow state.
  • Check the terminal or service logs for the simplex-chat process itself, especially if the WebSocket runtime exits or cannot bind the expected port.
For persistent runtime startup and service examples, see Runtime Setup.