Upgrade runtime

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## Unreleased
+
+### Changed
+
+- Switched the SimpleX runtime path to the official `simplex-chat` Node runtime and removed the CLI/WebSocket sidecar runtime path.
+- Updated the package license to `AGPL-3.0-or-later` because the plugin now depends directly on the official SimpleX runtime package.
+- Expanded channel config schema, manifest metadata, README, and docs for Node runtime storage fields.
+
 ## [1.5.0] - 2026-04-26
 
 ### Changed

biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.4.13/schema.json",
   "files": {
     "includes": ["**", "!**/dist"]
   },

docs/docs.json

@@ -19,7 +19,6 @@
         "pages": [
           "guide/getting-started",
           "guide/why-simplex",
-          "guide/how-it-works",
           "guide/architecture",
           "guide/runtime-setup",
           "guide/security-model",
@@ -29,12 +28,7 @@
       },
       {
         "group": "Reference",
-        "pages": [
-          "reference/config",
-          "reference/gateway-methods",
-          "reference/example-commands",
-          "reference/screenshots"
-        ]
+        "pages": ["reference/config", "reference/gateway-methods", "reference/example-commands"]
       }
     ]
   },

docs/guide/architecture.mdx

@@ -1,11 +1,11 @@
 ---
 title: Architecture
-description: Understand the runtime boundaries between OpenClaw, the SimpleX channel plugin, and the external simplex-chat process including their responsibilities.
+description: Understand the runtime boundaries between OpenClaw, the SimpleX channel plugin, and the official Node runtime.
 ---
 
-The architecture is built around one rule: OpenClaw should enforce policy and route messages, but it should not own the <code>simplex-chat</code> process lifecycle for this plugin.
+The architecture is built around one rule: OpenClaw enforces policy and routes messages; this plugin only translates between OpenClaw channel events/actions and SimpleX runtime API events.
 
-That separation keeps the channel implementation explicit, makes host-level supervision a deployment choice, and avoids hiding the network/runtime boundary inside plugin startup code.
+The runtime path uses the official <code>simplex-chat</code> Node package in-process. There is no separate CLI process or local WebSocket API.
 
 ## High-level diagram
 
@@ -26,10 +26,10 @@ That separation keeps the channel implementation explicit, makes host-level supe
             | - account/runtime state |
             +------------+------------+
                          |
-                         | WebSocket API
+                         | Node runtime API
                          v
             +-------------------------+
-            |   SimpleX CLI Runtime   |
+            |  SimpleX Node Runtime   |
             |      (simplex-chat)     |
             +------------+------------+
                          |
@@ -47,7 +47,7 @@ That separation keeps the channel implementation explicit, makes host-level supe
     Access checks stay in OpenClaw through <code>dmPolicy</code>, <code>allowFrom</code>, <code>groupPolicy</code>, pairing state, and command authorization.
   </Card>
   <Card title="Runtime boundary" icon="server">
-    The plugin connects to a separately running <code>simplex-chat</code> instance over WebSocket instead of spawning or supervising that process.
+    The official SimpleX Node runtime runs in the OpenClaw process.
   </Card>
 </Columns>
 
@@ -56,20 +56,22 @@ That separation keeps the channel implementation explicit, makes host-level supe
     Account-specific overrides live under <code>channels.openclaw-simplex.accounts</code>, while shared channel config remains at the channel root.
   </Card>
   <Card title="Failure isolation" icon="triangle-alert">
-    If the SimpleX WebSocket endpoint is unavailable, this channel reports a runtime error and disconnect state without taking down unrelated OpenClaw channels.
+    The Node runtime removes the unauthenticated local WebSocket surface, but it shares process fate with OpenClaw.
   </Card>
 </Columns>
 
 ## Data flow
 
-1. <code>simplex-chat</code> emits events through its WebSocket API.
+1. The SimpleX runtime emits events through the Node API.
 2. The plugin monitor parses those events into OpenClaw channel context.
 3. OpenClaw applies policy checks and runs the agent.
