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: 
openclaw plugins list
Then inspect the plugin entry directly: 
openclaw plugins info openclaw-simplex
What to verify:
  • the package is installed in the same runtime environment where OpenClaw is running
  • plugins.allow includes openclaw-simplex
  • 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: 
simplex-chat -p 5225
Then verify the configured channel endpoint: 
openclaw channels add --channel openclaw-simplex --url ws://127.0.0.1:5225
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: 
openclaw pairing list
Approve a sender if needed: 
openclaw pairing approve openclaw-simplex <pairingCode>

​
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: 
openclaw simplex invite create --qr
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)
  • 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: 
simplex-chat -p 5225
List installed plugins: 
openclaw plugins list
Inspect this plugin’s enable/allow state: 
openclaw plugins info openclaw-simplex
Write the channel endpoint config explicitly: 
openclaw channels add --channel openclaw-simplex --url ws://127.0.0.1:5225
Show runtime status: 
openclaw simplex runtime status
Run runtime diagnostics: 
openclaw simplex runtime doctor
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. List pending SimpleX contact requests: 
openclaw simplex requests list

​
Where to inspect errors

  • 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.