測試

• 完整測試套件（測試套件、即時測試、Docker）：測試
• 更新與外掛套件驗證：測試更新與外掛

Agent 預設行為

只有在來源可信任且現有相依套件已安裝妥當時，Agent 工作階段才會在本機執行一個或少數幾個聚焦測試及低成本靜態檢查。絕不在本機執行不受信任的儲存庫工具。較大型的測試套件、會展開型別檢查／程式碼檢查的變更閘門、建置、Docker、套件流程、E2E、即時證明及跨平台驗證，皆透過 Crabbox 遠端執行。受信任維護者的高負載證明預設使用 Blacksmith Testbox。已設定的 Testbox 工作流程會載入認證資訊，因此不受信任的貢獻者或分支程式碼必須改用不含祕密資訊的分支 CI，或經過清理的直接 AWS Crabbox。

不要為預期中的工作預先暖機。等第一個高負載命令準備就緒時，再延遲取得後端；後續高負載命令重複使用傳回的 tbx_... ID；每次執行時同步目前的簽出內容，並在交接前停止後端。

首次成功重複使用後，包裝程式會將租用環境的基底、相依套件及 Testbox 工作流程指紋記錄於 .crabbox/testbox-leases/。僅修改原始碼時，會繼續重複使用已暖機的環境。若合併基底、鎖定檔、套件管理器輸入、包裝程式或 Testbox 工作流程有所變更，系統會採取失敗關閉策略，並要求全新的租用環境。每次執行仍會同步目前的簽出內容。 OPENCLAW_TESTBOX_ALLOW_STALE=1 僅供刻意進行診斷時使用，不可作為發行證明。

下方的本機測試命令適用於人工工作流程與範圍受限的 Agent 證明。若遠端供應者無法使用，必須回報；這不代表可以默默改在本機執行廣泛閘門。

對於不受信任的高負載證明，請使用 --provider aws 延遲暖機。每次執行都必須設定 CRABBOX_ENV_ALLOW=CI、傳入 --provider aws --no-hydrate，並在安裝相依套件或執行測試前使用全新的暫時遠端 HOME。使用專供該不受信任來源、全新暖機的租用環境；絕不重複使用受信任或先前已載入認證資訊的租用環境。從乾淨且受信任的 main 簽出內容啟動已安裝且受信任的 Crabbox 二進位檔，並只使用 --fresh-pr 擷取遠端 PR；絕不在本機執行不受信任簽出內容中的包裝程式或設定。取消設定 CRABBOX_AWS_INSTANCE_PROFILE，且除非解析後的 aws.instanceProfile 為空，否則採取失敗關閉策略。進行任何安裝／測試之前，請使用受信任的絕對路徑工具要求 IMDSv2 權杖、證明 IAM 認證資訊端點傳回 404，並驗證遠端 git rev-parse HEAD 等於完整且已審查的 PR 頭部 SHA。將租用環境綁定至該 SHA，並在頭部變更時停止及重新暖機。將乾淨 main 中受信任的 scripts/crabbox-untrusted-bootstrap.sh 與 --fresh-pr 一併上傳；它會安裝固定版本的 Node/pnpm、驗證 SHA 與套件管理器版本固定設定、隔離 HOME、安裝相依套件，然後執行要求的測試。若代理程式無法證明不存在角色或遠端 PR，請使用不含祕密資訊的分支 CI。不要使用 hydrate-github、--no-sync 或會載入認證資訊的 Testbox 工作流程。 取消設定所有 CRABBOX_TAILSCALE* 覆寫、強制使用 --network public --tailscale=false、清除出口節點／LAN 旗標，並要求 crabbox inspect 在上傳任何指令碼之前，回報未包含任何 Tailscale 狀態的公用網路連線。

例行本機順序

1. pnpm test:changed 用於變更範圍的 Vitest 證明。
2. pnpm test <path-or-filter> 用於單一檔案、目錄或明確目標。
3. 只有在刻意需要完整本機 Vitest 測試套件時，才使用 pnpm test。

在 Codex 工作樹或連結／稀疏簽出中，Agent 應避免直接在本機使用 pnpm test*／pnpm check*／pnpm crabbox:run：