-4. The plugin translates replies, edits, reactions, media sends, and group actions back into SimpleX commands.
+4. The plugin translates replies, edits, reactions, media sends, and group actions into typed SimpleX runtime API calls.
 
 ## Implementation surfaces
 
-- <code>src/channel/simplex-monitor.ts</code>: inbound SimpleX event parsing and message normalization.
-- <code>src/channel/simplex-send.ts</code> and <code>src/channel/simplex-outbound.ts</code>: outbound message/action translation.
-- <code>src/simplex/simplex-ws-client.ts</code> and <code>src/simplex/simplex-transport.ts</code>: WebSocket transport and command execution.
+- <code>src/channel/events/simplex-monitor.ts</code>: inbound SimpleX event parsing and message normalization.
+- <code>src/channel/events/simplex-inbound-files.ts</code>: incoming file lifecycle, delayed dispatch, and reply delivery after file resolution.
+- <code>src/channel/messaging/simplex-send.ts</code> and <code>src/channel/messaging/simplex-outbound.ts</code>: outbound message/action translation.
+- <code>src/simplex/runtime/client.ts</code>: official Node runtime adapter.
+- <code>src/simplex/runtime/transport.ts</code>: active-client registry and runtime API execution.
 - <code>channels.openclaw-simplex</code> and <code>channels.openclaw-simplex.accounts</code>: shared and per-account runtime config.

docs/guide/getting-started.mdx

@@ -1,47 +1,15 @@
 ---
 title: Getting Started
-description: Install simplex-chat, configure the OpenClaw SimpleX plugin, generate your first invite link, and pair your first contact with the agent step by step.
+description: Install the OpenClaw SimpleX plugin, start the official Node runtime, generate your first one-time invite link, and pair your first contact with the agent step by step.
 ---
 
 This path gets you from zero to the first invited contact talking to your OpenClaw agent over SimpleX.
 
-<Steps>
-  <Step title="Install SimpleX CLI">
-    Install the official <code>simplex-chat</code> CLI:
-
-    ```bash
-    curl -o- https://raw.githubusercontent.com/simplex-chat/simplex-chat/stable/install.sh | bash
-    ```
-
-    Verify the CLI:
-
-    ```bash
-    simplex-chat -h
-    ```
-
-    <Note>
-      If the official installer picks the wrong Darwin/Linux build for your host, use the temporary arch-matrix installer:
-
-      ```bash
-      curl -o- https://raw.githubusercontent.com/dangoldbj/simplex-chat/install-arch-matrix/install.sh | bash
-      ```
-    </Note>
-  </Step>
-
-  <Step title="Start the SimpleX runtime">
-    Start the WebSocket runtime in a separate terminal:
-
-    ```bash
-    simplex-chat -p 5225
-    ```
-
-    Expected result: <code>simplex-chat</code> stays in the foreground and serves the WebSocket API on port <code>5225</code>.
-
-    <Info>
-      This is a long-running foreground process. If you want it to start automatically, use the host-managed service examples in <a href="/guide/runtime-setup">Runtime Setup</a>.
-    </Info>
-  </Step>
+<Warning>
+  <strong>Breaking in 2.0.0:</strong> OpenClaw SimpleX now uses the official <code>simplex-chat</code> Node runtime only. The old WebSocket/CLI runtime configuration is no longer supported. If you are upgrading from any pre-2.0.0 install, run <code>openclaw simplex migrate</code> before relying on the channel; see the [Migration guide](/guide/migration).
+</Warning>
 
+<Steps>
   <Step title="Install and enable the plugin">
     Install the plugin in OpenClaw:
 
@@ -67,35 +35,30 @@ This path gets you from zero to the first invited contact talking to your OpenCl
   </Step>
 
   <Step title="Configure the channel">
-    Point OpenClaw at the local SimpleX WebSocket endpoint:
+    Add the channel:
 
     ```bash
-    openclaw channels add --channel openclaw-simplex --url ws://127.0.0.1:5225
+    openclaw channels add --channel openclaw-simplex
     ```
 
