Kiểm thử

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• Mỗi bộ kiểm thử bao phủ những gì (và những gì nó cố ý không bao phủ).
• Lệnh nào cần chạy cho các quy trình phổ biến (cục bộ, trước khi đẩy, gỡ lỗi).
• Cách kiểm thử live phát hiện thông tin xác thực và chọn mô hình/nhà cung cấp.
• Cách thêm hồi quy cho các sự cố mô hình/nhà cung cấp trong thực tế.

​

Bắt đầu nhanh

• Cổng kiểm tra đầy đủ (được kỳ vọng trước khi đẩy): pnpm build && pnpm check && pnpm check:test-types && pnpm test
• Chạy toàn bộ bộ kiểm thử cục bộ nhanh hơn trên máy dư tài nguyên: pnpm test:max
• Vòng lặp watch Vitest trực tiếp: pnpm test:watch
• Nhắm mục tiêu tệp trực tiếp giờ cũng định tuyến các đường dẫn extension/channel: pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
• Ưu tiên các lượt chạy có mục tiêu trước khi bạn đang lặp trên một lỗi duy nhất.
• Trang QA dựa trên Docker: pnpm qa:lab:up
• Lane QA dựa trên VM Linux: pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

• Cổng coverage: pnpm test:coverage
• Bộ kiểm thử E2E: pnpm test:e2e

• Bộ live (mô hình + các probe công cụ/hình ảnh của Gateway): pnpm test:live
• Nhắm mục tiêu một tệp live trong chế độ yên lặng: pnpm test:live -- src/agents/models.profiles.live.test.ts
• Báo cáo hiệu năng runtime: dispatch OpenClaw Performance với live_gpt54=true cho một lượt agent openai/gpt-5.4 thật hoặc deep_profile=true cho các artifact CPU/heap/trace của Kova. Các lượt chạy theo lịch hằng ngày xuất bản artifact của các lane mock-provider, deep-profile và GPT 5.4 lên openclaw/clawgrit-reports khi CLAWGRIT_REPORTS_TOKEN được cấu hình. Báo cáo mock-provider cũng bao gồm số liệu ở cấp nguồn cho khởi động Gateway, bộ nhớ, áp lực Plugin, vòng lặp hello fake-model lặp lại và khởi động CLI.
• Quét mô hình live bằng Docker: pnpm test:docker:live-models
  • Mỗi mô hình được chọn giờ chạy một lượt văn bản cộng với một probe nhỏ kiểu đọc tệp. Các mô hình có metadata quảng bá đầu vào image cũng chạy một lượt hình ảnh nhỏ. Tắt các probe bổ sung bằng OPENCLAW_LIVE_MODEL_FILE_PROBE=0 hoặc OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0 khi cô lập lỗi nhà cung cấp.
  • Phạm vi CI: OpenClaw Scheduled Live And E2E Checks hằng ngày và OpenClaw Release Checks thủ công đều gọi workflow live/E2E tái sử dụng với include_live_suites: true, bao gồm các job ma trận mô hình live Docker riêng được chia shard theo nhà cung cấp.
  • Để chạy lại CI có trọng tâm, dispatch OpenClaw Live And E2E Checks (Reusable) với include_live_suites: true và live_models_only: true.
  • Thêm secret nhà cung cấp tín hiệu cao mới vào scripts/ci-hydrate-live-auth.sh cùng .github/workflows/openclaw-live-and-e2e-checks-reusable.yml và các caller theo lịch/phát hành của nó.
• Smoke trò chuyện ràng buộc Codex native: pnpm test:docker:live-codex-bind
  • Chạy một lane live Docker trên đường dẫn app-server Codex, ràng buộc một Slack DM tổng hợp bằng /codex bind, thực thi /codex fast và /codex permissions, rồi xác minh một phản hồi thường và một tệp đính kèm hình ảnh đi qua ràng buộc Plugin native thay vì ACP.
• Smoke harness app-server Codex: pnpm test:docker:live-codex-harness
  • Chạy các lượt agent Gateway qua harness app-server Codex do Plugin sở hữu, xác minh /codex status và /codex models, và theo mặc định thực thi các probe hình ảnh, cron MCP, sub-agent và Guardian. Tắt probe sub-agent bằng OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0 khi cô lập các lỗi khác của app-server Codex. Để kiểm tra sub-agent có trọng tâm, hãy tắt các probe khác: OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness. Lệnh này thoát sau probe sub-agent trừ khi OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0 được đặt.
• Smoke cài đặt Codex theo yêu cầu: pnpm test:docker:codex-on-demand
  • Cài đặt tarball OpenClaw đã đóng gói trong Docker, chạy onboarding bằng OpenAI API-key, và xác minh Plugin Codex cùng dependency @openai/codex đã được tải xuống npm root được quản lý theo yêu cầu.
• Smoke dependency công cụ Plugin live: pnpm test:docker:live-plugin-tool
  • Đóng gói một Plugin fixture với dependency slugify thật, cài đặt nó thông qua npm-pack:, xác minh dependency dưới npm root được quản lý, rồi yêu cầu một mô hình OpenAI live gọi công cụ Plugin và trả về slug ẩn.
• Smoke lệnh cứu hộ Crestodian: pnpm test:live:crestodian-rescue-channel
  • Kiểm tra opt-in belt-and-suspenders cho bề mặt lệnh cứu hộ kênh tin nhắn. Nó thực thi /crestodian status, xếp hàng một thay đổi mô hình bền vững, trả lời /crestodian yes, và xác minh đường dẫn ghi audit/config.
• Smoke Docker planner Crestodian: pnpm test:docker:crestodian-planner
  • Chạy Crestodian trong container không có config với Claude CLI giả trên PATH và xác minh fallback planner mờ được dịch thành một lần ghi config đã audit và có kiểu.
• Smoke Docker lần chạy đầu của Crestodian: pnpm test:docker:crestodian-first-run
  • Bắt đầu từ thư mục trạng thái OpenClaw trống, định tuyến openclaw trần tới Crestodian, áp dụng các lần ghi setup/model/agent/Plugin Discord + SecretRef, xác thực config và xác minh các mục audit. Cùng đường dẫn thiết lập Ring 0 này cũng được bao phủ trong QA Lab bởi pnpm openclaw qa suite --scenario crestodian-ring-zero-setup.
• Smoke chi phí Moonshot/Kimi: với MOONSHOT_API_KEY được đặt, chạy openclaw models list --provider moonshot --json, rồi chạy một lượt tách biệt openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json trên moonshot/kimi-k2.6. Xác minh JSON báo cáo Moonshot/K2.6 và bản ghi assistant lưu usage.cost đã chuẩn hóa.

​

Runner dành riêng cho QA

• pnpm openclaw qa suite
  • Chạy các kịch bản QA được hậu thuẫn bởi repo trực tiếp trên máy chủ.
  • Theo mặc định, chạy song song nhiều kịch bản đã chọn với các worker gateway cô lập. qa-channel mặc định concurrency là 4 (bị giới hạn bởi số lượng kịch bản đã chọn). Dùng --concurrency <count> để tinh chỉnh số worker, hoặc --concurrency 1 cho lane tuần tự cũ hơn.
  • Thoát với mã khác 0 khi bất kỳ kịch bản nào thất bại. Dùng --allow-failures khi bạn muốn có artifact mà không có mã thoát thất bại.
  • Hỗ trợ các chế độ provider live-frontier, mock-openai, và aimock. aimock khởi động một server provider cục bộ được hậu thuẫn bởi AIMock cho coverage fixture và protocol-mock thử nghiệm mà không thay thế lane mock-openai nhận biết kịch bản.
