Upgrade package

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## Unreleased
+
+### Changed
+
+- Kept the runtime path on the external `simplex-chat` WebSocket API and removed the direct Node runtime dependency experiment from this branch.
+- Restored the package posture to MIT-compatible runtime boundaries by avoiding direct `simplex-chat` package embedding.
+- Reworked the runtime adapter into a capability-oriented WebSocket client while preserving the newer services/actions/events architecture.
+
 ## [1.5.0] - 2026-04-26
 
 ### Changed

README.md

@@ -116,16 +116,23 @@ The key runtime boundary is explicit: OpenClaw does not own or supervise the `si
 - Direct and group messaging over SimpleX
 - Media send/receive support
 - Pairing approval, exec approval auth, and allowlist enforcement
+- Context visibility controls and OpenClaw security audit findings for broad access or unsafe WebSocket config
 - Invite link, address link, and QR generation
 - Shared `message` actions including `upload-file`, reactions, polls, edits, deletes, and group actions
-- Plugin tools and gateway methods for invite and group administration
+- Plugin tools and gateway methods for invite/address management, runtime diagnostics, contact requests, group links, and link onboarding
 - Runtime status reporting, command handling, heartbeat readiness, and Control UI configuration
 - External WebSocket runtime integration with explicit operator-managed lifecycle
 
 ---
 
 ## Install
 
+Requirements:
+
+- OpenClaw `2026.5.4` or newer
+- Node.js `22` or newer in the OpenClaw plugin host
+- an external `simplex-chat` runtime reachable over WebSocket
+
 ### 1. Install SimpleX CLI (`simplex-chat`)
 
 Official installer:
@@ -206,7 +213,15 @@ This appends `openclaw-simplex` to the existing allowlist instead of replacing i
 }
 ```
 
-OpenClaw does not supervise `simplex-chat` for external plugins. If you want it to start automatically, run it as a host-managed user service such as `systemd --user` or `launchd`.
+OpenClaw does not supervise `simplex-chat` for external plugins. If you want it to start automatically, run it as a host-managed user service such as `systemd --user`, `launchd`, or SysV init.
+
+The plugin CLI can generate that service for the current host:
+
+```bash
+openclaw simplex runtime service install
+```
+
+It auto-detects user systemd on Linux, launchd on macOS, or SysV init as a Linux fallback, prints the target file and next commands, and asks for approval before writing the service file. It prints supervisor commands for you to run instead of executing them from the plugin, so install-time scanners do not see shell execution capability.
 
 Keep the split clear:
 
@@ -215,6 +230,8 @@ Keep the split clear:
 
 For full persistent runtime examples and recommended startup-flag placement: https://openclaw-simplex.mintlify.app/guide/runtime-setup
 
+Deployment templates also live in `examples/`, including a Docker sidecar compose file, a hardened systemd unit, and a Caddy TLS proxy example.
+
 ---
 
 ## Invite and address management
@@ -249,6 +266,17 @@ For automation and integrations, OpenClaw exposes gateway methods:
 - `simplex.invite.create`
 - `simplex.invite.list`
 - `simplex.invite.revoke`
+- `simplex.runtime.status`
+- `simplex.runtime.doctor`
+- `simplex.requests.list`
+- `simplex.requests.accept`
+- `simplex.requests.reject`
+- `simplex.groups.create`
+- `simplex.groups.link.create`
+- `simplex.groups.link.list`
+- `simplex.groups.link.revoke`
+- `simplex.connect.plan`
+- `simplex.connect`
 
 ---
 
