Kiểm thử

• Bộ công cụ kiểm thử đầy đủ (bộ kiểm thử, live, Docker): Kiểm thử

• Xác thực bản cập nhật và gói Plugin: Kiểm thử bản cập nhật và Plugin

• Thứ tự kiểm thử cục bộ thường dùng:

  1. pnpm test:changed để có bằng chứng Vitest theo phạm vi đã thay đổi.
  2. pnpm test <path-or-filter> cho một tệp, thư mục hoặc đích rõ ràng.
  3. pnpm test chỉ khi bạn chủ ý cần toàn bộ bộ Vitest cục bộ.

• pnpm test:force: Dừng mọi tiến trình gateway còn sót lại đang giữ cổng điều khiển mặc định, rồi chạy toàn bộ bộ Vitest với một cổng gateway cô lập để các kiểm thử máy chủ không va chạm với phiên bản đang chạy. Dùng lệnh này khi một lần chạy gateway trước đó để lại cổng 18789 bị chiếm dụng.

• pnpm test:coverage: Chạy bộ kiểm thử đơn vị với coverage V8 (qua vitest.unit.config.ts). Đây là cổng coverage của lane đơn vị mặc định, không phải coverage toàn bộ mọi tệp trong repo. Ngưỡng là 70% cho dòng/hàm/câu lệnh và 55% cho nhánh. Vì coverage.all là false và lane mặc định giới hạn phạm vi coverage vào các kiểm thử đơn vị không nhanh có tệp nguồn cùng cấp, cổng này đo phần nguồn do lane này sở hữu thay vì mọi import bắc cầu mà nó tình cờ tải.

• pnpm test:coverage:changed: Chỉ chạy coverage đơn vị cho các tệp đã thay đổi kể từ origin/main.

• pnpm test:changed: lần chạy kiểm thử thay đổi thông minh, chi phí thấp. Nó chạy các đích chính xác từ chỉnh sửa kiểm thử trực tiếp, tệp *.test.ts cùng cấp, ánh xạ nguồn rõ ràng và đồ thị import cục bộ. Thay đổi rộng/cấu hình/gói bị bỏ qua trừ khi chúng ánh xạ tới kiểm thử chính xác.

• OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed: lần chạy kiểm thử thay đổi rộng rõ ràng. Dùng khi chỉnh sửa harness/cấu hình/gói kiểm thử nên rơi về hành vi kiểm thử thay đổi rộng hơn của Vitest.

• pnpm changed:lanes: hiển thị các lane kiến trúc được kích hoạt bởi diff so với origin/main.

• pnpm check:changed: mặc định ủy quyền cho Crabbox/Testbox ngoài CI, rồi chạy cổng kiểm tra thay đổi thông minh cho diff so với origin/main bên trong tiến trình con từ xa. Nó chạy typecheck, lint và các lệnh guard cho các lane kiến trúc bị ảnh hưởng, nhưng không chạy kiểm thử Vitest. Dùng pnpm test:changed hoặc pnpm test <target> rõ ràng để có bằng chứng kiểm thử.

• Worktree Codex và checkout liên kết/thưa: tránh chạy trực tiếp cục bộ pnpm test*, pnpm check* và pnpm crabbox:run trừ khi bạn đã xác minh pnpm sẽ không đối soát lại phụ thuộc. Với bằng chứng tệp rõ ràng rất nhỏ, dùng node scripts/run-vitest.mjs <path-or-filter>; với cổng thay đổi hoặc bằng chứng rộng, dùng 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 chạy bên trong Testbox.

• Bằng chứng Testbox-thông-qua-Crabbox: dùng exitCode cuối cùng của wrapper và JSON thời gian làm kết quả lệnh. Lần chạy Blacksmith GitHub Actions được ủy quyền có thể hiển thị cancelled sau một lệnh SSH thành công vì Testbox bị dừng từ bên ngoài action keepalive; hãy xác minh tóm tắt wrapper và đầu ra lệnh trước khi xem đó là lỗi kiểm thử.

• OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command>: giữ tuần tự hóa kiểm tra nặng bên trong worktree hiện tại thay vì thư mục Git chung cho các lệnh như pnpm check:changed và pnpm test ... có đích. Chỉ dùng trên máy chủ cục bộ dung lượng cao khi bạn chủ ý chạy các kiểm tra độc lập trên nhiều worktree liên kết.

• pnpm test: định tuyến các đích tệp/thư mục rõ ràng qua các lane Vitest có phạm vi. Các lần chạy không có đích là bằng chứng toàn bộ bộ: chúng dùng các nhóm shard cố định, mở rộng thành cấu hình lá để thực thi song song cục bộ và in fanout shard cục bộ dự kiến trước khi bắt đầu. Nhóm extension luôn mở rộng thành các cấu hình shard theo từng extension thay vì một tiến trình dự án gốc khổng lồ.

• Các lần chạy wrapper kiểm thử kết thúc bằng tóm tắt ngắn [test] passed|failed|skipped ... in .... Dòng thời lượng riêng của Vitest vẫn là chi tiết theo từng shard.

• Trạng thái kiểm thử OpenClaw dùng chung: dùng src/test-utils/openclaw-test-state.ts từ Vitest khi kiểm thử cần HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, fixture cấu hình, workspace, thư mục agent hoặc kho auth-profile cô lập.

• pnpm test:env-mutations:report: báo cáo không chặn về các kiểm thử và harness trực tiếp thay đổi HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, OPENCLAW_WORKSPACE_DIR hoặc các khóa env OpenClaw liên quan. Dùng để tìm ứng viên di chuyển sang helper test-state dùng chung.

• Control UI E2E được mock: dùng pnpm test:ui:e2e cho lane Vitest + Playwright khởi động Vite Control UI và điều khiển một trang Chromium thật dựa trên WebSocket Gateway được mock. Kiểm thử nằm trong ui/src/**/*.e2e.test.ts; mock và điều khiển dùng chung nằm trong ui/src/test-helpers/control-ui-e2e.ts. pnpm test:e2e bao gồm lane này. Trong worktree Codex, ưu tiên 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 cho bằng chứng nhỏ có đích sau khi đã cài phụ thuộc, hoặc Testbox/Crabbox cho bằng chứng GUI rộng hơn.

• Helper E2E tiến trình: dùng test/helpers/openclaw-test-instance.ts khi kiểm thử E2E cấp tiến trình Vitest cần một Gateway đang chạy, env CLI, thu thập log và dọn dẹp ở cùng một nơi.

• Kiểm thử TUI PTY: dùng node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts cho lane PTY backend giả nhanh. Dùng OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 hoặc pnpm tui:pty:test:watch --mode local cho smoke tui --local chậm hơn, vốn chỉ mock endpoint mô hình bên ngoài. Khẳng định văn bản hiển thị ổn định hoặc các lời gọi fixture, không phải snapshot ANSI thô.

• Helper Docker/Bash E2E: các lane source scripts/lib/docker-e2e-image.sh có thể truyền docker_e2e_test_state_shell_b64 <label> <scenario> vào container và giải mã bằng scripts/lib/openclaw-e2e-instance.sh; script nhiều home có thể truyền docker_e2e_test_state_function_b64 và gọi openclaw_test_state_create <label> <scenario> trong từng flow. Caller cấp thấp hơn có thể dùng scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name> cho đoạn shell trong container, hoặc node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json cho tệp env trên host có thể source. Dấu -- trước create ngăn các runtime Node mới hơn xem --env-file là cờ Node. Các lane Docker/Bash khởi chạy Gateway có thể source scripts/lib/openclaw-e2e-instance.sh bên trong container để phân giải entrypoint, mock khởi động OpenAI, khởi chạy Gateway foreground/background, probe sẵn sàng, xuất env trạng thái, dump log và dọn dẹp tiến trình.