• 相依套件已就緒時的範圍受限聚焦證明： node scripts/run-vitest.mjs <path-or-filter>。
• 先分類再進行的變更檢查：node scripts/check-changed.mjs；僅文件、無變更及小型中繼資料方案會在相依套件已就緒時保留於本機執行，而高負載或缺少相依套件的方案則委派給 Testbox。
• 明確保留租用環境的廣泛證明：node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox ... -- env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 corepack pnpm check:changed，使 pnpm 在 Testbox 內執行。
• 包裝程式最後的 exitCode 與計時 JSON 即為命令結果。委派的 Blacksmith GitHub Actions 執行在 SSH 命令成功後可能顯示 cancelled，因為 Testbox 是從保活動作外部停止；將其視為失敗前，請先檢查包裝程式摘要與命令輸出。
• OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command>：對於 pnpm check:changed 及指定目標的 pnpm test ... 等命令，會將高負載檢查的序列化保留在目前工作樹內，而不是 Git 共用目錄中。只有在高容量本機主機上刻意跨連結工作樹執行獨立檢查時，才使用此功能。

核心命令

測試包裝程式執行結束時會顯示簡短的 [test] passed|failed|skipped ... in ... 摘要；Vitest 本身的持續時間行則保留為各分片的詳細資訊。

共用測試狀態與程序輔助工具

• src/test-utils/openclaw-test-state.ts：當測試需要隔離的 HOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH、設定固定資料、工作區、Agent 目錄或驗證設定檔儲存區時，請從 Vitest 使用。
• pnpm test:env-mutations:report：以非阻斷方式回報直接修改 HOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH、OPENCLAW_WORKSPACE_DIR 或相關環境變數鍵的測試／測試框架。使用此功能尋找適合遷移至共用測試狀態輔助工具的候選項目。
• test/helpers/openclaw-test-instance.ts：將需要執行中閘道、命令列介面環境、日誌擷取及清理作業的程序層級 E2E 測試集中處理。
• 載入 scripts/lib/docker-e2e-image.sh 的 Docker／Bash E2E 流程可將 docker_e2e_test_state_shell_b64 <label> <scenario> 傳入容器，並使用 scripts/lib/openclaw-e2e-instance.sh 解碼；多主目錄指令碼可傳入 docker_e2e_test_state_function_b64，並在每個流程中呼叫 openclaw_test_state_create <label> <scenario>。node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json 會寫入可供載入的主機環境檔案（create 前的 -- 可避免較新的 Node 執行環境將 --env-file 視為 Node 旗標）。啟動閘道的流程可載入 scripts/lib/openclaw-e2e-instance.sh，用於進入點解析、模擬 OpenAI 啟動、前景／背景啟動、就緒探測、狀態環境變數匯出、日誌傾印及程序清理。

Control UI、終端介面與擴充功能流程

