OpenClaw Manual OpenClaw

OpenClaw Matrix Channel

Decentralized
Medium

Connect OpenClaw to Matrix — an open, federated communication protocol. This integration lets your AI assistant participate in Matrix rooms and direct messages across any homeserver (matrix.org, Element, or self-hosted). OpenClaw connects via the Matrix Client-Server API with optional end-to-end encryption (E2EE) support through the Rust crypto SDK. The Matrix channel ships as a plugin and supports federation, threads, reactions, and rich media.

Quick Info
Difficulty Medium
Category Decentralized
Features Supported 5 / 6

Matrix Supported Features

Text Messages

Supported

Media & Files

Supported

Reactions

Supported

Threads

Supported

Voice Messages

Not Supported

Group Chat

Supported

Matrix Prerequisites

  • An active Matrix account on any homeserver (matrix.org, Element, or self-hosted)
  • The Matrix plugin installed: openclaw plugins install @openclaw/matrix
  • OpenClaw Gateway running and configured
  • Node.js 18+ installed on your server

Matrix Quick Setup

1

Install Matrix plugin

The Matrix channel ships as a separate plugin. Install it via 'openclaw plugins install @openclaw/matrix'. The plugin will be downloaded from the npm registry and enabled automatically.

2

Get Matrix credentials

You need either an access token or username/password. For access tokens: use curl to call your homeserver's login endpoint and copy the token. For username/password: the Gateway will automatically log in and store the token in ~/.openclaw/credentials/matrix/credentials.json.

3

Add Matrix channel config

Add the Matrix channel configuration to ~/.openclaw/openclaw.json with your homeserver URL and credentials. You can also use environment variables MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, MATRIX_USER_ID, and MATRIX_PASSWORD.

4

Start Gateway and test

Run 'openclaw gateway' to start the service. Send a direct message to your Matrix bot user from another account. If using the default pairing policy, approve the sender via 'openclaw pairing approve matrix <code>' in your terminal.

Matrix Configuration Example

config.json 
{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "accessToken": "your_access_token_here",
      "dmPolicy": "pairing"
    }
  }
}

Matrix Deep Dive

Architecture Overview

OpenClaw connects to Matrix through the Client-Server API, acting as a standard Matrix client. The architecture is event-driven: your bot receives events (messages, reactions, membership changes) via long-polling sync requests, processes them with your AI, and sends responses back through the API. Matrix is federated, meaning your bot can communicate with users on any homeserver across the global Matrix network — not just the homeserver where your bot account is registered. This is fundamentally different from centralized platforms like WhatsApp or Telegram. The flow is: User sends message in Matrix → Homeserver routes to your Gateway via sync → OpenClaw processes with AI → reply sent via send event API → message delivered across federation.
Federation means your bot on matrix.org can chat with users on any Matrix homeserver (e.g., element.io, Mozilla's homeserver, or self-hosted instances).
The Matrix plugin uses long-polling by default. There's no need for webhooks or public URLs — the Gateway connects outbound to your homeserver.

Authentication Methods

OpenClaw supports two authentication approaches for Matrix: 1. **Access Token (recommended)** — Obtain a token by calling your homeserver's login API using curl or a Matrix client. Set channels.matrix.accessToken in your config. The system automatically fetches your user ID via the /whoami endpoint. 2. **Username/Password** — Set channels.matrix.userId and channels.matrix.password. OpenClaw calls the login endpoint automatically and stores the access token in ~/.openclaw/credentials/matrix/credentials.json. Environment variables take precedence over config files: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, MATRIX_USER_ID, MATRIX_PASSWORD.
openclaw.json 
# Access token method
{
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.example.org",
      "accessToken": "syt_xxx..."
    }
  }
}

# Username/password method
{
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.example.org",
      "userId": "@bot:example.org",
      "password": "your_password"
    }
  }
}
Never commit access tokens or passwords to version control. Use environment variables for production deployments. If your token is compromised, log out all devices via your Matrix client to invalidate all tokens, then generate a new one.

DM Policies

DM (Direct Message) policies control who can interact with your AI assistant. OpenClaw supports four policies: • pairing (default) — Unknown users receive a pairing code on first contact. Approve via 'openclaw pairing approve matrix <CODE>' to grant access. Once approved, the user can chat freely. • allowlist — Only Matrix user IDs explicitly listed in channels.matrix.dm.allowFrom can message the bot. Everyone else is silently ignored. • open — Anyone who messages the bot gets a response. Requires allowFrom: ["*"]. Use with caution. • disabled — DM handling is completely turned off. Allowlists accept full Matrix user IDs in the format @user:server (e.g., @alice:matrix.org).
openclaw.json 
{
  "channels": {
    "matrix": {
      "dmPolicy": "allowlist",
      "dm": {
        "allowFrom": ["@alice:matrix.org", "@bob:example.org"]
      }
    }
  }
}