• Các lần chạy shard đầy đủ, extension và include-pattern cập nhật dữ liệu thời gian cục bộ trong .artifacts/vitest-shard-timings.json; các lần chạy toàn cấu hình sau đó dùng các thời gian đó để cân bằng shard chậm và nhanh. Shard CI include-pattern thêm tên shard vào khóa thời gian, giúp thời gian shard đã lọc vẫn hiển thị mà không thay thế dữ liệu thời gian toàn cấu hình. Đặt OPENCLAW_TEST_PROJECTS_TIMINGS=0 để bỏ qua artifact thời gian cục bộ.

• Các tệp kiểm thử plugin-sdk và commands được chọn hiện định tuyến qua các lane nhẹ chuyên dụng chỉ giữ test/setup.ts, để các trường hợp nặng về runtime ở lại các lane hiện có.

• Tệp nguồn có kiểm thử cùng cấp ánh xạ tới tệp cùng cấp đó trước khi rơi về glob thư mục rộng hơn. Chỉnh sửa helper dưới src/channels/plugins/contracts/test-helpers, src/plugin-sdk/test-helpers và src/plugins/contracts dùng đồ thị import cục bộ để chạy các kiểm thử đang import thay vì chạy rộng mọi shard khi đường dẫn phụ thuộc chính xác.

• auto-reply hiện cũng tách thành ba cấu hình chuyên dụng (core, top-level, reply) để harness reply không lấn át các kiểm thử trạng thái/token/helper top-level nhẹ hơn.

• Cấu hình Vitest cơ sở hiện mặc định là pool: "threads" và isolate: false, với runner không cô lập dùng chung được bật trên các cấu hình trong repo.

• pnpm test:channels chạy vitest.channels.config.ts.

• pnpm test:extensions và pnpm test extensions chạy tất cả shard extension/plugin. Các plugin kênh nặng, plugin trình duyệt và OpenAI chạy dưới dạng shard chuyên dụng; các nhóm plugin khác vẫn được gom lô. Dùng pnpm test extensions/<id> cho một lane plugin đóng gói.

• pnpm test:perf:imports: bật báo cáo thời lượng import + phân tích import, trong khi vẫn dùng định tuyến lane có phạm vi cho các đích tệp/thư mục rõ ràng.

• pnpm test:perf:imports:changed: cùng profiling import, nhưng chỉ cho các tệp đã thay đổi kể từ origin/main.

• pnpm test:perf:changed:bench -- --ref <git-ref> benchmark đường dẫn chế độ thay đổi đã định tuyến so với lần chạy dự án gốc native cho cùng diff git đã commit.

• pnpm test:perf:changed:bench -- --worktree benchmark tập thay đổi worktree hiện tại mà không cần commit trước.

• pnpm test:perf:profile:main: ghi CPU profile cho luồng chính Vitest (.artifacts/vitest-main-profile).

• pnpm test:perf:profile:runner: ghi CPU + heap profile cho runner đơn vị (.artifacts/vitest-runner-profile).

• pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json: chạy tuần tự mọi cấu hình lá Vitest toàn bộ bộ và ghi dữ liệu thời lượng theo nhóm cùng artifact JSON/log theo từng cấu hình. Test Performance Agent dùng dữ liệu này làm baseline trước khi thử sửa các kiểm thử chậm.

• pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json: so sánh báo cáo theo nhóm sau một thay đổi tập trung vào hiệu năng.

• pnpm test:docker:timings <summary.json> kiểm tra các lane Docker chậm sau một lần chạy Docker toàn bộ; dùng pnpm test:docker:rerun <run-id|summary.json|failures.json> để in các lệnh chạy lại có đích, chi phí thấp từ cùng artifact.

• Tích hợp Gateway: bật chọn bằng OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test hoặc pnpm test:gateway.

• pnpm test:e2e: Chạy tổng hợp E2E của repo: kiểm thử smoke gateway đầu-cuối cộng với lane E2E trình duyệt được mock của Control UI.

