diff --git a/docs/channels/index.md b/docs/channels/index.md index f5ae8761852..95357fe9f3c 100644 --- a/docs/channels/index.md +++ b/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). diff --git a/docs/channels/matrix-js.md b/docs/channels/matrix-js.md new file mode 100644 index 00000000000..5f677341358 --- /dev/null +++ b/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 "" +``` + +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`). diff --git a/docs/channels/matrix.md b/docs/channels/matrix.md index 9bb56d1ddb7..b49922a04ee 100644 --- a/docs/channels/matrix.md +++ b/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, diff --git a/docs/docs.json b/docs/docs.json index 5e91b350113..d2ba02e66ff 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -903,6 +903,7 @@ "channels/msteams", "channels/synology-chat", "channels/line", + "channels/matrix-js", "channels/matrix", "channels/nextcloud-talk", "channels/nostr", diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index 9250501f2d9..4dcc7be3da1 100644 --- a/docs/tools/plugin.md +++ b/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` diff --git a/extensions/matrix-js/package.json b/extensions/matrix-js/package.json index d067972e315..63c7a7b54fb 100644 --- a/extensions/matrix-js/package.json +++ b/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 diff --git a/extensions/matrix-js/src/cli.ts b/extensions/matrix-js/src/cli.ts index 9e39771e936..ee618805c8d 100644 --- a/extensions/matrix-js/src/cli.ts +++ b/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");