How to Connect Openclaw to Matrix

Table of contents: [Show]

Quick Start

Matrix is an open, decentralized communication protocol. Connecting Openclaw to Matrix lets your AI agent respond to messages in Matrix rooms and DMs. This guide walks you through the setup in under 5 minutes.

Install the Matrix Plugin

The Matrix integration is not bundled with the core install. First, install the plugin using the CLI:

Openclaw plugins install @Openclaw/matrix

Note: If you run Openclaw from a local git repository, use ./extensions/matrix instead.

Configure Authentication

You have two options for authentication: auto-login with credentials or using a pre-generated access token.

Option A: Auto-login with User ID and Password

Add your bot full Matrix ID (e.g., @bot:example.org) and password to your ~/.Openclaw/Openclaw.json:

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.example.org",
      "userId": "@bot:example.org",
      "password": "your-password",
      "dm": { "policy": "pairing" }
    }
  }
}

Openclaw will automatically log in, fetch the access token, and store it for future use.

Option B: Access Token

If you manually generated an access token, provide it via environment variables (MATRIX_HOMESERVER and MATRIX_ACCESS_TOKEN) or in your configuration:

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

Testing Your Setup

Once configured, start your Openclaw gateway:

Openclaw gateway

Send a message to your bot in a Matrix room or DM. The bot should respond if dm.policy is set to pairing and you have initiated contact.

Troubleshooting

Connection refused: Verify your homeserver URL includes the protocol (https://).
Invalid token: Regenerate the access token in your Matrix client and update the config.
Bot not responding: Check that the room is not encrypted (or configure E2E support separately).

For more messaging integrations, check out our guides on Mattermost Openclaw and Synology Chat Openclaw setup.