docs: add matrix-js setup and config docs

docs/channels/index.md

@@ -28,7 +28,8 @@ Text is supported everywhere; media and reactions vary by channel.
 - [Synology Chat](/channels/synology-chat) — Synology NAS Chat via outgoing+incoming webhooks (plugin, installed separately).
 - [LINE](/channels/line) — LINE Messaging API bot (plugin, installed separately).
 - [Nextcloud Talk](/channels/nextcloud-talk) — Self-hosted chat via Nextcloud Talk (plugin, installed separately).
-- [Matrix](/channels/matrix) — Matrix protocol (plugin, installed separately).
+- [Matrix-js](/channels/matrix-js) — Matrix via the official `matrix-js-sdk` (plugin, installed separately).
+- [Matrix (legacy)](/channels/matrix) — Legacy Matrix plugin using `@vector-im/matrix-bot-sdk`.
 - [Nostr](/channels/nostr) — Decentralized DMs via NIP-04 (plugin, installed separately).
 - [Tlon](/channels/tlon) — Urbit-based messenger (plugin, installed separately).
 - [Twitch](/channels/twitch) — Twitch chat via IRC connection (plugin, installed separately).

docs/channels/matrix-js.md

@@ -0,0 +1,247 @@
+---
+summary: "Matrix-js support status, setup, and configuration examples"
+read_when:
+  - Setting up Matrix-js in OpenClaw
+  - Configuring Matrix E2EE and verification
+title: "Matrix-js"
+---
+
+# Matrix-js (plugin)
+
+Matrix-js is the current Matrix channel plugin for OpenClaw.
+It uses the official `matrix-js-sdk` and supports DMs, rooms, threads, media, reactions, polls, location, and E2EE.
+
+For new setups, use Matrix-js.
+If you need legacy compatibility with `@vector-im/matrix-bot-sdk`, use [Matrix (legacy)](/channels/matrix).
+
+## Plugin required
+
+Matrix-js is a plugin and is not bundled with core OpenClaw.
+
+Install from npm:
+
+```bash
+openclaw plugins install @openclaw/matrix-js
+```
+
+Install from a local checkout:
+
+```bash
+openclaw plugins install ./extensions/matrix-js
+```
+
+See [Plugins](/tools/plugin) for plugin behavior and install rules.
+
+## Setup
+
+1. Install the plugin.
+2. Create a Matrix account on your homeserver.
+3. Configure `channels["matrix-js"]` with either:
+   - `homeserver` + `accessToken`, or
+   - `homeserver` + `userId` + `password`.
+4. Restart the gateway.
+5. Start a DM with the bot or invite it to a room.
+
+Minimal token-based setup:
+
+```json5
+{
+  channels: {
+    "matrix-js": {
+      enabled: true,
+      homeserver: "https://matrix.example.org",
+      accessToken: "syt_xxx",
+      dm: { policy: "pairing" },
+    },
+  },
+}
+```
+
+Password-based setup (token is cached after login):
+
+```json5
+{
+  channels: {
+    "matrix-js": {
+      enabled: true,
+      homeserver: "https://matrix.example.org",
+      userId: "@bot:example.org",
+      password: "replace-me",
+      deviceName: "OpenClaw Gateway",
+    },
+  },
+}
+```
+
+Environment variable equivalents (used when the config key is not set):
+
+- `MATRIX_HOMESERVER`
+- `MATRIX_ACCESS_TOKEN`
+- `MATRIX_USER_ID`
+- `MATRIX_PASSWORD`
+- `MATRIX_DEVICE_ID`
+- `MATRIX_DEVICE_NAME`
+- `MATRIX_REGISTER`
+
+## Configuration example
+
+This is a practical baseline config with DM pairing, room allowlist, and E2EE enabled:
+
+```json5
+{
+  channels: {
+    "matrix-js": {
+      enabled: true,
+      homeserver: "https://matrix.example.org",
+      accessToken: "syt_xxx",
+      encryption: true,
+
+      dm: {
+        policy: "pairing",
+      },
+
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["@admin:example.org"],
+      groups: {
+        "!roomid:example.org": {
+          requireMention: true,
+        },
+      },
+
+      autoJoin: "allowlist",
+      autoJoinAllowlist: ["!roomid:example.org"],
+      threadReplies: "inbound",
+      replyToMode: "off",
+    },
+  },
+}
+```
+
+## E2EE setup
+
+Enable encryption:
+
+```json5
+{
+  channels: {
+    "matrix-js": {
+      enabled: true,
+      homeserver: "https://matrix.example.org",
+      accessToken: "syt_xxx",
+      encryption: true,
+      dm: { policy: "pairing" },
+    },
+  },
+}
+```
+
+Check verification status:
+
+```bash
+openclaw matrix-js verify status
+```
+
+Bootstrap cross-signing and verification state:
+
+```bash
+openclaw matrix-js verify bootstrap
+```
+
+Verify with a recovery key:
+
+```bash
+openclaw matrix-js verify recovery-key "<your-recovery-key>"
+```
+
+Use `openclaw matrix-js verify status --json` when scripting verification checks.
+
+## Automatic verification routing
+
+Matrix-js automatically routes verification lifecycle updates to the agent as normal inbound messages.
+That includes:
+
+- verification request notices
+- verification start and completion notices
+- SAS details (emoji and decimal) when available
+
+This means an agent can guide users through verification directly in chat without ad hoc harness scripts.
+
+## DM and room policy example
+
+```json5
+{
+  channels: {
+    "matrix-js": {
+      dm: {
+        policy: "allowlist",
+        allowFrom: ["@admin:example.org"],
+      },
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["@admin:example.org"],
+      groups: {
+        "!roomid:example.org": {
+          requireMention: true,
+        },
+      },
+    },
+  },
+}
+```
+
+See [Groups](/channels/groups) for mention-gating and allowlist behavior.
+
+## Multi-account example
+
+```json5
+{
+  channels: {
+    "matrix-js": {
+      enabled: true,
+      dm: { policy: "pairing" },
+      accounts: {
+        assistant: {
+          homeserver: "https://matrix.example.org",
+          accessToken: "syt_assistant_xxx",
+          encryption: true,
+        },
+        alerts: {
+          homeserver: "https://matrix.example.org",
+          accessToken: "syt_alerts_xxx",
+          dm: {
+            policy: "allowlist",
+            allowFrom: ["@ops:example.org"],
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Configuration reference
+
+- `enabled`: enable or disable the channel.
+- `homeserver`: homeserver URL, for example `https://matrix.example.org`.
+- `userId`: full Matrix user ID, for example `@bot:example.org`.
+- `accessToken`: access token for token-based auth.
+- `password`: password for password-based login.
+- `register`: auto-register if login fails and homeserver allows registration.
+- `deviceId`: explicit Matrix device ID.
+- `deviceName`: device display name for password login.
+- `initialSyncLimit`: startup sync event limit.
+- `encryption`: enable E2EE.
+- `allowlistOnly`: force allowlist-only behavior for DMs and rooms.
+- `groupPolicy`: `open`, `allowlist`, or `disabled`.
+- `groupAllowFrom`: allowlist of user IDs for room traffic.
+- `replyToMode`: `off`, `first`, or `all`.
+- `threadReplies`: `off`, `inbound`, or `always`.
+- `textChunkLimit`: outbound message chunk size.
+- `chunkMode`: `length` or `newline`.
+- `responsePrefix`: optional message prefix for outbound replies.
+- `mediaMaxMb`: outbound media size cap in MB.
+- `autoJoin`: invite auto-join policy (`always`, `allowlist`, `off`).
+- `autoJoinAllowlist`: rooms/aliases allowed when `autoJoin` is `allowlist`.
+- `dm`: DM policy block (`enabled`, `policy`, `allowFrom`).
+- `groups`: per-room policy map.
+- `rooms`: legacy alias for `groups`.
+- `actions`: per-action tool gating (`messages`, `reactions`, `pins`, `memberInfo`, `channelInfo`, `verification`).

