Matrix

Decentralized Matrix protocol integration with E2EE, rooms, threads, reactions, polls, location, and multi-homeserver support.

Matrix is OpenClaw's integration for the decentralized Matrix protocol, connecting your AI agent to any Matrix homeserver using the official matrix-js-sdk. Matrix is an open, federated communication protocol where anyone can run their own server and all servers interoperate — like email but for real-time messaging. This makes it the go-to choice for privacy-conscious users and organizations that need full data sovereignty. The plugin supports two authentication methods: access token (simpler, recommended for most setups) or username + password (token is cached after first login). Interactive setup is available via 'openclaw channels add' which walks through homeserver URL, auth method, device name, E2EE enablement, and initial room configuration. Matrix credentials are cached in ~/.openclaw/credentials/matrix/ for session persistence across restarts. Matrix's feature set is impressively broad: DMs, rooms, threads, reactions, polls, location sharing, media (images, audio, video, files), and end-to-end encryption via the Rust crypto SDK. E2EE is optional and can be enabled per-deployment. The integration supports Beeper (the Matrix-based universal inbox) with E2EE compatibility. Thread replies keep conversations organized within rooms, and poll sending enables interactive engagement. The decentralized nature means your agent can be reached from any Matrix client — Element, FluffyChat, Cinny, Beeper, or any other Matrix-compatible app. Multi-account support allows connecting to multiple homeservers from one OpenClaw instance. Room identity uses stable Matrix room IDs (not aliases), and the interactive wizard resolves room names and user IDs live against the directory. For self-hosters who want an open-protocol AI assistant without depending on any central service, Matrix is the clear choice.

Tags: messaging, decentralized, open-protocol, e2ee, privacy

Category: Messaging

Use Cases

Privacy-first AI assistant on a self-hosted Matrix homeserver
Decentralized team AI bot accessible from any Matrix client
E2EE-encrypted AI conversations for security-sensitive organizations
Open-protocol AI assistant without vendor lock-in
Beeper users wanting AI integration across their unified inbox
Community knowledge bot in public Matrix rooms with mention-gated access
Multi-homeserver AI deployment for federated organizations

Tips

Use access token auth for simplicity — generate from Element or via Matrix client API
Prefer room IDs (!room:server) over aliases (#alias:server) in config — they're stable even if aliases change
Use 'openclaw channels resolve --channel matrix "Room Name"' to convert display names to room IDs before configuring
Enable E2EE if your homeserver enforces it or if you want encrypted AI conversations
Run your own homeserver (Synapse, Conduit) for complete data sovereignty
Multi-account env vars follow the pattern MATRIX_<ACCOUNT_ID>_HOMESERVER — account IDs are normalized (ops-bot → OPS_BOT)
The interactive wizard offers an env var shortcut if Matrix auth env vars are already set
Matrix works with any client — Element, FluffyChat, Cinny, Beeper, even bridged from other platforms

Known Issues & Gotchas

Room allowlist prompts accept full @user:server values immediately — display names only work when live directory lookup finds exactly one match
Room identity uses the stable Matrix room ID (!room:server), NOT aliases or display names — aliases are only used as lookup inputs
Unresolved room names during setup are kept as-typed but ignored by runtime allowlist resolution — always prefer !room:server or #alias:server format
When adding another Matrix account interactively, the account name is normalized (e.g., 'Ops Bot' becomes 'ops-bot') for config and env var naming
E2EE key trust may need manual verification for new devices — check element's device verification flow
Credentials are cached in ~/.openclaw/credentials/matrix/ — back up this directory if moving installations
Password auth caches the access token — changing the password invalidates cached credentials
Runtime room resolution uses stable room IDs, not aliases — if a room alias changes, the session key doesn't change

Alternatives

Signal
Discord
IRC
Telegram

Community Feedback

Matrix + OpenClaw is the dream stack for self-hosters. Your own homeserver, your own AI agent, all your own data. No corporate servers in the loop.
— Reddit r/selfhosted

I've been running OpenClaw on my Synapse homeserver and it works beautifully. E2EE support means even the AI conversations are encrypted. The setup is a bit involved but worth it.
— Reddit r/Matrix

Matrix channel: E2EE with Rust crypto SDK. This was the most requested feature for the Matrix integration. Finally landed and works with Beeper too.
— GitHub Discussions

Frequently Asked Questions

Do I need to run my own Matrix homeserver?

No. You can create a free account on matrix.org or any public homeserver. However, running your own (Synapse, Conduit, Dendrite) gives you complete data sovereignty — a major reason people choose Matrix in the first place.

Does Matrix support E2EE with OpenClaw?

Yes. The Matrix plugin uses the Rust crypto SDK for E2EE. Enable it with e2ee: true in your config. E2EE works with Element, Beeper, and other clients that support Matrix encryption. Note that messages are decrypted at the OpenClaw server for processing.

Is the Matrix plugin bundled with OpenClaw?

No. Matrix is a plugin that must be installed separately: openclaw plugins install @openclaw/matrix. It's not bundled with core OpenClaw.

Can I use Beeper with OpenClaw's Matrix integration?

Yes. Beeper is built on Matrix, so OpenClaw's Matrix plugin works with it. E2EE must be enabled for Beeper compatibility. Your agent appears as a Matrix user that Beeper can DM or invite to rooms.

How do I generate a Matrix access token?

In Element: Settings → Help & About → scroll to 'Access Token' (may need to enable in advanced settings). Or use the Matrix client API: POST /_matrix/client/v3/login with username and password. The access token is the most reliable auth method for bots.

Does Matrix support streaming responses?

No. The Matrix plugin sends complete messages, not streaming edits. Matrix supports message editing in the protocol, but OpenClaw's plugin currently sends responses as single messages.

What Matrix clients work with OpenClaw?

Any Matrix client works: Element (web/desktop/mobile), FluffyChat, Cinny, Beeper, Nheko, SchildiChat, and more. The bot appears as a standard Matrix user. E2EE compatibility depends on the client supporting Matrix encryption.

Configuration Examples

Token-based setup

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

Password-based with E2EE

channels:
  matrix:
    enabled: true
    homeserver: "https://matrix.example.org"
    userId: "@bot:example.org"
    password: "bot-password"
    deviceName: "OpenClaw Gateway"
    e2ee: true
    dm:
      policy: pairing

Multi-homeserver setup

channels:
  matrix:
    enabled: true
    homeserver: "https://matrix.example.org"
    accessToken: "syt_default_token"
    dm:
      policy: pairing
    accounts:
      work:
        homeserver: "https://matrix.company.com"
        accessToken: "syt_work_token"
        dm:
          policy: allowlist
          allowFrom:
            - "@alice:company.com"
            - "@bob:company.com"

Installation

openclaw plugins install @openclaw/matrix