測試

• 完整測試工具組（測試套件、即時測試、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. pnpm test：僅在刻意需要完整本機 Vitest 測試套件時使用。

在 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>：讓重型檢查的序列化保持在目前工作樹內，而不是 Git 共用目錄中，適用於 pnpm check:changed 與目標式 pnpm test ... 等命令。僅在高容量本機主機上刻意跨連結工作樹執行獨立檢查時使用。

核心命令

測試包裝程式執行結束時會顯示簡短的 [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／節點配對）。預設使用 threads + isolate: false，並在 vitest.e2e.config.ts 中使用自適應工作程序；可透過 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 壓縮封裝檔，建置／重複使用基本的 Node/Git 執行器映像檔，以及將該壓縮封裝檔安裝至 /app 的功能映像檔，然後透過加權排程器執行 Docker 冒煙測試通道。scripts/package-openclaw-for-docker.mjs 是唯一的本機／CI 套件封裝器，會在 Docker 使用壓縮封裝檔之前驗證該檔案和 dist/postinstall-inventory.json。

• 基本映像檔（OPENCLAW_DOCKER_E2E_BARE_IMAGE）：安裝程式／更新／外掛相依性測試通道；掛載預先建置的壓縮封裝檔，而非複製的儲存庫原始碼。
• 功能映像檔（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

相關內容

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