OpenClaw 測試指南：執行單元測試與效能基準檢測

身為開發者，最讓人頭痛的莫過於在提交程式碼後，才發現測試環境與生產環境的行為不一致，或是因為依賴衝突導致測試套件頻繁崩潰。為了確保 OpenClaw 的穩定性與效能，我們建立了一套完整的測試與基準測試流程，幫助你快速驗證變更並優化開發體驗。

這份指南將帶你了解如何使用 OpenClaw 進行測試、效能基準評估以及容器化環境的驗證。

測試

這是一套完整的測試工具組，包含測試套件、即時測試與 Docker 支援：Testing

1. pnpm test:force: 終止任何佔用預設控制 port 的殘留 Gateway 進程，然後以隔離的 Gateway port 執行完整的 Vitest 套件，確保伺服器測試不會與正在執行的實例衝突。當之前的 Gateway 執行導致 port 18789 被佔用時，請使用此指令。
2. pnpm test:coverage: 使用 V8 覆蓋率執行單元測試套件（透過 vitest.unit.config.ts）。這是一個已載入檔案的單元覆蓋率閘道，而非全儲存庫的檔案覆蓋率。門檻為 70% 的行數/函數/語句以及 55% 的分支。由於 coverage.all 為 false，此閘道測量的是由單元覆蓋率套件載入的檔案，而不是將每個拆分路徑的原始碼檔案視為未覆蓋。
3. pnpm test:coverage:changed: 僅針對自 origin/main 以來變更過的檔案執行單元覆蓋率測試。
4. pnpm test:changed: 當 diff 僅涉及可路由的原始碼/測試檔案時，將變更的 git 路徑擴展為範圍限定的 Vitest 通道。配置/設定變更仍會回退到原生的根專案執行，因此在需要時可以廣泛地重新執行佈線編輯。
5. pnpm changed:lanes: 顯示針對 origin/main 的 diff 所觸發的架構通道。
6. pnpm check:changed: 針對 origin/main 的 diff 執行智慧變更閘道。它使用核心測試通道執行核心工作，使用擴充功能測試通道執行擴充功能工作，使用測試型別檢查/測試執行僅測試工作，並將公開的 Plugin SDK 或插件合約變更擴展到擴充功能驗證。
7. pnpm test: 透過範圍限定的 Vitest 通道路由明確的檔案/目錄目標。未設定目標的執行會使用固定的分片群組，並擴展到葉節點配置以進行本地平行執行；擴充功能群組總是擴展到每個擴充功能的分片配置，而不是一個巨大的根專案進程。
8. 完整與擴充功能分片執行會更新 .artifacts/vitest-shard-timings.json 中的本地計時資料；後續執行會使用這些計時來平衡慢速與快速分片。設定 OPENCLAW_TEST_PROJECTS_TIMINGS=0 可忽略本地計時產物。
9. 選定的 plugin-sdk 和 commands 測試檔案現在透過專用的輕量通道路由，僅保留 test/setup.ts，將執行繁重的案例留在現有的通道上。
10. 選定的 plugin-sdk 和 commands 輔助原始碼檔案也將 pnpm test:changed 對應到這些輕量通道中的明確兄弟測試，因此小的輔助編輯可以避免重新執行繁重的執行階段支援套件。
11. auto-reply 現在也拆分為三個專用配置（core、top-level、reply），因此回覆工具不會佔用較輕量的頂層狀態/令牌/輔助測試。
12. 基礎 Vitest 配置現在預設為 pool: "threads" 和 isolate: false，並在儲存庫配置中啟用共享的非隔離執行器。
13. pnpm test:channels 執行 vitest.channels.config.ts。
14. pnpm test:extensions 和 pnpm test extensions 執行所有擴充功能/插件分片。繁重的頻道擴充功能和 OpenAI 作為專用分片執行；其他擴充功能群組保持批次處理。使用 pnpm test extensions/<id> 執行單一捆綁插件通道。
15. pnpm test:perf:imports: 啟用 Vitest 匯入持續時間 + 匯入細分報告，同時仍對明確的檔案/目錄目標使用範圍限定的通道路由。
16. pnpm test:perf:imports:changed: 相同的匯入分析，但僅針對自 origin/main 以來變更過的檔案。
17. pnpm test:perf:changed:bench -- --ref <git-ref> 針對相同的已提交 git diff，對路由變更模式路徑與原生根專案執行進行基準測試。
18. pnpm test:perf:changed:bench -- --worktree 在不先提交的情況下，對當前的工作樹變更集進行基準測試。
19. pnpm test:perf:profile:main: 為 Vitest 主執行緒寫入 CPU 設定檔（.artifacts/vitest-main-profile）。
20. pnpm test:perf:profile:runner: 為單元執行器寫入 CPU + 堆疊設定檔（.artifacts/vitest-runner-profile）。
21. Gateway 整合：透過 OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test 或 pnpm test:gateway 選擇加入。
22. pnpm test:e2e: 執行 Gateway 端對端冒煙測試（多實例 WS/HTTP/Node.js 配對）。預設為 threads + isolate: false，並在 vitest.e2e.config.ts 中使用自適應工作執行緒；透過 OPENCLAW_E2E_WORKERS=<n> 進行調整，並設定 OPENCLAW_E2E_VERBOSE=1 以獲取詳細日誌。
23. pnpm test:live: 執行提供者即時測試（minimax/zai）。需要 API 密鑰和 LIVE=1（或提供者特定的 *_LIVE_TEST=1）才能取消跳過。
24. pnpm test:docker:openwebui: 啟動 Docker 化的 OpenClaw + Open WebUI，透過 Open WebUI 登入，檢查 /api/models，然後透過 /api/chat/completions 執行真實的代理聊天。需要可用的即時模型密鑰（例如 ~/.profile 中的 OpenAI），拉取外部 Open WebUI 映像，且預期不會像正常的單元/e2e 套件那樣在 CI 中保持穩定。
25. pnpm test:docker:mcp-channels: 啟動一個種子 Gateway 容器和第二個客戶端容器，後者會產生 openclaw mcp serve，然後驗證路由對話發現、轉錄讀取、附件元資料、即時事件佇列行為、出站傳送路由以及透過真實 stdio 橋接的 Claude 風格頻道 + 權限通知。Claude 通知斷言直接讀取原始 stdio MCP 影格，因此冒煙測試反映了橋接器實際發出的內容。

