Matrix QA

Matrix QA 通道針對 Docker 中的一次性 Tuwunel homeserver 執行內建的 @openclaw/matrix 外掛程式，並包含暫時的驅動程式、SUT 和觀察者帳戶以及預先植入的房間。這是 Matrix 的即時傳輸真實覆蓋範圍。

這是僅供維護者使用的工具。封裝的 OpenClaw 版本有意省略了 qa-lab，因此 openclaw qa 只能從原始碼結帳中獲得。原始碼結帳直接載入捆綁的執行器 - 不需要安裝外掛程式。

有關更廣泛的 QA 框架背景，請參閱 QA 概述。

快速入門

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

單純的 pnpm openclaw qa matrix 會執行 --profile all 並且不會在第一次失敗時停止。請使用 --profile fast --fail-fast 作為發布閘道；當平行執行完整清單時，請使用 --profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli 將目錄分片。

通道的用途

1. 在 Docker 中佈建一次性 Tuwunel homeserver（預設映像檔 ghcr.io/matrix-construct/tuwunel:v1.5.1、伺服器名稱 matrix-qa.test、連接埠 28008）。
2. 註冊三個臨時使用者 - driver（發送入站流量）、sut（受測試的 OpenClaw Matrix 帳號）、observer（第三方流量捕獲）。
3. 植入所選情境所需的房間（主要、執行緒、媒體、重新啟動、次要、允許清單、E2EE、驗證 DM 等）。
4. 啟動子 OpenClaw 閘道，並將真實的 Matrix 外掛程式範圍限定於 SUT 帳戶；子程序中不會載入 qa-channel。
5. 依序執行情境，透過驅動程式/觀察者 Matrix 用戶端觀察事件。
6. 拆除 homeserver，撰寫報告和摘要成品，然後結束。

CLI

pnpm openclaw qa matrix [options]

常見旗標

旗標	預設值	說明
--profile <profile>	all	情境設定檔。請參閱 設定檔。
--fail-fast	off	在第一個檢查或場景失敗時停止。
--scenario <id>	-	僅執行此情境。可重複。請參閱 情境。
--output-dir <path>	<repo>/.artifacts/qa-e2e/matrix-<timestamp>	寫入報告、摘要、觀察事件和輸出日誌的位置。相對路徑相對於 --repo-root 解析。
--repo-root <path>	process.cwd()	從中性工作目錄調用時的儲存庫根目錄。
--sut-account <id>	sut	QA 閘道配置中的 Matrix 帳戶 ID。

提供者標誌

此通道使用真實的 Matrix 傳輸，但模型提供者是可配置的：

標誌	預設值	描述
--provider-mode <mode>	live-frontier	用於確定性模擬分派的 mock-openai 或用於即時前沿提供者的 live-frontier。舊版別名 live-openai 仍然有效。
--model <ref>	提供者預設值	主要 provider/model 參考。
--alt-model <ref>	提供者預設值	場景中途切換時使用的替代 provider/model 參考。
--fast	關閉	在支援的情況下啟用提供者快速模式。

Matrix QA 不接受 --credential-source 或 --credential-role。此通道會在本地配置一次性使用者；沒有共享憑證池可供租用。

設定檔

選取的設定檔決定執行哪些場景。

設定檔	用途
all (預設)	完整目錄。緩慢但窮盡。
fast	執行即時傳輸契約的發布門檻子集：金絲雀、提及閘控、允許清單封鎖、回覆形狀、重新啟動恢復、主題後續追蹤、主題隔離、反應觀察以及執行核准元數據傳遞。
transport	傳輸層級的主題、私訊、聊天室、自動加入、提及/允許清單、核准和反應情境。
media	圖片、音訊、影片、PDF、EPUB 附件涵蓋範圍。
e2ee-smoke	最低 E2EE 涵蓋範圍 - 基本加密回覆、主題後續追蹤、啟動成功。
e2ee-deep	窮盡的 E2EE 狀態遺失、備份、金鑰與復原情境。
e2ee-cli	透過 QA 隨機測試驅動的 openclaw matrix encryption setup 與 verify * CLI 情境。

確切對應關係存於 extensions/qa-matrix/src/runners/contract/scenario-catalog.ts。

情境

完整的情境 ID 清單是 extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15 中的 MatrixQaScenarioId 聯集。分類包含：

