How to Connect OpenClaw to Matrix - Homeserver Setup Guide

Matrix is a strong fit when you want a self-hosted chat stack and you care about granular room control. OpenClaw ships Matrix as a bundled channel plugin, and the docs give you a fairly mature surface: DMs, rooms, threads, media, reactions, polls, location support, and optional encryption.

What the official docs support

The official Matrix docs describe token-based and password-based setup, room and DM policies, invite auto-join, E2EE, and opt-in preview streaming. The detail that matters most in real deployments is autoJoin: it defaults to off, so fresh invites do nothing unless you explicitly allow them.

This is the channel I would choose when an org already has a Matrix homeserver and wants OpenClaw to behave like a first-class team bot instead of a sidecar integration. You can keep DMs on pairing, restrict rooms by stable IDs or aliases, and make invite behavior fail closed.

What you need first

• A Matrix homeserver URL
• Either an access token or a user ID plus password
• A clear autoJoin policy for invited rooms
• Stable room IDs or aliases for allowlists

Recommended setup flow

The docs make Matrix look flexible, but the cleanest setup is still the conservative one: authenticate, choose how invites should work, then define the rooms you actually want the bot to join.

1. Create the Matrix account that will represent the bot on your homeserver. OpenClaw accepts homeserver plus accessToken for a token-first setup, or homeserver plus userId and password if you want the token cached after login.
2. Run the normal channel setup flow or edit channels.matrix directly. The wizard asks for homeserver URL, auth method, optional device name, whether encryption should be enabled, and whether to configure room access and invite auto-join right away.
3. Decide what autoJoin should do before you start inviting the bot around. The docs warn that autoJoin defaults to off, which means invited rooms and DM-style invites do not work unless you manually join first. For most teams, allowlist mode with stable !roomId or #alias entries is the right compromise.
4. Add room-level controls for the places where the bot should actually reply. The documented baseline uses groupPolicy allowlist, groupAllowFrom for trusted senders, requireMention in rooms, and dm.policy pairing for direct chats.
5. Restart the gateway and invite the bot into a DM or room. If you want live reply previews, turn on streaming partial later. Start without it if you want the most conservative Matrix API footprint and the fewest notification surprises.

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,
      dm: { policy: "pairing", sessionScope: "per-room" },
      groupPolicy: "allowlist",
      autoJoin: "allowlist",
      autoJoinAllowlist: ["!roomid:example.org"]
    }
  }
}

Access, safety, and operational notes

Matrix access control is more nuanced than most channels because invite handling happens before OpenClaw can fully classify a room. The docs spell that out. autoJoin governs invites first, then DM policy applies once the room is known to be a DM. That is why stable IDs and aliases matter so much.

If you use named accounts, remember that Matrix escapes punctuation in account-scoped environment variables. That sounds minor, but it is the sort of detail that explains mysterious auth failures later when an account name like ops-bot becomes MATRIX_OPS_X2D_BOT_* in env form.

How to verify it is working

Test one DM and one room invite separately. For rooms, verify the bot actually joins, then verify mention-gated replies. If a room name is ambiguous, resolve it first with openclaw channels resolve --channel matrix "Project Room" so your saved allowlist points to a stable identifier instead of a guess.

Common gotchas

• autoJoin is off by default, so invites quietly fail until you configure it
• Use stable room IDs or aliases, unresolved plain names are ignored at runtime
• Preview streaming is opt-in and costs extra Matrix API calls

If you want the operator version with tighter rollout checklists, safer defaults, and more production patterns, The OpenClaw Playbook is the easiest shortcut.