warning

Set `autoJoin: "allowlist"` plus `autoJoinAllowlist` to restrict which invites the bot accepts, or `autoJoin: "always"` to accept every invite.

only accepts stable targets: , , or . Plain room names are rejected; alias entries are resolved against the homeserver, not against state claimed by the invited room.

json5
Copy
{
  channels: {
    matrix: {
      autoJoin: "allowlist",
      autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],
      groups: {
        "!ops:example.org": { requireMention: true },
      },
    },
  },
}

To accept every invite, use

.

Allowlist target formats

DM and room allowlists are best populated with stable IDs:

• DMs (
  text

  Copy

  dm.allowFrom
  ,
  text

  Copy

  groupAllowFrom
  ,
  text

  Copy

  groups.<room>.users
  ): use
  text

  Copy

  @user:server
  . Display names only resolve when the homeserver directory returns exactly one match.
• Rooms (
  text

  Copy

  groups
  ,
  text

  Copy

  autoJoinAllowlist
  ): use
  text

  Copy

  !room:server
  or
  text

  Copy

  #alias:server
  . Names are resolved best-effort against joined rooms; unresolved entries are ignored at runtime.

Account ID normalization

The wizard converts a friendly name into a normalized account ID. For example,

becomes . Punctuation is escaped in scoped env-var names so that two accounts cannot collide: → , so maps to .

Cached credentials

Matrix stores cached credentials under

:

• default account:
  text

  Copy

  credentials.json
• named accounts:
  text

  Copy

  credentials-<account>.json

When cached credentials exist there, OpenClaw treats Matrix as configured even if the access token is not in the config file — that covers setup,

, and channel-status probes.

Environment variables

Used when the equivalent config key is not set. The default account uses unprefixed names; named accounts use the account ID inserted before the suffix.

For account

, the names become , , and so on. The recovery-key env vars are read by recovery-aware CLI flows (, , ) when you pipe the key in via .

cannot be set from a workspace ; see Workspace

text

Copy

.env

files.

Configuration example

A practical baseline with DM pairing, room allowlist, and E2EE:

json5
Copy
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,

      dm: {
        policy: "pairing",
        sessionScope: "per-room",
        threadReplies: "off",
      },

      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": { requireMention: true },
      },

      autoJoin: "allowlist",
      autoJoinAllowlist: ["!roomid:example.org"],
      threadReplies: "inbound",
      replyToMode: "off",
      streaming: "partial",
    },
  },
}

Streaming previews

Matrix reply streaming is opt-in.

controls how OpenClaw delivers the in-flight assistant reply; controls whether each completed block is preserved as its own Matrix message.

json5
Copy
{
  channels: {
    matrix: {
      streaming: "partial",
    },
  },
}

To keep live answer previews but hide interim tool/progress lines, use object form:

json5
Copy
{
  channels: {
    matrix: {
      streaming: {
        mode: "partial",
        preview: {
          toolProgress: false,
        },
      },
    },
  },
}

is independent of :

Notes:

• If a preview grows past Matrix's per-event size limit, OpenClaw stops preview streaming and falls back to final-only delivery.
• Media replies always send attachments normally. If a stale preview can no longer be reused safely, OpenClaw redacts it before sending the final media reply.
• Tool-progress preview updates are enabled by default when Matrix preview streaming is active. Set
  text

  Copy

  streaming.preview.toolProgress: false
  to keep preview edits for answer text but leave tool progress on the normal delivery path.
• Preview edits cost extra Matrix API calls. Leave
  text

  Copy

  streaming: "off"
  if you want the most conservative rate-limit profile.

Approval metadata

Matrix native approval prompts are normal

events with OpenClaw-specific custom event content under . Matrix permits custom event-content keys, so stock clients still render the text body while OpenClaw-aware clients can read the structured approval id, kind, state, available decisions, and exec/plugin details.

When an approval prompt is too long for one Matrix event, OpenClaw chunks the visible text and attaches

to the first chunk only. Reactions for allow/deny decisions are bound to that first event, so long prompts keep the same approval target as single-event prompts.

Self-hosted push rules for quiet finalized previews

only notifies recipients once a block or turn is finalized — a per-user push rule has to match the finalized preview marker. See Matrix push rules for quiet previews for the full recipe (recipient token, pusher check, rule install, per-homeserver notes).

