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

   The config half of this now happens on its own. The plugin registers the same migration with OpenClaw, so legacy simplex plugin and channel ids are rewritten when the config is loaded, and openclaw doctor reports any leftover pre-1.0 runtime fields and repairs them under its fix command.

   Running openclaw simplex migrate is still worth doing once, because it is the only step that also renames the pairing and allowlist state files. A setup-time migration is a pure function over the config, so it cannot touch the filesystem.

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