Matrix (plugin)

Plugin required

openclaw plugins install @openclaw/matrix

openclaw plugins install ./extensions/matrix

Setup

1. Install the Matrix plugin:
   • From npm: openclaw plugins install @openclaw/matrix
   • From a local checkout: openclaw plugins install ./extensions/matrix
2. From npm: openclaw plugins install @openclaw/matrix
3. From a local checkout: openclaw plugins install ./extensions/matrix
4. Create a Matrix account on a homeserver:
   • Browse hosting options at https://matrix.org/ecosystem/hosting/
   • Or host it yourself.
5. Browse hosting options at https://matrix.org/ecosystem/hosting/
6. Or host it yourself.
7. Get an access token for the bot account:
   • Use the Matrix login API with curl at your home server:
   Copy

   curl --request POST \
     --url https://matrix.example.org/_matrix/client/v3/login \
     --header 'Content-Type: application/json' \
     --data '{
     "type": "m.login.password",
     "identifier": {
       "type": "m.id.user",
       "user": "your-user-name"
     },
     "password": "your-password"
   }'
   
   • Replace matrix.example.org with your homeserver URL.
   • Or set channels.matrix.userId + channels.matrix.password: OpenClaw calls the same login endpoint, stores the access token in ~/.openclaw/credentials/matrix/credentials.json, and reuses it on next start.
8. Use the Matrix login API with curl at your home server:
9. Replace matrix.example.org with your homeserver URL.
10. Or set channels.matrix.userId + channels.matrix.password: OpenClaw calls the same login endpoint, stores the access token in ~/.openclaw/credentials/matrix/credentials.json, and reuses it on next start.
11. Configure credentials:
    • Env: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (or MATRIX_USER_ID + MATRIX_PASSWORD)
    • Or config: channels.matrix.*
    • If both are set, config takes precedence.
    • With access token: user ID is fetched automatically via /whoami.
    • When set, channels.matrix.userId should be the full Matrix ID (example: @bot:example.org).
12. Env: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (or MATRIX_USER_ID + MATRIX_PASSWORD)
13. Or config: channels.matrix.*
14. If both are set, config takes precedence.
15. With access token: user ID is fetched automatically via /whoami.
16. When set, channels.matrix.userId should be the full Matrix ID (example: @bot:example.org).
17. Restart the gateway (or finish onboarding).
18. Start a DM with the bot or invite it to a room from any Matrix client (Element, Beeper, etc.; see https://matrix.org/ecosystem/clients/). Beeper requires E2EE, so set channels.matrix.encryption: true and verify the device.

• From npm: openclaw plugins install @openclaw/matrix
• From a local checkout: openclaw plugins install ./extensions/matrix

• Browse hosting options at https://matrix.org/ecosystem/hosting/
• Or host it yourself.

• Use the Matrix login API with curl at your home server:

curl --request POST \
  --url https://matrix.example.org/_matrix/client/v3/login \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "m.login.password",
  "identifier": {
    "type": "m.id.user",
    "user": "your-user-name"
  },
  "password": "your-password"
}'

• Replace matrix.example.org with your homeserver URL.
• Or set channels.matrix.userId + channels.matrix.password: OpenClaw calls the same login endpoint, stores the access token in ~/.openclaw/credentials/matrix/credentials.json, and reuses it on next start.

• Env: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (or MATRIX_USER_ID + MATRIX_PASSWORD)
• Or config: channels.matrix.*
• If both are set, config takes precedence.
• With access token: user ID is fetched automatically via /whoami.
• When set, channels.matrix.userId should be the full Matrix ID (example: @bot:example.org).

{
  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" },
    },
  },
}

Encryption (E2EE)

