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

# 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 <code>simplex-chat</code> WebSocket endpoint, or policy settings are correctly rejecting a sender you expected to allow.

<Tip>
  Two common mistakes: <code>simplex-chat</code> is listening on one port but <code>wsUrl</code> points to another, or <code>dmPolicy: "pairing"</code> is enabled but the sender has not been approved yet.
</Tip>

## Plugin not listed

First check:

```bash theme={null}
openclaw plugins list
```

Then inspect the plugin entry directly:

```bash theme={null}
openclaw plugins info openclaw-simplex
```

What to verify:

* the package is installed in the same runtime environment where OpenClaw is running
* <code>plugins.allow</code> includes <code>openclaw-simplex</code>
* 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: <code>simplex-chat</code> must be running on the same WebSocket endpoint that <code>channels.openclaw-simplex.connection.wsUrl</code> points to.

Start the runtime manually if needed:

```bash theme={null}
simplex-chat -p 5225
```

Then verify the configured channel endpoint:

```bash theme={null}
openclaw channels add --channel openclaw-simplex --url ws://127.0.0.1:5225
```

What to verify:

* <code>channels.openclaw-simplex.connection</code> exists
* <code>wsUrl</code> matches the port where <code>simplex-chat</code> is actually listening
* if you use <code>wsHost</code>/<code>wsPort</code> instead, those values match the runtime endpoint
* if you point at a plaintext non-loopback <code>ws\://</code> endpoint, either move it behind loopback/private networking or explicitly set <code>connection.allowUnsafeRemoteWs</code>
* channel status shows the latest connection error if the WebSocket handshake fails

For persistent startup, run <code>simplex-chat</code> under a host-managed service. See [Runtime Setup](/guide/runtime-setup).

## Channel shows `Running No` or `Connected No`

If the channel is configured but not connected, check the runtime boundary first:

* <code>Configured Yes</code> means OpenClaw has enough channel config to attempt startup.
* <code>Running No</code> means OpenClaw does not currently have a running channel runtime for that account.
* <code>Connected No</code> means the plugin is not connected to the configured <code>simplex-chat</code> 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 <code>connection.wsUrl</code>.

## Inbound messages dropped

If messages arrive in SimpleX but the agent does not answer, check policy first:

* <code>dmPolicy: "pairing"</code> means a newly discovered contact must be approved before responses start
* <code>dmPolicy: "allowlist"</code> means the sender must match <code>allowFrom</code>
* group traffic may be blocked by <code>groupPolicy</code> or <code>groupAllowFrom</code>
* 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 <code>/\_groups</code> 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:

```bash theme={null}
openclaw pairing list
```

Approve a sender if needed:

```bash theme={null}
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 <code>simplex-chat</code> runtime.

Use the plugin CLI first:

```bash theme={null}
openclaw simplex invite create --qr
```

If that fails:

* confirm the account's <code>connection.wsUrl</code> points at a running runtime
* check whether the channel account is enabled
* inspect the latest channel status/runtime error in OpenClaw
* run <code>openclaw simplex runtime status</code> or <code>openclaw simplex runtime doctor</code> 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 (<code>mediaMaxMb</code>)
* 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:

```bash theme={null}
simplex-chat -p 5225
```

List installed plugins:

```bash theme={null}
openclaw plugins list
```

Inspect this plugin's enable/allow state:

```bash theme={null}
openclaw plugins info openclaw-simplex
```

Write the channel endpoint config explicitly:

```bash theme={null}
openclaw channels add --channel openclaw-simplex --url ws://127.0.0.1:5225
```

Show runtime status:

```bash theme={null}
openclaw simplex runtime status
```

Run runtime diagnostics:

```bash theme={null}
openclaw simplex runtime doctor
```

Run the runtime doctor again after enabling SimpleX-native live replies with
<code>streaming.nativeTransport</code>. The doctor reports advisory capability
probe states from the active WebSocket runtime, but it does not spawn, supervise,
or manage <code>simplex-chat</code>.

List pending SimpleX contact requests:

```bash theme={null}
openclaw simplex requests list
```

## Where to inspect errors

* In Control UI, open <code>Control -> Channels -> SimpleX</code> and inspect the channel status and connection state.
* Use <code>openclaw plugins info openclaw-simplex</code> to verify plugin enable/allow state.
* Check the terminal or service logs for the <code>simplex-chat</code> process itself, especially if the WebSocket runtime exits or cannot bind the expected port.

For persistent runtime startup and service examples, see [Runtime Setup](/guide/runtime-setup).