• pnpm test:e2e:gateway: Chạy kiểm thử smoke gateway đầu-cuối (ghép nối nhiều phiên bản WS/HTTP/node). Mặc định dùng threads + isolate: false với worker thích ứng trong vitest.e2e.config.ts; tinh chỉnh bằng OPENCLAW_E2E_WORKERS=<n> và đặt OPENCLAW_E2E_VERBOSE=1 để có log chi tiết.

• pnpm test:live: Chạy kiểm thử live provider (minimax/zai). Yêu cầu khóa API và LIVE=1 (hoặc *_LIVE_TEST=1 theo từng provider) để bỏ qua trạng thái skip.

• pnpm test:docker:all: Xây dựng image kiểm thử live dùng chung, đóng gói OpenClaw một lần dưới dạng tarball npm, xây dựng/tái sử dụng một image runner Node/Git tối giản cùng một image chức năng cài tarball đó vào /app, rồi chạy các lane smoke Docker với OPENCLAW_SKIP_DOCKER_BUILD=1 thông qua bộ lập lịch có trọng số. Image tối giản (OPENCLAW_DOCKER_E2E_BARE_IMAGE) được dùng cho các lane installer/update/plugin-dependency; các lane đó mount tarball đã dựng sẵn thay vì dùng source repo được sao chép. Image chức năng (OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE) được dùng cho các lane chức năng built-app thông thường. scripts/package-openclaw-for-docker.mjs là bộ đóng gói package cục bộ/CI duy nhất và xác thực tarball cùng dist/postinstall-inventory.json trước khi Docker tiêu thụ nó. Định nghĩa lane Docker nằm trong scripts/lib/docker-e2e-scenarios.mjs; logic planner nằm trong scripts/lib/docker-e2e-plan.mjs; scripts/test-docker-all.mjs thực thi kế hoạch đã chọn. node scripts/test-docker-all.mjs --plan-json phát ra kế hoạch CI do bộ lập lịch sở hữu cho các lane đã chọn, loại image, nhu cầu package/live-image, kịch bản trạng thái và kiểm tra thông tin xác thực mà không xây dựng hoặc chạy Docker. OPENCLAW_DOCKER_ALL_PARALLELISM=<n> điều khiển số slot tiến trình và mặc định là 10; OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n> điều khiển pool tail nhạy với provider và mặc định là 10. Giới hạn lane nặng mặc định là OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9, OPENCLAW_DOCKER_ALL_NPM_LIMIT=5 và OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7; giới hạn provider mặc định là một lane nặng cho mỗi provider qua OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4, OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4 và OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4. Dùng OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT hoặc OPENCLAW_DOCKER_ALL_DOCKER_LIMIT cho host lớn hơn. Nếu một lane vượt quá trọng số hiệu dụng hoặc giới hạn tài nguyên trên host có mức song song thấp, lane đó vẫn có thể bắt đầu từ một pool rỗng và sẽ chạy một mình cho đến khi giải phóng dung lượng. Theo mặc định, thời điểm bắt đầu lane được giãn cách 2 giây để tránh các đợt tạo container dồn dập trên Docker daemon cục bộ; ghi đè bằng OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>. Runner mặc định preflight Docker, dọn các container OpenClaw E2E cũ, phát trạng thái lane đang hoạt động mỗi 30 giây, chia sẻ cache công cụ CLI của provider giữa các lane tương thích, thử lại lỗi live-provider tạm thời một lần theo mặc định (OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>) và lưu thời lượng lane trong .artifacts/docker-tests/lane-timings.json để sắp xếp lane dài nhất trước trong các lần chạy sau. Dùng OPENCLAW_DOCKER_ALL_DRY_RUN=1 để in manifest lane mà không chạy Docker, OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms> để điều chỉnh đầu ra trạng thái, hoặc OPENCLAW_DOCKER_ALL_TIMINGS=0 để tắt tái sử dụng thời lượng. Dùng OPENCLAW_DOCKER_ALL_LIVE_MODE=skip để chỉ chạy các lane xác định/cục bộ hoặc OPENCLAW_DOCKER_ALL_LIVE_MODE=only để chỉ chạy các lane live-provider; alias package là pnpm test:docker:local:all và pnpm test:docker:live:all. Chế độ chỉ live hợp nhất các lane live chính và tail vào một pool dài nhất trước để các bucket provider có thể gom việc Claude, Codex và Gemini cùng nhau. Runner dừng lập lịch các lane pooled mới sau lỗi đầu tiên trừ khi đặt OPENCLAW_DOCKER_ALL_FAIL_FAST=0, và mỗi lane có timeout dự phòng 120 phút có thể ghi đè bằng OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS; một số lane live/tail được chọn dùng giới hạn theo lane chặt hơn. Các lệnh thiết lập Docker cho backend CLI có timeout riêng qua OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS (mặc định 180). Log theo lane, summary.json, failures.json và thời lượng theo pha được ghi dưới .artifacts/docker-tests/<run-id>/; dùng pnpm test:docker:timings <summary.json> để kiểm tra các lane chậm và pnpm test:docker:rerun <run-id|summary.json|failures.json> để in các lệnh chạy lại có mục tiêu, chi phí thấp.

