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

# Migration to openclaw-simplex

> Migrate from the legacy simplex plugin and channel identifiers to the renamed openclaw-simplex format introduced in version 1.0.0 with step-by-step commands.

Use this guide only if you previously configured or paired the plugin under the old <code>simplex</code> ids. For a fresh install, start with [Getting Started](/guide/getting-started).

## What changed in `1.0.0`

* plugin id: `simplex` -> `openclaw-simplex`
* channel id: `simplex` -> `openclaw-simplex`
* pairing approval commands now use `openclaw-simplex`

<Info>
  Gateway method names keep the <code>simplex.\*</code> prefix. Programmatic invite flows still use <code>simplex.invite.create</code>, <code>simplex.invite.list</code>, and <code>simplex.invite.revoke</code>; newer runtime, request, group, and link-onboarding methods use the same prefix.
</Info>

The migration helper updates config keys and stored pairing/allowlist state so existing approvals can carry forward. It also normalizes legacy runtime fields by moving supported WebSocket fields under <code>connection</code> and removing unsupported managed-mode fields.

<Steps>
  <Step title="Start the external SimpleX runtime">
    Run <code>simplex-chat</code> yourself and expose the WebSocket endpoint the channel should use:

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

    Make sure your config points to that endpoint under <code>channels.openclaw-simplex.connection.wsUrl</code>.
  </Step>

  <Step title="Preview the migration">
    ```bash theme={null}
    openclaw simplex migrate --dry-run
    ```

    Review the planned config/state renames before writing anything.
  </Step>

  <Step title="Apply the migration">
    ```bash theme={null}
    openclaw simplex migrate
    ```

    This rewrites the old <code>simplex</code> config keys, normalizes legacy runtime fields for the external WebSocket runtime, and renames the related pairing/allowlist state files in the OpenClaw state directory.
  </Step>

  <Step title="Verify the new ids and pairing flow">
    Check the plugin under its new id:

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

    If you need to re-add the channel explicitly, use the new channel id:

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

    Pairing approval also uses the new channel id:

    ```bash theme={null}
    openclaw pairing approve openclaw-simplex <pairingCode>
    ```

    Send a SimpleX message from an already approved contact and confirm the approval still holds after migration.
  </Step>
</Steps>

## Target config shape

After migration, the channel should be configured under <code>openclaw-simplex</code>:

```json theme={null}
{
  "channels": {
    "openclaw-simplex": {
      "connection": {
        "wsUrl": "ws://127.0.0.1:5225"
      }
    }
  }
}
```

## What the migration helper updates

* `plugins.entries.simplex` -> `plugins.entries.openclaw-simplex`
* `plugins.installs.simplex` -> `plugins.installs.openclaw-simplex`
* `plugins.allow` / `plugins.deny`
* `channels.simplex` -> `channels.openclaw-simplex`
* legacy top-level runtime fields such as `wsUrl`, `url`, `host`, and `port` are moved under `connection`
* unsupported managed-mode fields such as `managed`, `cliPath`, `token`, and `dbFilePrefix` are removed from root and per-account SimpleX config
* OpenClaw pairing and allowlist state files under the OpenClaw state directory