Matrix

Matrix is a downloadable channel plugin (@openclaw/matrix) built on the official matrix-js-sdk. It supports DMs, rooms, threads, media, reactions, polls, location, and E2EE.

Node remains the recommended runtime. Matrix also accepts the opt-in Bun runtime; E2EE requires the Matrix SDK's native crypto bindings to be available for your platform.

openclaw matrix verify status, verify bootstrap, and verify device route through the local Gateway when it is running. Update an older Gateway if it does not support this routing; failed requests are never replayed locally.

Other openclaw matrix commands require the local Gateway to be stopped, including device diagnostics: preparing the account can update its crypto state. Stop the Gateway through its service owner, run the command, then restart it. Commands refuse before loading account state when a Gateway owns the state directory. Offline ownership lasts through crypto persistence and client shutdown.

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

Every section heading from the previous single-page version keeps its anchor here, so an existing link such as /channels/matrix#streaming-previews still resolves. Each entry points at the page that now holds the content.

• Install
• Setup
• Interactive setup
• Minimal config
• Auto-join
• Group join introductions
• Allowlist target formats
• Account ID normalization
• Cached credentials
• Environment variables
• Configuration example
• Streaming previews
• Voice messages
• Reply controls and presentations
• Approval metadata
• Self-hosted push rules for quiet finalized previews
• Bot-to-bot rooms
• Encryption and verification
• Enable encryption
• Status and trust signals
• Verify this device with a recovery key
• Bootstrap or repair cross-signing
• Room-key backup
• Listing, requesting, and responding to verifications
• Multi-account notes
• Profile management
• Threads
• Session routing (sessionScope)
• Reply threading (threadReplies)
• Thread inheritance and slash commands
• ACP conversation bindings
• Thread binding config
• Reactions
• History context
• Context visibility
• DM and room policy
• Direct room repair
• Exec approvals
• Slash commands
• Multi-account
• Private/LAN homeservers
• Proxying Matrix traffic
• Target resolution
• Listing, requesting, and responding to verifications
• Session routing (sessionScope)
• Reply threading (threadReplies)
• Private/LAN homeservers
• Startup behavior
• Verification notices
• Deleted or invalid Matrix device
• Device hygiene
• Crypto store

Configuration reference

Allowlist-style user fields (groupAllowFrom, dm.allowFrom, groups.<room>.users) accept full Matrix user IDs (safest). Non-ID entries are ignored by default. If dangerouslyAllowNameMatching: true is set, exact Matrix directory display-name matches are resolved at startup and whenever the allowlist changes while the monitor is running; unresolvable entries are ignored at runtime.

Room allowlist keys (groups, legacy rooms) should be room IDs or aliases. Plain room-name keys are ignored by default; dangerouslyAllowNameMatching: true restores best-effort lookup against joined room names.

Account and connection

• enabled: enable or disable the channel.
• name: optional display label for the account.
• defaultAccount: preferred account ID when multiple Matrix accounts are configured.
• accounts: named per-account overrides. Top-level channels.matrix values are inherited as defaults.
• homeserver: homeserver URL, for example https://matrix.example.org.
• network.dangerouslyAllowPrivateNetwork: allow this account to connect to localhost, LAN/Tailscale IPs, or internal hostnames.
• proxy: optional HTTP(S) proxy URL for Matrix traffic. Per-account override supported.
• userId: full Matrix user ID (@bot:example.org).
• accessToken: access token for token-based auth. Plaintext and SecretRef values supported across env/file/exec/store providers (Secrets Management).
• password: password for password-based login. Plaintext and SecretRef values supported.
• deviceId: explicit Matrix device ID.
• deviceName: device display name used at password-login time.
• avatarUrl: stored self-avatar URL for profile sync and profile set updates.
• initialSyncLimit: maximum number of events fetched during startup sync.

Encryption

• encryption: enable E2EE. Default: false.
• startupVerification: "if-unverified" (default when E2EE is on) or "off". Auto-requests self-verification on startup when this device is unverified.
• startupVerificationCooldownHours: cooldown before the next automatic startup request. Default: 24.

Access and policy