-    That command writes channel config equivalent to:
+    That writes channel config equivalent to:
 
     ```json
     {
       "channels": {
         "openclaw-simplex": {
-          "enabled": true,
-          "connection": {
-            "wsUrl": "ws://127.0.0.1:5225"
-          },
-          "dmPolicy": "pairing",
-          "allowFrom": ["*"]
+          "enabled": true
         }
       }
     }
     ```
 
     <Info>
-      OpenClaw will not start the channel until <code>channels.openclaw-simplex.connection</code> exists. If <code>simplex-chat</code> is not running at that endpoint, OpenClaw will mark the channel disconnected and record the connection error in channel status.
+      By default, direct messages use <code>dmPolicy: "pairing"</code>. A new SimpleX contact can reach the runtime, but OpenClaw will not run the agent until you approve the pairing request. The plugin also uses the same database prefix as the SimpleX terminal CLI: <code>~/.simplex/simplex_v1</code> on Linux/macOS and <code>%APPDATA%/simplex/simplex_v1</code> on Windows. Set <code>dbFilePrefix</code> only when you want a separate bot identity or a named account.
     </Info>
   </Step>
 
-  <Step title="Generate the first invite and verify">
+  <Step title="Generate the first one-time invite and verify">
     Confirm the plugin is installed and enabled:
 
     ```bash
@@ -114,7 +77,7 @@ This path gets you from zero to the first invited contact talking to your OpenCl
     openclaw simplex invite create --qr
     ```
 
-    Expected result: the command prints a SimpleX invite link, and <code>--qr</code> renders a scannable QR code in the terminal.
+    Expected result: the command prints a SimpleX one-time invite link, and <code>--qr</code> renders a scannable QR code in the terminal.
 
     In Control UI, you can also open <code>Control -&gt; Channels -&gt; SimpleX</code> to inspect the channel config and runtime state.
 
@@ -142,13 +105,11 @@ openclaw pairing approve openclaw-simplex <pairingCode>
 
 5. Send another message in SimpleX and verify the agent responds.
 
-For a visual walkthrough, see [Screenshots](/reference/screenshots).
-
-For recurring address links, invite listing, revoke flows, and automation APIs, see [Example Commands](/reference/example-commands) and [Gateway Methods](/reference/gateway-methods).
+For the reusable SimpleX address, address display, revoke flows, and automation APIs, see [Example Commands](/reference/example-commands) and [Gateway Methods](/reference/gateway-methods).
 
-## Upgrading from an older `simplex` install
+## Upgrading from an older install
 
