Use this file to discover all available pages before exploring further.

Matrix QA

The Matrix QA lane runs the bundled

text

@openclaw/matrix

plugin against a disposable Tuwunel homeserver in Docker, with temporary driver, SUT, and observer accounts plus seeded rooms. It is the live transport-real coverage for Matrix.

This is maintainer-only tooling. Packaged OpenClaw releases intentionally omit

text

qa-lab

, so

text

openclaw qa

is only available from a source checkout. Source checkouts load the bundled runner directly — no plugin install step is needed.

For broader QA framework context, see QA overview.

Quick start


bash
pnpm openclaw qa matrix --profile fast --fail-fast

Plain

text

pnpm openclaw qa matrix

runs

text

--profile all

and does not stop on first failure. Use

text

--profile fast --fail-fast

for a release gate; shard the catalog with

text

--profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli

when running the full inventory in parallel.

What the lane does

Provisions a disposable Tuwunel homeserver in Docker (default image
text
ghcr.io/matrix-construct/tuwunel:v1.5.1
, server name
text
matrix-qa.test
, port
text
28008
).
Registers three temporary users —
text
driver
(sends inbound traffic),
text
sut
(the OpenClaw Matrix account under test),
text
observer
(third-party traffic capture).
Seeds rooms required by the selected scenarios (main, threading, media, restart, secondary, allowlist, E2EE, verification DM, etc.).
Starts a child OpenClaw gateway with the real Matrix plugin scoped to the SUT account;
text
qa-channel
is not loaded in the child.
Runs scenarios in sequence, observing events through the driver/observer Matrix clients.
Tears down the homeserver, writes report and summary artifacts, then exits.

CLI


text
pnpm openclaw qa matrix [options]

Common flags

Flag	Default	Description
text `--profile <profile>`	text `all`	Scenario profile. See Profiles.
text `--fail-fast`	off	Stop after the first failed check or scenario.
text `--scenario <id>`	—	Run only this scenario. Repeatable. See Scenarios.
text `--output-dir <path>`	text `<repo>/.artifacts/qa-e2e/matrix-<timestamp>`	Where reports, summary, observed events, and the output log are written. Relative paths resolve against text `--repo-root` .
text `--repo-root <path>`	text `process.cwd()`	Repository root when invoking from a neutral working directory.
text `--sut-account <id>`	text `sut`	Matrix account id inside the QA gateway config.

Provider flags

The lane uses a real Matrix transport but the model provider is configurable:

Flag	Default	Description
text `--provider-mode <mode>`	text `live-frontier`	text `mock-openai` for deterministic mock dispatch or text `live-frontier` for live frontier providers. The legacy alias text `live-openai` still works.
text `--model <ref>`	provider default	Primary text `provider/model` ref.
text `--alt-model <ref>`	provider default	Alternate text `provider/model` ref where scenarios switch mid-run.
text `--fast`	off	Enable provider fast mode where supported.

Matrix QA does not accept

text

--credential-source

text

--credential-role

. The lane provisions disposable users locally; there is no shared credential pool to lease against.

Profiles

The selected profile decides which scenarios run.

Profile	Use it for
text `all` (default)	Full catalog. Slow but exhaustive.
text `fast`	Release-gate subset that exercises the live transport contract: canary, mention gating, allowlist block, reply shape, restart resume, thread follow-up, thread isolation, reaction observation, and exec approval metadata delivery.
text `transport`	Transport-level threading, DM, room, autojoin, mention/allowlist, approval, and reaction scenarios.
text `media`	Image, audio, video, PDF, EPUB attachment coverage.
text `e2ee-smoke`	Minimum E2EE coverage — basic encrypted reply, thread follow-up, bootstrap success.
text `e2ee-deep`	Exhaustive E2EE state-loss, backup, key, and recovery scenarios.
text `e2ee-cli`	text `openclaw matrix encryption setup` and text `verify *` CLI scenarios driven through the QA harness.

The exact mapping lives in

text

extensions/qa-matrix/src/runners/contract/scenario-catalog.ts

Scenarios

The full scenario id list is the

text

MatrixQaScenarioId

union in

text

extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15

. Categories include:

threading —
text
matrix-thread-*
,
text
matrix-subagent-thread-spawn
top-level / DM / room —
text
matrix-top-level-reply-shape
,
text
matrix-room-*
,
text
matrix-dm-*
streaming and tool progress —
text
matrix-room-partial-streaming-preview
,
text
matrix-room-quiet-streaming-preview
,
text
matrix-room-tool-progress-*
,
text
matrix-room-block-streaming
media —
text
matrix-media-type-coverage
,
text
matrix-room-image-understanding-attachment
,
text
matrix-attachment-only-ignored
,
text
matrix-unsupported-media-safe
routing —
text
matrix-room-autojoin-invite
,
text
matrix-secondary-room-*
reactions —
text
matrix-reaction-*
approvals —
text
matrix-approval-*
(exec/plugin metadata, chunked fallback, deny reactions, threads, and
text
target: "both"
routing)
restart and replay —
text
matrix-restart-*
,
text
matrix-stale-sync-replay-dedupe
,
text
matrix-room-membership-loss
,
text
matrix-homeserver-restart-resume
,
text
matrix-initial-catchup-then-incremental
mention gating, bot-to-bot, and allowlists —
text
matrix-mention-*
,
text
matrix-allowbots-*
,
text
matrix-allowlist-*
,
text
matrix-multi-actor-ordering
,
text
matrix-inbound-edit-*
,
text
matrix-mxid-prefixed-command-block
,
text
matrix-observer-allowlist-override
E2EE —
text
matrix-e2ee-*
(basic reply, thread follow-up, bootstrap, recovery key lifecycle, state-loss variants, server backup behavior, device hygiene, SAS / QR / DM verification, restart, artifact redaction)
E2EE CLI —
text
matrix-e2ee-cli-*
(encryption setup, idempotent setup, bootstrap failure, recovery-key lifecycle, multi-account, gateway-reply round-trip, self-verification)

Pass

text

--scenario <id>

(repeatable) to run a hand-picked set; combine with

text

--profile all

to ignore profile gating.

Environment variables

Variable	Default	Effect
text `OPENCLAW_QA_MATRIX_TIMEOUT_MS`	text `1800000` (30 min)	Hard upper bound on the entire run.
text `OPENCLAW_QA_MATRIX_CANARY_TIMEOUT_MS`	text `45000`	Bound for the initial canary reply. Release CI raises this on shared runners so a slow first gateway turn does not fail before scenario coverage starts.
text `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS`	text `8000`	Quiet window for negative no-reply assertions. Clamped to text `≤` the run timeout.
text `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS`	text `90000`	Bound for Docker teardown. Failure surfaces include the recovery text `docker compose ... down --remove-orphans` command.
text `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`	text `ghcr.io/matrix-construct/tuwunel:v1.5.1`	Override the homeserver image when validating against a different Tuwunel version.
text `OPENCLAW_QA_MATRIX_PROGRESS`	on	text `0` silences text `[matrix-qa] ...` progress lines on stderr. text `1` forces them on.
text `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT`	redacted	text `1` keeps message body and text `formatted_body` in text `matrix-qa-observed-events.json` . Default redacts to keep CI artifacts safe.
text `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT`	off	text `1` skips the deterministic text `process.exit` after artifact write. The default forces exit because matrix-js-sdk's native crypto handles can keep the event loop alive past artifact completion.
text `OPENCLAW_RUN_NODE_OUTPUT_LOG`	unset	When set by an outer launcher (e.g. text `scripts/run-node.mjs` ), Matrix QA reuses that log path instead of starting its own tee.

Output artifacts

Written to

text

--output-dir

text
matrix-qa-report.md
— Markdown protocol report (what passed, failed, was skipped, and why).
text
matrix-qa-summary.json
— Structured summary suitable for CI parsing and dashboards.
text
matrix-qa-observed-events.json
— Observed Matrix events from the driver and observer clients. Bodies are redacted unless
text
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1
; approval metadata is summarized with selected safe fields and truncated command preview.
text
matrix-qa-output.log
— Combined stdout/stderr from the run. If
text
OPENCLAW_RUN_NODE_OUTPUT_LOG
is set, the outer launcher's log is reused instead.

The default output dir is

text

<repo>/.artifacts/qa-e2e/matrix-<timestamp>

so successive runs do not overwrite each other.

Triage tips

Run hangs near the end:
text
matrix-js-sdk
native crypto handles can outlive the harness. The default forces a clean
text
process.exit
after artifact write; if you have unset
text
OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1
, expect the process to linger.
Cleanup error: look for the printed recovery command (a
text
docker compose ... down --remove-orphans
invocation) and run it manually to release the homeserver port.
Flaky negative-assertion windows in CI: lower
text
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS
(default 8 s) when CI is fast; raise it on slow shared runners.
Need redacted bodies for a bug report: rerun with
text
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1
and attach
text
matrix-qa-observed-events.json
. Treat the resulting artifact as sensitive.
Different Tuwunel version: point
text
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE
at the version under test. The lane checks in only the pinned default image.

Live transport contract

Matrix is one of three live transport lanes (Matrix, Telegram, Discord) that share a single contract checklist defined in QA overview → Live transport coverage.

text

qa-channel

remains the broad synthetic suite and is intentionally not part of that matrix.

QA overview — overall QA stack and live transport contract
QA Channel — synthetic channel adapter for repo-backed scenarios
Testing — running tests and adding QA coverage
Matrix — the channel plugin under test

OpenClaw Docs

Matrix QA

Quick start

What the lane does

CLI

Common flags

Provider flags

Profiles

Scenarios

Environment variables

Output artifacts

Triage tips

Live transport contract

Related