Group Chat (Room) Support

Matrix group conversations are called "rooms". By default, OpenClaw uses an allowlist policy for rooms, requiring mention-based activation. You can configure which rooms the bot participates in and how it responds. Rooms are identified by room IDs (!roomId:server) or room aliases (#alias:server). You can configure room-specific settings like auto-join behavior, mention requirements, and per-room user allowlists.
openclaw.json 
{
  "channels": {
    "matrix": {
      "groupPolicy": "allowlist",
      "groups": {
        "!abc123:matrix.org": {
          "allow": true,
          "requireMention": false,
          "users": ["@alice:matrix.org"]
        },
        "#team-chat:example.org": {
          "allow": true
        }
      },
      "autoJoin": "allowlist"
    }
  }
}
Set autoJoin to 'always' to automatically accept all room invites, 'allowlist' to only join configured rooms, or 'off' to ignore invites.
Use requireMention: false to enable auto-replies without mentioning the bot. Be cautious in high-traffic rooms.

End-to-End Encryption (E2EE)

Matrix supports end-to-end encryption (E2EE) through the Olm and Megolm protocols. OpenClaw can participate in encrypted rooms when you enable encryption via the Rust crypto SDK. When enabled, the system automatically decrypts encrypted messages, encrypts outbound media in secured rooms, and stores crypto state in ~/.openclaw/matrix/accounts/ (SQLite). Device verification is required on first connection — approve the verification request in Element or another Matrix client to enable key sharing. If crypto modules fail to load, E2EE is disabled and encrypted rooms remain inaccessible.
openclaw.json 
{
  "channels": {
    "matrix": {
      "encryption": true
    }
  }
}
Changing access tokens requires device re-verification. Keep backups of your crypto state directory (~/.openclaw/matrix/accounts/) to prevent losing access to encrypted message history.

Federation & Homeserver Selection

Matrix is a federated protocol — there's no single central server. You can choose to register your bot on any homeserver: • **matrix.org** — The flagship homeserver run by the Matrix Foundation. Open registration, high reliability, but can be slower due to high traffic. • **Element Matrix Services** — Professionally hosted homeservers at element.io with premium features and support. • **Self-hosted** — Run your own homeserver for maximum control and privacy. Synapse is the most mature and actively developed option. Dendrite (Go) and Conduit (Rust) are lighter alternatives suited to smaller deployments, though both are now in maintenance or limited-development mode. Your bot can communicate with users on any homeserver regardless of where it's registered, thanks to federation.
For production deployments, consider using a self-hosted homeserver or Element Matrix Services for better control and performance.
Federation works transparently — users don't need to know which homeserver your bot is on.

Threading & Reply Modes

Matrix supports threaded conversations through the m.thread relation type. OpenClaw can participate in threads and control how it handles replies. The threadReplies setting controls thread behavior: 'off' disables thread support, 'inbound' only reads thread context, and 'always' both reads and creates threaded replies. The replyToMode setting controls metadata attachment for reply relationships.
openclaw.json 
{
  "channels": {
    "matrix": {
      "threadReplies": "always",
      "replyToMode": "reference"
    }
  }
}

Media Handling & File Uploads

Matrix supports rich media including images, videos, audio, and documents. OpenClaw automatically handles media uploads — files are uploaded to your homeserver's media repository and referenced in message events. You can configure maximum file sizes via the mediaMaxMb setting. The default is 50 MB for inbound media, with automatic JPEG optimization and resizing for oversized images on outbound sends.
openclaw.json 
{
  "channels": {
    "matrix": {
      "mediaMaxMb": 50
    }
  }
}
Media uploads are stored on your homeserver. If you're using a public homeserver like matrix.org, be mindful of storage limits and terms of service.

Reactions & Rich Features

OpenClaw supports Matrix reactions (emoji responses to messages), polls, location sharing (geo URI format), and other rich features. Reactions can be sent and read via tools if enabled. You can gate specific operations through the actions configuration, restricting what your AI agent can do (reactions, messages, pins, member/channel info).
openclaw.json 
{
  "channels": {
    "matrix": {
      "actions": {
        "reactions": true,
        "messages": true,
        "pins": false
      }
    }
  }
}

Why Matrix for Self-Hosted AI?

Matrix is an excellent choice for self-hosted AI assistants because: • **Truly open** — Open specification, no vendor lock-in, multiple client and server implementations. • **Federated** — No single point of control or failure. Your bot can communicate across the global Matrix network. • **Privacy-focused** — E2EE support, self-hosted options, and no centralized data collection. • **Rich features** — Threads, reactions, media, polls, and extensible event types. • **No phone number required** — Unlike WhatsApp or Signal, Matrix doesn't require a phone number for registration. The tradeoff is complexity: Matrix's federation model and E2EE setup can be more involved than centralized platforms. For privacy-conscious users and teams, this tradeoff is worthwhile.

Matrix Configuration Reference

enabled
Type: boolean Default: true

Enable or disable the Matrix channel

homeserver
Type: string Default: "https://matrix.org"

Matrix homeserver URL (e.g., https://matrix.org, https://element.io)

accessToken
Type: string Default: ""

Matrix access token for authentication (recommended method)

userId
Type: string Default: ""

Matrix user ID (e.g., @bot:matrix.org) — used with password auth

password
Type: string Default: ""

Matrix account password — used with userId for login

encryption
Type: boolean Default: false

Enable end-to-end encryption via Rust crypto SDK

dmPolicy
Type: string Default: "pairing"

DM access policy: pairing, allowlist, open, or disabled

dm.allowFrom
Type: array Default: []

Allowed Matrix user IDs for DMs (e.g., [@alice:matrix.org])

groupPolicy
Type: string Default: "allowlist"

Room policy: allowlist or disabled

groups
Type: object Default: {}

Room-specific configuration (room ID or alias as key)

groups.<roomId>.allow
Type: boolean Default: false

Allow bot to participate in this room

groups.<roomId>.requireMention
Type: boolean Default: true

Require bot mention to trigger responses in this room

groups.<roomId>.users
Type: array Default: []

Per-room user allowlist (Matrix user IDs)

autoJoin
Type: string Default: "allowlist"

Auto-join room invites: always, allowlist, or off

textChunkLimit
Type: number Default: 4096

Maximum characters per outbound message

chunkMode
Type: string Default: "length"

How to split long responses: length (hard limit) or newline (paragraph boundaries)

threadReplies
Type: string Default: "inbound"

Thread behavior: off, inbound (read only), or always (read + create)

replyToMode
Type: string Default: "reference"

Reply metadata attachment mode

mediaMaxMb
Type: number Default: 50

Maximum media file size in megabytes

actions.reactions
Type: boolean Default: true

Allow the agent to send/read reactions

actions.messages
Type: boolean Default: true

Allow the agent to read/send/edit/delete messages

actions.pins
Type: boolean Default: true

Allow the agent to pin/unpin messages

actions.memberInfo
Type: boolean Default: true

Allow the agent to look up room member information

actions.channelInfo
Type: boolean Default: true

Allow the agent to retrieve room/channel information

Matrix Frequently Asked Questions

Matrix Troubleshooting

Bot not receiving messages

DM policy blocking messages, or bot not in room

Check channels.matrix.dmPolicy and dm.allowFrom settings. For rooms, ensure the room is in your groups allowlist and the bot has been invited and joined.
E2EE encrypted rooms show no messages

Device not verified or crypto modules failed to load

Verify your bot's device in Element or another Matrix client. Check logs for crypto module load errors. Ensure channels.matrix.encryption is set to true.
Access token invalid or expired

Token was revoked or invalidated on the homeserver

Generate a new access token by logging in again. If using username/password, delete ~/.openclaw/credentials/matrix/credentials.json and restart the Gateway.
Bot joins room but doesn't respond

Room not in allowlist or requireMention is enabled

Add the room to channels.matrix.groups with allow: true. If requireMention is true, users must mention the bot to get a response.
Federation errors with other homeservers

Homeserver connectivity or federation issues

Check your homeserver's federation status at federationtester.matrix.org. Verify DNS SRV records and SSL certificates if self-hosted.
Plugin installation fails

npm registry access or Node.js version incompatibility

Ensure Node.js 18+ is installed. Try 'openclaw plugins install @openclaw/matrix --verbose' for detailed error logs. Check network connectivity to the npm registry.
View Full Documentation Back to All Channels

Related Channels

Nostr

Advanced

OpenClaw decentralized NIP-04 DM integration

Setup Guide

Tlon

Advanced

OpenClaw Urbit messenger integration

Setup Guide