Matrix

OpenClaw Matrix channel plugin. Connect to Matrix homeservers for decentralized messaging.

The Matrix plugin connects OpenClaw to any Matrix homeserver, enabling your AI agent to communicate through the decentralized Matrix protocol. Built on the official matrix-js-sdk, it supports DMs, rooms, threads, media attachments, reactions, polls, location sharing, and end-to-end encryption (E2EE) — making it one of the most feature-complete channel plugins available. Matrix is a federated, open protocol for real-time communication. Unlike centralized platforms like Discord or Telegram, Matrix lets you self-host your own homeserver (using Synapse, Dendrite, or Conduit) and communicate across servers via federation. This makes the Matrix plugin ideal for privacy-conscious users, self-hosters, and organizations that need full data sovereignty. Setup supports two authentication methods: access token (recommended for production) or username/password (token is cached after initial login). The plugin stores credentials in ~/.openclaw/credentials/matrix/ and supports named accounts for multi-bot deployments. An interactive wizard guides you through homeserver URL, auth method, E2EE settings, and room/DM allowlists. Environment variables (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, etc.) work as fallbacks when config keys aren't set. The plugin's E2EE support using Olm/Megolm is a standout feature — your AI conversations can be truly private, encrypted end-to-end between your client and the bot. Room identity uses stable Matrix room IDs for session management, with alias resolution available for convenience. Best for self-hosters, privacy advocates, and anyone who wants their AI assistant on a decentralized, censorship-resistant platform.

Tags: channel, messaging, self-hosted

Use Cases

Privacy-focused personal AI assistant with end-to-end encrypted conversations
Self-hosted AI bot on a private Matrix homeserver for full data sovereignty
Federated team assistant accessible across multiple Matrix homeservers in an organization
Homelab AI agent that communicates through Matrix rooms for automation and monitoring alerts
Decentralized community bot for open-source projects using Matrix as their communication platform

Tips

Use access token auth for production — it's more reliable than password auth and avoids login rate limits
Enable E2EE for private conversations, especially when handling sensitive data or personal information
Use 'openclaw channels resolve --channel matrix "Room Name"' to verify room IDs before adding them to allowlists
Set up a dedicated Matrix account for the bot rather than using your personal account
For self-hosted homeservers, Dendrite is lighter than Synapse and works well for single-user bot deployments
Use environment variables for credentials in Docker deployments to avoid secrets in config files
Start with DM-only policy for testing before opening up room access

Known Issues & Gotchas

Use room IDs (!room:server) or aliases (#alias:server) in allowlists — display names are unreliable for runtime resolution
E2EE device verification may be required before encrypted rooms accept messages from the bot
Password auth caches a token after first login — subsequent restarts use the cached token, not the password
If your homeserver uses a .well-known delegation, ensure the base URL points to the actual server, not the delegated domain
Multi-account setups use account-scoped env vars (MATRIX_OPS_HOMESERVER) — the account name is normalized (spaces become hyphens)
The interactive wizard only offers env-var shortcuts when auth environment variables are already set
Room name resolution only works for rooms the bot has already joined — unresolved names are silently ignored at runtime
Credential files should have 0600 permissions to prevent unauthorized access

Alternatives

Discord (@openclaw/discord)
Telegram (built-in)
Rocket.Chat (openclaw-rocketchat)
XMPP/Jabber

Community Feedback

Matrix: Decentralized messaging. And more! Each one has its own setup process. Check the OpenClaw docs for specific instructions!
— Reddit r/AiForSmallBusiness

If you care about self-sovereign comms, Matrix with OpenClaw is the way. Full E2EE, your homeserver, your data.
— Reddit r/selfhosted

OpenClaw only nukes your box if you actually give it tools that can nuke your box and don't put guardrails around them. Matrix + allowlists is the secure way.
— Reddit r/homelab

Frequently Asked Questions

How do I get a Matrix access token for the bot?

You can generate an access token by logging into your Matrix account via Element or another client and extracting it from Settings > Help & About. Alternatively, use the password auth method in OpenClaw and it will cache a token automatically after the first login.

Does the Matrix plugin support end-to-end encryption?

Yes. The plugin supports E2EE via Olm/Megolm encryption. Enable it in config and ensure libolm is installed on your system. Device verification may be required before the bot can participate in encrypted rooms.

Can I use matrix.org as my homeserver?

Yes, you can create a free account on matrix.org and use it as your homeserver. However, for production use or privacy-sensitive deployments, self-hosting with Synapse or Dendrite is recommended.

How do I invite the bot to a room?

Invite the bot's Matrix user ID (e.g., @bot:example.org) to any room from your Matrix client. The bot will auto-accept invites if configured to do so. Use room allowlists to control which rooms it responds in.

Does federation work with the OpenClaw Matrix bot?

Yes. Since the bot is a standard Matrix user, it works across federated homeservers. Users on different homeservers can DM or invite the bot to rooms, subject to federation policies on both servers.

What's the difference between room IDs and aliases?

Room IDs (!abc:server) are stable identifiers that never change. Aliases (#name:server) are human-readable but can be reassigned. Always use room IDs in allowlists for reliability. Use 'openclaw channels resolve' to look up IDs from names.

Configuration Examples

Token-Based Authentication

channels:
  matrix:
    enabled: true
    homeserver: https://matrix.example.org
    accessToken: syt_xxxxxxxxxxxxx
    dm:
      policy: pairing

Password Auth with E2EE

channels:
  matrix:
    enabled: true
    homeserver: https://matrix.example.org
    userId: '@bot:example.org'
    password: ${MATRIX_PASSWORD}
    deviceName: OpenClaw Gateway
    encryption:
      enabled: true

Multi-Account Matrix Setup

channels:
  matrix:
    enabled: true
    homeserver: https://matrix.example.org
    accessToken: ${MATRIX_ACCESS_TOKEN}
    accounts:
      ops:
        homeserver: https://matrix.ops.internal
        accessToken: ${MATRIX_OPS_ACCESS_TOKEN}
        rooms:
          allowed:
            - '!abc123:ops.internal'

Installation

openclaw plugins install @openclaw/matrix