• Control UI 模擬 E2E： pnpm test:ui:e2e 會執行 Vitest + Playwright 測試管線，啟動 Vite Control UI，並以真實 Chromium 頁面連線至模擬的閘道 WebSocket。測試位於 ui/src/**/*.e2e.test.ts；共用模擬與控制項位於 ui/src/test-helpers/control-ui-e2e.ts。pnpm test:e2e 包含此測試管線。代理程式執行預設使用 Testbox/Crabbox，包括針對性驗證；僅在明確需要本機備援時使用 node scripts/run-vitest.mjs run --config test/vitest/vitest.ui-e2e.config.ts --configLoader runner ui/src/ui/e2e/chat-flow.e2e.test.ts。
• 終端介面 PTY 測試： node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts 會執行快速的模擬後端 PTY 測試管線。OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 或 pnpm tui:pty:test:watch --mode local 會執行較慢的 tui --local 冒煙測試，該測試僅模擬外部模型端點。請斷言穩定的可見文字或測試資料呼叫，而非原始 ANSI 快照。
• pnpm test:extensions 和 pnpm test extensions 會執行所有擴充功能／外掛分片。負載較重的頻道外掛、瀏覽器外掛和 OpenAI 會使用專用分片執行；其他外掛群組則維持批次執行。pnpm test extensions/<id> 會執行一個內建外掛測試管線。
• 具有同層測試的原始碼檔案會先對應至該同層測試，再退回至範圍較廣的目錄 glob。對 src/channels/plugins/contracts/test-helpers、src/plugin-sdk/test-helpers 和 src/plugins/contracts 下輔助程式的編輯，會使用本機匯入圖來執行匯入它們的測試；當相依性路徑明確時，不會廣泛執行每個分片。
• 合約目錄目標會展開至各自的合約測試管線：pnpm test src/channels/plugins/contracts 會執行四個頻道合約設定，而 pnpm test src/plugins/contracts 會執行外掛合約設定，因為通用的 channels/plugins 專案會排除 contracts/**。
• auto-reply 會拆分成三個專用設定（core、top-level、reply），避免回覆測試框架佔用較輕量的頂層狀態／權杖／輔助程式測試的大部分資源。
• 選定的 plugin-sdk 和 commands 測試檔案會透過專用的輕量測試管線執行，這些管線僅保留 test/setup.ts，而執行階段負載較重的案例則留在其既有測試管線中。
• 基礎 Vitest 設定預設為 pool: "threads" 和 isolate: false，並在整個儲存庫的設定中啟用共用的非隔離執行器。
• pnpm test:channels 會執行 vitest.channels.config.ts。

閘道與 E2E

• 閘道整合為選用功能：OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test 或 pnpm test:gateway。
• pnpm test:e2e：儲存庫 E2E 彙總 = pnpm test:e2e:gateway && pnpm test:ui:e2e。
• pnpm test:e2e:gateway：閘道端對端冒煙測試（多執行個體 WS/HTTP/節點配對）。在 vitest.e2e.config.ts 中預設使用 threads + isolate: false 與自適應工作程序；使用 OPENCLAW_E2E_WORKERS=<n> 調整，使用 OPENCLAW_E2E_VERBOSE=1 啟用詳細記錄。
• pnpm test:live：供應商即時測試（Claude/Minimax/DeepSeek/z.ai/等，由 *.live.test.ts 控制）。需要 API 金鑰以及 LIVE=1（或 OPENCLAW_LIVE_TEST=1）才能取消略過；使用 OPENCLAW_LIVE_TEST_QUIET=0 啟用詳細輸出。

完整 Docker 套件（pnpm test:docker:all）

建置共用的即時測試映像，將 OpenClaw 一次封裝為 npm tarball，建置／重複使用精簡的 Node/Git 執行器映像，以及將該 tarball 安裝至 /app 的功能映像，接著透過加權排程器執行 Docker 冒煙測試管線。scripts/package-openclaw-for-docker.mjs 是唯一的本機／CI 套件封裝器，會先驗證 tarball 與 dist/postinstall-inventory.json，再交由 Docker 使用。

• 精簡映像（OPENCLAW_DOCKER_E2E_BARE_IMAGE）：安裝程式／更新／外掛相依性測試管線；掛載預先建置的 tarball，而非複製的儲存庫原始碼。
• 功能映像（OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE）：一般已建置應用程式功能測試管線。
• 測試管線定義：scripts/lib/docker-e2e-scenarios.mjs。規劃器：scripts/lib/docker-e2e-plan.mjs。執行器：scripts/test-docker-all.mjs。
• node scripts/test-docker-all.mjs --plan-json 會輸出由排程器管理的 CI 計畫（測試管線、映像種類、套件／即時映像需求、狀態情境、認證資訊檢查），但不建置或執行 Docker。

排程調整參數（環境變數，括號內為預設值）：

資源上限的環境變數模式為 OPENCLAW_DOCKER_ALL_<RESOURCE>_LIMIT（資源名稱轉為大寫，非英數字元會合併為 _）。

其他行為：執行器預設會預先檢查 Docker、清理過期的 OpenClaw E2E 容器、在相容的執行通道之間共用供應商命令列介面工具快取，並在第一次失敗後停止排程新的集區執行通道，除非已設定 OPENCLAW_DOCKER_ALL_FAIL_FAST=0。如果某個執行通道在低平行度主機上超過有效權重／資源上限，它仍可從空集區啟動並獨立執行，直到釋放容量。各執行通道的記錄、summary.json、failures.json 與階段計時會寫入 .artifacts/docker-tests/<run-id>/；使用 pnpm test:docker:timings <summary.json> 檢查緩慢的執行通道，並使用 pnpm test:docker:rerun <run-id|summary.json|failures.json> 輸出成本低廉的針對性重新執行命令。

值得注意的 Docker 執行通道

本機 PR 閘門

若要執行本機 PR 合併／閘門檢查，請執行：

• pnpm check:changed
• pnpm check
• pnpm check:test-types
• pnpm build
• pnpm test
• pnpm check:docs

如果 pnpm test 在高負載主機上偶發失敗，請先重新執行一次，再將其視為迴歸，接著使用 pnpm test <path/to/test> 加以隔離。對於記憶體受限的主機：

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

測試效能工具

• pnpm test:perf:imports：啟用 Vitest 匯入時間與匯入明細報告，同時仍對明確的檔案／目錄目標使用限定範圍的執行通道路由。pnpm test:perf:imports:changed 將相同的效能分析限定於自 origin/main 起已變更的檔案。
• pnpm test:perf:changed:bench -- --ref <git-ref> 會針對相同的已提交 git 差異，比較經路由的變更模式路徑與原生根專案執行的基準；pnpm test:perf:changed:bench -- --worktree 則在不先提交的情況下，對目前工作樹的變更集進行基準測試。
• pnpm test:perf:profile:main 會為 Vitest 主執行緒寫入 CPU 效能分析（.artifacts/vitest-main-profile）；pnpm test:perf:profile:runner 會為單元測試執行器寫入 CPU 與堆積效能分析（.artifacts/vitest-runner-profile）。
• pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json：依序執行每個完整測試套件的 Vitest 葉節點設定，並寫入分組的執行時間資料，以及各設定的 JSON／記錄成品。完整測試套件報告預設會隔離檔案，因此先前檔案所保留的模組圖與 GC 暫停時間不會計入後續斷言；只有在刻意分析共用工作執行緒的累積情況時，才傳入 -- --no-isolate。測試效能代理程式會在嘗試修正緩慢測試前，以此作為基準。pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json 會比較效能導向變更前後的分組報告。
• 完整、擴充功能與包含模式的分片執行會更新 .artifacts/vitest-shard-timings.json 中的本機計時資料；後續的完整設定執行會使用這些計時來平衡較慢與較快的分片。包含模式的 CI 分片會將分片名稱附加至計時鍵，讓篩選後的分片計時保持可見，而不會取代完整設定的計時資料。設定 OPENCLAW_TEST_PROJECTS_TIMINGS=0 可忽略本機計時成品。

基準測試

pnpm tsx scripts/bench-model.ts --runs 10

pnpm test:startup:benchpnpm test:startup:bench:smokepnpm test:startup:bench:savepnpm test:startup:bench:updatepnpm test:startup:bench:checkpnpm tsx scripts/bench-cli-startup.ts --runs 12pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --case gatewayStatus --runs 3pnpm tsx scripts/bench-cli-startup.ts --entry openclaw.mjs --entry-secondary dist/entry.js --preset all

pnpm test:startup:gateway -- --runs 5 --warmup 1pnpm test:startup:gateway -- --case skipChannels --case fiftyPlugins --runs 5node --import tsx scripts/bench-gateway-startup.ts --case default --runs 5 --output .artifacts/gateway-startup.json

pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5pnpm test:restart:gateway -- --case default --runs 3 --restarts 3 --warmup 1

新手引導端對端測試（Docker）

選用；僅容器化新手引導煙霧測試需要。在乾淨的 Linux 容器中執行完整的冷啟動流程：

scripts/e2e/onboard-docker.sh

透過虛擬終端機驅動互動式精靈，驗證設定／工作區／工作階段檔案，接著啟動閘道並執行 openclaw health。

QR 匯入煙霧測試（Docker）

確保受維護的 QR 執行階段輔助工具可在支援的 Docker Node 執行階段下載入（預設為 Node 24，相容於 Node 22）：

pnpm test:docker:qr

相關內容

• 測試
• 即時測試
• 測試更新與外掛