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.
Jalur Matrix QA menjalankan Plugin bawaan @openclaw/matrix terhadap homeserver Tuwunel sekali pakai di Docker, dengan akun sementara untuk penggerak, SUT, dan pengamat serta ruang yang sudah diisi data awal. Ini adalah cakupan live berbasis transport nyata untuk Matrix.
Ini adalah tooling khusus maintainer. Rilis OpenClaw terpaket sengaja tidak menyertakan qa-lab, sehingga openclaw qa hanya tersedia dari checkout sumber. Checkout sumber memuat runner bawaan secara langsung - tidak diperlukan langkah pemasangan Plugin.
Untuk konteks framework QA yang lebih luas, lihat ikhtisar QA.
Mulai cepat
pnpm openclaw qa matrix --profile fast --fail-fast
pnpm openclaw qa matrix biasa menjalankan --profile all dan tidak berhenti pada kegagalan pertama. Gunakan --profile fast --fail-fast untuk gate rilis; bagi katalog dengan --profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli saat menjalankan seluruh inventaris secara paralel.
Yang dilakukan jalur ini
- Menyediakan homeserver Tuwunel sekali pakai di Docker (image default
ghcr.io/matrix-construct/tuwunel:v1.5.1, nama server matrix-qa.test, port 28008).
- Mendaftarkan tiga pengguna sementara -
driver (mengirim traffic masuk), sut (akun Matrix OpenClaw yang diuji), observer (penangkap traffic pihak ketiga).
- Mengisi data awal ruang yang diperlukan oleh skenario terpilih (utama, threading, media, restart, sekunder, allowlist, E2EE, DM verifikasi, dll.).
- Memulai Gateway OpenClaw turunan dengan Plugin Matrix nyata yang dibatasi ke akun SUT;
qa-channel tidak dimuat di turunan tersebut.
- Menjalankan skenario secara berurutan, mengamati event melalui klien Matrix driver/observer.
- Membongkar homeserver, menulis artefak laporan dan ringkasan, lalu keluar.
CLI
pnpm openclaw qa matrix [options]
Flag umum
| Flag | Default | Deskripsi |
|---|
--profile <profile> | all | Profil skenario. Lihat Profil. |
--fail-fast | nonaktif | Berhenti setelah pemeriksaan atau skenario pertama yang gagal. |
--scenario <id> | - | Jalankan hanya skenario ini. Dapat diulang. Lihat Skenario. |
--output-dir <path> | <repo>/.artifacts/qa-e2e/matrix-<timestamp> | Tempat laporan, ringkasan, event yang diamati, dan log output ditulis. Path relatif diselesaikan terhadap --repo-root. |
--repo-root <path> | process.cwd() | Root repositori saat dipanggil dari direktori kerja netral. |
--sut-account <id> | sut | ID akun Matrix di dalam konfigurasi Gateway QA. |
Flag penyedia
Jalur ini menggunakan transport Matrix nyata, tetapi penyedia model dapat dikonfigurasi:
| Flag | Default | Deskripsi |
|---|
--provider-mode <mode> | live-frontier | mock-openai untuk dispatch mock deterministik atau live-frontier untuk penyedia frontier live. Alias lama live-openai masih berfungsi. |
--model <ref> | default penyedia | Ref provider/model utama. |
--alt-model <ref> | default penyedia | Ref provider/model alternatif saat skenario beralih di tengah eksekusi. |
--fast | nonaktif | Mengaktifkan mode cepat penyedia jika didukung. |
--credential-source atau --credential-role. Jalur ini menyediakan pengguna sekali pakai secara lokal; tidak ada pool kredensial bersama untuk disewa.
Profil
Profil yang dipilih menentukan skenario mana yang berjalan.
| Profil | Gunakan untuk |
|---|
all (default) | Katalog penuh. Lambat tetapi menyeluruh. |
fast | Subset gate rilis yang menguji kontrak transport live: canary, gating mention, blok allowlist, bentuk balasan, resume restart, tindak lanjut thread, isolasi thread, pengamatan reaksi, dan pengiriman metadata persetujuan exec. |
transport | Skenario threading, DM, ruang, autojoin, mention/allowlist, persetujuan, dan reaksi pada level transport. |
media | Cakupan lampiran gambar, audio, video, PDF, EPUB. |
e2ee-smoke | Cakupan E2EE minimum - balasan terenkripsi dasar, tindak lanjut thread, keberhasilan bootstrap. |
e2ee-deep | Skenario E2EE menyeluruh untuk kehilangan status, cadangan, kunci, dan pemulihan. |
e2ee-cli | Skenario CLI openclaw matrix encryption setup dan verify * yang dijalankan melalui harness QA. |
extensions/qa-matrix/src/runners/contract/scenario-catalog.ts.
Skenario
Daftar ID skenario lengkap adalah union MatrixQaScenarioId di extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15. Kategorinya mencakup:
- threading -
matrix-thread-*, matrix-subagent-thread-spawn
- level teratas / DM / ruang -
matrix-top-level-reply-shape, matrix-room-*, matrix-dm-*
- streaming dan progres tool -
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-*
- reaksi -
matrix-reaction-*
- persetujuan -
matrix-approval-* (metadata exec/Plugin, fallback terpotong, reaksi penolakan, thread, dan routing target: "both")
- restart dan replay -
matrix-restart-*, matrix-stale-sync-replay-dedupe, matrix-room-membership-loss, matrix-homeserver-restart-resume, matrix-initial-catchup-then-incremental
- gating mention, bot-ke-bot, dan allowlist -
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-* (balasan dasar, tindak lanjut thread, bootstrap, siklus hidup kunci pemulihan, varian kehilangan status, perilaku cadangan server, kebersihan perangkat, verifikasi SAS / QR / DM, restart, redaksi artefak)
- CLI E2EE -
matrix-e2ee-cli-* (setup enkripsi, setup idempoten, kegagalan bootstrap, siklus hidup recovery-key, multi-akun, round-trip balasan Gateway, verifikasi mandiri)
Berikan --scenario <id> (dapat diulang) untuk menjalankan set pilihan manual; gabungkan dengan --profile all untuk mengabaikan gating profil.
Variabel lingkungan
| Variabel | Bawaan | Efek |
|---|
OPENCLAW_QA_MATRIX_TIMEOUT_MS | 1800000 (30 menit) | Batas atas tegas untuk keseluruhan eksekusi. |
OPENCLAW_QA_MATRIX_CANARY_TIMEOUT_MS | 45000 | Batas untuk balasan canary awal. CI rilis menaikkan nilai ini pada runner bersama agar giliran Gateway pertama yang lambat tidak gagal sebelum cakupan skenario dimulai. |
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS | 8000 | Jendela senyap untuk asersi negatif tanpa balasan. Dibatasi hingga ≤ batas waktu eksekusi. |
OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS | 90000 | Batas untuk pembongkaran Docker. Permukaan kegagalan menyertakan perintah pemulihan docker compose ... down --remove-orphans. |
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE | ghcr.io/matrix-construct/tuwunel:v1.5.1 | Timpa image homeserver saat memvalidasi terhadap versi Tuwunel yang berbeda. |
OPENCLAW_QA_MATRIX_PROGRESS | aktif | 0 membisukan baris progres [matrix-qa] ... di stderr. 1 memaksanya aktif. |
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT | disunting | 1 mempertahankan isi pesan dan formatted_body di matrix-qa-observed-events.json. Bawaan menyunting untuk menjaga artefak CI tetap aman. |
OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT | nonaktif | 1 melewati process.exit deterministik setelah penulisan artefak. Bawaan memaksa keluar karena handle kripto native matrix-js-sdk dapat membuat event loop tetap hidup setelah artefak selesai. |
OPENCLAW_RUN_NODE_OUTPUT_LOG | tidak disetel | Saat disetel oleh peluncur luar (misalnya scripts/run-node.mjs), QA Matrix menggunakan kembali jalur log tersebut alih-alih memulai tee-nya sendiri. |
Artefak keluaran
Ditulis ke --output-dir:
matrix-qa-report.md - Laporan protokol Markdown (apa yang lulus, gagal, dilewati, dan alasannya).matrix-qa-summary.json - Ringkasan terstruktur yang cocok untuk penguraian CI dan dashboard.matrix-qa-observed-events.json - Event Matrix yang diamati dari klien driver dan observer. Isi disunting kecuali OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1; metadata persetujuan diringkas dengan field aman terpilih dan pratinjau perintah yang dipotong.matrix-qa-output.log - Gabungan stdout/stderr dari eksekusi. Jika OPENCLAW_RUN_NODE_OUTPUT_LOG disetel, log peluncur luar digunakan kembali sebagai gantinya.
Direktori keluaran bawaan adalah <repo>/.artifacts/qa-e2e/matrix-<timestamp> sehingga eksekusi berurutan tidak saling menimpa.
Tips triase
- Eksekusi menggantung menjelang akhir: handle kripto native
matrix-js-sdk dapat bertahan lebih lama daripada harness. Bawaan memaksa process.exit yang bersih setelah penulisan artefak; jika Anda telah membatalkan setelan OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1, proses diperkirakan akan tetap berjalan.
- Kesalahan pembersihan: cari perintah pemulihan yang dicetak (pemanggilan
docker compose ... down --remove-orphans) dan jalankan secara manual untuk melepaskan port homeserver.
- Jendela asersi negatif tidak stabil di CI: turunkan
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS (bawaan 8 dtk) saat CI cepat; naikkan pada runner bersama yang lambat.
- Memerlukan isi yang disunting untuk laporan bug: jalankan ulang dengan
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1 dan lampirkan matrix-qa-observed-events.json. Perlakukan artefak yang dihasilkan sebagai sensitif.
- Versi Tuwunel berbeda: arahkan
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE ke versi yang sedang diuji. Lane hanya memeriksa image bawaan yang dipin.
Kontrak transport live
Matrix adalah salah satu dari tiga lane transport live (Matrix, Telegram, Discord) yang berbagi satu daftar periksa kontrak yang didefinisikan di Ikhtisar QA → Cakupan transport live. qa-channel tetap menjadi suite sintetis yang luas dan sengaja bukan bagian dari matriks tersebut.
Terkait
- Ikhtisar QA - stack QA keseluruhan dan kontrak transport live
- QA Channel - adaptor channel sintetis untuk skenario yang didukung repo
- Pengujian - menjalankan pengujian dan menambahkan cakupan QA
- Matrix - Plugin channel yang diuji