Bot-to-bot rooms

By default, Matrix messages from other configured OpenClaw Matrix accounts are ignored.

Use

when you intentionally want inter-agent Matrix traffic:

json5
Copy
{
  channels: {
    matrix: {
      allowBots: "mentions", // true | "mentions"
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

• text

  Copy

  allowBots: true
  accepts messages from other configured Matrix bot accounts in allowed rooms and DMs.
• text

  Copy

  allowBots: "mentions"
  accepts those messages only when they visibly mention this bot in rooms. DMs are still allowed.
• text

  Copy

  groups.<room>.allowBots
  overrides the account-level setting for one room.
• OpenClaw still ignores messages from the same Matrix user ID to avoid self-reply loops.
• Matrix does not expose a native bot flag here; OpenClaw treats "bot-authored" as "sent by another configured Matrix account on this OpenClaw gateway".

Use strict room allowlists and mention requirements when enabling bot-to-bot traffic in shared rooms.

Encryption and verification

In encrypted (E2EE) rooms, outbound image events use

so image previews are encrypted alongside the full attachment. Unencrypted rooms still use plain . No configuration is needed — the plugin detects E2EE state automatically.

All

commands accept (full diagnostics), (machine-readable output), and (multi-account setups). Output is concise by default with quiet internal SDK logging. The examples below show the canonical form; add the flags as needed.

Enable encryption

bash
Copy
openclaw matrix encryption setup

Bootstraps secret storage and cross-signing, creates a room-key backup if needed, then prints status and next steps. Useful flags:

• text

  Copy

  --recovery-key <key>
  apply a recovery key before bootstrapping (prefer the stdin form documented below)
• text

  Copy

  --force-reset-cross-signing
  discard the current cross-signing identity and create a new one (use only intentionally)

For a new account, enable E2EE at creation time:

bash
Copy
openclaw matrix account add \
  --homeserver https://matrix.example.org \
  --access-token syt_xxx \
  --enable-e2ee

is an alias for .

Manual config equivalent:

json5
Copy
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,
      dm: { policy: "pairing" },
    },
  },
}

Status and trust signals

bash
Copy
openclaw matrix verify status
openclaw matrix verify status --include-recovery-key --json

reports three independent trust signals ( shows all of them):

• text

  Copy

  Locally trusted
  : trusted by this client only
• text

  Copy

  Cross-signing verified
  : the SDK reports verification via cross-signing
• text

  Copy

  Signed by owner
  : signed by your own self-signing key (diagnostic only)

becomes only when is . Local trust or an owner signature alone is not enough.

returns best-effort diagnostics without preparing the Matrix account first; useful for offline or partially-configured probes.

Verify this device with a recovery key

The recovery key is sensitive — pipe it via stdin instead of passing it on the command line. Set

(or for a named account):

bash
Copy
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin

The command reports three states:

• text

  Copy

  Recovery key accepted
  : Matrix accepted the key for secret storage or device trust.
• text

  Copy

  Backup usable
  : room-key backup can be loaded with the trusted recovery material.
• text

  Copy

  Device verified by owner
  : this device has full Matrix cross-signing identity trust.

It exits non-zero when full identity trust is incomplete, even if the recovery key unlocked backup material. In that case, finish self-verification from another Matrix client:

bash
Copy
openclaw matrix verify self

waits for before it exits successfully. Use to tune the wait.

The literal-key form

is also accepted, but the key ends up in your shell history.

Bootstrap or repair cross-signing

bash
Copy
openclaw matrix verify bootstrap

is the repair and setup command for encrypted accounts. In order, it:

• bootstraps secret storage, reusing an existing recovery key when possible
• bootstraps cross-signing and uploads missing public keys
• marks and cross-signs the current device
• creates a server-side room-key backup if one does not already exist

If the homeserver requires UIA to upload cross-signing keys, OpenClaw tries no-auth first, then

, then (requires ).

Useful flags:

• text

  Copy

  --recovery-key-stdin
  (pair with
  text

  Copy

  printf '%s\n' "$MATRIX_RECOVERY_KEY" | …
  ) or
  text

  Copy

  --recovery-key <key>
