測試

• 完整測試套件（suites、live、Docker）：測試

• pnpm test:force：終止任何佔用預設控制埠的 gateway 行程，然後以隔離的 gateway 埠執行完整 Vitest 套件，避免伺服器測試與執行中的實例衝突。當先前的 gateway 執行佔用了埠 18789 時使用。

• pnpm test:coverage：以 V8 覆蓋率執行單元套件（透過 vitest.unit.config.ts）。全域閾值為 70% 行數/分支/函式/陳述。覆蓋率排除整合密集的進入點（CLI 串接、gateway/telegram 橋接、webchat 靜態伺服器），聚焦在可單元測試的邏輯上。

• Node 22、23 和 24 上的 pnpm test 預設使用 Vitest vmForks 以加快啟動。Node 25+ 回退至 forks 直到重新驗證。可用 OPENCLAW_TEST_VM_FORKS=0|1 強制行為。

• pnpm test：預設執行快速的核心單元通道以提供快速的本地回饋。

• pnpm test:channels：執行頻道密集的套件。

• pnpm test:extensions：執行擴充套件/外掛套件。

• Gateway 整合：透過 OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test 或 pnpm test:gateway 選擇加入。

• pnpm test:e2e：執行 gateway 端對端冒煙測試（多實例 WS/HTTP/節點配對）。預設使用 vitest.e2e.config.ts 中的 vmForks + 自適應 workers；以 OPENCLAW_E2E_WORKERS=<n> 調整，設定 OPENCLAW_E2E_VERBOSE=1 取得詳細日誌。

• pnpm test:live：執行供應商即時測試（minimax/zai）。需要 API 金鑰和 LIVE=1（或供應商專屬的 *_LIVE_TEST=1）以取消跳過。

本地 PR 閘門

本地 PR 落地/閘門檢查，執行：

• pnpm check
• pnpm build
• pnpm test
• pnpm check:docs

若 pnpm test 在高負載主機上不穩定，先重跑一次再視為回歸，然後用 pnpm vitest run <path/to/test> 隔離。記憶體受限主機使用：

• OPENCLAW_TEST_PROFILE=low OPENCLAW_TEST_SERIAL_GATEWAY=1 pnpm test

模型延遲基準測試（本地金鑰）

腳本：scripts/bench-model.ts

使用方式：

• source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10
• 選用環境變數：MINIMAX_API_KEY、MINIMAX_BASE_URL、MINIMAX_MODEL、ANTHROPIC_API_KEY
• 預設 prompt：「Reply with a single word: ok. No punctuation or extra text.」

最近一次執行（2025-12-31，20 次）：

• minimax 中位數 1279ms（最小 1114，最大 2431）
• opus 中位數 2454ms（最小 1224，最大 3170）

CLI 啟動基準測試

腳本：scripts/bench-cli-startup.ts

使用方式：

• pnpm tsx scripts/bench-cli-startup.ts
• pnpm tsx scripts/bench-cli-startup.ts --runs 12
• pnpm tsx scripts/bench-cli-startup.ts --entry dist/entry.js --timeout-ms 45000

測試以下指令：

• --version
• --help
• health --json
• status --json
• status

輸出包含每個指令的 avg、p50、p95、min/max 和 exit-code/signal 分佈。

安裝引導端對端測試（Docker）

Docker 為選用；僅在容器化的安裝引導冒煙測試中需要。

完整的冷啟動流程在乾淨的 Linux 容器中：

scripts/e2e/onboard-docker.sh

此腳本透過 pseudo-tty 驅動互動式精靈，驗證設定/工作區/session 檔案，然後啟動 gateway 並執行 openclaw health。

QR 匯入冒煙測試（Docker）

確保 qrcode-terminal 在支援的 Docker Node 執行時（Node 24 預設、Node 22 相容）下可載入：

pnpm test:docker:qr