Connect Matrix to Your AI Agent

Why Matrix Suits a Hosted Bot

Some chat platforms need to reach your agent from the outside, which means a public endpoint. Matrix works the other way around — the agent connects out to the homeserver and holds the connection open. That makes it a good fit for a hosted instance, and it works with matrix.org or any homeserver you run yourself.

Matrix is not one of the one-click tiles in Connect Platforms yet, so this is set up from the Web Terminal on your instance.

Before You Start

• A Matrix account for the bot. Create a separate one rather than reusing your own.
• Your homeserver URL, for example https://matrix.org.
• An access token, or the account password.
• The room IDs or aliases you want the bot to work in.

OpenClaw Setup

Install the Matrix channel plugin from the Web Terminal:

openclaw plugins install @openclaw/matrix

Then run the interactive setup:

openclaw channels add

The wizard asks for the homeserver URL, how to authenticate (token or password), the user ID if you chose password auth, an optional device name, whether to enable end-to-end encryption, and how room access and auto-join should work.

If you want to restrict the bot to specific rooms, resolve friendly names to room IDs first so the allowlist is stable:

openclaw channels resolve --channel matrix "Project Room"

OpenClaw caches the Matrix credentials in its own state store, so once the account is set up the channel stays configured even if the access token is not written into the config file.

Check it came up:

openclaw channels status --probe

Hermes Setup

Run the guided setup and pick Matrix:

hermes gateway setup

Or configure it directly. The settings that matter most are the allowlists and whether the bot needs to be mentioned before it answers:

MATRIX_REQUIRE_MENTION=true
MATRIX_ALLOWED_USERS=@alice:matrix.org
MATRIX_ALLOWED_ROOMS=!abc123:matrix.org
MATRIX_SESSION_SCOPE=room
MATRIX_AUTO_THREAD=true

MATRIX_SESSION_SCOPE=room is worth setting for project rooms — it keeps one conversation thread per room, so the agent holds context about that room rather than mixing everything together.

If your homeserver is bridged to other networks, you may want the bot to ignore the bridge puppets so it does not react to relayed users:

MATRIX_IGNORE_USER_PATTERNS='^@telegram_,^@whatsapp_'

End-to-End Encryption

Matrix supports E2EE, and both frameworks can participate. On OpenClaw, enabling encryption during the wizard runs the encryption bootstrap for you. Bear in mind that an encrypted room means the agent holds device keys, and a device that is not verified may not be able to read history from before it joined.

Troubleshooting

• The bot joins but never replies. It is probably waiting to be mentioned. Either mention it by name or turn the mention requirement off.
• Messages appear as unreadable blocks. That is an encrypted room the bot cannot decrypt. Verify the bot session, or invite it to the room again so it receives keys going forward.
• Login fails on a self-hosted homeserver. Check the homeserver URL is the client API base, not the web client address, and that federation or registration restrictions are not blocking the bot account.
• The bot replies to relayed users from a bridge. Add an ignore pattern for those user prefixes.

Need a Hand?

Contact support from your dashboard and we will set Matrix up on your instance for you.