OpenClaw Matrix threads and sessions

Matrix supports native threads, and OpenClaw treats threading and session routing as two independent decisions: where a reply is posted, and which session a conversation belongs to. Add ACP bindings that turn a room or thread into a durable coding workspace and a room-history window that only carries what the agent has not yet seen, and you have the full picture. Here are the two knobs, inheritance and commands, ACP bindings and their config, and the history rules.

The two knobs

• The DM session scope decides how DM rooms map to sessions: per user, the default, shares one session across every DM room with the same routed peer, while per room gives each Matrix DM room its own session key even for the same peer.
• Reply threading decides where the bot posts: off keeps replies top-level and inbound threaded messages on the parent session, inbound replies inside a thread only when the inbound message was already in it, and always replies inside a thread rooted at the triggering message and routes that conversation through a thread-scoped session from the first trigger; a DM-only override can keep DMs flat while room threads stay isolated.
• Selecting a reply target inside a thread preserves both the thread and the selected message, and the reply metadata older clients receive on threaded messages is not treated as a quoted message in the agent’s context.
• Inbound threaded messages include the thread root as extra context, message-tool sends auto-inherit the current thread when targeting the same room or the same DM user unless a thread id is given, DM user-target reuse only applies when session metadata proves the same peer on the same account, and the session unbind, agents, idle and max-age commands plus thread-bound ACP spawns all work in Matrix rooms and DMs.

Explicit conversation bindings always win over sessionScope; bound rooms and threads keep their chosen target session.

ACP bindings

Matrix rooms, DMs and existing threads can become durable ACP workspaces without changing the chat surface. The operator flow is one command: an ACP spawn with a bind-here flag inside the DM, room or thread to keep using; in a top-level DM or room the current surface stays the chat and future messages route to the spawned ACP session, inside an existing thread the flag binds that thread in place, the new-session and reset commands reset the same bound session in place, and an ACP close command ends the session and removes the binding. Bind-here never creates a child thread; creating or binding a child thread through the spawn command’s thread option is gated by the spawn-sessions setting. When OpenClaw detects a DM room colliding with another on the same shared session it posts a one-time notice suggesting the per-room scope, only while thread bindings are enabled.

Config and history

• Matrix inherits the global thread-binding defaults with per-channel overrides: enabled, idle hours, maximum age, a spawn-sessions flag that gates both sub-agent and ACP thread spawns and is on by default, and a default spawn context; deprecated per-kind spawn keys are migrated by the doctor fix, and an isolated spawn context stops native sub-agent thread spawns from forking the parent transcript.
• A history limit sets how many recent room messages are included as inbound history when a room message triggers the agent, falling back to the global group-chat limit and defaulting to zero, disabled, when both are unset; room history is room-only, DMs keep normal session history.
• Room history is pending-only: OpenClaw buffers room messages that did not trigger a reply, snapshots that window when a mention or other trigger arrives, keeps the current trigger out of the history block since it is the inbound body, and reuses the original snapshot on retries of the same event rather than drifting forward.

OpenClaw on Matrix is the channel post this deepens, and OpenClaw sessions the keys and resets these mappings are built on.

The same shape on Discord

Thread bindings, idle and max-age controls and ACP bindings are shared policy across channels, so a workflow learned on one carries over. OpenClaw Discord threads and sessions is the Discord version of the same page, and OpenClaw sub-agents the spawns that get thread-bound sessions.

On Diali

Matrix is on Diali’s connectable list, alongside WhatsApp, Telegram, Discord, Slack, Mattermost, SMS and voice: the homeserver account and the room allowlist are yours, the Gateway is ours. Hosted OpenClaw on Diali is the assistant and Connect your first channel in five minutes explains how those channels are linked.

• Scope decides the session; threading decides the reply.
• Bindings win; bind-here never creates a thread.
• History is pending-only and snapshot-stable on retry.