Local PR gate

在進行本地 PR 合併或閘道檢查時，請執行以下步驟：

1. pnpm check:changed
2. pnpm check
3. pnpm check:test-types
4. pnpm build
5. pnpm test
6. pnpm check:docs

如果 pnpm test 在已載入的主機上不穩定，請在將其視為回歸之前重新執行一次，然後使用 pnpm test <path/to/test> 進行隔離。對於記憶體受限的主機，請使用：

1. OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
2. OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed

Model latency bench (local keys)

此腳本用於評估模型延遲，相關程式碼位於：scripts/bench-model.ts

使用方式如下：

1. source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10
2. 可選環境變數：MINIMAX_API_KEY, MINIMAX_BASE_URL, MINIMAX_MODEL, ANTHROPIC_API_KEY
3. 預設提示詞：“Reply with a single word: ok. No punctuation or extra text.”

上次執行結果（2025-12-31, 20 次執行）：

1. minimax 中位數 1279ms (最小 1114, 最大 2431)
2. opus 中位數 2454ms (最小 1224, 最大 3170)

CLI startup bench

此腳本用於評估 CLI 啟動效能，相關程式碼位於：scripts/bench-cli-startup.ts

使用方式如下：

1. pnpm test:startup:bench
2. pnpm test:startup:bench:smoke
3. pnpm test:startup:bench:save
4. pnpm test:startup:bench:update
5. pnpm test:startup:bench:check
6. pnpm tsx scripts/bench-cli-startup.ts
7. pnpm tsx scripts/bench-cli-startup.ts --runs 12
8. pnpm tsx scripts/bench-cli-startup.ts --preset real
9. pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --case gatewayStatus --runs 3
10. pnpm tsx scripts/bench-cli-startup.ts --entry openclaw.mjs --entry-secondary dist/entry.js --preset all
11. pnpm tsx scripts/bench-cli-startup.ts --preset all --output .artifacts/cli-startup-bench-all.json
12. pnpm tsx scripts/bench-cli-startup.ts --preset real --case gatewayStatusJson --output .artifacts/cli-startup-bench-smoke.json
13. pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
14. pnpm tsx scripts/bench-cli-startup.ts --json

預設集說明：

1. startup: --version, --help, health, health --json, status --json, status
2. real: health, status, status --json, sessions, sessions --json, agents list --json, gateway status, gateway status --json, gateway health --json, config get gateway.port
3. all: 包含上述兩個預設集

輸出包含每個指令的 sampleCount、平均值、p50、p95、最小/最大值、退出代碼/訊號分佈以及最大 RSS 摘要。可選的 --cpu-prof-dir / --heap-prof-dir 會為每次執行寫入 V8 設定檔，因此計時和設定檔擷取使用相同的工具。

已儲存輸出的慣例：

1. pnpm test:startup:bench:smoke 將目標冒煙測試產物寫入 .artifacts/cli-startup-bench-smoke.json
2. pnpm test:startup:bench:save 使用 runs=5 和 warmup=1 將完整套件產物寫入 .artifacts/cli-startup-bench-all.json
3. pnpm test:startup:bench:update 使用 runs=5 和 warmup=1 更新 test/fixtures/cli-startup-bench.json 中的簽入基準固定裝置

簽入的固定裝置：

1. test/fixtures/cli-startup-bench.json
2. 使用 pnpm test:startup:bench:update 重新整理
3. 使用 pnpm test:startup:bench:check 將當前結果與固定裝置進行比較

Onboarding E2E (Docker)

Docker 是選用的；這僅用於容器化的開箱冒煙測試。

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

scripts/e2e/onboard-docker.sh

此腳本透過虛擬終端機驅動互動式精靈，驗證配置/工作區/會話檔案，然後啟動 Gateway 並執行 openclaw health。

QR import smoke (Docker)

確保 qrcode-terminal 在支援的 Docker Node.js 執行階段（預設為 Node.js 24，相容 Node.js 22）下正常載入：

pnpm test:docker:qr

---

相關文件

• Testing

如果你在測試過程中遇到任何問題，歡迎隨時透過 AI Setup Assistant 尋求協助。