docs/channels/matrix.md

@@ -7,6 +7,10 @@ title: "Matrix"
 
 # Matrix (plugin)
 
+This page documents the legacy Matrix plugin (`@openclaw/matrix`) built on
+`@vector-im/matrix-bot-sdk`.
+For the current plugin built on `matrix-js-sdk`, see [Matrix-js](/channels/matrix-js).
+
 Matrix is an open, decentralized messaging protocol. OpenClaw connects as a Matrix **user**
 on any homeserver, so you need a Matrix account for the bot. Once it is logged in, you can DM
 the bot directly or invite it to rooms (Matrix "groups"). Beeper is a valid client option too,

docs/docs.json

@@ -903,6 +903,7 @@
                   "channels/msteams",
                   "channels/synology-chat",
                   "channels/line",
+                  "channels/matrix-js",
                   "channels/matrix",
                   "channels/nextcloud-talk",
                   "channels/nostr",

docs/tools/plugin.md

@@ -46,7 +46,8 @@ Looking for third-party listings? See [Community plugins](/plugins/community).
 - Memory (LanceDB) — bundled long-term memory plugin (auto-recall/capture; set `plugins.slots.memory = "memory-lancedb"`)
 - [Voice Call](/plugins/voice-call) — `@openclaw/voice-call`
 - [Zalo Personal](/plugins/zalouser) — `@openclaw/zalouser`
-- [Matrix](/channels/matrix) — `@openclaw/matrix`
+- [Matrix-js](/channels/matrix-js) — `@openclaw/matrix-js`
+- [Matrix (legacy)](/channels/matrix) — `@openclaw/matrix`
 - [Nostr](/channels/nostr) — `@openclaw/nostr`
 - [Zalo](/channels/zalo) — `@openclaw/zalo`
 - [Microsoft Teams](/channels/msteams) — `@openclaw/msteams`

extensions/matrix-js/package.json

@@ -22,8 +22,8 @@
       "id": "matrix-js",
       "label": "Matrix-js",
       "selectionLabel": "Matrix-js (plugin)",
-      "docsPath": "/channels/matrix",
-      "docsLabel": "matrix",
+      "docsPath": "/channels/matrix-js",
+      "docsLabel": "matrix-js",
       "blurb": "open protocol; install the plugin to enable.",
       "order": 70,
       "quickstartAllowFrom": true

extensions/matrix-js/src/cli.ts

@@ -38,7 +38,7 @@ export function registerMatrixJsCli(params: { program: Command }): void {
   const root = params.program
     .command("matrix-js")
     .description("Matrix-js channel utilities")
-    .addHelpText("after", () => "\nDocs: https://docs.openclaw.ai/channels/matrix\n");
+    .addHelpText("after", () => "\nDocs: https://docs.openclaw.ai/channels/matrix-js\n");
 
   const verify = root.command("verify").description("Device verification for Matrix E2EE");