Matrix Channel Plugin Setup and Configuration Guide

Matrix ships as a channel plugin you download (@openclaw/matrix), and it is built on the official matrix-js-sdk. DMs, rooms, threads, media, reactions, polls, location, and E2EE are all supported.

Node stays the recommended runtime. The opt-in Bun runtime is also accepted by Matrix; for E2EE, the Matrix SDK's native crypto bindings must be available on your platform.

Matrix account and token-hash stores use the effective database.families.state.engine (or database.engine when inherited). With PostgreSQL, every root gets its own local anchor and remote namespace, its serialized crypto state included. To move existing roots, stop the Gateway and use database port; editing config alone will not migrate them. Leave the Matrix plugin installed so that backup, restore, updates, and Doctor can find its retained roots, disabled accounts included.

When the local Gateway is running, openclaw matrix verify status, verify bootstrap, and verify device are routed through it. If an older Gateway lacks support for this routing, update it; requests that fail are never replayed locally.

The remaining openclaw matrix commands need the local Gateway stopped, device diagnostics among them: preparing the account may update its crypto state. Stop the Gateway via its service owner, run the command, then start it again. If a Gateway owns the state directory, commands refuse before any account state is loaded. Offline ownership holds through crypto persistence and client shutdown.

When an encrypted session was interrupted, openclaw matrix doctor inspect lists the accounts that require explicit snapshot recovery. Clean sessions keep their crypto guard files, so do not delete them. Read encrypted-state recovery before you accept a snapshot rollback.

Setup, Install the plugin and connect a homeserver account.
Encryption, Enable E2EE and verify the gateway device.
Matrix migration, Encrypted-state recovery limits and the upgrade flow.

What each page covers

Matrix setup, install the plugin, point it at a homeserver, choose auth, and control invites and allowlists.
Matrix access control, DM and room policy, allowlists, bot-to-bot traffic, context visibility, and command authorization.
Matrix message behavior, streaming previews, inbound voice-note transcription, and reactions.
Matrix rich messages and approvals, structured reply controls, approval event metadata, and exec approval prompts.
Matrix encryption and verification, E2EE setup, device verification, cross-signing repair, room-key backup, and crypto-store layout.
Matrix threads and sessions, session routing, reply threading, ACP conversation bindings, and room history context.
Matrix accounts and homeservers, multi-account layout, private/LAN homeservers, proxies, profiles, direct-room repair, and target resolution.

Where each section moved

Anchor IDs for all section headings from the earlier single-page version are preserved on this page, so links already in use, such as /channels/matrix#streaming-previews, continue to resolve. Each entry links to the page that now carries the content.

Configuration reference

Allowlist user fields (groupAllowFrom, dm.allowFrom, groups.<room>.users) take full Matrix user IDs, which is the safest option. Entries that are not IDs get ignored unless you opt in. When dangerouslyAllowNameMatching: true is enabled, exact matches against Matrix directory display names are resolved at startup and again each time the allowlist is modified while the monitor runs. Any entry that cannot be resolved is skipped at runtime.

Room allowlist keys (groups, plus the legacy rooms) ought to be room IDs or aliases. Keys given as plain room names are ignored unless you opt in; setting dangerouslyAllowNameMatching: true brings back a best-effort lookup against the names of joined rooms.

Account and connection

enabled: turns the channel on or off.
name: an optional label shown for the account.
defaultAccount: the account ID to prefer when more than one Matrix account is configured.
accounts: overrides scoped to a named account. Values set at the top level under channels.matrix are inherited as defaults.
homeserver: the homeserver URL, such as https://matrix.example.org.
network.dangerouslyAllowPrivateNetwork: permits this account to reach localhost, LAN/Tailscale IPs, or internal hostnames.
proxy: an optional HTTP(S) proxy URL applied to Matrix traffic. A per-account override is supported.
userId: the full Matrix user ID (@bot:example.org).
accessToken: an access token for token-based auth. Both plaintext and SecretRef values work across the env/file/exec/store providers (Secrets Management).
password: a password for password-based login. Both plaintext and SecretRef values work.
deviceId: an explicit Matrix device ID.
deviceName: the device display name applied when logging in with a password.
avatarUrl: a stored self-avatar URL used for profile sync and for profile set updates.
initialSyncLimit: the cap on events fetched during the startup sync.

Encryption

encryption: turns E2EE on. Default: false.
startupVerification: either "if-unverified" (the default while E2EE is enabled) or "off". When this device is unverified, self-verification is requested automatically on startup.
startupVerificationCooldownHours: how long to wait before the next automatic startup request. Default: 24.

Access and policy

openclaw config validate reports missing dm.allowFrom entries, covering both account overrides and inherited defaults. In the case of dm.policy: "open", either add "*" to the nested allowlist it points to or run openclaw doctor --fix; in the case of "allowlist", add the Matrix user IDs you intend to allow.