• pnpm test:plugins:kitchen-sink-live
  • Chạy gauntlet Plugin OpenAI Kitchen Sink trực tiếp qua QA Lab. Nó cài đặt gói Kitchen Sink bên ngoài, xác minh inventory bề mặt plugin SDK, thăm dò /healthz và /readyz, ghi lại bằng chứng CPU/RSS của Gateway, chạy một lượt OpenAI trực tiếp, và kiểm tra chẩn đoán đối kháng. Yêu cầu xác thực OpenAI trực tiếp như OPENAI_API_KEY. Trong các phiên Testbox đã được hydrate, nó tự động source hồ sơ live-auth của Testbox khi có helper openclaw-testbox-env.
• pnpm test:gateway:cpu-scenarios
  • Chạy benchmark khởi động Gateway cùng một gói nhỏ các kịch bản QA Lab mock (channel-chat-baseline, memory-failure-fallback, gateway-restart-inflight-run) và ghi bản tóm tắt quan sát CPU kết hợp vào .artifacts/gateway-cpu-scenarios/.
  • Theo mặc định chỉ gắn cờ các quan sát CPU nóng kéo dài (--cpu-core-warn cùng --hot-wall-warn-ms), nên các đợt tăng ngắn khi khởi động được ghi như metric mà không trông giống hồi quy Gateway ghim CPU kéo dài nhiều phút.
  • Dùng artifact dist đã build; hãy chạy build trước khi checkout chưa có output runtime mới.
• pnpm openclaw qa suite --runner multipass
  • Chạy cùng bộ QA bên trong một VM Linux Multipass dùng một lần.
  • Giữ cùng hành vi chọn kịch bản như qa suite trên máy chủ.
  • Tái sử dụng cùng các cờ chọn provider/model như qa suite.
  • Các lần chạy trực tiếp chuyển tiếp những input xác thực QA được hỗ trợ và thực tế cho guest: khóa provider dựa trên env, đường dẫn cấu hình provider trực tiếp của QA, và CODEX_HOME khi có.
  • Thư mục output phải nằm dưới gốc repo để guest có thể ghi ngược qua workspace đã mount.
  • Ghi báo cáo QA + tóm tắt thông thường cùng log Multipass dưới .artifacts/qa-e2e/....
• pnpm qa:lab:up
  • Khởi động site QA được hậu thuẫn bởi Docker cho công việc QA kiểu operator.
• pnpm test:docker:npm-onboard-channel-agent
  • Build một tarball npm từ checkout hiện tại, cài đặt toàn cục trong Docker, chạy onboarding khóa API OpenAI không tương tác, cấu hình Telegram theo mặc định, xác minh runtime Plugin đã đóng gói tải được mà không cần sửa dependency lúc khởi động, chạy doctor, và chạy một lượt agent cục bộ với endpoint OpenAI được mock.
  • Dùng OPENCLAW_NPM_ONBOARD_CHANNEL=discord để chạy cùng lane packaged-install với Discord.
• pnpm test:docker:session-runtime-context
  • Chạy một smoke Docker ứng dụng đã build có tính xác định cho transcript ngữ cảnh runtime nhúng. Nó xác minh ngữ cảnh runtime OpenClaw ẩn được lưu dưới dạng thông điệp tùy chỉnh không hiển thị thay vì rò rỉ vào lượt người dùng nhìn thấy được, sau đó seed một JSONL phiên bị hỏng chịu ảnh hưởng và xác minh openclaw doctor --fix ghi lại nó sang nhánh active với một bản sao lưu.
• pnpm test:docker:npm-telegram-live
  • Cài đặt một candidate gói OpenClaw trong Docker, chạy onboarding gói đã cài, cấu hình Telegram qua CLI đã cài, rồi tái sử dụng lane QA Telegram trực tiếp với gói đã cài đó làm Gateway SUT.
  • Wrapper chỉ mount source harness qa-lab từ checkout; gói đã cài sở hữu dist, openclaw/plugin-sdk, và runtime Plugin đi kèm để lane không trộn các Plugin từ checkout hiện tại vào gói đang được kiểm thử.
  • Mặc định là OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta; đặt OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz hoặc OPENCLAW_CURRENT_PACKAGE_TGZ để kiểm thử một tarball cục bộ đã resolve thay vì cài đặt từ registry.
  • Dùng cùng thông tin xác thực env Telegram hoặc nguồn thông tin xác thực Convex như pnpm openclaw qa telegram. Với tự động hóa CI/release, đặt OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex cùng OPENCLAW_QA_CONVEX_SITE_URL và role secret. Nếu OPENCLAW_QA_CONVEX_SITE_URL và một Convex role secret có trong CI, wrapper Docker tự động chọn Convex.
  • Wrapper xác thực env thông tin xác thực Telegram hoặc Convex trên máy chủ trước công việc build/cài đặt Docker. Chỉ đặt OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1 khi cố ý debug thiết lập trước thông tin xác thực.
  • OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer ghi đè OPENCLAW_QA_CREDENTIAL_ROLE dùng chung chỉ cho lane này.
  • GitHub Actions hiển thị lane này dưới dạng workflow maintainer thủ công NPM Telegram Beta E2E. Nó không chạy khi merge. Workflow dùng môi trường qa-live-shared và các lease thông tin xác thực CI Convex.
• GitHub Actions cũng hiển thị Package Acceptance cho bằng chứng sản phẩm chạy bên cạnh trên một gói candidate. Nó chấp nhận một ref đáng tin cậy, spec npm đã phát hành, URL tarball HTTPS cùng SHA-256, hoặc artifact tarball từ một lần chạy khác, upload openclaw-current.tgz đã chuẩn hóa dưới tên package-under-test, rồi chạy scheduler Docker E2E hiện có với các hồ sơ lane smoke, package, product, full, hoặc custom. Đặt telegram_mode=mock-openai hoặc live-frontier để chạy workflow QA Telegram với cùng artifact package-under-test.
  • Bằng chứng sản phẩm beta mới nhất:

gh workflow run package-acceptance.yml --ref main \
  -f source=npm \
  -f package_spec=openclaw@beta \
  -f suite_profile=product \
  -f telegram_mode=mock-openai

• Bằng chứng URL tarball chính xác yêu cầu digest:

gh workflow run package-acceptance.yml --ref main \
  -f source=url \
  -f package_url=https://registry.npmjs.org/openclaw/-/openclaw-VERSION.tgz \
  -f package_sha256=<sha256> \
  -f suite_profile=package

• Bằng chứng artifact tải xuống một artifact tarball từ một lần chạy Actions khác:

gh workflow run package-acceptance.yml --ref main \
  -f source=artifact \
  -f artifact_run_id=<run-id> \
  -f artifact_name=<artifact-name> \
  -f suite_profile=smoke

• pnpm test:docker:plugins
  • Đóng gói và cài đặt bản build OpenClaw hiện tại trong Docker, khởi động Gateway với OpenAI đã cấu hình, rồi bật các kênh/Plugin đi kèm qua chỉnh sửa cấu hình.
  • Xác minh discovery thiết lập để vắng mặt các Plugin có thể tải xuống chưa cấu hình, lần sửa doctor đầu tiên đã cấu hình sẽ cài đặt rõ ràng từng Plugin có thể tải xuống bị thiếu, và lần khởi động lại thứ hai không chạy sửa dependency ẩn.
  • Cũng cài đặt một baseline npm cũ đã biết, bật Telegram trước khi chạy openclaw update --tag <candidate>, và xác minh doctor sau cập nhật của candidate dọn dẹp phần thừa dependency Plugin cũ mà không có sửa postinstall phía harness.
