OpenClaw QA 測試

OpenClaw QA 測試 是做什麼的？

使用此技能進行 qa-lab / qa-channel 相關工作。僅限於儲存庫本地端的 QA。

請先閱讀

• docs/concepts/qa-e2e-automation.md
• docs/help/testing.md
• docs/channels/qa-channel.md
• qa/README.md
• qa/scenarios/index.yaml
• extensions/qa-lab/src/suite.ts
• extensions/qa-lab/src/character-eval.ts

模型政策

• 正常的即時測試套件運行應依賴 QA Lab 的來源及認證相關預設值。
• 預設情況下請勿傳入 --model、--alt-model 或 --fast。省略 --fast 不代表停用快速模式；快速行為由來源端管理。
• 對於特定場景的運行，完整的 execution.summary 具有權威性，並會覆蓋一般的預設指引，包括當它要求其他旗標時的情況。僅在 execution.config.requiredProvider 或 requiredModel 要求時，才加入明確的提供商/模型指定。

預設工作流程

1. 閱讀場景包與目前的套件實作。
2. 決定運行管道：
   • 模擬/開發：mock-openai
   • 真實驗證：live-frontier
3. 對於正常的即時套件，使用：

pnpm openclaw qa suite \
  --provider-mode live-frontier \
  --output-dir .artifacts/qa-e2e/run-all-live-frontier-<tag>

4. 監看輸出：
   • 摘要：.artifacts/qa-e2e/run-all-live-frontier-<tag>/qa-suite-summary.json
   • 報告：.artifacts/qa-e2e/run-all-live-frontier-<tag>/qa-suite-report.md
5. 如果使用者想要觀看即時 UI，請找到目前的 openclaw-qa 監聽埠號並回報 http://127.0.0.1:<port>。
6. 如果某個場景失敗，請修正產品或測試框架的根本原因，然後重新執行完整管道。

OTEL 煙霧測試

若要進行本機 QA-lab 的 OpenTelemetry 驗證，請使用：

pnpm qa:otel:smoke

這會啟動一個本機的 OTLP/HTTP 追蹤接收器，透過 qa-channel 執行 otel-trace-smoke 場景，解碼發出的 protobuf 跨度，並驗證匯出的追蹤名稱與隱私合約。此過程不需要 Opik、Langfuse 或外部收集器憑證。

QA 憑證與 1Password

• 在此儲存庫中，僅在 tmux 內使用 op 進行 QA 密碼查詢。
• 在 tmux 內快速檢查認證狀態：

op account list

• 直接使用 Telegram npm 即時測試的密碼目前存放於 1Password 項目中：
  • 保管庫：OpenClaw
  • 項目：Telegram E2E
• 該項目是查詢下列項目的首要位置：
  • OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN
  • OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN
  • OPENCLAW_QA_PROVIDER_MODE
  • OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC
• Convex QA 秘密目前存放於 1Password 項目中：
  • 保管庫：OpenClaw
  • 項目：OPENCLAW_QA_CONVEX_SITE_URL
  • 項目：OPENCLAW_QA_CONVEX_SECRET_MAINTAINER
  • 項目：OPENCLAW_QA_CONVEX_SECRET_CI
• 其他在 QA 憑證工作中看到的相關註記/登入項目：
  • 保管庫：Private
  • 項目：OPENCLAW QA、Convex、Telegram
• 如果上述註記中缺少必要的值：
  • 請不要猜測
  • 請向維護者/操作者詢問目前的值或目前的 1Password 項目名稱
  • 對於 Telegram 直接運行，OPENCLAW_QA_TELEGRAM_GROUP_ID 可能與 Telegram E2E 分開存放
  • 對於 Convex 運行，租用的 Telegram 憑證應同時提供 Telegram 群組 ID 與機器人 Token；無需另外要求獨立的 OPENCLAW_QA_TELEGRAM_GROUP_ID
  • 對於 Convex 運行，優先使用 OpenClaw/OPENCLAW_QA_CONVEX_SITE_URL；如果該值過時或不清楚，請在運行前詢問有效的池 URL
• 當可用時，對於 npm Telegram Docker 管道，偏好直接使用 Telegram 環境變數：

OPENCLAW_QA_TELEGRAM_GROUP_ID="..." \
OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN="..." \
OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN="..." \
OPENCLAW_QA_PROVIDER_MODE="mock-openai" \
OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC="openclaw@beta" \
pnpm test:docker:npm-telegram-live

• 當目標是穩定的共享 QA 基礎設施時，偏好使用 Convex 模式：
  • 輪詢式憑證租用
  • 針對特定頻道設定的更精簡包裝
  • 圍繞共用憑證的 CLI/管理流程
