Skip to main content

​
Matrix (plugin)

Status: supported via plugin (matrix-js-sdk). Direct messages, rooms, threads, media, reactions, and polls.

​
Plugin required

Matrix ships as a plugin and is not bundled with the core install. Install via CLI (npm registry): 
clawdbot plugins install @clawdbot/matrix
Local checkout (when running from a git repo): 
clawdbot plugins install ./extensions/matrix
If you choose Matrix during configure/onboarding and a git checkout is detected, Clawdbot will offer the local install path automatically. Details: Plugins

​
Quick setup (beginner)

  1. Install the Matrix plugin:
    • From npm: clawdbot plugins install @clawdbot/matrix
    • From a local checkout: clawdbot plugins install ./extensions/matrix
  2. Configure credentials:
    • Env: MATRIX_HOMESERVER, MATRIX_USER_ID, MATRIX_ACCESS_TOKEN (or MATRIX_PASSWORD)
    • Or config: channels.matrix.*
  3. Restart the gateway (or finish onboarding).
  4. DM access defaults to pairing; approve the pairing code on first contact.
Runtime note: Matrix requires Node.js (Bun is not supported). Minimal config: 
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      userId: "@clawdbot:example.org",
      accessToken: "syt_***",
      dm: { policy: "pairing" }
    }
  }
}

​
Encryption (E2EE)

End-to-end encrypted rooms are not supported.
  • Use unencrypted rooms or disable encryption when creating the room.
  • If a room is E2EE, the bot will receive encrypted events and won’t reply.

​
What it is

Matrix is an open messaging protocol. Clawdbot connects as a Matrix user and listens to DMs and rooms.
  • A Matrix user account owned by the Gateway.
  • Deterministic routing: replies 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:
    • clawdbot pairing list matrix
    • clawdbot pairing approve matrix <CODE>
  • Public DMs: channels.matrix.dm.policy="open" plus channels.matrix.dm.allowFrom=["*"].

​
Rooms (groups)

  • Default: channels.matrix.groupPolicy = "allowlist" (mention-gated).
  • Allowlist rooms with channels.matrix.rooms:
{
  channels: {
    matrix: {
      rooms: {
        "!roomId:example.org": { requireMention: true }
      }
    }
  }
}
  • requireMention: false enables auto-reply in that room.

​
Threads

  • Reply threading is supported.
  • channels.matrix.replyToMode controls replies when tagged:
    • off (default), first, all

​
Capabilities

FeatureStatus
Direct messages✅ Supported
Rooms✅ Supported
Threads✅ Supported
Media✅ Supported
Reactions✅ Supported
Polls✅ Supported
Native commands✅ Supported

​
Configuration reference (Matrix)

Full configuration: Configuration Provider options:
  • channels.matrix.enabled: enable/disable channel startup.
  • channels.matrix.homeserver: homeserver URL.
  • channels.matrix.userId: Matrix user ID.
  • channels.matrix.accessToken: access token.
  • channels.matrix.password: password for login (token stored).
  • channels.matrix.deviceName: device display name.
  • channels.matrix.initialSyncLimit: initial sync limit.
  • channels.matrix.threadReplies: off | inbound | always (default: inbound).
  • channels.matrix.textChunkLimit: outbound text chunk size (chars).
  • channels.matrix.dm.policy: pairing | allowlist | open | disabled (default: pairing).
  • channels.matrix.dm.allowFrom: DM allowlist. open requires "*".
  • channels.matrix.groupPolicy: allowlist | open | disabled (default: allowlist).
  • channels.matrix.allowlistOnly: force allowlist rules for DMs + rooms.
  • channels.matrix.rooms: per-room settings and allowlist.
  • 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).