openclaw/docs/channels/matrix-js.md

summary, read_when, title

summary	read_when	title
Matrix-js support status, setup, and configuration examples	Setting up Matrix-js in OpenClaw Configuring Matrix E2EE and verification	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).

Plugin required

Matrix-js is a plugin and is not bundled with core OpenClaw.

Install from npm:

openclaw plugins install @openclaw/matrix-js

Install from a local checkout:

openclaw plugins install ./extensions/matrix-js

See Plugins 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:

{
  channels: {
    "matrix-js": {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      dm: { policy: "pairing" },
    },
  },
}

Password-based setup (token is cached after login):

{
  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

For non-default accounts, use account-scoped env vars:

• MATRIX_<ACCOUNT_ID>_HOMESERVER
• MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN
• MATRIX_<ACCOUNT_ID>_USER_ID
• MATRIX_<ACCOUNT_ID>_PASSWORD
• MATRIX_<ACCOUNT_ID>_DEVICE_ID
• MATRIX_<ACCOUNT_ID>_DEVICE_NAME

Example for account ops:

• MATRIX_OPS_HOMESERVER
• MATRIX_OPS_ACCESS_TOKEN

Configuration example

This is a practical baseline config with DM pairing, room allowlist, and E2EE enabled:

{
  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:

{
  channels: {
    "matrix-js": {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,
      dm: { policy: "pairing" },
    },
  },
}

Check verification status:

openclaw matrix-js verify status

Verbose status (full diagnostics):

openclaw matrix-js verify status --verbose

Bootstrap cross-signing and verification state:

openclaw matrix-js verify bootstrap

Verbose bootstrap diagnostics:

openclaw matrix-js verify bootstrap --verbose

Verify this device with a recovery key:

openclaw matrix-js verify device "<your-recovery-key>"

Verbose device verification details:

openclaw matrix-js verify device "<your-recovery-key>" --verbose

Check room-key backup health:

openclaw matrix-js verify backup status

Verbose backup health diagnostics:

openclaw matrix-js verify backup status --verbose

Restore room keys from server backup:

openclaw matrix-js verify backup restore

Verbose restore diagnostics:

openclaw matrix-js verify backup restore --verbose

All verify commands are concise by default (including quiet internal SDK logging) and show detailed diagnostics only with --verbose. Use --json for full machine-readable output when scripting.

When encryption: true, Matrix-js defaults startupVerification to "if-unverified". On startup, if this device is still unverified, Matrix-js will request self-verification in another Matrix client, skip duplicate requests while one is already pending, and apply a local cooldown before retrying after restarts. Failed request attempts retry sooner than successful request creation by default. Set startupVerification: "off" to disable automatic startup requests, or tune startupVerificationCooldownHours if you want a shorter or longer retry window.

Automatic verification notices

Matrix-js now posts verification lifecycle notices directly into the Matrix room as m.notice messages. That includes:

• verification request notices
• verification ready notices (with explicit "Verify by emoji" guidance)
• verification start and completion notices
• SAS details (emoji and decimal) when available

Inbound SAS requests are auto-confirmed by the bot device, so once the user confirms "They match" in their Matrix client, verification completes without requiring a manual OpenClaw tool step. Verification protocol/system notices are not forwarded to the agent chat pipeline, so they do not produce NO_REPLY.

Threads

Matrix-js supports native Matrix threads for both automatic replies and message-tool sends.

• threadReplies: "off" keeps replies top-level.
• threadReplies: "inbound" replies inside a thread only when the inbound message was already in that thread.
• threadReplies: "always" keeps room replies in a thread rooted at the triggering message.
• Inbound threaded messages include the thread root message as extra agent context.
• Message-tool sends now auto-inherit the current Matrix thread when the target is the same room, or the same DM user target, unless an explicit threadId is provided.
• Runtime thread bindings are supported for Matrix-js. /focus, /unfocus, /agents, /session idle, /session max-age, and thread-bound /acp spawn now work in Matrix rooms and DMs.
• Top-level Matrix room/DM /focus creates a new Matrix thread and binds it to the target session.
• Running /focus or /acp spawn --thread here inside an existing Matrix thread binds that current thread instead.

Thread Binding Config

Matrix-js inherits global defaults from session.threadBindings, and also supports per-channel overrides:

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSubagentSessions
• threadBindings.spawnAcpSessions

For Matrix-js, spawn flags default to enabled unless you turn them off explicitly.

Reactions

Matrix-js supports outbound reaction actions, inbound reaction notifications, and inbound ack reactions.

• Outbound reaction tooling is gated by channels["matrix-js"].actions.reactions.
• react adds a reaction to a specific Matrix event.
• reactions lists the current reaction summary for a specific Matrix event.
• emoji="" removes the bot account's own reactions on that event.
• remove: true removes only the specified emoji reaction from the bot account.

Ack reactions use the standard OpenClaw resolution order:

• channels["matrix-js"].accounts.<accountId>.ackReaction
• channels["matrix-js"].ackReaction
• messages.ackReaction
• agent identity emoji fallback

Ack reaction scope resolves in this order:

• channels["matrix-js"].accounts.<accountId>.ackReactionScope
• channels["matrix-js"].ackReactionScope
• messages.ackReactionScope

Reaction notification mode resolves in this order:

• channels["matrix-js"].accounts.<accountId>.reactionNotifications
• channels["matrix-js"].reactionNotifications
• default: own

Current behavior:

• reactionNotifications: "own" forwards added m.reaction events when they target bot-authored Matrix messages.
• reactionNotifications: "off" disables reaction system events.
• Reaction removals are still not synthesized into system events because Matrix surfaces those as redactions, not as standalone m.reaction removals.

DM and room policy example

{
  channels: {
    "matrix-js": {
      dm: {
        policy: "allowlist",
        allowFrom: ["@admin:example.org"],
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

See Groups for mention-gating and allowlist behavior.

Multi-account example

{
  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.
• 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.
• threadBindings: per-channel overrides for thread-bound session routing and lifecycle.
• startupVerification: automatic self-verification request mode on startup (if-unverified, off).
• startupVerificationCooldownHours: cooldown before retrying automatic startup verification requests.
• textChunkLimit: outbound message chunk size.
• chunkMode: length or newline.
• responsePrefix: optional message prefix for outbound replies.
• ackReaction: optional ack reaction override for this channel/account.
• ackReactionScope: optional ack reaction scope override (group-mentions, group-all, direct, all, none, off).
• reactionNotifications: inbound reaction notification mode (own, off).
• 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).