• pnpm test:docker:browser-cdp-snapshot: Xây dựng một container source E2E dựa trên Chromium, khởi động CDP thô cùng một Gateway cô lập, chạy browser doctor --deep, rồi xác minh snapshot vai trò CDP bao gồm URL liên kết, phần tử có thể nhấp được nâng cấp từ con trỏ, tham chiếu iframe và metadata frame.

• pnpm test:docker:skill-install: Cài tarball OpenClaw đã đóng gói trong một runner Docker tối giản, tắt skills.install.allowUploadedArchives, phân giải một slug skill hiện tại từ tìm kiếm ClawHub live, cài qua openclaw skills install, và xác minh SKILL.md, .clawhub/origin.json, .clawhub/lock.json và skills info --json.

• Các probe Docker live cho backend CLI có thể chạy dưới dạng lane tập trung, ví dụ pnpm test:docker:live-cli-backend:claude, pnpm test:docker:live-cli-backend:claude:resume hoặc pnpm test:docker:live-cli-backend:claude:mcp. Gemini có các alias :resume và :mcp tương ứng.

• pnpm test:docker:openwebui: Khởi động OpenClaw + Open WebUI trong Docker, đăng nhập qua Open WebUI, kiểm tra /api/models, rồi chạy một cuộc chat proxy thật qua /api/chat/completions. Yêu cầu khóa model live dùng được, pull một image Open WebUI bên ngoài và không được kỳ vọng ổn định trên CI như các bộ unit/e2e thông thường.

• pnpm test:docker:mcp-channels: Khởi động một container Gateway đã seed và một container client thứ hai spawn openclaw mcp serve, rồi xác minh khám phá hội thoại được định tuyến, đọc transcript, metadata tệp đính kèm, hành vi hàng đợi sự kiện live, định tuyến gửi outbound, và thông báo channel + quyền kiểu Claude qua cầu nối stdio thật. Assertion thông báo Claude đọc trực tiếp các frame MCP stdio thô để smoke phản ánh đúng những gì cầu nối thật sự phát ra.

• pnpm test:docker:upgrade-survivor: Cài tarball OpenClaw đã đóng gói đè lên một fixture người dùng cũ bị bẩn, chạy cập nhật package cùng doctor không tương tác mà không có khóa live provider hoặc channel, rồi khởi động một Gateway local loopback và kiểm tra rằng agent, cấu hình channel, allowlist Plugin, tệp workspace/session, trạng thái dependency Plugin legacy cũ, startup và trạng thái RPC vẫn tồn tại.