• text

  Copy

  --force-reset-cross-signing
  to discard the current cross-signing identity (intentional only)

Room-key backup

bash
Copy
openclaw matrix verify backup status
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin

shows whether a server-side backup exists and whether this device can decrypt it. imports backed-up room keys into the local crypto store; if the recovery key is already on disk you can omit .

To replace a broken backup with a fresh baseline (accepts losing unrecoverable old history; can also recreate secret storage if the current backup secret is unloadable):

bash
Copy
openclaw matrix verify backup reset --yes

Add

only when you intentionally want the previous recovery key to stop unlocking the fresh backup baseline.

Listing, requesting, and responding to verifications

bash
Copy
openclaw matrix verify list

Lists pending verification requests for the selected account.

bash
Copy
openclaw matrix verify request --own-user
openclaw matrix verify request --user-id @ops:example.org --device-id ABCDEF

Sends a verification request from this OpenClaw account.

requests self-verification (you accept the prompt in another Matrix client of the same user); // target someone else. cannot be combined with the other targeting flags.

For lower-level lifecycle handling — typically while shadowing inbound requests from another client — these commands act on a specific request

(printed by and ):

, , , , , and all accept and as DM follow-up hints when the verification is anchored to a specific direct-message room.

Multi-account notes

Without

, Matrix CLI commands use the implicit default account. If you have multiple named accounts and have not set , they will refuse to guess and ask you to choose. When E2EE is disabled or unavailable for a named account, errors point at that account's config key, for example .

Startup behavior

Verification notices

Deleted or invalid Matrix device

Device hygiene

Crypto store

Profile management

Update the Matrix self-profile for the selected account:

bash
Copy
openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png

You can pass both options in one call. Matrix accepts

avatar URLs directly; when you pass or , OpenClaw uploads the file first and stores the resolved URL into (or the per-account override).

Threads

Matrix supports native Matrix threads for both automatic replies and message-tool sends. Two independent knobs control behavior:

Session routing (

text

Copy

sessionScope

)

decides how Matrix DM rooms map to OpenClaw sessions:

• text

  Copy

  "per-user"
  (default): all DM rooms with the same routed peer share one session.
• text

  Copy

  "per-room"
  : each Matrix DM room gets its own session key, even when the peer is the same.

Explicit conversation bindings always win over

, so bound rooms and threads keep their chosen target session.

Reply threading (

text

Copy

threadReplies

)

decides where the bot posts its reply:

• text

  Copy

  "off"
  : replies are top-level. Inbound threaded messages stay on the parent session.
• text

  Copy

  "inbound"
  : reply inside a thread only when the inbound message was already in that thread.
• text

  Copy

  "always"
  : reply inside a thread rooted at the triggering message; that conversation is routed through a matching thread-scoped session from the first trigger onward.

overrides this for DMs only — for example, keep room threads isolated while keeping DMs flat.

Thread inheritance and slash commands

• Inbound threaded messages include the thread root message as extra agent context.
• Message-tool sends auto-inherit the current Matrix thread when targeting the same room (or the same DM user target), unless an explicit
  text

  Copy

  threadId
  is provided.
• DM user-target reuse only kicks in when the current session metadata proves the same DM peer on the same Matrix account; otherwise OpenClaw falls back to normal user-scoped routing.
• text

  Copy

  /focus
  ,
  text

  Copy

  /unfocus
  ,
  text

  Copy

  /agents
  ,
  text

  Copy

  /session idle
  ,
  text

  Copy

  /session max-age
  , and thread-bound
  text

  Copy

  /acp spawn
  all work in Matrix rooms and DMs.
• Top-level
  text

  Copy

  /focus
  creates a new Matrix thread and binds it to the target session when
  text

  Copy

  threadBindings.spawnSubagentSessions: true
  .
• Running
  text

  Copy

  /focus
  or
  text

  Copy

  /acp spawn --thread here
  inside an existing Matrix thread binds that thread in place.

When OpenClaw detects a Matrix DM room colliding with another DM room on the same shared session, it posts a one-time

in that room pointing to the escape hatch and suggesting a change. The notice only appears when thread bindings are enabled.

ACP conversation bindings