@@ -274,13 +302,15 @@ This migrates:
 - `plugins.installs.simplex` → `plugins.installs.openclaw-simplex`
 - `plugins.allow` / `plugins.deny` entries from `simplex` → `openclaw-simplex`
 - `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 SimpleX config
 - OpenClaw pairing and allowlist state files under the OpenClaw state directory
 
 Current note:
 
 - The current plugin id is `openclaw-simplex`
 - The current channel id is `openclaw-simplex`
-- Gateway method names remain `simplex.invite.*`
+- Gateway method names keep the `simplex.*` prefix
 
 ---
 
@@ -310,6 +340,11 @@ openclaw pairing list
 - `simplex.invite.create`
 - `simplex.invite.list`
 - `simplex.invite.revoke`
+- `simplex.runtime.status`
+- `simplex.runtime.doctor`
+- `simplex.requests.*`
+- `simplex.groups.*`
+- `simplex.connect.*`
 
 **Plugin tools:**
 - `simplex_invite_create`
@@ -328,6 +363,7 @@ openclaw pairing list
 | Plugin not visible | Check `plugins.allow` and run `openclaw plugins list` |
 | Channel not starting | Verify `channels.openclaw-simplex.connection` exists and points to a running SimpleX runtime |
 | `Configured No` | Add explicit `channels.openclaw-simplex.connection` config; plugin defaults alone are not enough for startup |
+| `Running No` / `Connected No` | Check whether `simplex-chat` is reachable at `wsUrl`; the plugin reconnects after runtime restarts, but the endpoint still has to come back on the same address |
 | Inbound issues | Review `allowFrom`, `dmPolicy`, and group policy settings |
 | Media issues | Validate URLs and check size limits |
 

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/guide/architecture.mdx

@@ -69,7 +69,8 @@ That separation keeps the channel implementation explicit, makes host-level supe
 
 ## 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 monitoring, reconnect handling, parsing, and message normalization.
+- <code>src/channel/messaging/simplex-send.ts</code> and <code>src/channel/messaging/simplex-outbound.ts</code>: outbound message delivery and reply translation.
+- <code>src/actions/actions.ts</code>, <code>src/actions/message-actions.ts</code>, and <code>src/actions/group-actions.ts</code>: shared OpenClaw message actions such as upload-file, reactions, polls, edits, deletes, and group operations.
+- <code>src/simplex/runtime/ws-client.ts</code> and <code>src/simplex/runtime/transport.ts</code>: WebSocket transport and command execution.
 - <code>channels.openclaw-simplex</code> and <code>channels.openclaw-simplex.accounts</code>: shared and per-account runtime config.

docs/guide/getting-started.mdx

@@ -5,6 +5,12 @@ description: Install simplex-chat, configure the OpenClaw SimpleX plugin, genera
 
 This path gets you from zero to the first invited contact talking to your OpenClaw agent over SimpleX.
 
+## Requirements
+
+- OpenClaw <code>2026.5.4</code> or newer
+- Node.js <code>22</code> or newer in the OpenClaw plugin host
+- a <code>simplex-chat</code> CLI runtime that can expose the WebSocket API
+
 <Steps>
   <Step title="Install SimpleX CLI">
     Install the official <code>simplex-chat</code> CLI:

docs/guide/migration.mdx

@@ -12,10 +12,10 @@ Use this guide only if you previously configured or paired the plugin under the
 - 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>.
+  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.
+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">
@@ -41,7 +41,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 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">
@@ -89,4 +89,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 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

docs/guide/runtime-setup.mdx

@@ -9,6 +9,33 @@ Use this page after the first setup is already working and you want to make the
 
 If you want the SimpleX runtime to start automatically on login or machine boot, let the host OS supervise it and keep OpenClaw focused on the channel connection itself.
 
+The plugin CLI can generate and install a host service for the current machine:
+
+```bash
+openclaw simplex runtime service install
+```
+
+The service helper auto-detects <code>systemd --user</code> on Linux, <code>launchd</code> on macOS, and SysV init as a Linux fallback. It prints the generated service file and next commands first, and it asks for interactive approval before writing files. It prints supervisor commands for the operator to run instead of executing them from the plugin. Use <code>--provider systemd</code>, <code>--provider launchd</code>, or <code>--provider sysvinit</code> to override detection.
+
+Common install options:
+
+```bash
+openclaw simplex runtime service install \
+  --port 5225 \
+  --simplex-chat-path ~/.local/bin/simplex-chat \
+  --device-name "OpenClaw SimpleX" \
+  --files-folder ~/.simplex/files \
+  --temp-folder ~/.simplex/tmp
+```
+
+Use <code>--dry-run</code> with <code>install</code> to print the plan without writing files.
+
+The repo also ships deployment templates under <code>examples/</code>:
+
+- <code>examples/docker-compose.sidecar.yml</code>: OpenClaw plus a private <code>simplex-chat</code> sidecar network.
+- <code>examples/systemd/simplex-chat.service</code>: hardened user service template.
+- <code>examples/caddy/Caddyfile</code>: TLS/auth proxy example for exceptional remote WebSocket access.
+
 ## Decide which settings go where
 
 Use this rule:
@@ -19,6 +46,7 @@ Use this rule:
 Plugin-side settings:
 
 - <code>connection.wsUrl</code>
+- <code>connection.allowUnsafeRemoteWs</code>
 - <code>connection.connectTimeoutMs</code>
 - <code>connection.autoAcceptFiles</code>
 - <code>dmPolicy</code>, <code>allowFrom</code>, <code>groupPolicy</code>
@@ -29,7 +57,9 @@ Runtime-side startup flags:
 - local storage/layout: <code>--database</code>, <code>--files-folder</code>, <code>--temp-folder</code>, <code>--log-file</code>
 - runtime process behavior: <code>--device-name</code>, <code>--maintenance</code>, <code>--mute</code>, <code>--mark-read</code>
 
-### Create the service
+### Manual service files
+
+The CLI helper above is the preferred path. These examples show what it writes and are useful when you want to manage the service definition yourself.
 
 <Tabs>
   <Tab title="Linux">
@@ -151,3 +181,9 @@ These are reasonable patterns to consider when you run <code>simplex-chat</code>
 If you need to bring up the runtime without immediately serving chat traffic, run it with <code>--maintenance</code> and start chat manually inside the runtime later.
 
 This is a <code>simplex-chat</code> operational mode, not an OpenClaw channel config field, so it belongs in the service command only when you intentionally want that behavior.
+
+## Remote WebSocket endpoints
+
+Prefer loopback, a private sidecar network, or <code>wss://</code> with access controls. Plaintext <code>ws://</code> endpoints on non-loopback hosts are blocked by default because the WebSocket API controls the SimpleX runtime.
+
+Only set <code>connection.allowUnsafeRemoteWs: true</code> when that endpoint is protected by a private network, firewall, or authenticated TLS proxy.

docs/guide/security-model.mdx

@@ -41,6 +41,7 @@ There are three boundaries to keep straight:
 - You decide where the runtime runs, which relay path it uses, and whether relays are public or self-hosted.
 - If you need a fully internal deployment, keep <code>simplex-chat</code> and your relays inside that network boundary.
 - External runtime mode is the supported deployment model for this plugin. OpenClaw does not spawn or supervise <code>simplex-chat</code> here.
+- Plaintext remote WebSocket endpoints are blocked by default. Use loopback, private networking, or <code>wss://</code>; set <code>connection.allowUnsafeRemoteWs</code> only when the endpoint is protected by other controls.
 
 ## What this does not protect against
 
@@ -52,5 +53,7 @@ There are three boundaries to keep straight:
 
 - Start with `dmPolicy: "pairing"` and `groupPolicy: "allowlist"`.
 - Keep `allowFrom`/`groupAllowFrom` narrow.
+- Set `contextVisibility` deliberately if supplemental context exposure should be restricted for this channel.
 - Prefer one-time invite links for onboarding and revoke address links when they are no longer needed.
-- Monitor status snapshots and logs for repeated authorization failures.
+- Protect the SimpleX WebSocket endpoint, database, and file-transfer directories as sensitive local state.
+- Monitor OpenClaw security audit findings, status snapshots, and logs for broad policies, unsafe WebSocket endpoints, or repeated authorization failures.

docs/guide/troubleshooting.mdx

@@ -53,10 +53,21 @@ 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:
@@ -93,6 +104,7 @@ 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
@@ -128,6 +140,24 @@ Write the channel endpoint config explicitly:
 openclaw channels add --channel openclaw-simplex --url ws://127.0.0.1:5225
 ```
 