• pnpm test:docker:published-upgrade-survivor: Cài openclaw@latest theo mặc định, seed các tệp người dùng hiện có thực tế mà không có khóa live provider hoặc channel, cấu hình baseline đó bằng một công thức lệnh openclaw config set đã nhúng, cập nhật bản cài đã phát hành đó lên tarball OpenClaw đã đóng gói, chạy doctor không tương tác, ghi .artifacts/upgrade-survivor/summary.json, rồi khởi động một Gateway local loopback và kiểm tra rằng intent đã cấu hình, tệp workspace/session, cấu hình Plugin cũ và trạng thái dependency legacy, startup, /healthz, /readyz và trạng thái RPC vẫn tồn tại hoặc được sửa sạch. Ghi đè một baseline bằng OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC, mở rộng một ma trận cục bộ chính xác bằng OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS như openclaw@2026.5.2 openclaw@2026.4.23 openclaw@2026.4.15, hoặc thêm fixture kịch bản bằng OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues; bộ reported-issues bao gồm configured-plugin-installs để xác minh các Plugin OpenClaw bên ngoài đã cấu hình được cài tự động trong quá trình nâng cấp và stale-source-plugin-shadow để giữ các shadow Plugin chỉ có source không làm hỏng startup. Package Acceptance phơi bày các giá trị đó dưới dạng published_upgrade_survivor_baseline, published_upgrade_survivor_baselines và published_upgrade_survivor_scenarios, đồng thời phân giải các token baseline meta như last-stable-4 hoặc all-since-2026.4.23 trước khi chuyển thông số package chính xác cho các lane Docker.

• pnpm test:docker:update-migration: Chạy harness published-upgrade survivor trong kịch bản plugin-deps-cleanup thiên về dọn dẹp, mặc định bắt đầu từ openclaw@2026.4.23. Workflow Update Migration riêng mở rộng lane này với baselines=all-since-2026.4.23 để mọi package ổn định đã phát hành từ .23 trở đi đều cập nhật lên candidate và chứng minh việc dọn dẹp dependency của Plugin đã cấu hình bên ngoài Full Release CI.

• pnpm test:docker:plugins: Chạy smoke install/update cho local path, file:, package npm registry có dependency được hoist, git moving refs, fixture ClawHub, cập nhật marketplace và bật/kiểm tra Claude-bundle.

Cổng kiểm tra PR cục bộ

Đối với các kiểm tra đưa PR vào nhánh/gate cục bộ, chạy:

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

Nếu pnpm test bị lỗi không ổn định trên một host đang tải nặng, hãy chạy lại một lần trước khi xem đó là hồi quy, rồi cô lập bằng pnpm test <path/to/test>. Đối với các host bị giới hạn bộ nhớ, dùng:

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

Benchmark độ trễ mô hình (khóa cục bộ)

Script: scripts/bench-model.ts

Cách dùng:

• pnpm tsx scripts/bench-model.ts --runs 10
• Env tùy chọn: MINIMAX_API_KEY, MINIMAX_BASE_URL, MINIMAX_MODEL, ANTHROPIC_API_KEY
• Prompt mặc định: "Trả lời bằng một từ duy nhất: ok. Không dùng dấu câu hoặc văn bản bổ sung."

Lần chạy gần nhất (2025-12-31, 20 lần chạy):

• minimax trung vị 1279ms (nhỏ nhất 1114, lớn nhất 2431)
• opus trung vị 2454ms (nhỏ nhất 1224, lớn nhất 3170)

Benchmark khởi động CLI

Script: scripts/bench-cli-startup.ts

Cách dùng:

• pnpm test:startup:bench
• pnpm test:startup:bench:smoke
• pnpm test:startup:bench:save
• pnpm test:startup:bench:update
• pnpm test:startup:bench:check
• pnpm tsx scripts/bench-cli-startup.ts
• pnpm tsx scripts/bench-cli-startup.ts --runs 12
• pnpm tsx scripts/bench-cli-startup.ts --preset real
• pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --case gatewayStatus --runs 3
• pnpm tsx scripts/bench-cli-startup.ts --preset real --case tasksJson --case tasksListJson --case tasksAuditJson --runs 3
• pnpm tsx scripts/bench-cli-startup.ts --entry openclaw.mjs --entry-secondary dist/entry.js --preset all
• pnpm tsx scripts/bench-cli-startup.ts --preset all --output .artifacts/cli-startup-bench-all.json
• pnpm tsx scripts/bench-cli-startup.ts --preset real --case gatewayStatusJson --output .artifacts/cli-startup-bench-smoke.json
• pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
• pnpm tsx scripts/bench-cli-startup.ts --json

Preset:

• startup: --version, --help, health, health --json, status --json, status
• real: health, status, status --json, sessions, sessions --json, tasks --json, tasks list --json, tasks audit --json, agents list --json, gateway status, gateway status --json, gateway health --json, config get gateway.port
• all: cả hai preset

Đầu ra bao gồm sampleCount, trung bình, p50, p95, nhỏ nhất/lớn nhất, phân bố exit-code/signal, và tóm tắt RSS tối đa cho từng lệnh. --cpu-prof-dir / --heap-prof-dir tùy chọn ghi hồ sơ V8 cho mỗi lần chạy để đo thời gian và thu thập hồ sơ dùng cùng một harness.

Quy ước đầu ra đã lưu:

• pnpm test:startup:bench:smoke ghi artifact smoke được nhắm mục tiêu tại .artifacts/cli-startup-bench-smoke.json
• pnpm test:startup:bench:save ghi artifact bộ đầy đủ tại .artifacts/cli-startup-bench-all.json bằng runs=5 và warmup=1
• pnpm test:startup:bench:update làm mới fixture baseline đã checked-in tại test/fixtures/cli-startup-bench.json bằng runs=5 và warmup=1

Fixture đã checked-in:

• test/fixtures/cli-startup-bench.json
• Làm mới bằng pnpm test:startup:bench:update
• So sánh kết quả hiện tại với fixture bằng pnpm test:startup:bench:check

Benchmark khởi động Gateway

Script: scripts/bench-gateway-startup.ts

Benchmark mặc định dùng entry CLI đã build tại dist/entry.js; chạy pnpm build trước khi dùng các lệnh package-script. Để đo runner nguồn thay vào đó, truyền --entry scripts/run-node.mjs và giữ các kết quả đó tách biệt với baseline entry đã build.

Cách dùng:

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

ID case:

• default: khởi động Gateway bình thường.
• skipChannels: khởi động Gateway với phần khởi động kênh bị bỏ qua.
• oneInternalHook: một hook nội bộ đã cấu hình.
• allInternalHooks: tất cả hook nội bộ.
• fiftyPlugins: 50 Plugin manifest.
• fiftyStartupLazyPlugins: 50 Plugin manifest startup-lazy.

Đầu ra bao gồm đầu ra quy trình đầu tiên, /healthz, /readyz, thời gian log lắng nghe HTTP, thời gian log Gateway sẵn sàng, thời gian CPU, tỷ lệ lõi CPU, RSS tối đa, heap, chỉ số trace khởi động, độ trễ event-loop, và chỉ số chi tiết bảng tra cứu Plugin. Script bật OPENCLAW_GATEWAY_STARTUP_TRACE=1 trong môi trường Gateway con.

Đọc /healthz là liveness: máy chủ HTTP có thể trả lời. Đọc /readyz là trạng thái sẵn sàng sử dụng được: các sidecar Plugin khởi động, kênh, và công việc post-attach ready-critical đã ổn định. Các hook khởi động Gateway được dispatch bất đồng bộ và không thuộc bảo đảm sẵn sàng. Thời gian log sẵn sàng là dấu thời gian log sẵn sàng nội bộ của Gateway; nó hữu ích để quy kết phía quy trình nhưng không thay thế cho probe /readyz bên ngoài.