• 主題 - matrix-thread-*, matrix-subagent-thread-spawn
• 頂層 / 私訊 / 聊天室 - matrix-top-level-reply-shape, matrix-room-*, matrix-dm-*
• 串流和工具進度 - matrix-room-partial-streaming-preview, matrix-room-quiet-streaming-preview, matrix-room-tool-progress-*, matrix-room-block-streaming
• 媒體 - matrix-media-type-coverage, matrix-room-image-understanding-attachment, matrix-attachment-only-ignored, matrix-unsupported-media-safe
• 路由 - matrix-room-autojoin-invite, matrix-secondary-room-*
• 反應 - matrix-reaction-*
• 核准 - matrix-approval-* (exec/plugin 元數據、分塊後備、拒絕反應、主題以及 target: "both" 路由)
• 重新啟動和重播 - matrix-restart-*, matrix-stale-sync-replay-dedupe, matrix-room-membership-loss, matrix-homeserver-restart-resume, matrix-initial-catchup-then-incremental
• 提及閘控、機器人對機器人以及允許清單 - 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-* (基本回覆、主題後續追蹤、引導、復原金鑰生命週期、狀態遺失變體、伺服器備份行為、裝置衛生、SAS / QR / DM 驗證、重新啟動、編輯 artifacts)
• E2EE CLI - matrix-e2ee-cli-* (加密設定、等冪設定、引導失敗、復原金鑰生命週期、多帳號、閘道回覆往返、自我驗證)

傳遞 --scenario <id> (可重複) 以執行精選集合；結合 --profile all 以忽略設定檔閘控。

環境變數

變數	預設值	效果
OPENCLAW_QA_MATRIX_TIMEOUT_MS	1800000 (30 分鐘)	整個執行的硬性上限。
OPENCLAW_QA_MATRIX_CANARY_TIMEOUT_MS	45000	初始金絲雀回覆的邊界。Release CI 會在共用執行器上增加此值，以便在情境覆蓋率開始之前，緩慢的首次閘道輪次不會失敗。
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	針對不同 Tuwunel 版本進行驗證時，覆寫 homeserver 映像檔。
OPENCLAW_QA_MATRIX_PROGRESS	開啟	0 會讓 stderr 上的 [matrix-qa] ... 進度列保持靜音。1 則強制顯示。
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT	已編輯	1 會保留 matrix-qa-observed-events.json 中的訊息主體和 formatted_body。預設為編輯以保護 CI 成品安全。
OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT	關閉	1 會在寫入產出資料後跳過確定性 process.exit。預設會強制退出，因為 matrix-js-sdk 的原生加密控制項可能會讓事件循環在產出資料完成後繼續運作。
OPENCLAW_RUN_NODE_OUTPUT_LOG	未設定	當由外部啟動器（例如 scripts/run-node.mjs）設定時，Matrix QA 會重用該日誌路徑，而不是啟動它自己的 tee。

輸出產出資料

寫入至 --output-dir：

• matrix-qa-report.md - Markdown 協議報告（顯示通過、失敗、跳過的項目及原因）。
• matrix-qa-summary.json - 適合 CI 解析與儀表板使用的結構化摘要。
• matrix-qa-observed-events.json - 從驅動程式與觀察者客戶端觀察到的 Matrix 事件。除非設定 OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1，否則內文會被編輯；核准元數據會以選定的安全欄位與截斷的指令預覽來進行摘要。
• matrix-qa-output.log - 執行期間的合併 stdout/stderr。如果設定了 OPENCLAW_RUN_NODE_OUTPUT_LOG，則會改用外部啟動器的日誌。

預設輸出目錄為 <repo>/.artifacts/qa-e2e/matrix-<timestamp>，因此連續執行不會互相覆寫。

排查提示

• 執行在最後階段掛起： matrix-js-sdk 原生加密控制項可能會比測試工具更長壽。預設會在寫入產出資料後強制執行乾淨的 process.exit；如果您取消設定 OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1，請預期程序會滯留。
• 清理錯誤： 尋找列印的復原指令（即 docker compose ... down --remove-orphans 呼叫）並手動執行以釋放 homeserver 連接埠。
• CI 中的不穩定否定斷言時間視窗： 當 CI 速度較快時，降低 OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS（預設為 8 秒）；在緩慢的共用執行器上則提高它。
• 錯誤回報需要未編輯的內文： 使用 OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1 重新執行並附上 matrix-qa-observed-events.json。請將產生的產出資料視為敏感資料。
• 不同的 Tuwunel 版本： 將 OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE 指向受測版本。此通道僅簽入固定的預設映像檔。

即時傳輸合約

Matrix 是三個即時傳輸通道（Matrix、Telegram、Discord）之一，它們共用一個在 QA 概覽 → 即時傳輸覆蓋率 中定義的單一契約檢查清單。qa-channel 仍然是廣泛的綜合測試套件，且故意不包含在該矩陣中。

相關

• QA 概覽 - 整體 QA 堆疊與即時傳輸契約
• QA Channel - 用於支援 repo 的情境的綜合通道適配器
• 測試 - 執行測試並新增 QA 覆蓋率
• Matrix - 受測試的通道外掛