Matrix rooms, DMs, and existing Matrix threads can be turned into durable ACP workspaces without changing the chat surface.

Fast operator flow:

• Run
  text

  Copy

  /acp spawn codex --bind here
  inside the Matrix DM, room, or existing thread you want to keep using.
• In a top-level Matrix DM or room, the current DM/room stays the chat surface and future messages route to the spawned ACP session.
• Inside an existing Matrix thread,
  text

  Copy

  --bind here
  binds that current thread in place.
• text

  Copy

  /new
  and
  text

  Copy

  /reset
  reset the same bound ACP session in place.
• text

  Copy

  /acp close
  closes the ACP session and removes the binding.

Notes:

• text

  Copy

  --bind here
  does not create a child Matrix thread.
• text

  Copy

  threadBindings.spawnAcpSessions
  is only required for
  text

  Copy

  /acp spawn --thread auto|here
  , where OpenClaw needs to create or bind a child Matrix thread.

Thread binding config

Matrix inherits global defaults from

, and also supports per-channel overrides:

• text

  Copy

  threadBindings.enabled
• text

  Copy

  threadBindings.idleHours
• text

  Copy

  threadBindings.maxAgeHours
• text

  Copy

  threadBindings.spawnSubagentSessions
• text

  Copy

  threadBindings.spawnAcpSessions

Matrix thread-bound spawn flags are opt-in:

• Set
  text

  Copy

  threadBindings.spawnSubagentSessions: true
  to allow top-level
  text

  Copy

  /focus
  to create and bind new Matrix threads.
• Set
  text

  Copy

  threadBindings.spawnAcpSessions: true
  to allow
  text

  Copy

  /acp spawn --thread auto|here
  to bind ACP sessions to Matrix threads.

Reactions

Matrix supports outbound reactions, inbound reaction notifications, and ack reactions.

Outbound reaction tooling is gated by

:

• text

  Copy

  react
  adds a reaction to a Matrix event.
• text

  Copy

  reactions
  lists the current reaction summary for a Matrix event.
• text

  Copy

  emoji=""
  removes the bot's own reactions on that event.
• text

  Copy

  remove: true
  removes only the specified emoji reaction from the bot.

Resolution order (first defined value wins):

forwards added events when they target bot-authored Matrix messages; disables reaction system events. Reaction removals are not synthesized into system events because Matrix surfaces those as redactions, not as standalone removals.

History context

• text

  Copy

  channels.matrix.historyLimit
  controls how many recent room messages are included as
  text

  Copy

  InboundHistory
  when a Matrix room message triggers the agent. Falls back to
  text

  Copy

  messages.groupChat.historyLimit
  ; if both are unset, the effective default is
  text

  Copy

  0
  . Set
  text

  Copy

  0
  to disable.
• Matrix room history is room-only. DMs keep using normal session history.
• Matrix room history is pending-only: OpenClaw buffers room messages that did not trigger a reply yet, then snapshots that window when a mention or other trigger arrives.
• The current trigger message is not included in
  text

  Copy

  InboundHistory
  ; it stays in the main inbound body for that turn.
• Retries of the same Matrix event reuse the original history snapshot instead of drifting forward to newer room messages.

Context visibility

Matrix supports the shared

control for supplemental room context such as fetched reply text, thread roots, and pending history.

• text

  Copy

  contextVisibility: "all"
  is the default. Supplemental context is kept as received.
• text

  Copy

  contextVisibility: "allowlist"
  filters supplemental context to senders allowed by the active room/user allowlist checks.
• text

  Copy

  contextVisibility: "allowlist_quote"
  behaves like
  text

  Copy

  allowlist
  , but still keeps one explicit quoted reply.

This setting affects supplemental context visibility, not whether the inbound message itself can trigger a reply. Trigger authorization still comes from

, , , and DM policy settings.

DM and room policy

json5
Copy
{
  channels: {
    matrix: {
      dm: {
        policy: "allowlist",
        allowFrom: ["@admin:example.org"],
        threadReplies: "off",
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": { requireMention: true },
      },
    },
  },
}

To silence DMs entirely while keeping rooms working, set

:

json5
Copy
{
  channels: {
    matrix: {
      dm: { enabled: false },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
    },
  },
}

See Groups for mention-gating and allowlist behavior.

