Troubleshooting

Diagnose and fix common OpenClaw SimpleX problems including WebSocket connection failures, plugin trust errors, policy rejections, and pairing issues.

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

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

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

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.