groupPolicy: "open", "allowlist", or "disabled". Default: "allowlist".
groupAllowFrom: user ID allowlist that governs room traffic.
mentionPatterns: regex patterns scoped per room for mentions. An object containing { mode: "allow"|"deny", allowIn: [roomId, ...], denyIn: [roomId, ...] }. Determines whether the configured agents.entries.*.groupChat.mentionPatterns take effect room by room.
dm.enabled: if false, every DM is ignored. Default: true.
dm.policy: "pairing" (default), "allowlist", "open", or "disabled". Takes effect once the bot has joined and classified the room as a DM; invite handling is unaffected.
dm.allowFrom: user ID allowlist that governs DM traffic.
dm.sessionScope: "per-user" (default) or "per-room".
dm.threadReplies: DM-only override for reply threading ("off", "inbound", "always").
allowBots: accept messages sent by other configured Matrix bot accounts (true or "mentions").
allowlistOnly: if true, every active DM policy (except "disabled") and all "open" group policies are forced to "allowlist". "disabled" policies stay as they are.
dangerouslyAllowNameMatching: if true, Matrix display-name directory lookup is allowed for user allowlist entries, and joined-room name lookup is allowed for room allowlist keys. Full @user:server IDs and room IDs or aliases are preferred.
autoJoin: "always", "allowlist", or "off". Default: "off". Every Matrix invite is subject to this, DM-style invites included.
autoJoinAllowlist: the rooms and aliases permitted when autoJoin is "allowlist". Only room IDs, aliases, or * can match; any other entry, such as a user ID (which belongs in dm.allowFrom), is ignored at runtime with a warning. Alias entries are resolved against the homeserver, not against state the invited room claims.
contextVisibility: visibility of supplemental context ("all" by default, "allowlist", "allowlist_quote").

Reply behavior

joinIntro: sets when the bot joins a group room that is allowed. Default: true. Override per account: accounts.<accountId>.joinIntro.
replyToMode: one of "off" (default), "first", "all", or "batched".
threadReplies: "off", "inbound" (default), or "always".
threadBindings: overrides applied per channel for session routing tied to threads and their lifecycle.
streaming: an object with nested { mode, chunkMode, block: { enabled, coalesce }, preview: { toolProgress }, progress: { label, labels, maxLines, maxLineChars, toolProgress } }. mode accepts "off" (default), "partial", "quiet", or "progress". Older scalar and boolean spellings are migrated by openclaw doctor --fix.
streaming.block.enabled: when true is on, each completed assistant block is retained as its own progress message. Default: false.
markdown: optional configuration for rendering Markdown in outbound text.
responsePrefix: an optional string placed at the start of outbound replies.
textChunkLimit: character count for outbound chunks when streaming.chunkMode: "length" applies. Default: 4000.
streaming.chunkMode: either "length" (the default, which splits by character count) or "newline" (which splits at line boundaries).
historyLimit: how many recent room messages are passed along as InboundHistory when a room message triggers the agent. If unset, the value falls back to messages.groupChat.historyLimit; the effective default is 0 (disabled).
mediaMaxMb: cap on media size, in MB, for both outbound sends and inbound processing. Default: 20.

Reaction settings

ackReaction: overrides the ack reaction for this channel or account.
ackReactionScope: overrides the scope ("group-mentions" is the default, plus "group-all", "direct", "all", "none", "off").
reactionNotifications: mode for inbound reaction notifications ("own" is the default, or "off").

Tooling and per-room overrides

actions: tool gating applied per action (messages, reactions, pins, profile, memberInfo, channelInfo, verification).
groups: a policy map keyed by room. Once resolved, session identity relies on the stable room ID. (rooms remains a legacy alias.) Room tool and mention policies are selected by room IDs resolved from the configured keys; a display name arriving inbound can never cause another room's policy to be chosen.
- groups.<room>.account: narrows one inherited room entry so it applies only to a given account.
- groups.<room>.enabled: a toggle that works per room. If set to false, the room is skipped, exactly as though the map did not contain it.
- groups.<room>.requireMention: overrides, for a single room, the mention requirement set at channel level.
- groups.<room>.allowBots: overrides, for a single room, the channel-level setting (true or "mentions").
- groups.<room>.botLoopProtection: overrides, for a single room, the budget that guards against bot-to-bot loops.
- groups.<room>.users: an allowlist of senders for one room.
- groups.<room>.tools: allow/deny overrides for tools, scoped to one room.
- groups.<room>.autoReply: overrides mention gating for one room. Setting true turns off mention requirements in that room; false turns them back on.
- groups.<room>.skills: a skill filter applied to one room.
- groups.<room>.systemPrompt: a system prompt snippet for one room.

Exec approval settings

execApprovals.enabled: exec approvals are delivered as Matrix-native prompts.
execApprovals.approvers: the Matrix user IDs permitted to approve. Defaults to dm.allowFrom when unset.
execApprovals.target: "dm" (default), "channel", or "both".
execApprovals.agentFilter / execApprovals.sessionFilter: optional allowlists of agents/sessions that may receive delivery.

Channels Overview - every channel that is supported
Pairing - how DM authentication and the pairing flow work
Groups - group chat behavior and gating on mentions
Channel routing - how messages are routed to sessions
Security - the access model and hardening