Pairing example for Matrix DMs:

bash
Copy
openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

If an unapproved Matrix user keeps messaging you before approval, OpenClaw reuses the same pending pairing code and may send a reminder reply after a short cooldown instead of minting a new code.

See Pairing for the shared DM pairing flow and storage layout.

Direct room repair

If direct-message state drifts out of sync, OpenClaw can end up with stale

mappings that point at old solo rooms instead of the live DM. Inspect the current mapping for a peer:

bash
Copy
openclaw matrix direct inspect --user-id @alice:example.org

Repair it:

bash
Copy
openclaw matrix direct repair --user-id @alice:example.org

Both commands accept

for multi-account setups. The repair flow:

• prefers a strict 1:1 DM that is already mapped in
  text

  Copy

  m.direct
• falls back to any currently joined strict 1:1 DM with that user
• creates a fresh direct room and rewrites
  text

  Copy

  m.direct
  if no healthy DM exists

It does not delete old rooms automatically. It picks the healthy DM and updates the mapping so future Matrix sends, verification notices, and other direct-message flows target the right room.

Exec approvals

Matrix can act as a native approval client. Configure under

(or for a per-account override):

• text

  Copy

  enabled
  : deliver approvals through Matrix-native prompts. When unset or
  text

  Copy

  "auto"
  , Matrix auto-enables once at least one approver can be resolved. Set
  text

  Copy

  false
  to disable explicitly.
• text

  Copy

  approvers
  : Matrix user IDs (
  text

  Copy

  @owner:example.org
  ) allowed to approve exec requests. Optional — falls back to
  text

  Copy

  channels.matrix.dm.allowFrom
  .
• text

  Copy

  target
  : where prompts go.
  text

  Copy

  "dm"
  (default) sends to approver DMs;
  text

  Copy

  "channel"
  sends to the originating Matrix room or DM;
  text

  Copy

  "both"
  sends to both.
• text

  Copy

  agentFilter
  /
  text

  Copy

  sessionFilter
  : optional allowlists for which agents/sessions trigger Matrix delivery.

Authorization differs slightly between approval kinds:

• Exec approvals use
  text

  Copy

  execApprovals.approvers
  , falling back to
  text

  Copy

  dm.allowFrom
  .
• Plugin approvals authorize through
  text

  Copy

  dm.allowFrom
  only.

Both kinds share Matrix reaction shortcuts and message updates. Approvers see reaction shortcuts on the primary approval message:

• text

  Copy

  ✅
  allow once
• text

  Copy

  ❌
  deny
• text

  Copy

  ♾️
  allow always (when the effective exec policy allows it)

Fallback slash commands:

, , .

Only resolved approvers can approve or deny. Channel delivery for exec approvals includes the command text — only enable

or in trusted rooms.

Related: Exec approvals.

Slash commands

Slash commands (

, , , , , , , , , etc.) work directly in DMs. In rooms, OpenClaw also recognizes commands that are prefixed with the bot's own Matrix mention, so triggers the command path without a custom mention regex. This keeps the bot responsive to the room-style posts that Element and similar clients emit when a user tab-completes the bot before typing the command.

Authorization rules still apply: command senders must satisfy the same DM or room allowlist/owner policies as plain messages.

Multi-account

json5
Copy
{
  channels: {
    matrix: {
      enabled: true,
      defaultAccount: "assistant",
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_xxx",
          encryption: true,
        },
        alerts: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_xxx",
          dm: {
            policy: "allowlist",
            allowFrom: ["@ops:example.org"],
            threadReplies: "off",
          },
        },
      },
    },
  },
}

Inheritance:

• Top-level
  text

  Copy

  channels.matrix
  values act as defaults for named accounts unless an account overrides them.
• Scope an inherited room entry to a specific account with
  text

  Copy

  groups.<room>.account
  . Entries without
  text

  Copy

  account
  are shared across accounts;
  text

  Copy

  account: "default"
  still works when the default account is configured at the top level.

Default account selection:

• Set
  text

  Copy

  defaultAccount
  to pick the named account that implicit routing, probing, and CLI commands prefer.
• If you have multiple accounts and one is literally named
  text

  Copy

  default
  , OpenClaw uses it implicitly even when
  text

  Copy

  defaultAccount
  is unset.