• pnpm test:parallels:npm-update
  • Chạy smoke cập nhật cài đặt gói native trên các guest Parallels. Mỗi nền tảng được chọn trước tiên cài đặt gói baseline được yêu cầu, sau đó chạy lệnh openclaw update đã cài trong cùng guest và xác minh phiên bản đã cài, trạng thái cập nhật, độ sẵn sàng của Gateway, và một lượt agent cục bộ.
  • Dùng --platform macos, --platform windows, hoặc --platform linux khi lặp trên một guest. Dùng --json cho đường dẫn artifact tóm tắt và trạng thái từng lane.
  • Lane OpenAI dùng openai/gpt-5.5 cho bằng chứng lượt agent trực tiếp theo mặc định. Truyền --model <provider/model> hoặc đặt OPENCLAW_PARALLELS_OPENAI_MODEL khi cố ý xác thực một model OpenAI khác.
  • Bọc các lần chạy cục bộ dài trong timeout của máy chủ để các lần kẹt transport Parallels không tiêu tốn phần còn lại của cửa sổ kiểm thử:
    timeout --foreground 150m pnpm test:parallels:npm-update -- --json
    timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json
    
  • Script ghi các log lane lồng nhau dưới /tmp/openclaw-parallels-npm-update.*. Kiểm tra windows-update.log, macos-update.log, hoặc linux-update.log trước khi giả định wrapper bên ngoài bị treo.
  • Cập nhật Windows có thể mất 10 đến 15 phút trong công việc doctor sau cập nhật và cập nhật package trên một guest lạnh; điều đó vẫn lành mạnh khi log debug npm lồng nhau đang tiến triển.
  • Không chạy wrapper tổng hợp này song song với các lane smoke Parallels macOS, Windows, hoặc Linux riêng lẻ. Chúng dùng chung trạng thái VM và có thể va chạm khi khôi phục snapshot, phục vụ package, hoặc trạng thái Gateway của guest.
  • Bằng chứng sau cập nhật chạy bề mặt Plugin đi kèm thông thường vì các facade capability như speech, tạo ảnh, và hiểu media được tải qua API runtime đi kèm ngay cả khi bản thân lượt agent chỉ kiểm tra một phản hồi văn bản đơn giản.
• pnpm openclaw qa aimock
  • Chỉ khởi động server provider AIMock cục bộ cho kiểm thử smoke protocol trực tiếp.
• pnpm openclaw qa matrix
  • Chạy lane QA Matrix trực tiếp với một homeserver Tuwunel dùng một lần được hậu thuẫn bởi Docker. Chỉ source-checkout - các bản cài đặt đóng gói không ship qa-lab.
  • CLI đầy đủ, catalog hồ sơ/kịch bản, env var, và bố cục artifact: QA Matrix.
• pnpm openclaw qa telegram
  • Chạy lane QA Telegram trực tiếp với một nhóm riêng tư thật bằng token bot driver và SUT từ env.
  • Yêu cầu OPENCLAW_QA_TELEGRAM_GROUP_ID, OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN, và OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN. ID nhóm phải là ID chat Telegram dạng số.
  • Hỗ trợ --credential-source convex cho thông tin xác thực dùng chung theo pool. Dùng chế độ env theo mặc định, hoặc đặt OPENCLAW_QA_CREDENTIAL_SOURCE=convex để chọn dùng lease theo pool.
  • Mặc định bao phủ canary, cổng mention, định địa chỉ lệnh, /status, trả lời được mention giữa bot với bot, và trả lời lệnh native cốt lõi. Mặc định mock-openai cũng bao phủ các hồi quy reply-chain có tính xác định và streaming final-message Telegram. Dùng --list-scenarios cho các probe tùy chọn như session_status.
  • Thoát với mã khác 0 khi bất kỳ kịch bản nào thất bại. Dùng --allow-failures khi bạn muốn có artifact mà không có mã thoát thất bại.
  • Yêu cầu hai bot riêng biệt trong cùng một nhóm riêng tư, với bot SUT hiển thị username Telegram.
  • Để quan sát ổn định giữa bot với bot, bật Bot-to-Bot Communication Mode trong @BotFather cho cả hai bot và đảm bảo bot driver có thể quan sát traffic bot trong nhóm.
  • Ghi báo cáo QA Telegram, tóm tắt, và artifact observed-messages dưới .artifacts/qa-e2e/.... Các kịch bản trả lời bao gồm RTT từ yêu cầu gửi của driver đến phản hồi SUT quan sát được.

@Mantis telegram
@Mantis telegram scenario=telegram-status-command
@Mantis telegram scenarios=telegram-status-command,telegram-mentioned-message-reply

@Mantis telegram desktop proof

• pnpm openclaw qa mantis telegram-desktop-builder
  • Thuê hoặc tái sử dụng một desktop Linux Crabbox, cài đặt Telegram Desktop gốc, cấu hình OpenClaw với token bot SUT Telegram được thuê, khởi động Gateway, và ghi lại bằng chứng ảnh chụp màn hình/MP4 từ desktop VNC đang hiển thị.
  • Mặc định dùng --credential-source convex để workflow chỉ cần secret broker Convex. Dùng --credential-source env với cùng các biến OPENCLAW_QA_TELEGRAM_* như pnpm openclaw qa telegram.
  • Telegram Desktop vẫn cần một hồ sơ/phiên đăng nhập người dùng. Token bot chỉ cấu hình OpenClaw. Dùng --telegram-profile-archive-env <name> cho kho lưu trữ hồ sơ .tgz base64, hoặc dùng --keep-lease và đăng nhập thủ công qua VNC một lần.
  • Ghi mantis-telegram-desktop-builder-report.md, mantis-telegram-desktop-builder-summary.json, telegram-desktop-builder.png, và telegram-desktop-builder.mp4 dưới thư mục đầu ra.

​

Thông tin xác thực Telegram dùng chung qua Convex (v1)

• qa/convex-credential-broker/

