openclaw/docs/channels/matrix.md

summary, read_when, title

summary	read_when	title
Matrix support status, setup, and configuration examples	Setting up Matrix in OpenClaw Configuring Matrix E2EE and verification	Matrix

Matrix (plugin)

Matrix is the Matrix channel plugin for OpenClaw. It uses the official matrix-js-sdk and supports DMs, rooms, threads, media, reactions, polls, location, and E2EE.

Plugin required

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

Install from npm:

openclaw plugins install @openclaw/matrix

Install from a local checkout:

openclaw plugins install ./extensions/matrix

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 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: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      dm: { policy: "pairing" },
    },
  },
}

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

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      userId: "@bot:example.org",
      password: "replace-me",
      deviceName: "OpenClaw Gateway",
    },
  },
}

Matrix stores cached credentials in ~/.openclaw/credentials/matrix/. The default account uses credentials.json; named accounts use credentials-<account>.json.

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: {
      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: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,
      dm: { policy: "pairing" },
    },
  },
}

Check verification status:

openclaw matrix verify status

Verbose status (full diagnostics):

openclaw matrix verify status --verbose

Bootstrap cross-signing and verification state:

openclaw matrix verify bootstrap

Verbose bootstrap diagnostics:

openclaw matrix verify bootstrap --verbose

Verify this device with a recovery key:

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

Verbose device verification details:

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

Check room-key backup health:

openclaw matrix verify backup status

Verbose backup health diagnostics:

openclaw matrix verify backup status --verbose

Restore room keys from server backup:

openclaw matrix verify backup restore

Verbose restore diagnostics:

openclaw matrix 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 defaults startupVerification to "if-unverified". On startup, if this device is still unverified, Matrix 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.

Upgrading from the previous public Matrix plugin:

• OpenClaw automatically reuses the same Matrix account, access token, and device identity when possible.
• If the previous plugin stored a Matrix room-key backup decryption key locally, startup or openclaw doctor --fix will import it into the new recovery-key flow automatically.
• On the next gateway start, backed-up room keys are restored automatically into the new crypto store.
• If the old plugin had local-only room keys that were never backed up, OpenClaw will warn clearly. Those keys cannot be exported automatically from the previous rust crypto store, so some old encrypted history may remain unavailable until recovered manually.
• See Matrix migration for the full upgrade flow, limits, recovery commands, and common migration messages.

Encrypted runtime state is stored per account and per access token in ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/. That directory contains the sync store (bot-storage.json), crypto store (crypto/), recovery key file (recovery-key.json), IndexedDB snapshot (crypto-idb-snapshot.json), thread bindings (thread-bindings.json), and startup verification state (startup-verification.json) when those features are in use.

Automatic verification notices

Matrix 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 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. /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 when threadBindings.spawnSubagentSessions=true.
• Running /focus or /acp spawn --thread here inside an existing Matrix thread binds that current thread instead.

Thread Binding Config

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

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

Matrix thread-bound spawn flags are opt-in:

• Set threadBindings.spawnSubagentSessions: true to allow top-level /focus to create and bind new Matrix threads.
• Set threadBindings.spawnAcpSessions: true to allow /acp spawn --thread auto|here to bind ACP sessions to Matrix threads.

Reactions

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

• Outbound reaction tooling is gated by channels["matrix"].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"].accounts.<accountId>.ackReaction
• channels["matrix"].ackReaction
• messages.ackReaction
• agent identity emoji fallback

Ack reaction scope resolves in this order:

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

Reaction notification mode resolves in this order:

• channels["matrix"].accounts.<accountId>.reactionNotifications
• channels["matrix"].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: {
      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: {
      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).