• If you have multiple named accounts and no default is selected, CLI commands refuse to guess — set
  text

  Copy

  defaultAccount
  or pass
  text

  Copy

  --account <id>
  .
• The top-level
  text

  Copy

  channels.matrix.*
  block is only treated as the implicit
  text

  Copy

  default
  account when its auth is complete (
  text

  Copy

  homeserver
  +
  text

  Copy

  accessToken
  , or
  text

  Copy

  homeserver
  +
  text

  Copy

  userId
  +
  text

  Copy

  password
  ). Named accounts remain discoverable from
  text

  Copy

  homeserver
  +
  text

  Copy

  userId
  once cached credentials cover auth.

Promotion:

• When OpenClaw promotes a single-account config to multi-account during repair or setup, it preserves the existing named account if one exists or
  text

  Copy

  defaultAccount
  already points at one. Only Matrix auth/bootstrap keys move into the promoted account; shared delivery-policy keys stay at the top level.

See Configuration reference for the shared multi-account pattern.

Private/LAN homeservers

By default, OpenClaw blocks private/internal Matrix homeservers for SSRF protection unless you explicitly opt in per account.

If your homeserver runs on localhost, a LAN/Tailscale IP, or an internal hostname, enable

for that Matrix account:

json5
Copy
{
  channels: {
    matrix: {
      homeserver: "http://matrix-synapse:8008",
      network: {
        dangerouslyAllowPrivateNetwork: true,
      },
      accessToken: "syt_internal_xxx",
    },
  },
}

CLI setup example:

bash
Copy
openclaw matrix account add \
  --account ops \
  --homeserver http://matrix-synapse:8008 \
  --allow-private-network \
  --access-token syt_ops_xxx

This opt-in only allows trusted private/internal targets. Public cleartext homeservers such as

remain blocked. Prefer whenever possible.

Proxying Matrix traffic

If your Matrix deployment needs an explicit outbound HTTP(S) proxy, set

:

json5
Copy
{
  channels: {
    matrix: {
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
    },
  },
}

Named accounts can override the top-level default with

. OpenClaw uses the same proxy setting for runtime Matrix traffic and account status probes.

Target resolution

Matrix accepts these target forms anywhere OpenClaw asks you for a room or user target:

• Users:
  text

  Copy

  @user:server
  ,
  text

  Copy

  user:@user:server
  , or
  text

  Copy

  matrix:user:@user:server
• Rooms:
  text

  Copy

  !room:server
  ,
  text

  Copy

  room:!room:server
  , or
  text

  Copy

  matrix:room:!room:server
• Aliases:
  text

  Copy

  #alias:server
  ,
  text

  Copy

  channel:#alias:server
  , or
  text

  Copy

  matrix:channel:#alias:server

Matrix room IDs are case-sensitive. Use the exact room ID casing from Matrix when configuring explicit delivery targets, cron jobs, bindings, or allowlists. OpenClaw keeps internal session keys canonical for storage, so those lowercase keys are not a reliable source for Matrix delivery IDs.

Live directory lookup uses the logged-in Matrix account:

• User lookups query the Matrix user directory on that homeserver.
• Room lookups accept explicit room IDs and aliases directly, then fall back to searching joined room names for that account.
• Joined-room name lookup is best-effort. If a room name cannot be resolved to an ID or alias, it is ignored by runtime allowlist resolution.

Configuration reference

Allowlist-style fields (

, , ) accept full Matrix user IDs (safest). Exact directory matches are resolved at startup and whenever the allowlist changes while the monitor is running; entries that cannot be resolved are ignored at runtime. Room allowlists prefer room IDs or aliases for the same reason.

Account and connection

• text

  Copy

  enabled
  : enable or disable the channel.
• text

  Copy

  name
  : optional display label for the account.
• text

  Copy

  defaultAccount
  : preferred account ID when multiple Matrix accounts are configured.
• text

  Copy

  accounts
  : named per-account overrides. Top-level
  text

  Copy

  channels.matrix
  values are inherited as defaults.
• text

  Copy

  homeserver
  : homeserver URL, for example
  text

  Copy

  https://matrix.example.org
  .