• OPENCLAW_QA_CONVEX_SITE_URL (ví dụ https://your-deployment.convex.site)
• Một secret cho vai trò đã chọn:
  • OPENCLAW_QA_CONVEX_SECRET_MAINTAINER cho maintainer
  • OPENCLAW_QA_CONVEX_SECRET_CI cho ci
• Chọn vai trò thông tin xác thực:
  • CLI: --credential-role maintainer|ci
  • Mặc định env: OPENCLAW_QA_CREDENTIAL_ROLE (mặc định là ci trong CI, nếu không là maintainer)

• OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS (mặc định 1200000)
• OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS (mặc định 30000)
• OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS (mặc định 90000)
• OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS (mặc định 15000)
• OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX (mặc định /qa-credentials/v1)
• OPENCLAW_QA_CREDENTIAL_OWNER_ID (id truy vết tùy chọn)
• OPENCLAW_QA_ALLOW_INSECURE_HTTP=1 cho phép URL Convex loopback http:// chỉ dành cho phát triển cục bộ.

pnpm openclaw qa credentials doctor
pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json
pnpm openclaw qa credentials list --kind telegram
pnpm openclaw qa credentials remove --credential-id <credential-id>

• POST /acquire
  • Yêu cầu: { kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }
  • Thành công: { status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }
  • Hết tài nguyên/có thể thử lại: { status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }
• POST /payload-chunk
  • Yêu cầu: { kind, ownerId, actorRole, credentialId, leaseToken, index }
  • Thành công: { status: "ok", index, data }
• POST /heartbeat
  • Yêu cầu: { kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }
  • Thành công: { status: "ok" } (hoặc 2xx rỗng)
• POST /release
  • Yêu cầu: { kind, ownerId, actorRole, credentialId, leaseToken }
  • Thành công: { status: "ok" } (hoặc 2xx rỗng)
• POST /admin/add (chỉ secret maintainer)
  • Yêu cầu: { kind, actorId, payload, note?, status? }
  • Thành công: { status: "ok", credential }
• POST /admin/remove (chỉ secret maintainer)
  • Yêu cầu: { credentialId, actorId }
  • Thành công: { status: "ok", changed, credential }
  • Chặn lease đang hoạt động: { status: "error", code: "LEASE_ACTIVE", ... }
• POST /admin/list (chỉ secret maintainer)
  • Yêu cầu: { kind?, status?, includePayload?, limit? }
  • Thành công: { status: "ok", credentials, count }

• { groupId: string, driverToken: string, sutToken: string }
• groupId phải là chuỗi id cuộc trò chuyện Telegram dạng số.
• admin/add xác thực dạng này cho kind: "telegram" và từ chối payload sai định dạng.

• { groupId: string, sutToken: string, testerUserId: string, testerUsername: string, telegramApiId: string, telegramApiHash: string, tdlibDatabaseEncryptionKey: string, tdlibArchiveBase64: string, tdlibArchiveSha256: string, desktopTdataArchiveBase64: string, desktopTdataArchiveSha256: string }
• groupId, testerUserId, và telegramApiId phải là chuỗi số.
• tdlibArchiveSha256 và desktopTdataArchiveSha256 phải là chuỗi hex SHA-256.
• kind: "telegram-user" đại diện cho một tài khoản burner Telegram. Xem lease là phạm vi toàn tài khoản: trình điều khiển CLI TDLib và nhân chứng trực quan Telegram Desktop khôi phục từ cùng payload, và mỗi lần chỉ một job được giữ lease.

tmp=$(mktemp -d /tmp/openclaw-telegram-user.XXXXXX)
node --import tsx scripts/e2e/telegram-user-credential.ts lease-restore \
  --user-driver-dir "$tmp/user-driver" \
  --desktop-workdir "$tmp/desktop" \
  --lease-file "$tmp/lease.json"
TELEGRAM_USER_DRIVER_STATE_DIR="$tmp/user-driver" \
  uv run ~/.codex/skills/custom/telegram-e2e-bot-to-bot/scripts/user-driver.py status --json
node --import tsx scripts/e2e/telegram-user-credential.ts release --lease-file "$tmp/lease.json"

pnpm qa:telegram-user:crabbox -- start \
  --tdlib-url http://artifacts.openclaw.ai/tdlib-v1.8.0-linux-x64.tgz \
  --output-dir .artifacts/qa-e2e/telegram-user-crabbox/pr-review
pnpm qa:telegram-user:crabbox -- send \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  --text /status
pnpm qa:telegram-user:crabbox -- finish \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json

• send --session <file> --text <message> gửi qua người dùng TDLib thật và chờ phản hồi SUT.
• run --session <file> -- <remote command> chạy một lệnh tùy ý trên Crabbox và lưu đầu ra của lệnh đó, ví dụ bash -lc 'source /tmp/openclaw-telegram-user-crabbox/env.sh && python3 /tmp/openclaw-telegram-user-crabbox/user-driver.py transcript --limit 20 --json'.
• screenshot --session <file> chụp desktop đang hiển thị hiện tại.
• status --session <file> in lease và lệnh WebVNC.
• finish --session <file> dừng bộ ghi, chụp ảnh chụp màn hình/video/artifact cắt theo chuyển động, giải phóng thông tin xác thực Convex, dừng các tiến trình SUT cục bộ, và dừng lease Crabbox trừ khi truyền --keep-box.
• publish --session <file> --pr <number> mặc định xuất bản bình luận PR chỉ có GIF. Chỉ truyền --full-artifacts khi cố ý cần log hoặc artifact JSON.

pnpm qa:telegram-user:crabbox -- --text /status

• Discord: { guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string, voiceChannelId?: string }
• WhatsApp: { driverPhoneE164: string, sutPhoneE164: string, driverAuthArchiveBase64: string, sutAuthArchiveBase64: string, groupJid?: string }

​

Thêm một kênh vào QA

​

Bộ kiểm thử (chạy ở đâu)

​

Unit / integration (mặc định)

• Lệnh: pnpm test
• Cấu hình: các lần chạy không nhắm mục tiêu dùng bộ shard vitest.full-*.config.ts và có thể mở rộng shard đa dự án thành cấu hình theo từng dự án để lập lịch song song
• Tệp: inventory core/unit dưới src/**/*.test.ts, packages/**/*.test.ts, và test/**/*.test.ts; kiểm thử unit UI chạy trong shard chuyên dụng unit-ui
• Phạm vi:
  • Kiểm thử unit thuần
  • Kiểm thử integration trong tiến trình (xác thực Gateway, định tuyến, công cụ, phân tích cú pháp, cấu hình)
  • Hồi quy có tính xác định cho các lỗi đã biết
• Kỳ vọng:
  • Chạy trong CI
  • Không yêu cầu khóa thật
  • Nên nhanh và ổn định
  • Các kiểm thử resolver và loader bề mặt công khai phải chứng minh hành vi fallback rộng của api.js và runtime-api.js bằng fixture Plugin nhỏ được tạo ra, không phải API nguồn của Plugin được đóng gói thật. Tải API Plugin thật thuộc về các bộ kiểm thử hợp đồng/integration do Plugin sở hữu.

• Bản cài đặt kiểm thử mặc định bỏ qua các bản dựng opus Discord native tùy chọn. Nhận giọng nói Discord dùng bộ giải mã opusscript pure-JS, và @discordjs/opus vẫn bị vô hiệu hóa trong allowBuilds để các bài kiểm thử cục bộ và làn Testbox không biên dịch addon native.
• Dùng một làn hiệu năng giọng nói Discord hoặc làn live chuyên dụng nếu bạn chủ ý cần so sánh một bản dựng opus native. Không đặt @discordjs/opus thành true trong allowBuilds mặc định; điều đó khiến các vòng lặp cài đặt/kiểm thử không liên quan phải biên dịch mã native.

​

Độ ổn định (gateway)

• Lệnh: pnpm test:stability:gateway
• Cấu hình: vitest.gateway.config.ts, bị ép về một worker
• Phạm vi:
  • Khởi động một Gateway loopback thật với diagnostics được bật theo mặc định
  • Đẩy churn thông điệp gateway, memory và payload lớn tổng hợp qua đường dẫn sự kiện diagnostic
  • Truy vấn diagnostics.stability qua Gateway WS RPC
  • Bao phủ các helper lưu bền bundle độ ổn định diagnostic
  • Khẳng định recorder vẫn bị giới hạn, các mẫu RSS tổng hợp ở dưới budget áp lực và độ sâu hàng đợi theo phiên thoát về không
• Kỳ vọng:
  • An toàn cho CI và không cần key
  • Làn hẹp cho theo dõi regression độ ổn định, không thay thế bộ Gateway đầy đủ

​

E2E (gateway smoke)

• Lệnh: pnpm test:e2e
• Cấu hình: vitest.e2e.config.ts
• Tệp: src/**/*.e2e.test.ts, test/**/*.e2e.test.ts, và các kiểm thử E2E bundled-plugin dưới extensions/
• Mặc định runtime:
  • Dùng threads của Vitest với isolate: false, khớp với phần còn lại của repo.
  • Dùng worker thích ứng (CI: tối đa 2, cục bộ: mặc định 1).
  • Mặc định chạy ở chế độ silent để giảm chi phí console I/O.
• Ghi đè hữu ích:
  • OPENCLAW_E2E_WORKERS=<n> để ép số lượng worker (giới hạn ở 16).
  • OPENCLAW_E2E_VERBOSE=1 để bật lại đầu ra console verbose.
• Phạm vi:
  • Hành vi end-to-end của gateway đa instance
  • Bề mặt WebSocket/HTTP, ghép cặp node và networking nặng hơn
• Kỳ vọng:
  • Chạy trong CI (khi được bật trong pipeline)
  • Không cần key thật
  • Nhiều phần chuyển động hơn kiểm thử unit (có thể chậm hơn)

​

E2E: OpenShell backend smoke

• Lệnh: pnpm test:e2e:openshell
• Tệp: extensions/openshell/src/backend.e2e.test.ts
• Phạm vi:
  • Khởi động một gateway OpenShell cô lập trên host qua Docker
  • Tạo sandbox từ một Dockerfile cục bộ tạm thời
  • Thực thi backend OpenShell của OpenClaw qua sandbox ssh-config thật + SSH exec
  • Xác minh hành vi hệ thống tệp remote-canonical qua bridge fs của sandbox
• Kỳ vọng:
  • Chỉ opt-in; không thuộc lần chạy pnpm test:e2e mặc định
  • Cần CLI openshell cục bộ cùng một Docker daemon hoạt động
  • Dùng HOME / XDG_CONFIG_HOME cô lập, rồi hủy gateway kiểm thử và sandbox
• Ghi đè hữu ích:
  • OPENCLAW_E2E_OPENSHELL=1 để bật kiểm thử khi chạy thủ công bộ e2e rộng hơn
  • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell để trỏ tới binary CLI không mặc định hoặc script wrapper

​

Live (provider thật + model thật)

• Lệnh: pnpm test:live
• Cấu hình: vitest.live.config.ts
• Tệp: src/**/*.live.test.ts, test/**/*.live.test.ts, và các kiểm thử live của Plugin đóng gói dưới extensions/
• Mặc định: được bật bởi pnpm test:live (đặt OPENCLAW_LIVE_TEST=1)
• Phạm vi:
  • “Provider/model này có thực sự hoạt động hôm nay với thông tin xác thực thật không?”
  • Bắt các thay đổi định dạng của provider, điểm đặc thù khi gọi công cụ, sự cố xác thực và hành vi giới hạn tốc độ
• Kỳ vọng:
  • Theo thiết kế không ổn định cho CI (mạng thật, chính sách provider thật, hạn mức, sự cố ngừng hoạt động)
  • Tốn tiền / dùng giới hạn tốc độ
  • Ưu tiên chạy các tập con đã thu hẹp thay vì “mọi thứ”
• Các lần chạy live nạp ~/.profile để lấy các khóa API còn thiếu.
• Theo mặc định, các lần chạy live vẫn cô lập HOME và sao chép vật liệu cấu hình/xác thực vào một thư mục home kiểm thử tạm thời để fixture đơn vị không thể sửa đổi ~/.openclaw thật của bạn.
• Chỉ đặt OPENCLAW_LIVE_USE_REAL_HOME=1 khi bạn chủ ý cần kiểm thử live dùng thư mục home thật của mình.
• pnpm test:live hiện mặc định dùng chế độ ít ồn hơn: chế độ này giữ đầu ra tiến trình [live] ..., nhưng ẩn thông báo ~/.profile bổ sung và tắt tiếng nhật ký khởi động Gateway/tiếng ồn Bonjour. Đặt OPENCLAW_LIVE_TEST_QUIET=0 nếu bạn muốn bật lại toàn bộ nhật ký khởi động.
• Xoay vòng khóa API (theo từng provider): đặt *_API_KEYS với định dạng phân tách bằng dấu phẩy/chấm phẩy hoặc *_API_KEY_1, *_API_KEY_2 (ví dụ OPENAI_API_KEYS, ANTHROPIC_API_KEYS, GEMINI_API_KEYS) hoặc ghi đè theo từng live qua OPENCLAW_LIVE_*_KEY; kiểm thử sẽ thử lại khi nhận phản hồi giới hạn tốc độ.
• Đầu ra tiến trình/Heartbeat:
  • Các bộ kiểm thử live hiện phát các dòng tiến trình ra stderr để các lệnh gọi provider lâu vẫn hiển thị là đang hoạt động ngay cả khi cơ chế bắt console của Vitest im lặng.
  • vitest.live.config.ts tắt cơ chế chặn console của Vitest để các dòng tiến trình provider/Gateway được truyền ngay trong các lần chạy live.
  • Điều chỉnh Heartbeat mô hình trực tiếp bằng OPENCLAW_LIVE_HEARTBEAT_MS.
  • Điều chỉnh Heartbeat Gateway/probe bằng OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS.

​

Tôi nên chạy bộ kiểm thử nào?

• Chỉnh sửa logic/kiểm thử: chạy pnpm test (và pnpm test:coverage nếu bạn thay đổi nhiều)
• Chạm vào mạng Gateway / giao thức WS / ghép đôi: thêm pnpm test:e2e
• Gỡ lỗi “bot của tôi bị sập” / lỗi theo provider / gọi công cụ: chạy một pnpm test:live đã thu hẹp

​

Kiểm thử live (chạm mạng)

​

Trình chạy Docker (kiểm tra tùy chọn “hoạt động trong Linux”)

• Trình chạy mô hình live: test:docker:live-models và test:docker:live-gateway chỉ chạy tệp live profile-key tương ứng của chúng bên trong ảnh Docker của repo (src/agents/models.profiles.live.test.ts và src/gateway/gateway-models.profiles.live.test.ts), gắn thư mục cấu hình cục bộ và workspace của bạn (và nạp ~/.profile nếu được gắn). Các điểm vào cục bộ tương ứng là test:live:models-profiles và test:live:gateway-profiles.
• Trình chạy Docker live mặc định dùng giới hạn smoke nhỏ hơn để một lượt quét Docker đầy đủ vẫn thực tế: test:docker:live-models mặc định là OPENCLAW_LIVE_MAX_MODELS=12, và test:docker:live-gateway mặc định là OPENCLAW_LIVE_GATEWAY_SMOKE=1, OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8, OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000, và OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000. Ghi đè các biến môi trường đó khi bạn chủ ý muốn quét toàn diện lớn hơn.
• test:docker:all dựng ảnh Docker live một lần qua test:docker:live-build, đóng gói OpenClaw một lần thành npm tarball thông qua scripts/package-openclaw-for-docker.mjs, rồi dựng/tái sử dụng hai ảnh scripts/e2e/Dockerfile. Ảnh bare chỉ là trình chạy Node/Git cho các làn install/update/plugin-dependency; các làn đó gắn tarball đã dựng sẵn. Ảnh functional cài cùng tarball đó vào /app cho các làn chức năng ứng dụng đã dựng. Định nghĩa làn Docker nằm trong scripts/lib/docker-e2e-scenarios.mjs; logic lập kế hoạch nằm trong scripts/lib/docker-e2e-plan.mjs; scripts/test-docker-all.mjs thực thi kế hoạch đã chọn. Phần tổng hợp dùng bộ lập lịch cục bộ có trọng số: OPENCLAW_DOCKER_ALL_PARALLELISM kiểm soát các slot tiến trình, trong khi các giới hạn tài nguyên ngăn các làn live nặng, npm-install và đa dịch vụ cùng khởi động một lúc. Nếu một làn riêng lẻ nặng hơn các giới hạn đang hoạt động, bộ lập lịch vẫn có thể khởi động làn đó khi pool trống rồi giữ làn đó chạy một mình cho đến khi lại có dung lượng. Mặc định là 10 slot, OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9, OPENCLAW_DOCKER_ALL_NPM_LIMIT=10, và OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7; chỉ điều chỉnh OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT hoặc OPENCLAW_DOCKER_ALL_DOCKER_LIMIT khi máy chủ Docker có nhiều dư địa hơn. Trình chạy thực hiện preflight Docker theo mặc định, xóa các container OpenClaw E2E cũ, in trạng thái mỗi 30 giây, lưu thời gian của các làn thành công vào .artifacts/docker-tests/lane-timings.json, và dùng các thời gian đó để khởi động các làn dài hơn trước trong những lần chạy sau. Dùng OPENCLAW_DOCKER_ALL_DRY_RUN=1 để in manifest làn có trọng số mà không dựng hoặc chạy Docker, hoặc node scripts/test-docker-all.mjs --plan-json để in kế hoạch CI cho các làn đã chọn, nhu cầu package/ảnh và thông tin xác thực.
• Package Acceptance là cổng package gốc GitHub cho “tarball có thể cài đặt này có hoạt động như một sản phẩm không?” Nó phân giải một package ứng viên từ source=npm, source=ref, source=url, hoặc source=artifact, tải nó lên dưới tên package-under-test, rồi chạy các làn Docker E2E tái sử dụng trên đúng tarball đó thay vì đóng gói lại ref đã chọn. Các profile được sắp theo độ rộng: smoke, package, product, và full. Xem Kiểm thử cập nhật và Plugin để biết hợp đồng package/cập nhật/Plugin, ma trận sống sót qua nâng cấp đã phát hành, mặc định phát hành và phân loại lỗi.
• Kiểm tra build và release chạy scripts/check-cli-bootstrap-imports.mjs sau tsdown. Guard này duyệt đồ thị đã build tĩnh từ dist/entry.js và dist/cli/run-main.js và báo lỗi nếu quá trình khởi động trước dispatch nhập các dependency package như Commander, prompt UI, undici hoặc logging trước khi dispatch lệnh; nó cũng giữ chunk chạy Gateway đóng gói dưới ngưỡng và từ chối import tĩnh các đường dẫn Gateway lạnh đã biết. Smoke CLI đã đóng gói cũng bao phủ root help, onboard help, doctor help, status, config schema và lệnh liệt kê mô hình.
• Khả năng tương thích kế thừa của Package Acceptance được giới hạn ở 2026.4.25 (bao gồm 2026.4.25-beta.*). Tới mốc đó, harness chỉ dung thứ các khoảng trống metadata của package đã phát hành: mục QA inventory riêng tư bị bỏ qua, thiếu gateway install --wrapper, thiếu tệp patch trong fixture git lấy từ tarball, thiếu update.channel đã lưu, vị trí install-record Plugin kế thừa, thiếu lưu install-record marketplace và migration metadata cấu hình trong plugins update. Với các package sau 2026.4.25, các đường dẫn đó là lỗi nghiêm ngặt.
• Trình chạy smoke container: test:docker:openwebui, test:docker:onboard, test:docker:npm-onboard-channel-agent, test:docker:skill-install, test:docker:update-channel-switch, test:docker:upgrade-survivor, test:docker:published-upgrade-survivor, test:docker:session-runtime-context, test:docker:agents-delete-shared-workspace, test:docker:gateway-network, test:docker:browser-cdp-snapshot, test:docker:mcp-channels, test:docker:pi-bundle-mcp-tools, test:docker:cron-mcp-cleanup, test:docker:plugins, test:docker:plugin-update, test:docker:plugin-lifecycle-matrix, và test:docker:config-reload khởi động một hoặc nhiều container thật và xác minh các đường dẫn tích hợp cấp cao hơn.

• Mô hình trực tiếp: pnpm test:docker:live-models (script: scripts/test-live-models-docker.sh)
• Kiểm thử nhanh ràng buộc ACP: pnpm test:docker:live-acp-bind (script: scripts/test-live-acp-bind-docker.sh; mặc định bao phủ Claude, Codex và Gemini, với phạm vi bao phủ Droid/OpenCode nghiêm ngặt qua pnpm test:docker:live-acp-bind:droid và pnpm test:docker:live-acp-bind:opencode)
• Kiểm thử nhanh backend CLI: pnpm test:docker:live-cli-backend (script: scripts/test-live-cli-backend-docker.sh)
• Kiểm thử nhanh harness app-server Codex: pnpm test:docker:live-codex-harness (script: scripts/test-live-codex-harness-docker.sh)
• Gateway + agent dev: pnpm test:docker:live-gateway (script: scripts/test-live-gateway-models-docker.sh)
• Kiểm thử nhanh khả năng quan sát: pnpm qa:otel:smoke là một làn kiểm tra source-checkout QA riêng tư. Làn này cố ý không nằm trong các làn phát hành Docker của gói vì tarball npm bỏ qua QA Lab.
• Kiểm thử nhanh live Open WebUI: pnpm test:docker:openwebui (script: scripts/e2e/openwebui-docker.sh)
• Trình hướng dẫn onboarding (TTY, dựng khung đầy đủ): pnpm test:docker:onboard (script: scripts/e2e/onboard-docker.sh)
• Kiểm thử nhanh onboarding/channel/agent bằng tarball npm: pnpm test:docker:npm-onboard-channel-agent cài đặt tarball OpenClaw đã đóng gói ở phạm vi toàn cục trong Docker, cấu hình OpenAI qua onboarding tham chiếu env cùng Telegram theo mặc định, chạy doctor và chạy một lượt agent OpenAI được mock. Tái sử dụng tarball đã dựng sẵn với OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz, bỏ qua việc dựng lại trên host với OPENCLAW_NPM_ONBOARD_HOST_BUILD=0, hoặc chuyển kênh bằng OPENCLAW_NPM_ONBOARD_CHANNEL=discord hoặc OPENCLAW_NPM_ONBOARD_CHANNEL=slack.
• Kiểm thử nhanh cài đặt Skill: pnpm test:docker:skill-install cài đặt tarball OpenClaw đã đóng gói ở phạm vi toàn cục trong Docker, tắt cài đặt archive đã tải lên trong cấu hình, phân giải slug skill ClawHub live hiện tại từ tìm kiếm, cài đặt bằng openclaw skills install, rồi xác minh skill đã cài đặt cùng metadata nguồn gốc/khóa .clawhub.
• Kiểm thử nhanh chuyển kênh cập nhật: pnpm test:docker:update-channel-switch cài đặt tarball OpenClaw đã đóng gói ở phạm vi toàn cục trong Docker, chuyển từ gói stable sang git dev, xác minh kênh đã lưu và Plugin sau cập nhật hoạt động, rồi chuyển lại về gói stable và kiểm tra trạng thái cập nhật.
• Kiểm thử nhanh sống sót sau nâng cấp: pnpm test:docker:upgrade-survivor cài đặt tarball OpenClaw đã đóng gói đè lên một fixture người dùng cũ còn bẩn với agent, cấu hình kênh, danh sách cho phép Plugin, trạng thái phụ thuộc Plugin cũ và các tệp workspace/session hiện có. Lệnh này chạy cập nhật gói cùng doctor không tương tác mà không có khóa nhà cung cấp hoặc kênh live, sau đó khởi động một Gateway loopback và kiểm tra việc giữ nguyên cấu hình/trạng thái cùng ngân sách khởi động/trạng thái.
• Kiểm thử nhanh sống sót sau nâng cấp bản đã phát hành: pnpm test:docker:published-upgrade-survivor mặc định cài đặt openclaw@latest, seed các tệp người dùng hiện có thực tế, cấu hình baseline đó bằng một công thức lệnh được nhúng sẵn, xác thực cấu hình thu được, cập nhật bản cài đặt đã phát hành đó lên tarball ứng viên, chạy doctor không tương tác, ghi .artifacts/upgrade-survivor/summary.json, rồi khởi động một Gateway loopback và kiểm tra intent đã cấu hình, việc giữ nguyên trạng thái, khởi động, /healthz, /readyz và ngân sách trạng thái RPC. Ghi đè một baseline bằng OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC, yêu cầu bộ lập lịch tổng hợp mở rộng các baseline 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, và mở rộng fixture dạng issue bằng OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS như reported-issues; tập reported-issues bao gồm configured-plugin-installs để tự động sửa cài đặt Plugin OpenClaw bên ngoài. Package Acceptance cung cấp các mục đó dưới dạng published_upgrade_survivor_baseline, published_upgrade_survivor_baselines và published_upgrade_survivor_scenarios, phân giải các token baseline meta như last-stable-4 hoặc all-since-2026.4.23, và Full Release Validation mở rộng cổng gói release-soak thành last-stable-4 2026.4.23 2026.5.2 2026.4.15 cộng với reported-issues.
• Kiểm thử nhanh ngữ cảnh runtime session: pnpm test:docker:session-runtime-context xác minh việc duy trì transcript ngữ cảnh runtime ẩn cùng sửa chữa bằng doctor cho các nhánh prompt-rewrite trùng lặp bị ảnh hưởng.
• Kiểm thử nhanh cài đặt toàn cục Bun: bash scripts/e2e/bun-global-install-smoke.sh đóng gói cây hiện tại, cài đặt bằng bun install -g trong một home cô lập, và xác minh openclaw infer image providers --json trả về các nhà cung cấp hình ảnh được đóng gói thay vì bị treo. Tái sử dụng tarball đã dựng sẵn với OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz, bỏ qua dựng trên host với OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0, hoặc sao chép dist/ từ một image Docker đã dựng bằng OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local.
• Kiểm thử nhanh Docker trình cài đặt: bash scripts/test-install-sh-docker.sh dùng chung một cache npm cho các container root, update và direct-npm. Kiểm thử nhanh cập nhật mặc định dùng npm latest làm baseline stable trước khi nâng cấp lên tarball ứng viên. Ghi đè bằng OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22 cục bộ, hoặc bằng input update_baseline_version của workflow Install Smoke trên GitHub. Các kiểm tra trình cài đặt không phải root giữ một cache npm cô lập để các mục cache do root sở hữu không che khuất hành vi cài đặt cục bộ của người dùng. Đặt OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache để tái sử dụng cache root/update/direct-npm qua các lần chạy lại cục bộ.
• Install Smoke CI bỏ qua cập nhật toàn cục direct-npm trùng lặp bằng OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1; chạy script cục bộ không có env đó khi cần phạm vi bao phủ npm install -g trực tiếp.
• Kiểm thử nhanh CLI xóa workspace dùng chung của agent: pnpm test:docker:agents-delete-shared-workspace (script: scripts/e2e/agents-delete-shared-workspace-docker.sh) mặc định dựng image Dockerfile gốc, seed hai agent với một workspace trong home container cô lập, chạy agents delete --json, và xác minh JSON hợp lệ cùng hành vi giữ lại workspace. Tái sử dụng image install-smoke với OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1.
• Mạng Gateway (hai container, xác thực WS + sức khỏe): pnpm test:docker:gateway-network (script: scripts/e2e/gateway-network-docker.sh)
• Kiểm thử nhanh snapshot CDP trình duyệt: pnpm test:docker:browser-cdp-snapshot (script: scripts/e2e/browser-cdp-snapshot-docker.sh) dựng image E2E nguồn cùng một lớp Chromium, khởi động Chromium với CDP thô, chạy browser doctor --deep, và xác minh snapshot vai trò CDP bao phủ URL liên kết, phần tử có thể nhấp được nâng cấp bằng con trỏ, tham chiếu iframe và metadata frame.
• Hồi quy reasoning tối thiểu OpenAI Responses web_search: pnpm test:docker:openai-web-search-minimal (script: scripts/e2e/openai-web-search-minimal-docker.sh) chạy một máy chủ OpenAI được mock qua Gateway, xác minh web_search nâng reasoning.effort từ minimal lên low, sau đó buộc schema nhà cung cấp từ chối và kiểm tra chi tiết thô xuất hiện trong log Gateway.
• Cầu nối kênh MCP (Gateway đã seed + cầu nối stdio + kiểm thử nhanh notification-frame Claude thô): pnpm test:docker:mcp-channels (script: scripts/e2e/mcp-channels-docker.sh)
• Công cụ MCP gói Pi (máy chủ MCP stdio thật + kiểm thử nhanh allow/deny hồ sơ Pi nhúng): pnpm test:docker:pi-bundle-mcp-tools (script: scripts/e2e/pi-bundle-mcp-tools-docker.sh)
• Dọn dẹp MCP Cron/subagent (Gateway thật + gỡ bỏ tiến trình con MCP stdio sau cron cô lập và các lần chạy subagent một lần): pnpm test:docker:cron-mcp-cleanup (script: scripts/e2e/cron-mcp-cleanup-docker.sh)
• Plugins (kiểm thử nhanh cài đặt/cập nhật cho đường dẫn cục bộ, file:, registry npm với phụ thuộc được hoist, ref git di động, ClawHub kitchen-sink, cập nhật marketplace và bật/kiểm tra Claude-bundle): pnpm test:docker:plugins (script: scripts/e2e/plugins-docker.sh) Đặt OPENCLAW_PLUGINS_E2E_CLAWHUB=0 để bỏ qua khối ClawHub, hoặc ghi đè cặp package/runtime kitchen-sink mặc định bằng OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC và OPENCLAW_PLUGINS_E2E_CLAWHUB_ID. Nếu không có OPENCLAW_CLAWHUB_URL/CLAWHUB_URL, bài kiểm tra dùng một máy chủ fixture ClawHub cục bộ khép kín.
• Kiểm thử nhanh Plugin update không đổi: pnpm test:docker:plugin-update (script: scripts/e2e/plugin-update-unchanged-docker.sh)
• Kiểm thử nhanh ma trận vòng đời Plugin: pnpm test:docker:plugin-lifecycle-matrix cài đặt tarball OpenClaw đã đóng gói trong một container trống, cài đặt một Plugin npm, bật/tắt, nâng cấp và hạ cấp nó qua một registry npm cục bộ, xóa mã đã cài đặt, rồi xác minh uninstall vẫn xóa trạng thái cũ trong khi ghi log các chỉ số RSS/CPU cho từng giai đoạn vòng đời.
• Kiểm thử nhanh metadata tải lại cấu hình: pnpm test:docker:config-reload (script: scripts/e2e/config-reload-source-docker.sh)
• Plugins: pnpm test:docker:plugins bao phủ kiểm thử nhanh cài đặt/cập nhật cho đường dẫn cục bộ, file:, registry npm với phụ thuộc được hoist, ref git di động, fixture ClawHub, cập nhật marketplace và bật/kiểm tra Claude-bundle. pnpm test:docker:plugin-update bao phủ hành vi cập nhật không đổi cho Plugin đã cài đặt. pnpm test:docker:plugin-lifecycle-matrix bao phủ cài đặt, bật, tắt, nâng cấp, hạ cấp và uninstall khi thiếu mã của Plugin npm có theo dõi tài nguyên.

OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build
OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels

• bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...
• Giữ script này cho các workflow hồi quy/debug. Nó có thể lại cần cho việc xác thực định tuyến thread ACP, vì vậy đừng xóa nó.

• OPENCLAW_CONFIG_DIR=... (mặc định: ~/.openclaw) được mount vào /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR=... (mặc định: ~/.openclaw/workspace) được mount vào /home/node/.openclaw/workspace
• OPENCLAW_PROFILE_FILE=... (mặc định: ~/.profile) được mount vào /home/node/.profile và được source trước khi chạy kiểm thử
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1 để chỉ xác minh các biến môi trường được source từ OPENCLAW_PROFILE_FILE, dùng các thư mục config/workspace tạm thời và không mount auth CLI bên ngoài
• OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (mặc định: ~/.cache/openclaw/docker-cli-tools) được mount vào /home/node/.npm-global cho các cài đặt CLI được cache bên trong Docker
• Các thư mục/tệp auth CLI bên ngoài dưới $HOME được mount chỉ đọc dưới /host-auth..., rồi được sao chép vào /home/node/... trước khi kiểm thử bắt đầu
  • Thư mục mặc định: .minimax
  • Tệp mặc định: ~/.codex/auth.json, ~/.codex/config.toml, .claude.json, ~/.claude/.credentials.json, ~/.claude/settings.json, ~/.claude/settings.local.json
  • Các lần chạy provider đã thu hẹp chỉ mount những thư mục/tệp cần thiết được suy luận từ OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS
  • Ghi đè thủ công bằng OPENCLAW_DOCKER_AUTH_DIRS=all, OPENCLAW_DOCKER_AUTH_DIRS=none, hoặc danh sách phân tách bằng dấu phẩy như OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex
• OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... để thu hẹp lần chạy
• OPENCLAW_LIVE_GATEWAY_PROVIDERS=... / OPENCLAW_LIVE_PROVIDERS=... để lọc provider trong container
• OPENCLAW_SKIP_DOCKER_BUILD=1 để tái sử dụng image openclaw:local-live hiện có cho các lần chạy lại không cần rebuild
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 để đảm bảo cred đến từ profile store (không phải env)
• OPENCLAW_OPENWEBUI_MODEL=... để chọn mô hình gateway hiển thị cho smoke Open WebUI
• OPENCLAW_OPENWEBUI_PROMPT=... để ghi đè prompt kiểm tra nonce được smoke Open WebUI dùng
• OPENWEBUI_IMAGE=... để ghi đè tag image Open WebUI đã pin

​

Kiểm tra hợp lệ tài liệu

​

Hồi quy ngoại tuyến (an toàn cho CI)

• Gọi tool qua Gateway (OpenAI mock, gateway thật + vòng lặp agent): src/gateway/gateway.test.ts (case: “runs a mock OpenAI tool call end-to-end via gateway agent loop”)
• Wizard Gateway (WS wizard.start/wizard.next, ghi config + bắt buộc auth): src/gateway/gateway.test.ts (case: “runs wizard over ws and writes auth token config”)

​

Đánh giá độ tin cậy agent (skills)

• Gọi tool mock qua gateway thật + vòng lặp agent (src/gateway/gateway.test.ts).
• Luồng wizard đầu cuối xác thực wiring session và hiệu lực config (src/gateway/gateway.test.ts).

• Ra quyết định: khi skills được liệt kê trong prompt, agent có chọn đúng skill (hoặc tránh những skill không liên quan) không?
• Tuân thủ: agent có đọc SKILL.md trước khi dùng và làm theo các bước/args bắt buộc không?
• Hợp đồng workflow: các kịch bản nhiều turn assert thứ tự tool, truyền tiếp lịch sử session, và ranh giới sandbox.

• Một scenario runner dùng provider mock để assert tool call + thứ tự, đọc tệp skill, và wiring session.
• Một bộ nhỏ các kịch bản tập trung vào skill (dùng so với tránh, gating, prompt injection).
• Đánh giá trực tiếp tùy chọn (opt-in, được gate bằng env) chỉ sau khi bộ an toàn cho CI đã có.

​

Kiểm thử hợp đồng (hình dạng plugin và kênh)

​

Lệnh

• Tất cả hợp đồng: pnpm test:contracts
• Chỉ hợp đồng kênh: pnpm test:contracts:channels
• Chỉ hợp đồng provider: pnpm test:contracts:plugins

​

Hợp đồng kênh

• plugin - Hình dạng plugin cơ bản (id, tên, capability)
• setup - Hợp đồng wizard thiết lập
• session-binding - Hành vi ràng buộc session
• outbound-payload - Cấu trúc payload tin nhắn
• inbound - Xử lý tin nhắn đến
• actions - Handler hành động kênh
• threading - Xử lý ID thread
• directory - API thư mục/roster
• group-policy - Thực thi chính sách nhóm

​

Hợp đồng trạng thái provider

• status - Probe trạng thái kênh
• registry - Hình dạng registry plugin

​

Hợp đồng provider

• auth - Hợp đồng luồng auth
• auth-choice - Lựa chọn/chọn auth
• catalog - API catalog mô hình
• discovery - Khám phá plugin
• loader - Tải plugin
• runtime - Runtime provider
• shape - Hình dạng/interface plugin
• wizard - Wizard thiết lập

​

Khi nào chạy

• Sau khi thay đổi export hoặc subpath của plugin-sdk
• Sau khi thêm hoặc sửa đổi một plugin kênh hoặc provider
• Sau khi refactor đăng ký hoặc khám phá plugin

​

Thêm hồi quy (hướng dẫn)

• Thêm hồi quy an toàn cho CI nếu có thể (provider mock/stub, hoặc capture phép biến đổi request-shape chính xác)
• Nếu nó vốn chỉ có thể kiểm thử live (rate limit, chính sách auth), giữ kiểm thử live hẹp và opt-in qua biến môi trường
• Ưu tiên nhắm vào lớp nhỏ nhất bắt được lỗi:
  • lỗi chuyển đổi/phát lại request provider → kiểm thử models trực tiếp
  • lỗi pipeline gateway session/history/tool → smoke gateway trực tiếp hoặc kiểm thử mock gateway an toàn cho CI
• Guardrail duyệt SecretRef:
  • src/secrets/exec-secret-ref-id-parity.test.ts suy ra một target được lấy mẫu cho mỗi lớp SecretRef từ metadata registry (listSecretTargetRegistryEntries()), rồi assert các exec id có segment duyệt bị từ chối.
  • Nếu bạn thêm một họ target SecretRef includeInPlan mới trong src/secrets/target-registry-data.ts, hãy cập nhật classifyTargetClass trong kiểm thử đó. Kiểm thử cố ý fail trên các target id chưa được phân loại để các lớp mới không thể bị bỏ qua âm thầm.

​

Liên quan

• Kiểm thử trực tiếp
• Kiểm thử cập nhật và plugin
• CI