Matrix

Matrix is an open decentralized messaging protocol. OpenClaw connects to any homeserver as a Matrix user, so you need to prepare a Matrix account for the bot. After logging in, you can DM the bot directly or invite it to rooms (Matrix's "group chats"/rooms). Beeper can also be used as a client, but it typically requires E2EE to be enabled.

Status: Supported via plugin (@vector-im/matrix-bot-sdk). Supports DMs, rooms, threads, media, reactions, polls (sending + inbound poll-start to text), location, and end-to-end encryption (E2EE) with crypto support.

Matrix is provided as a plugin and is not bundled with the core installation.

Install via CLI (npm registry):

openclaw plugins install @openclaw/matrix

Local installation (when running from a git repository):

openclaw plugins install ./extensions/matrix

If you select Matrix in configure/onboarding and a git checkout is detected, OpenClaw will automatically provide the local installation path.

Details: ''/plugin''

1. Install the Matrix plugin:

- npm: openclaw plugins install @openclaw/matrix

- local checkout: openclaw plugins install ./extensions/matrix

2. Create a Matrix account on a homeserver:

- For hosted options, see: <https://matrix.org/ecosystem/hosting/>

- Or self-host

3. Get the bot account's access token:

- Use the homeserver's Matrix login API (curl):

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_***",
      dm: { policy: "pairing" },
    },
  },
}

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

End-to-end encryption is supported (using Rust crypto SDK).

After setting channels.matrix.encryption: true:

- When the crypto module loads successfully, encrypted rooms are automatically decrypted.

- Media sent to encrypted rooms is encrypted.

- On first connection, OpenClaw will initiate device verification requests to your other sessions.

- Approve the verification request in another Matrix client (e.g., Element) to enable key sharing.

- If the crypto module cannot load, E2EE is disabled and encrypted rooms will not be decrypted; OpenClaw will log a warning.

- If you see errors about missing crypto modules (e.g., @matrix-org/matrix-sdk-crypto-nodejs-*), you need to allow build scripts for @matrix-org/matrix-sdk-crypto-nodejs and run:

- pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs, or

- node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js (to fetch binaries)

Crypto state is stored per account + access token at:

~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/

(SQLite database). Sync state is saved in bot-storage.json in the same directory.

If the access token (device) changes, a new store is created and the bot needs to be re-verified to read encrypted room messages.

Device verification:

After enabling E2EE, the bot will request verification from your other sessions on startup. Approve the request in Element (or another client) to establish trust. Only after verification is complete can the bot decrypt encrypted room messages.

- Replies always go back to Matrix.

- DMs share the agent's main session; rooms map to group sessions (independent session key).

- Default: channels.matrix.dm.policy = "pairing". Unknown senders receive a pairing code.

- Approve:

- openclaw pairing list matrix

- openclaw pairing approve matrix <CODE>

- Public DMs: channels.matrix.dm.policy="open" and channels.matrix.dm.allowFrom=["*"].

- channels.matrix.dm.allowFrom supports user IDs or display names. When directory search is available, the wizard will resolve display names to user IDs.

- Default: channels.matrix.groupPolicy = "allowlist" (and mention gating is enabled by default). If not set, channels.defaults.groupPolicy can be used to override the default.

- Use channels.matrix.groups for room allowlists (room IDs, aliases, or names can be used):

{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
      groupAllowFrom: ["@owner:example.org"],
    },
  },
}

- requireMention: false makes the room auto-reply.

- groups."*" can set default mention behavior for all rooms.

- groupAllowFrom (optional) limits which senders can trigger the bot in rooms.

- Per-room users allowlists can further limit triggers within a room.

- configure/onboarding will prompt for room allowlists and resolve names when possible.

- On startup, OpenClaw will try to resolve room/user names in allowlists to IDs and log the mappings; failed entries remain as-is.

- Invites are auto-joined by default; use channels.matrix.autoJoin and channels.matrix.autoJoinAllowlist to control.

- To completely disable rooms, set channels.matrix.groupPolicy: "disabled" (or keep allowlist empty).

- Legacy key: channels.matrix.rooms (same structure as groups).

- Reply threading is supported.

- channels.matrix.threadReplies controls whether replies stay in threads:

- off, inbound (default), always

- channels.matrix.replyToMode controls reply-to metadata when replying outside threads:

- off (default), first, all

| Feature | Status |

| ----- |

| DMs | ✅ Supported |

| Rooms | ✅ Supported |

| Threads | ✅ Supported |

| Media | ✅ Supported |

| E2EE | ✅ Supported (requires crypto module) |

| Reactions | ✅ Supported (send/read via tools) |

| Polls | ✅ Sending supported; inbound poll-start converted to text (responses/ends ignored) |

| Location | ✅ Supported (geo URI; altitude ignored) |

| Native commands | ✅ Supported |

Full configuration: ''/gateway/configuration''

Provider options:

- channels.matrix.enabled: Whether to enable the channel

- channels.matrix.homeserver: Homeserver URL

- channels.matrix.userId: Matrix user ID (optional when using access token)

- channels.matrix.accessToken: Access token

- channels.matrix.password: Password for login (token will be persisted)

- channels.matrix.deviceName: Device display name

- channels.matrix.encryption: Whether to enable E2EE (default false)

- channels.matrix.initialSyncLimit: Initial sync limit

- channels.matrix.threadReplies: off | inbound | always (default inbound)

- channels.matrix.textChunkLimit: Outbound text chunk size (characters)

- channels.matrix.chunkMode: length (default) or newline (split by blank lines first, then by length)

- channels.matrix.dm.policy: pairing | allowlist | open | disabled (default pairing)

- channels.matrix.dm.allowFrom: DM allowlist (user IDs or display names); open requires "*"; auto-converted to IDs when resolvable

- channels.matrix.groupPolicy: allowlist | open | disabled (default allowlist)

- channels.matrix.groupAllowFrom: Group message sender allowlist

- channels.matrix.allowlistOnly: Force allowlist rules for both DMs and rooms

- channels.matrix.groups: Rooms allowlist + per-room settings

- channels.matrix.rooms: Legacy rooms allowlist/config

- channels.matrix.replyToMode: Reply-to mode for threads/tags

- channels.matrix.mediaMaxMb: Inbound/outbound media limit (MB)

- channels.matrix.autoJoin: Invite auto-join strategy (always | allowlist | off, default always)

- channels.matrix.autoJoinAllowlist: Room IDs/aliases allowed to auto-join

- channels.matrix.actions: Per-action tool toggles (reactions/messages/pins/memberInfo/channelInfo)