​

Matrix (plugin)

​

Plugin required

clawdia plugins install @clawdia/matrix

clawdia plugins install ./extensions/matrix

​

Setup

1. Install the Matrix plugin:
   • From npm: clawdia plugins install @clawdia/matrix
   • From a local checkout: clawdia plugins install ./extensions/matrix
2. Create a Matrix account on a homeserver:
   • Browse hosting options at https://matrix.org/ecosystem/hosting/
   • Or host it yourself.
3. 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: Clawdia calls the same login endpoint, stores the access token in ~/.clawdia/credentials/matrix/credentials.json, and reuses it on next start.
4. 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).
5. Restart the gateway (or finish onboarding).
6. 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.

{
  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, Clawdia 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; Clawdia 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:
  • clawdia pairing list matrix
  • clawdia 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.

​

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, Clawdia 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
• channels.matrix.replyToMode controls reply-to metadata when not replying in a thread:
  • 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 newlines 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).