• 即時 npm Telegram Docker 管道注意事項：
  • scripts/e2e/npm-telegram-live-runner.ts 讀取 OPENCLAW_NPM_TELEGRAM_PROVIDER_MODE
  • 不要假設 OPENCLAW_QA_PROVIDER_MODE 會被該包裝器使用
  • 如果 1Password 註記只提供了 OPENCLAW_QA_PROVIDER_MODE，請在執行 Docker 管道前明確將其映射為 OPENCLAW_NPM_TELEGRAM_PROVIDER_MODE
• 已驗證的即時運行形狀：
  • Convex 模式可以在沒有直接 Telegram 環境變數的情況下通過真實的 Docker 管道
  • 租用的 Telegram 酬載包含與驅動程式/SUT Token 配對的群組 ID
  • 使用以下設定實際執行 pnpm test:docker:npm-telegram-live 已成功：
    • OPENCLAW_QA_CREDENTIAL_SOURCE=convex
    • OPENCLAW_QA_CREDENTIAL_ROLE=maintainer
    • OPENCLAW_QA_CONVEX_SITE_URL
    • OPENCLAW_QA_CONVEX_SECRET_MAINTAINER
    • OPENCLAW_NPM_TELEGRAM_PROVIDER_MODE=mock-openai
• 如果本地缺少直接的 Telegram 環境變數且 op signin 受阻，請優先觸發手動 GitHub 管道，因為 qa-live-shared 環境已具有 Convex CI 憑證：

gh workflow run "NPM Telegram Beta E2E" --repo openclaw/openclaw --ref main \
  -f [email protected] \
  -f [email protected] \
  -f provider_mode=mock-openai

• 從觸發 URL 中輪詢確切的執行 ID。gh run view --json artifacts 不支援；請使用以下方式列出工件：

gh api repos/openclaw/openclaw/actions/runs/<run-id>/artifacts

WhatsApp 即時憑證

在設定或取代類型為 kind=whatsapp 的 Convex 憑證時使用。

• 將 WhatsApp QA 憑證視為操作者擁有的即時帳戶，而非產生的固定資料。
• 使用兩個專用的 WhatsApp 可用測試號碼：一個驅動程式帳戶和一個 SUT 帳戶。請勿在共用池中使用個人號碼或個人的 OpenClaw WhatsApp 帳戶。
• 手動向 WhatsApp 或 WhatsApp Business 註冊並連結每個帳戶，僅將 Web 認證資料儲存在儲存庫外隔離的本機 auth 目錄中。
• 為了群組覆蓋範圍，請建立一個包含兩個 QA 帳戶的專用測試群組，並將其 JID 儲存為 groupJid；否則預設應跳過群組提及限制場景，並在明確要求時失敗。
• 將兩個 Baileys auth 目錄打包成 base64 .tgz 酬載欄位，並新增一個有效的 Convex 憑證列。建議新增一個新列並停用過時/損壞的列，而不是原地覆寫憑證。
• 預期的酬載欄位：driverPhoneE164、sutPhoneE164、driverAuthArchiveBase64、sutAuthArchiveBase64 和可選的 groupJid。
• 將憑證資料排除在儲存庫、日誌、PR 和螢幕截圖之外。除非操作者明確要求本地除錯，否則請隱藏電話號碼。
• 使用 pnpm openclaw qa whatsapp --credential-source convex --credential-role maintainer --provider-mode mock-openai 進行驗證，並保留工件路徑以及隱藏敏感資訊的通過/失敗摘要。
• 如果 WhatsApp 使連結的 Web 會話過期或失效，請在本地重新連結，打包新的 auth 存檔，新增一個 Convex 列，然後停用過時的列。

角色評估

使用 qa character-eval 在多個即時模型上進行風格/人格/氛圍檢查。

pnpm openclaw qa character-eval \
  --output-dir .artifacts/qa-e2e/character-eval-<tag>

