跳轉到主要內容
Matrix QA 通道會在 Docker 中，針對一次性的 Tuwunel homeserver 執行隨附的 @openclaw/matrix 外掛，並使用臨時的 driver、SUT、observer 帳號以及預先建立的房間。這是 Matrix 的真實傳輸即時覆蓋。 僅限維護者使用的工具。封裝的 OpenClaw 發行版會省略 qa-lab，因此 openclaw qa 只會從原始碼 checkout 執行，並且會直接載入隨附的 runner，不需要外掛安裝步驟。 如需更完整的 QA 框架背景，請參閱 QA 概觀。

​
快速開始

pnpm openclaw qa matrix --profile fast --fail-fast
一般的 pnpm openclaw qa matrix 會執行 --profile all，且不會在第一次失敗時停止。可使用 --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. 建立所選情境需要的房間（main、threading、media、restart、secondary、allowlist、E2EE、verification DM 等）。
  4. 針對已記錄的 Tuwunel 邊界執行與基底無關的 matrix-qa-v1 通訊協定探測。單元測試會以 Matrix 通訊協定 fixture 證明探測合約；#99707 中的標準 QA 傳輸配接器主機負責真實 Crabline 目標接線。
  5. 啟動子 OpenClaw 閘道，並將真實 Matrix 外掛限定到 SUT 帳號。
  6. 依序執行情境，透過 driver/observer Matrix 用戶端觀察事件，並從已記錄的流量推導路由/狀態預期。
  7. 關閉 homeserver、寫入報告與證據成品，然後結束。

​
命令列介面

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>sutQA 閘道設定中的 Matrix 帳號 ID。

​
提供者旗標

此通道使用真實 Matrix 傳輸，但模型提供者可設定：
旗標預設值說明
--provider-mode <mode>live-frontiermock-openai 用於確定性的模擬派送，或 live-frontier 用於即時 frontier 提供者。舊別名 live-openai 仍可使用。
--model <ref>提供者預設值主要 provider/model ref。
--alt-model <ref>提供者預設值情境在執行中切換時使用的替代 provider/model ref。
--fast關閉在支援的地方啟用提供者快速模式。
Matrix QA 不接受 --credential-source 或 --credential-role。此通道會在本機佈建一次性使用者；沒有可租用的共享憑證池。

​
設定檔

設定檔使用時機
all（預設）完整目錄。較慢但詳盡。
fast發行閘門子集，會演練即時傳輸合約：canary、提及閘控、allowlist 封鎖、回覆形狀、重新啟動恢復、thread follow-up、thread isolation、reaction observation，以及 exec approval metadata delivery。
transport傳輸層級的 threading、DM、room、autojoin、mention/allowlist、approval 和 reaction 情境。
media圖片、音訊、影片、PDF、EPUB 附件覆蓋。
e2ee-smoke最低限度的 E2EE 覆蓋：基本加密回覆、thread follow-up、bootstrap success。
e2ee-deep詳盡的 E2EE state-loss、backup、key 和 recovery 情境。
e2ee-cli透過 QA harness 驅動的 openclaw matrix encryption setup 和 verify * 命令列介面情境。
確切對應位於 extensions/qa-matrix/src/runners/contract/scenario-catalog.ts。

​
情境

完整情境 ID 清單是 extensions/qa-matrix/src/runners/contract/scenario-catalog.ts 中的 MatrixQaScenarioId union。分類：
  • 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-*（exec/plugin metadata、chunked fallback、deny reactions、threads，以及 target: "both" routing）
  • 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-*（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 命令列介面：matrix-e2ee-cli-*（encryption setup、idempotent setup、bootstrap failure、recovery-key lifecycle、multi-account、gateway-reply round-trip、self-verification）
傳入 --scenario <id>（可重複）即可執行手動挑選的集合；搭配 --profile all 可忽略設定檔閘控。

​
環境變數

變數預設值影響
OPENCLAW_QA_MATRIX_TIMEOUT_MS1800000（30 分鐘）整個執行的硬性上限。
OPENCLAW_QA_MATRIX_CANARY_TIMEOUT_MS45000初始金絲雀回覆的上限。Release CI 會在共享 runner 上提高此值，避免緩慢的第一次閘道回合在情境覆蓋開始前失敗。
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS8000負向無回覆斷言的靜默視窗。會限制為 <= 執行逾時。
OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS90000Docker 清理的上限。失敗畫面會包含復原用的 docker compose ... down --remove-orphans 命令。
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGEghcr.io/matrix-construct/tuwunel:v1.5.1在針對不同 Tuwunel 版本驗證時覆寫主伺服器映像檔。
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（預設為 <repo>/.artifacts/qa-e2e/matrix-<timestamp>，讓連續執行不會互相覆寫）：
  • matrix-qa-report.md：Markdown 協定報告（哪些通過、失敗、被略過，以及原因）。
  • matrix-qa-summary.json：適合 CI 解析和儀表板使用的結構化摘要。
  • matrix-qa-route-state-manifest.json：依情境 id 索引的動態 matrix-qa-v1 清單。它記錄該次執行期間觀察到的已遮蔽路由/主體形狀、請求排序、觀察到的重試、錯誤、同步權杖連續性，以及裝置/金鑰/媒體/備份狀態族。這是可執行證據，而不是簽入的基準。
  • matrix-qa-observed-events.json：來自驅動程式和觀察者用戶端的已觀察 Matrix 事件。除非設定 OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1，否則主體會被遮蔽；核准中繼資料會以選定的安全欄位和截斷的命令預覽摘要。
  • matrix-qa-output.log：該次執行的 stdout/stderr 合併輸出。如果已設定 OPENCLAW_RUN_NODE_OUTPUT_LOG，則會改為重用外層啟動器的日誌。

​
分診提示

  • 執行在接近結尾時卡住： matrix-js-sdk 的原生加密控制代碼可能比測試框架存活更久。預設會在成品寫入後強制乾淨地 process.exit；如果你設定 OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1，預期程序會停留一段時間。
  • 清理錯誤： 尋找印出的復原命令（一個 docker compose ... down --remove-orphans 呼叫），並手動執行它以釋放主伺服器連接埠。
  • CI 中負向斷言視窗不穩定： 當 CI 很快時，降低 OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS（預設 8 秒）；在緩慢的共享 runner 上則提高它。
  • 需要已遮蔽主體以供錯誤報告使用： 使用 OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1 重新執行，並附上 matrix-qa-observed-events.json。請將產生的成品視為敏感資料。
  • 不同的 Tuwunel 版本： 將 OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE 指向受測版本。此通道只簽入已釘選的預設映像檔。

​
即時傳輸合約

Matrix 是三個即時傳輸通道（Matrix、Telegram、Discord）之一，它們共用 QA overview: 即時傳輸覆蓋 中定義的單一合約檢查清單。qa-channel 仍是廣泛的合成測試套件，且有意不屬於該矩陣的一部分。

​
相關

  • QA overview：整體 QA 堆疊和即時傳輸合約
  • QA Channel：用於以 repo 為基礎情境的合成通道配接器
  • 測試：執行測試並新增 QA 覆蓋
  • Matrix：受測的通道外掛