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.
QA-лінія Matrix запускає вбудований Plugin @openclaw/matrix проти одноразового homeserver Tuwunel у Docker, з тимчасовими обліковими записами driver, SUT і observer, а також попередньо заповненими кімнатами. Це live-покриття Matrix з реальним транспортом.
Це інструментарій лише для супровідників. Пакетовані релізи OpenClaw навмисно не містять qa-lab, тому openclaw qa доступний лише з вихідного checkout. Вихідні checkout завантажують вбудований runner напряму - крок установлення Plugin не потрібен.
Ширший контекст QA-фреймворку див. в огляді QA.
Швидкий старт
pnpm openclaw qa matrix --profile fast --fail-fast
pnpm openclaw qa matrix запускає --profile all і не зупиняється після першої помилки. Використовуйте --profile fast --fail-fast для релізного gate; розподіляйте каталог за допомогою --profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli, коли запускаєте повний інвентар паралельно.
Що робить лінія
- Підіймає одноразовий homeserver Tuwunel у Docker (типовий образ
ghcr.io/matrix-construct/tuwunel:v1.5.1, ім’я сервера matrix-qa.test, порт 28008).
- Реєструє трьох тимчасових користувачів -
driver (надсилає вхідний трафік), sut (обліковий запис OpenClaw Matrix, що тестується), observer (захоплення стороннього трафіку).
- Заповнює кімнати, потрібні вибраним сценаріям (main, threading, media, restart, secondary, allowlist, E2EE, verification DM тощо).
- Запускає дочірній OpenClaw gateway зі справжнім Plugin Matrix, обмеженим обліковим записом SUT;
qa-channel у дочірньому процесі не завантажується.
- Послідовно запускає сценарії, спостерігаючи події через Matrix-клієнти driver/observer.
- Зупиняє homeserver, записує артефакти звіту й підсумку, потім завершує роботу.
CLI
pnpm openclaw qa matrix [options]
Поширені прапорці
| Прапорець | Типове значення | Опис |
|---|
--profile <profile> | all | Профіль сценаріїв. Див. Профілі. |
--fail-fast | вимкнено | Зупинитися після першої невдалої перевірки або сценарію. |
--scenario <id> | - | Запустити лише цей сценарій. Можна повторювати. Див. Сценарії. |
--output-dir <path> | <repo>/.artifacts/qa-e2e/matrix-<timestamp> | Куди записуються звіти, підсумок, спостережені події та журнал виводу. Відносні шляхи обчислюються відносно --repo-root. |
--repo-root <path> | process.cwd() | Корінь репозиторію під час запуску з нейтрального робочого каталогу. |
--sut-account <id> | sut | Ідентифікатор облікового запису Matrix у конфігурації QA gateway. |
Прапорці провайдера
Лінія використовує справжній транспорт Matrix, але провайдер моделі можна налаштувати:
| Прапорець | Типове значення | Опис |
|---|
--provider-mode <mode> | live-frontier | mock-openai для детермінованої mock-диспетчеризації або live-frontier для live frontier провайдерів. Legacy-псевдонім live-openai ще працює. |
--model <ref> | типове значення провайдера | Основний ref provider/model. |
--alt-model <ref> | типове значення провайдера | Альтернативний ref provider/model, коли сценарії перемикаються посеред запуску. |
--fast | вимкнено | Увімкнути швидкий режим провайдера, де він підтримується. |
--credential-source або --credential-role. Лінія локально створює одноразових користувачів; спільного пулу облікових даних для оренди немає.
Профілі
Вибраний профіль визначає, які сценарії запускаються.
| Профіль | Для чого використовувати |
|---|
all (типовий) | Повний каталог. Повільно, але вичерпно. |
fast | Підмножина для релізного gate, що перевіряє live-контракт транспорту: canary, mention gating, блокування allowlist, форму відповіді, відновлення після рестарту, thread follow-up, ізоляцію thread, спостереження reaction і доставку metadata exec approval. |
transport | Сценарії transport-level threading, DM, room, autojoin, mention/allowlist, approval і reaction. |
media | Покриття вкладень image, audio, video, PDF, EPUB. |
e2ee-smoke | Мінімальне покриття E2EE - базова зашифрована відповідь, thread follow-up, успішний bootstrap. |
e2ee-deep | Вичерпні сценарії втрати стану E2EE, backup, ключів і відновлення. |
e2ee-cli | CLI-сценарії openclaw matrix encryption setup і verify *, керовані через QA harness. |
extensions/qa-matrix/src/runners/contract/scenario-catalog.ts.
Сценарії
Повний список ідентифікаторів сценаріїв - це union MatrixQaScenarioId у extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15. Категорії охоплюють:
- threading -
matrix-thread-*, matrix-subagent-thread-spawn
- top-level / DM / room -
matrix-top-level-reply-shape, matrix-room-*, matrix-dm-*
- streaming і перебіг інструментів -
matrix-room-partial-streaming-preview, matrix-room-quiet-streaming-preview, matrix-room-tool-progress-*, matrix-room-block-streaming
- media -
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-*
- reactions -
matrix-reaction-*
- approvals -
matrix-approval-* (metadata exec/plugin, chunked fallback, deny reactions, threads і routing target: "both")
- restart і replay -
matrix-restart-*, matrix-stale-sync-replay-dedupe, matrix-room-membership-loss, matrix-homeserver-restart-resume, matrix-initial-catchup-then-incremental
- mention gating, bot-to-bot і 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-* (базова відповідь, thread follow-up, bootstrap, життєвий цикл recovery key, варіанти втрати стану, поведінка server backup, гігієна пристроїв, верифікація SAS / QR / DM, restart, редагування артефактів)
- E2EE CLI -
matrix-e2ee-cli-* (encryption setup, ідемпотентний setup, помилка bootstrap, життєвий цикл recovery-key, multi-account, gateway-reply round-trip, self-verification)
Передайте --scenario <id> (можна повторювати), щоб запустити вручну вибраний набір; поєднуйте з --profile all, щоб ігнорувати фільтрацію профілю.
Змінні середовища
| Змінна | Типове значення | Вплив |
|---|
OPENCLAW_QA_MATRIX_TIMEOUT_MS | 1800000 (30 хв) | Жорстка верхня межа для всього запуску. |
OPENCLAW_QA_MATRIX_CANARY_TIMEOUT_MS | 45000 | Межа для початкової canary-відповіді. Release CI збільшує її на спільних раннерах, щоб повільний перший хід gateway не завершувався помилкою до початку покриття сценаріїв. |
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS | 8000 | Тихе вікно для негативних перевірок відсутності відповіді. Обмежується до ≤ таймауту запуску. |
OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS | 90000 | Межа для демонтажу Docker. Поверхні помилок містять команду відновлення docker compose ... down --remove-orphans. |
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE | ghcr.io/matrix-construct/tuwunel:v1.5.1 | Перевизначає образ homeserver під час перевірки з іншою версією Tuwunel. |
OPENCLAW_QA_MATRIX_PROGRESS | увімкнено | 0 вимикає рядки прогресу [matrix-qa] ... у stderr. 1 примусово вмикає їх. |
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT | заредактовано | 1 зберігає тіло повідомлення та formatted_body у matrix-qa-observed-events.json. Типово редагується, щоб артефакти CI залишалися безпечними. |
OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT | вимкнено | 1 пропускає детермінований process.exit після запису артефакту. Типово вихід примусовий, бо native crypto handles matrix-js-sdk можуть утримувати цикл подій живим після завершення артефакту. |
OPENCLAW_RUN_NODE_OUTPUT_LOG | не задано | Коли задано зовнішнім launcher (наприклад, scripts/run-node.mjs), Matrix QA повторно використовує цей шлях журналу замість запуску власного tee. |
Вихідні артефакти
Записуються в --output-dir:
matrix-qa-report.md - Markdown-звіт протоколу (що пройшло, завершилося помилкою, було пропущено і чому).matrix-qa-summary.json - Структурований підсумок, придатний для парсингу CI та dashboards.matrix-qa-observed-events.json - Спостережені події Matrix від клієнтів драйвера й observer. Тіла редагуються, якщо не задано OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1; метадані схвалення підсумовуються з вибраними безпечними полями та скороченим попереднім переглядом команди.matrix-qa-output.log - Об’єднані stdout/stderr із запуску. Якщо задано OPENCLAW_RUN_NODE_OUTPUT_LOG, натомість повторно використовується журнал зовнішнього launcher.
Типовий каталог виводу — <repo>/.artifacts/qa-e2e/matrix-<timestamp>, щоб послідовні запуски не перезаписували один одного.
Поради з тріажу
- Запуск зависає ближче до кінця: native crypto handles
matrix-js-sdk можуть жити довше за harness. Типово виконується примусовий чистий process.exit після запису артефакту; якщо ви скасували OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1, очікуйте, що процес затримається.
- Помилка cleanup: знайдіть надруковану команду відновлення (виклик
docker compose ... down --remove-orphans) і запустіть її вручну, щоб звільнити порт homeserver.
- Нестабільні вікна негативних перевірок у CI: зменште
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS (типово 8 с), коли CI швидкий; збільшуйте його на повільних спільних раннерах.
- Потрібні заредактовані тіла для звіту про bug: запустіть повторно з
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1 і долучіть matrix-qa-observed-events.json. Вважайте отриманий артефакт чутливим.
- Інша версія Tuwunel: спрямуйте
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE на версію, що тестується. Лейн перевіряє лише закріплений типовий образ.
Контракт живого транспорту
Matrix — один із трьох live transport lanes (Matrix, Telegram, Discord), які мають спільний список перевірок контракту, визначений у огляді QA → Покриття живого транспорту. qa-channel залишається широким синтетичним набором і навмисно не входить до цієї matrix.
Пов’язане
- Огляд QA - загальний стек QA та контракт живого транспорту
- QA Channel - синтетичний channel adapter для сценаріїв, підкріплених репозиторієм
- Тестування - запуск тестів і додавання покриття QA
- Matrix - channel plugin, що тестується