+Show runtime status:
+
+```bash
+openclaw simplex runtime status
+```
+
+Run runtime diagnostics:
+
+```bash
+openclaw simplex runtime doctor
+```
+
+List pending SimpleX contact requests:
+
+```bash
+openclaw simplex requests list
+```
+
 ## Where to inspect errors
 
 - In Control UI, open <code>Control -&gt; Channels -&gt; SimpleX</code> and inspect the channel status and connection state.

docs/guide/why-simplex.mdx

@@ -37,8 +37,8 @@ A SimpleX channel backed by a local <code>simplex-chat</code> WebSocket runtime:
 - pairing with allowlist enforcement and same-chat exec approvals
 - shared `message` actions, including `upload-file`, reactions, polls, edits, deletes, and group actions
 - plugin tools for invite generation/list/revoke and group administration
-- invite link and QR generation
-- runtime status and heartbeat readiness support
+- one-time invite link, SimpleX address, group-link, and QR generation
+- runtime status, runtime doctor, contact-request review, group-link lifecycle, link onboarding, and heartbeat readiness support
 - Control UI configuration
 
 ## Why teams choose it
@@ -56,7 +56,7 @@ The contribution is not just “another channel”. It adds a channel model that
 
 - no phone number requirement
 - no hosted bot account or bot API dependency
-- access starts from an invitation link, not a public platform identity
+- access starts from a one-time invite link or reusable SimpleX address, not a public platform identity
 
 <Note>
   Low risk to existing OpenClaw channels: the implementation stays isolated and is only active when <code>openclaw-simplex</code> is configured and enabled.