• groupPolicy: "open", "allowlist", or "disabled". Default: "allowlist".
• groupAllowFrom: allowlist of user IDs for room traffic.
• mentionPatterns: scoped regex patterns for room mentions. Object with { mode: "allow"|"deny", allowIn: [roomId, ...], denyIn: [roomId, ...] }. Controls whether configured agents.entries.*.groupChat.mentionPatterns apply per-room.
• dm.enabled: when false, ignore all DMs. Default: true.
• dm.policy: "pairing" (default), "allowlist", "open", or "disabled". Applies after the bot has joined and classified the room as a DM; it does not affect invite handling.
• dm.allowFrom: allowlist of user IDs for DM traffic.
• dm.sessionScope: "per-user" (default) or "per-room".
• dm.threadReplies: DM-only override for reply threading ("off", "inbound", "always").
• allowBots: accept messages from other configured Matrix bot accounts (true or "mentions").
• allowlistOnly: when true, forces all active DM policies (except "disabled") and "open" group policies to "allowlist". Does not change "disabled" policies.
• dangerouslyAllowNameMatching: when true, allows Matrix display-name directory lookup for user allowlist entries and joined-room name lookup for room allowlist keys. Prefer full @user:server IDs and room IDs or aliases.
• autoJoin: "always", "allowlist", or "off". Default: "off". Applies to every Matrix invite, including DM-style invites.
• autoJoinAllowlist: rooms/aliases allowed when autoJoin is "allowlist". Only room IDs, aliases, or * can match; the runtime warns about and ignores other entries (for example a user ID, which belongs in dm.allowFrom). Alias entries resolve against the homeserver, not against state claimed by the invited room.
• contextVisibility: supplemental context visibility ("all" default, "allowlist", "allowlist_quote").

Reply behavior

• joinIntro: introduce when the bot joins an allowed group room. Default: true. Per-account override: accounts.<accountId>.joinIntro.
• replyToMode: "off" (default), "first", "all", or "batched".
• threadReplies: "off", "inbound" (default), or "always".
• threadBindings: per-channel overrides for thread-bound session routing and lifecycle.
• streaming: nested object { mode, chunkMode, block: { enabled, coalesce }, preview: { toolProgress }, progress: { label, labels, maxLines, maxLineChars, toolProgress } }. mode is "off" (default), "partial", "quiet", or "progress". Legacy scalar/boolean spellings migrate via openclaw doctor --fix.
• streaming.block.enabled: when true, completed assistant blocks are kept as separate progress messages. Default: false.
• markdown: optional Markdown rendering config for outbound text.
• responsePrefix: optional string prepended to outbound replies.
• textChunkLimit: outbound chunk size in characters when streaming.chunkMode: "length". Default: 4000.
• streaming.chunkMode: "length" (default, splits by character count) or "newline" (splits at line boundaries).
• historyLimit: number of recent room messages included as InboundHistory when a room message triggers the agent. Falls back to messages.groupChat.historyLimit; effective default 0 (disabled).
• mediaMaxMb: media size cap in MB for outbound sends and inbound processing. Default: 20.

Reaction settings

• ackReaction: ack reaction override for this channel/account.
• ackReactionScope: scope override ("group-mentions" default, "group-all", "direct", "all", "none", "off").
• reactionNotifications: inbound reaction notification mode ("own" default, "off").

Tooling and per-room overrides

• actions: per-action tool gating (messages, reactions, pins, profile, memberInfo, channelInfo, verification).
• groups: per-room policy map. Session identity uses the stable room ID after resolution. (rooms is a legacy alias.)
  • groups.<room>.account: restrict one inherited room entry to a specific account.
  • groups.<room>.enabled: per-room toggle. When false, the room is ignored as if it were not in the map.
  • groups.<room>.requireMention: per-room override of the channel-level mention requirement.
  • groups.<room>.allowBots: per-room override of the channel-level setting (true or "mentions").
  • groups.<room>.botLoopProtection: per-room override for bot-to-bot loop protection budget.
  • groups.<room>.users: per-room sender allowlist.
  • groups.<room>.tools: per-room tool allow/deny overrides.
  • groups.<room>.autoReply: per-room mention-gating override. true disables mention requirements for that room; false forces them back on.
  • groups.<room>.skills: per-room skill filter.
  • groups.<room>.systemPrompt: per-room system prompt snippet.

Exec approval settings

• execApprovals.enabled: deliver exec approvals through Matrix-native prompts.
• execApprovals.approvers: Matrix user IDs allowed to approve. Falls back to dm.allowFrom.
• execApprovals.target: "dm" (default), "channel", or "both".
• execApprovals.agentFilter / execApprovals.sessionFilter: optional agent/session allowlists for delivery.

Related

• Channels Overview - all supported channels
• Pairing - DM authentication and pairing flow
• Groups - group chat behavior and mention gating
• Channel routing - session routing for messages
• Security - access model and hardening