Skip to main content
Use this guide only if you previously configured or paired the plugin under the old simplex ids. For a fresh install, start with 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
Gateway method names keep the simplex.* prefix. Programmatic invite flows still use simplex.invite.create, simplex.invite.list, and simplex.invite.revoke; newer runtime, request, group, and link-onboarding methods use the same prefix.
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 connection and removing unsupported managed-mode fields.
1

Start the external SimpleX runtime

Run simplex-chat yourself and expose the WebSocket endpoint the channel should use:
simplex-chat -p 5225
Make sure your config points to that endpoint under channels.openclaw-simplex.connection.wsUrl.
2

Preview the migration

openclaw simplex migrate --dry-run
Review the planned config/state renames before writing anything.
3

Apply the migration

openclaw simplex migrate
This rewrites the old simplex config keys, normalizes legacy runtime fields for the external WebSocket runtime, and renames the related pairing/allowlist state files in the OpenClaw state directory.
4

Verify the new ids and pairing flow

Check the plugin under its new id:
openclaw plugins info openclaw-simplex
If you need to re-add the channel explicitly, use the new channel id:
openclaw channels add --channel openclaw-simplex --url ws://127.0.0.1:5225
Pairing approval also uses the new channel id:
openclaw pairing approve openclaw-simplex <pairingCode>
Send a SimpleX message from an already approved contact and confirm the approval still holds after migration.

​
Target config shape

After migration, the channel should be configured under openclaw-simplex: 
{
  "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