• text

  Copy

  network.dangerouslyAllowPrivateNetwork
  : allow this account to connect to
  text

  Copy

  localhost
  , LAN/Tailscale IPs, or internal hostnames.
• text

  Copy

  proxy
  : optional HTTP(S) proxy URL for Matrix traffic. Per-account override supported.
• text

  Copy

  userId
  : full Matrix user ID (
  text

  Copy

  @bot:example.org
  ).
• text

  Copy

  accessToken
  : access token for token-based auth. Plaintext and SecretRef values supported across env/file/exec providers (Secrets Management).
• text

  Copy

  password
  : password for password-based login. Plaintext and SecretRef values supported.
• text

  Copy

  deviceId
  : explicit Matrix device ID.
• text

  Copy

  deviceName
  : device display name used at password-login time.
• text

  Copy

  avatarUrl
  : stored self-avatar URL for profile sync and
  text

  Copy

  profile set
  updates.
• text

  Copy

  initialSyncLimit
  : maximum number of events fetched during startup sync.

Encryption

• text

  Copy

  encryption
  : enable E2EE. Default:
  text

  Copy

  false
  .
• text

  Copy

  startupVerification
  :
  text

  Copy

  "if-unverified"
  (default when E2EE is on) or
  text

  Copy

  "off"
  . Auto-requests self-verification on startup when this device is unverified.
• text

  Copy

  startupVerificationCooldownHours
  : cooldown before the next automatic startup request. Default:
  text

  Copy

  24
  .

Access and policy

• text

  Copy

  groupPolicy
  :
  text

  Copy

  "open"
  ,
  text

  Copy

  "allowlist"
  , or
  text

  Copy

  "disabled"
  . Default:
  text

  Copy

  "allowlist"
  .
• text

  Copy

  groupAllowFrom
  : allowlist of user IDs for room traffic.
• text

  Copy

  dm.enabled
  : when
  text

  Copy

  false
  , ignore all DMs. Default:
  text

  Copy

  true
  .
• text

  Copy

  dm.policy
  :
  text

  Copy

  "pairing"
  (default),
  text

  Copy

  "allowlist"
  ,
  text

  Copy

  "open"
  , or
  text

  Copy

  "disabled"
  . Applies after the bot has joined and classified the room as a DM; it does not affect invite handling.
• text

  Copy

  dm.allowFrom
  : allowlist of user IDs for DM traffic.
• text

  Copy

  dm.sessionScope
  :
  text

  Copy

  "per-user"
  (default) or
  text

  Copy

  "per-room"
  .
• text

  Copy

  dm.threadReplies
  : DM-only override for reply threading (
  text

  Copy

  "off"
  ,
  text

  Copy

  "inbound"
  ,
  text

  Copy

  "always"
  ).
• text

  Copy

  allowBots
  : accept messages from other configured Matrix bot accounts (
  text

  Copy

  true
  or
  text

  Copy

  "mentions"
  ).
• text

  Copy

  allowlistOnly
  : when
  text

  Copy

  true
  , forces all active DM policies (except
  text

  Copy

  "disabled"
  ) and
  text

  Copy

  "open"
  group policies to
  text

  Copy

  "allowlist"
  . Does not change
  text

  Copy

  "disabled"
  policies.
• text

  Copy

  autoJoin
  :
  text

  Copy

  "always"
  ,
  text

  Copy

  "allowlist"
  , or
  text

  Copy

  "off"
  . Default:
  text

  Copy

  "off"
  . Applies to every Matrix invite, including DM-style invites.
• text

  Copy

  autoJoinAllowlist
  : rooms/aliases allowed when
  text

  Copy

  autoJoin
  is
  text

  Copy

  "allowlist"
  . Alias entries are resolved against the homeserver, not against state claimed by the invited room.
• text

  Copy

  contextVisibility
  : supplemental context visibility (
  text

  Copy

  "all"
  default,
  text

  Copy

  "allowlist"
  ,
  text

  Copy

  "allowlist_quote"
  ).

Reply behavior

• text

  Copy

  replyToMode
  :
  text

  Copy

  "off"
  ,
  text

  Copy

  "first"
  ,
  text

  Copy

  "all"
  , or
  text

  Copy

  "batched"
  .