• If the crypto module loads, encrypted rooms are decrypted automatically.
• Outbound media is encrypted when sending to encrypted rooms.
• On first connection, OpenClaw requests device verification from your other sessions.
• Verify the device in another Matrix client (Element, etc.) to enable key sharing.
• If the crypto module cannot be loaded, E2EE is disabled and encrypted rooms will not decrypt; OpenClaw logs a warning.
• If you see missing crypto module errors (for example, @matrix-org/matrix-sdk-crypto-nodejs-*), allow build scripts for @matrix-org/matrix-sdk-crypto-nodejs and run pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs or fetch the binary with node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js.

Routing model

• Replies always go back to Matrix.
• DMs share the agent’s main session; rooms map to group sessions.

Access control (DMs)

• Default: channels.matrix.dm.policy = "pairing". Unknown senders get a pairing code.
• Approve via:
  • openclaw pairing list matrix
  • openclaw pairing approve matrix <CODE>
• openclaw pairing list matrix
• openclaw pairing approve matrix <CODE>
• Public DMs: channels.matrix.dm.policy="open" plus channels.matrix.dm.allowFrom=["*"].
• channels.matrix.dm.allowFrom accepts user IDs or display names. The wizard resolves display names to user IDs when directory search is available.

• openclaw pairing list matrix
• openclaw pairing approve matrix <CODE>

Rooms (groups)

• Default: channels.matrix.groupPolicy = "allowlist" (mention-gated). Use channels.defaults.groupPolicy to override the default when unset.
• Allowlist rooms with channels.matrix.groups (room IDs, aliases, or names):

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

• requireMention: false enables auto-reply in that room.
• groups."*" can set defaults for mention gating across rooms.
• groupAllowFrom restricts which senders can trigger the bot in rooms (optional).
• Per-room users allowlists can further restrict senders inside a specific room.
• The configure wizard prompts for room allowlists (room IDs, aliases, or names) and resolves names when possible.
• On startup, OpenClaw resolves room/user names in allowlists to IDs and logs the mapping; unresolved entries are kept as typed.
• Invites are auto-joined by default; control with channels.matrix.autoJoin and channels.matrix.autoJoinAllowlist.
• To allow no rooms, set channels.matrix.groupPolicy: "disabled" (or keep an empty allowlist).
• Legacy key: channels.matrix.rooms (same shape as groups).

Threads

• Reply threading is supported.
• channels.matrix.threadReplies controls whether replies stay in threads:
  • off, inbound (default), always
• off, inbound (default), always
• channels.matrix.replyToMode controls reply-to metadata when not replying in a thread:
  • off (default), first, all
• off (default), first, all

• off, inbound (default), always

• off (default), first, all

Capabilities

Configuration reference (Matrix)

• channels.matrix.enabled: enable/disable channel startup.
• channels.matrix.homeserver: homeserver URL.
• channels.matrix.userId: Matrix user ID (optional with access token).
• channels.matrix.accessToken: access token.
• channels.matrix.password: password for login (token stored).
• channels.matrix.deviceName: device display name.
• channels.matrix.encryption: 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 (chars).
• channels.matrix.chunkMode: length (default) or newline to split on blank lines (paragraph boundaries) before length chunking.
• channels.matrix.dm.policy: pairing | allowlist | open | disabled (default: pairing).
• channels.matrix.dm.allowFrom: DM allowlist (user IDs or display names). open requires "*". The wizard resolves names to IDs when possible.
• channels.matrix.groupPolicy: allowlist | open | disabled (default: allowlist).
• channels.matrix.groupAllowFrom: allowlisted senders for group messages.
• channels.matrix.allowlistOnly: force allowlist rules for DMs + rooms.
• channels.matrix.groups: group allowlist + per-room settings map.
• channels.matrix.rooms: legacy group allowlist/config.
• channels.matrix.replyToMode: reply-to mode for threads/tags.
• channels.matrix.mediaMaxMb: inbound/outbound media cap (MB).
• channels.matrix.autoJoin: invite handling (always | allowlist | off, default: always).
• channels.matrix.autoJoinAllowlist: allowed room IDs/aliases for auto-join.
• channels.matrix.actions: per-action tool gating (reactions/messages/pins/memberInfo/channelInfo).