Documentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
Die Matrix-QA-Lane führt das gebündelte @openclaw/matrix-Plugin gegen einen temporären Tuwunel-Homeserver in Docker aus, mit temporären Driver-, SUT- und Observer-Konten sowie vorbefüllten Räumen. Sie ist die Live-Abdeckung mit realem Transport für Matrix.
Dies ist Tooling nur für Maintainer. Paketierte OpenClaw-Releases lassen qa-lab absichtlich aus, daher ist openclaw qa nur aus einem Source-Checkout verfügbar. Source-Checkouts laden den gebündelten Runner direkt - es ist kein Schritt zur Plugin-Installation erforderlich.
Weiteren Kontext zum umfassenderen QA-Framework finden Sie in der QA-Übersicht.
Schnellstart
pnpm openclaw qa matrix --profile fast --fail-fast
pnpm openclaw qa matrix führt --profile all aus und stoppt nicht beim ersten Fehler. Verwenden Sie --profile fast --fail-fast für ein Release-Gate; teilen Sie den Katalog mit --profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli in Shards auf, wenn Sie das vollständige Inventar parallel ausführen.
Was die Lane ausführt
- Stellt einen temporären Tuwunel-Homeserver in Docker bereit (Standard-Image
ghcr.io/matrix-construct/tuwunel:v1.5.1, Servername matrix-qa.test, Port 28008).
- Registriert drei temporäre Benutzer -
driver (sendet eingehenden Traffic), sut (das zu testende OpenClaw-Matrix-Konto), observer (Traffic-Erfassung durch Dritte).
- Befüllt Räume, die von den ausgewählten Szenarien benötigt werden (Hauptraum, Threading, Medien, Neustart, sekundärer Raum, Allowlist, E2EE, Verifizierungs-DM usw.).
- Startet ein untergeordnetes OpenClaw-Gateway mit dem echten Matrix-Plugin, das auf das SUT-Konto beschränkt ist;
qa-channel wird im untergeordneten Prozess nicht geladen.
- Führt Szenarien nacheinander aus und beobachtet Ereignisse über die Driver-/Observer-Matrix-Clients.
- Fährt den Homeserver herunter, schreibt Berichts- und Zusammenfassungsartefakte und beendet sich dann.
CLI
pnpm openclaw qa matrix [options]
Häufige Flags
| Flag | Standard | Beschreibung |
|---|
--profile <profile> | all | Szenarioprofil. Siehe Profile. |
--fail-fast | aus | Nach der ersten fehlgeschlagenen Prüfung oder dem ersten fehlgeschlagenen Szenario stoppen. |
--scenario <id> | - | Nur dieses Szenario ausführen. Wiederholbar. Siehe Szenarien. |
--output-dir <path> | <repo>/.artifacts/qa-e2e/matrix-<timestamp> | Zielort für Berichte, Zusammenfassung, beobachtete Ereignisse und das Ausgabelog. Relative Pfade werden relativ zu --repo-root aufgelöst. |
--repo-root <path> | process.cwd() | Repository-Root beim Aufruf aus einem neutralen Arbeitsverzeichnis. |
--sut-account <id> | sut | Matrix-Konto-ID innerhalb der QA-Gateway-Konfiguration. |
Provider-Flags
Die Lane verwendet einen echten Matrix-Transport, aber der Modell-Provider ist konfigurierbar:
| Flag | Standard | Beschreibung |
|---|
--provider-mode <mode> | live-frontier | mock-openai für deterministisches Mock-Dispatching oder live-frontier für Live-Frontier-Provider. Der Legacy-Alias live-openai funktioniert weiterhin. |
--model <ref> | Provider-Standard | Primäre provider/model-Referenz. |
--alt-model <ref> | Provider-Standard | Alternative provider/model-Referenz, wenn Szenarien während der Ausführung wechseln. |
--fast | aus | Provider-Fast-Modus aktivieren, sofern unterstützt. |
--credential-source noch --credential-role. Die Lane stellt lokal temporäre Benutzer bereit; es gibt keinen gemeinsamen Credential-Pool, gegen den geleast werden könnte.
Profile
Das ausgewählte Profil bestimmt, welche Szenarien ausgeführt werden.
| Profil | Verwenden Sie es für |
|---|
all (Standard) | Vollständiger Katalog. Langsam, aber umfassend. |
fast | Release-Gate-Teilmenge, die den Live-Transportvertrag prüft: Canary, Mention-Gating, Allowlist-Block, Antwortform, Wiederaufnahme nach Neustart, Thread-Follow-up, Thread-Isolation, Reaktionsbeobachtung und Zustellung von Exec-Approval-Metadaten. |
transport | Threading-, DM-, Raum-, Autojoin-, Mention-/Allowlist-, Approval- und Reaktionsszenarien auf Transportebene. |
media | Abdeckung für Bild-, Audio-, Video-, PDF- und EPUB-Anhänge. |
e2ee-smoke | Minimale E2EE-Abdeckung - einfache verschlüsselte Antwort, Thread-Follow-up, erfolgreicher Bootstrap. |
e2ee-deep | Umfassende E2EE-Szenarien für Zustandsverlust, Backup, Schlüssel und Wiederherstellung. |
e2ee-cli | openclaw matrix encryption setup- und verify *-CLI-Szenarien, die über den QA-Harness gesteuert werden. |
extensions/qa-matrix/src/runners/contract/scenario-catalog.ts.
Szenarien
Die vollständige Liste der Szenario-IDs ist die MatrixQaScenarioId-Union in extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15. Kategorien umfassen:
- Threading -
matrix-thread-*, matrix-subagent-thread-spawn
- Top-Level / DM / Raum -
matrix-top-level-reply-shape, matrix-room-*, matrix-dm-*
- Streaming und Tool-Fortschritt -
matrix-room-partial-streaming-preview, matrix-room-quiet-streaming-preview, matrix-room-tool-progress-*, matrix-room-block-streaming
- Medien -
matrix-media-type-coverage, matrix-room-image-understanding-attachment, matrix-attachment-only-ignored, matrix-unsupported-media-safe
- Routing -
matrix-room-autojoin-invite, matrix-secondary-room-*
- Reaktionen -
matrix-reaction-*
- Approvals -
matrix-approval-* (Exec-/Plugin-Metadaten, Chunked-Fallback, Deny-Reaktionen, Threads und target: "both"-Routing)
- Neustart und Replay -
matrix-restart-*, matrix-stale-sync-replay-dedupe, matrix-room-membership-loss, matrix-homeserver-restart-resume, matrix-initial-catchup-then-incremental
- Mention-Gating, Bot-zu-Bot und Allowlists -
matrix-mention-*, matrix-allowbots-*, matrix-allowlist-*, matrix-multi-actor-ordering, matrix-inbound-edit-*, matrix-mxid-prefixed-command-block, matrix-observer-allowlist-override
- E2EE -
matrix-e2ee-* (einfache Antwort, Thread-Follow-up, Bootstrap, Lebenszyklus von Wiederherstellungsschlüsseln, Zustandsverlustvarianten, Server-Backup-Verhalten, Gerätehygiene, SAS-/QR-/DM-Verifizierung, Neustart, Artefakt-Redaktion)
- E2EE-CLI -
matrix-e2ee-cli-* (Encryption-Setup, idempotentes Setup, Bootstrap-Fehler, Lebenszyklus von Wiederherstellungsschlüsseln, Multi-Account, Gateway-Reply-Roundtrip, Selbstverifizierung)
Übergeben Sie --scenario <id> (wiederholbar), um eine manuell ausgewählte Gruppe auszuführen; kombinieren Sie dies mit --profile all, um Profil-Gating zu ignorieren.
Umgebungsvariablen
| Variable | Standardwert | Auswirkung |
|---|
OPENCLAW_QA_MATRIX_TIMEOUT_MS | 1800000 (30 Min.) | Harte Obergrenze für den gesamten Lauf. |
OPENCLAW_QA_MATRIX_CANARY_TIMEOUT_MS | 45000 | Begrenzung für die anfängliche Canary-Antwort. Die Release-CI erhöht diesen Wert auf gemeinsam genutzten Runnern, damit ein langsamer erster Gateway-Durchlauf nicht fehlschlägt, bevor die Szenarioabdeckung startet. |
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS | 8000 | Ruhefenster für negative No-Reply-Assertions. Wird auf ≤ das Lauf-Timeout begrenzt. |
OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS | 90000 | Begrenzung für den Docker-Abbau. Fehlerausgaben enthalten den Wiederherstellungsbefehl docker compose ... down --remove-orphans. |
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE | ghcr.io/matrix-construct/tuwunel:v1.5.1 | Überschreibt das Homeserver-Image bei der Validierung mit einer anderen Tuwunel-Version. |
OPENCLAW_QA_MATRIX_PROGRESS | ein | 0 unterdrückt [matrix-qa] ...-Fortschrittszeilen auf stderr. 1 erzwingt sie. |
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT | geschwärzt | 1 behält Nachrichtentext und formatted_body in matrix-qa-observed-events.json bei. Standardmäßig wird geschwärzt, um CI-Artefakte sicher zu halten. |
OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT | aus | 1 überspringt das deterministische process.exit nach dem Schreiben der Artefakte. Standardmäßig wird das Beenden erzwungen, weil native Crypto-Handles von matrix-js-sdk die Event Loop über den Artefaktabschluss hinaus am Leben halten können. |
OPENCLAW_RUN_NODE_OUTPUT_LOG | nicht gesetzt | Wenn von einem äußeren Launcher (z. B. scripts/run-node.mjs) gesetzt, verwendet Matrix QA diesen Logpfad wieder, anstatt ein eigenes Tee zu starten. |
Ausgabeartefakte
Werden nach --output-dir geschrieben:
matrix-qa-report.md - Markdown-Protokollbericht (was bestanden hat, fehlgeschlagen ist, übersprungen wurde und warum).matrix-qa-summary.json - Strukturierte Zusammenfassung, die für CI-Parsing und Dashboards geeignet ist.matrix-qa-observed-events.json - Beobachtete Matrix-Ereignisse von den Treiber- und Beobachter-Clients. Inhalte werden geschwärzt, außer OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1; Genehmigungsmetadaten werden mit ausgewählten sicheren Feldern und gekürzter Befehlsvorschau zusammengefasst.matrix-qa-output.log - Kombinierte stdout/stderr-Ausgabe des Laufs. Wenn OPENCLAW_RUN_NODE_OUTPUT_LOG gesetzt ist, wird stattdessen das Log des äußeren Launchers wiederverwendet.
Das Standard-Ausgabeverzeichnis ist <repo>/.artifacts/qa-e2e/matrix-<timestamp>, damit aufeinanderfolgende Läufe einander nicht überschreiben.
Triagetipps
- Lauf hängt gegen Ende: Native Crypto-Handles von
matrix-js-sdk können länger leben als der Harness. Standardmäßig wird nach dem Schreiben der Artefakte ein sauberes process.exit erzwungen; wenn Sie OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1 deaktiviert haben, rechnen Sie damit, dass der Prozess weiterläuft.
- Bereinigungsfehler: Suchen Sie nach dem ausgegebenen Wiederherstellungsbefehl (einem Aufruf von
docker compose ... down --remove-orphans) und führen Sie ihn manuell aus, um den Homeserver-Port freizugeben.
- Instabile Fenster für negative Assertions in CI: Senken Sie
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS (Standard 8 s), wenn CI schnell ist; erhöhen Sie den Wert auf langsamen gemeinsam genutzten Runnern.
- Sie benötigen geschwärzte Inhalte für einen Fehlerbericht: Führen Sie den Lauf mit
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1 erneut aus und hängen Sie matrix-qa-observed-events.json an. Behandeln Sie das resultierende Artefakt als sensibel.
- Andere Tuwunel-Version: Setzen Sie
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE auf die zu testende Version. Die Lane prüft nur das angeheftete Standard-Image ein.
Live-Transportvertrag
Matrix ist eine von drei Live-Transport-Lanes (Matrix, Telegram, Discord), die eine einzelne Vertragscheckliste gemeinsam nutzen, die unter QA-Überblick → Live-Transportabdeckung definiert ist. qa-channel bleibt die breite synthetische Suite und ist absichtlich nicht Teil dieser Matrix.
Verwandte Themen
- QA-Überblick - gesamter QA-Stack und Live-Transportvertrag
- QA-Kanal - synthetischer Kanaladapter für repo-gestützte Szenarien
- Testen - Tests ausführen und QA-Abdeckung hinzufügen
- Matrix - das getestete Kanal-Plugin