• text

  Copy

  threadReplies
  :
  text

  Copy

  "off"
  ,
  text

  Copy

  "inbound"
  , or
  text

  Copy

  "always"
  .
• text

  Copy

  threadBindings
  : per-channel overrides for thread-bound session routing and lifecycle.
• text

  Copy

  streaming
  :
  text

  Copy

  "off"
  (default),
  text

  Copy

  "partial"
  ,
  text

  Copy

  "quiet"
  , or object form
  text

  Copy

  { mode, preview: { toolProgress } }
  .
  text

  Copy

  true
  ↔
  text

  Copy

  "partial"
  ,
  text

  Copy

  false
  ↔
  text

  Copy

  "off"
  .
• text

  Copy

  blockStreaming
  : when
  text

  Copy

  true
  , completed assistant blocks are kept as separate progress messages.
• text

  Copy

  markdown
  : optional Markdown rendering config for outbound text.
• text

  Copy

  responsePrefix
  : optional string prepended to outbound replies.
• text

  Copy

  textChunkLimit
  : outbound chunk size in characters when
  text

  Copy

  chunkMode: "length"
  . Default:
  text

  Copy

  4000
  .
• text

  Copy

  chunkMode
  :
  text

  Copy

  "length"
  (default, splits by character count) or
  text

  Copy

  "newline"
  (splits at line boundaries).
• text

  Copy

  historyLimit
  : number of recent room messages included as
  text

  Copy

  InboundHistory
  when a room message triggers the agent. Falls back to
  text

  Copy

  messages.groupChat.historyLimit
  ; effective default
  text

  Copy

  0
  (disabled).
• text

  Copy

  mediaMaxMb
  : media size cap in MB for outbound sends and inbound processing.

Reaction settings

• text

  Copy

  ackReaction
  : ack reaction override for this channel/account.
• text

  Copy

  ackReactionScope
  : scope override (
  text

  Copy

  "group-mentions"
  default,
  text

  Copy

  "group-all"
  ,
  text

  Copy

  "direct"
  ,
  text

  Copy

  "all"
  ,
  text

  Copy

  "none"
  ,
  text

  Copy

  "off"
  ).
• text

  Copy

  reactionNotifications
  : inbound reaction notification mode (
  text

  Copy

  "own"
  default,
  text

  Copy

  "off"
  ).

Tooling and per-room overrides

• text

  Copy

  actions
  : per-action tool gating (
  text

  Copy

  messages
  ,
  text

  Copy

  reactions
  ,
  text

  Copy

  pins
  ,
  text

  Copy

  profile
  ,
  text

  Copy

  memberInfo
  ,
  text

  Copy

  channelInfo
  ,
  text

  Copy

  verification
  ).
• text

  Copy

  groups
  : per-room policy map. Session identity uses the stable room ID after resolution. (
  text

  Copy

  rooms
  is a legacy alias.)
  • text

    Copy

    groups.<room>.account
    : restrict one inherited room entry to a specific account.
  • text

    Copy

    groups.<room>.allowBots
    : per-room override of the channel-level setting (
    text

    Copy

    true
    or
    text

    Copy

    "mentions"
    ).
  • text

    Copy

    groups.<room>.users
    : per-room sender allowlist.
  • text

    Copy

    groups.<room>.tools
    : per-room tool allow/deny overrides.
  • text

    Copy

    groups.<room>.autoReply
    : per-room mention-gating override.
    text

    Copy

    true
    disables mention requirements for that room;
    text

    Copy

    false
    forces them back on.
  • text

    Copy

    groups.<room>.skills
    : per-room skill filter.
  • text

    Copy

    groups.<room>.systemPrompt
    : per-room system prompt snippet.

Exec approval settings

• text

  Copy

  execApprovals.enabled
  : deliver exec approvals through Matrix-native prompts.
• text

  Copy

  execApprovals.approvers
  : Matrix user IDs allowed to approve. Falls back to
  text

  Copy

  dm.allowFrom
  .
• text

  Copy

  execApprovals.target
  :
  text

  Copy

  "dm"
  (default),
  text

  Copy

  "channel"
  , or
  text

  Copy

  "both"
  .
• text

  Copy

  execApprovals.agentFilter
  /
  text

  Copy

  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