• 執行本機 QA 閘道子程序，而非 Docker。
• 打包後的 pnpm build 依設計會省略 QA Lab + qa-channel（僅限原始碼簽出）。若要從建置後的 dist 執行 openclaw qa/qa-channel，請使用 OPENCLAW_BUILD_PRIVATE_QA=1 pnpm build 進行建置（會產生 dist/plugin-sdk/qa-lab.js、qa-runtime.js、dist/extensions/{qa-lab,qa-channel}）或透過 pnpm dev 執行。
• 在沒有模型旗標的情況下，角色評估會使用其目前來源定義的候選模型、評審模型、思考模型和快速預設值。
• 僅在需要明確替換對應庫存時，才重複使用 --model provider/model,thinking=<level>[,fast|,no-fast|,fast=<bool>] 或 --judge-model ...。
• 請勿新增帶有獨立 --model-thinking 的新範例；將該旗標保留為僅供向後相容的舊版功能。
• 報告包含評審排名、運行統計、持續時間和完整對話記錄；請勿包含原始評審回覆。持續時間是基準測試的背景資訊，而非評分訊號。
• 候選模型和評審模型的並發數預設為 16。當本機閘道或提供商限制需要更溫和的管道時，請使用 --concurrency <n> 和 --judge-concurrency <n> 進行覆寫。
• 場景來源僅限於 qa/scenarios/ 下的 YAML 檔案：使用 index.yaml 和每個場景的 *.yaml 檔案，包含頂層的 title、scenario 以及可選的 flow。請勿新增以 qa-scenario / qa-flow 為籬柵的 Markdown 檔案。
• 對於隔離的角色/人格評估，請將人格寫入 SOUL.md，並在場景流程中清空 IDENTITY.md。僅在有意測試正常的 OpenClaw 身份如何與該角色結合時，才使用 SOUL.md + IDENTITY.md。
• 保持提示自然且以任務為導向。候選模型應透過 SOUL.md 接收角色設定，然後進行正常的使用者互動，例如聊天、工作區幫助和小型檔案任務；請勿詢問「你會如何反應？」或告知模型它處於評估中。
• 偏好至少包含一個真實任務，例如建立或編輯一個小型工作區工件，以便對話記錄能夠捕捉角色在正常工具使用下的表現，而非純粹的角色扮演。

Codex CLI 模型管道

每當 QA 應將 Codex 作為模型後端進行測試時，請使用形如 codex-cli/<codex-model> 的模型參考。

範例：

pnpm openclaw qa suite \
  --provider-mode live-frontier \
  --model codex-cli/<codex-model> \
  --alt-model codex-cli/<codex-model> \
  --scenario <scenario-id> \
  --output-dir .artifacts/qa-e2e/codex-<tag>

pnpm openclaw qa manual \
  --model codex-cli/<codex-model> \
  --message "請僅回覆：CODEX_OK"

• 將具體的 Codex 模型名稱視為使用者/組態輸入；請勿在原始碼、文件範例或場景中對其進行硬編碼。
• 即時 QA 會保留 CODEX_HOME，以便 Codex CLI 認證/配置能夠正常運作，同時將 HOME 和 OPENCLAW_HOME 置於沙箱中。
• 模擬 QA 應清除 CODEX_HOME。
• 如果 Codex 在每次互動時都回傳後備/認證文字，請在更改場景斷言之前，先檢查 CODEX_HOME、相關的密碼認證以及閘道子程序日誌。
• 若要進行模型比較，請在 qa character-eval 中將 codex-cli/<codex-model> 作為另一個候選模型包含在內；報告應將其標示為一個不透明的模型名稱。

儲存庫事實

• 種子場景位於 qa/scenarios/index.yaml 和 qa/scenarios/<theme>/*.yaml。
• 主要的即時執行器：extensions/qa-lab/src/suite.ts
• QA lab 伺服器：extensions/qa-lab/src/lab-server.ts
• 子閘道框架：extensions/qa-lab/src/gateway-child.ts
• 合成頻道：extensions/qa-channel/

「完成」的樣貌

• 所要求管道的完整測試套件全部通過（綠燈）。
• 使用者會獲得：
  • 監看 URL（如果適用）
  • 通過/失敗計數
  • 工件路徑
  • 關於已修正問題的簡潔說明

常見失敗模式

• 即時超時時間過短：
  • 在 extensions/qa-lab/src/suite.ts 中加長即時等待時間
• 探索功能找不到儲存庫檔案：
  • 將提示指向已播種工作區內的 repo/...
• 子代理的證據過於脆弱：
  • 偏好穩定的最終回覆證據，而非短暫的子會話清單
• 測試框架「重建」延遲：
  • 髒污的工作樹可能會觸發運行前的建置；請預期此情況發生在連接埠出現之前

新增場景時

• 在 qa/scenarios/ 下新增或更新場景 YAML 檔案；請勿新增 .md 場景檔案或籬柵 YAML 區塊。
• 保持 qa/scenarios/index.yaml 中的啟動期望一致
• 在 extensions/qa-lab/src/suite.ts 中新增可執行的測試覆蓋
• 偏好端到端斷言而非僅模擬檢查
• 將輸出儲存在 .artifacts/qa-e2e/ 下