-If you are upgrading from an older `simplex` plugin/channel install, run the migration helper before switching your config and commands to `openclaw-simplex`:
+If you are upgrading from an older `simplex` plugin/channel install, or from an early `openclaw-simplex` install that used WebSocket/CLI runtime fields, run the migration helper before relying on the channel:
 
 ```bash
 openclaw simplex migrate

docs/guide/migration.mdx

@@ -1,31 +1,35 @@
 ---
 title: Migration to openclaw-simplex
-description: 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.
+description: Migrate legacy SimpleX installs to the openclaw-simplex id and the current Node runtime config shape 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).
+Use this guide if you previously configured or paired the plugin under the old <code>simplex</code> ids, or if you already used <code>openclaw-simplex</code> with the old WebSocket/CLI runtime config. For a fresh install, start with [Getting Started](/guide/getting-started).
 
-## What changed in `1.0.0`
+<Warning>
+  <strong>Breaking in 2.0.0:</strong> the SimpleX runtime model changed from the old WebSocket/CLI setup to the official <code>simplex-chat</code> Node runtime. Pre-2.0.0 runtime fields such as <code>wsUrl</code>, <code>url</code>, <code>host</code>, <code>port</code>, <code>token</code>, <code>managed</code>, and <code>cliPath</code> are no longer supported.
+</Warning>
 
-- plugin id: `simplex` -> `openclaw-simplex`
-- channel id: `simplex` -> `openclaw-simplex`
-- pairing approval commands now use `openclaw-simplex`
+## What changed
+
+- Legacy `0.x` installs used plugin id `simplex` and channel id `simplex`; current installs use `openclaw-simplex` for both.
+- Version `2.0.0` replaced the old WebSocket/CLI runtime setup with the official SimpleX Node runtime.
+- Early `openclaw-simplex` installs could still contain WebSocket/CLI runtime fields; current installs use the Node runtime config shape.
+- Pairing approval commands now use `openclaw-simplex`.
 
 <Info>
-  Gateway method names did not change. Programmatic invite flows still use <code>simplex.invite.create</code>, <code>simplex.invite.list</code>, and <code>simplex.invite.revoke</code>.
+  Legacy invite gateway method names did not change. Programmatic invite flows still use <code>simplex.invite.create</code>, <code>simplex.invite.list</code>, and <code>simplex.invite.revoke</code>.
 </Info>
 
-The migration helper updates config keys and stored pairing/allowlist state so existing approvals can carry forward.
+The migration helper is idempotent and covers two independent migrations:
 
-<Steps>
-  <Step title="Start the external SimpleX runtime">
-    Run <code>simplex-chat</code> yourself and expose the WebSocket endpoint the channel should use:
+- It renames legacy config and state from <code>simplex</code> to <code>openclaw-simplex</code> so existing approvals can carry forward.
+- It normalizes existing <code>openclaw-simplex</code> channel config for the Node runtime by removing legacy WebSocket/CLI fields such as <code>wsUrl</code>, <code>url</code>, <code>host</code>, <code>port</code>, <code>token</code>, <code>managed</code>, and <code>cliPath</code>.
 
-    ```bash
-    simplex-chat -p 5225
-    ```
+Policy fields and multi-account settings remain in place. If the helper prints <code>No changes were needed</code>, neither the old id shape nor the old runtime config shape was present.
 
-    Make sure your config points to that endpoint under <code>channels.openclaw-simplex.connection.wsUrl</code>.
+<Steps>
+  <Step title="Use the Node runtime">
+    New installs use the official SimpleX Node runtime. Legacy WebSocket runtime config is no longer part of the supported runtime model, and <code>openclaw simplex migrate</code> strips those old runtime fields from both root and per-account SimpleX config.
   </Step>
 
   <Step title="Preview the migration">
@@ -41,7 +45,7 @@ The migration helper updates config keys and stored pairing/allowlist state so e
     openclaw simplex migrate
     ```
 
-    This rewrites the old <code>simplex</code> config keys and renames the related pairing/allowlist state files in the OpenClaw state directory.
+    This rewrites the old <code>simplex</code> config keys, normalizes the runtime config for the Node runtime, and renames the related pairing/allowlist state files in the OpenClaw state directory.
   </Step>
 
   <Step title="Verify the new ids and pairing flow">
@@ -54,7 +58,7 @@ The migration helper updates config keys and stored pairing/allowlist state so e
     If you need to re-add the channel explicitly, use the new channel id:
 
     ```bash
-    openclaw channels add --channel openclaw-simplex --url ws://127.0.0.1:5225
+    openclaw channels add --channel openclaw-simplex
     ```
 
     Pairing approval also uses the new channel id:
@@ -75,9 +79,7 @@ After migration, the channel should be configured under <code>openclaw-simplex</
 {
   "channels": {
     "openclaw-simplex": {
-      "connection": {
-        "wsUrl": "ws://127.0.0.1:5225"
-      }
+      "dbFilePrefix": "~/.openclaw/simplex/openclaw-simplex"
     }
   }
 }
@@ -89,4 +91,6 @@ After migration, the channel should be configured under <code>openclaw-simplex</
 - `plugins.installs.simplex` -> `plugins.installs.openclaw-simplex`
 - `plugins.allow` / `plugins.deny`
 - `channels.simplex` -> `channels.openclaw-simplex`
+- legacy nested `connection.*` runtime fields are moved to top-level account fields
+- legacy SimpleX WebSocket/CLI runtime fields are removed from root and per-account SimpleX config
 - OpenClaw pairing and allowlist state files under the OpenClaw state directory