Dùng đầu ra JSON hoặc --output khi so sánh thay đổi. Chỉ dùng --cpu-prof-dir sau khi đầu ra trace chỉ đến import, compile, hoặc công việc bị ràng buộc bởi CPU không thể giải thích chỉ bằng thời gian từng pha. Không so sánh kết quả source-runner với kết quả dist/entry.js đã build như cùng một baseline.

Benchmark khởi động lại Gateway

Script: scripts/bench-gateway-restart.ts

Benchmark khởi động lại chỉ được hỗ trợ trên macOS và Linux. Nó dùng SIGUSR1 cho khởi động lại trong cùng quy trình và lỗi ngay trên Windows.

Benchmark mặc định dùng entry CLI đã build tại dist/entry.js; chạy pnpm build trước khi dùng các lệnh package-script. Để đo runner nguồn thay vào đó, truyền --entry scripts/run-node.mjs và giữ các kết quả đó tách biệt với baseline entry đã build.

Cách dùng:

• pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5
• pnpm test:restart:gateway -- --case default --runs 3 --restarts 3 --warmup 1
• pnpm test:restart:gateway -- --case skipChannelsAcpxProbe --case skipChannelsNoAcpxProbe --runs 1 --restarts 5
• node --import tsx scripts/bench-gateway-restart.ts --case fiftyPlugins --runs 1 --restarts 5 --output .artifacts/gateway-restart.json
• node --import tsx scripts/bench-gateway-restart.ts --json

ID case:

• skipChannels: khởi động lại với kênh bị bỏ qua.
• skipChannelsAcpxProbe: khởi động lại với kênh bị bỏ qua và probe khởi động ACPX bật.
• skipChannelsNoAcpxProbe: khởi động lại với kênh bị bỏ qua và probe khởi động ACPX tắt.
• default: khởi động lại bình thường.
• fiftyPlugins: khởi động lại với 50 Plugin manifest.

Đầu ra bao gồm /healthz tiếp theo, /readyz tiếp theo, thời gian ngừng hoạt động, thời điểm sẵn sàng sau khởi động lại, CPU, RSS, chỉ số trace khởi động cho quy trình thay thế, và chỉ số trace khởi động lại cho xử lý tín hiệu, xả active-work, các pha đóng, lần khởi động tiếp theo, thời điểm sẵn sàng, và snapshot bộ nhớ. Script bật OPENCLAW_GATEWAY_STARTUP_TRACE=1 và OPENCLAW_GATEWAY_RESTART_TRACE=1 trong môi trường Gateway con.

Dùng benchmark này khi một thay đổi chạm đến tín hiệu khởi động lại, trình xử lý đóng, khởi động sau khởi động lại, tắt sidecar, bàn giao dịch vụ, hoặc trạng thái sẵn sàng sau khởi động lại. Bắt đầu với skipChannels khi cô lập cơ chế Gateway khỏi phần khởi động kênh. Chỉ dùng default hoặc các case nhiều Plugin sau khi case hẹp giải thích được đường dẫn khởi động lại.

Chỉ số trace là gợi ý quy kết, không phải kết luận. Một thay đổi khởi động lại nên được đánh giá từ nhiều mẫu, span owner phù hợp, hành vi /healthz và /readyz, và hợp đồng khởi động lại mà người dùng thấy được.

Onboarding E2E (Docker)

Docker là tùy chọn; phần này chỉ cần cho các kiểm thử smoke onboarding trong container.

Luồng cold-start đầy đủ trong một container Linux sạch:

scripts/e2e/onboard-docker.sh

Script này điều khiển wizard tương tác qua pseudo-tty, xác minh các tệp config/workspace/session, rồi khởi động gateway và chạy openclaw health.

Smoke import QR (Docker)

Đảm bảo helper runtime QR được duy trì tải được dưới các runtime Docker Node được hỗ trợ (Node 24 mặc định, Node 22 tương thích):

pnpm test:docker:qr

Liên quan

• Kiểm thử
• Kiểm thử trực tiếp
• Kiểm thử bản cập nhật và Plugin