测试

• 完整测试工具包（测试套件、实时测试、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 工作树或链接/稀疏检出中，智能体应避免直接在本地运行 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 是从保活 action 外部停止的；在将其视为失败之前，请检查包装器摘要和命令输出。
• 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、配置固件、工作区、智能体目录或身份验证配置文件存储时，在 Vitest 中使用。
• pnpm test:env-mutations:report：以非阻塞方式报告直接修改 HOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH、OPENCLAW_WORKSPACE_DIR 或相关环境变量键的测试/测试工具。使用它查找共享测试状态辅助工具的迁移候选项。
• test/helpers/openclaw-test-instance.ts：用于需要在一个位置统一处理运行中的 Gateway 网关、CLI 环境、日志捕获和清理的进程级端到端测试。
• 引用 scripts/lib/docker-e2e-image.sh 的 Docker/Bash 端到端测试通道可以将 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 会写入可由 source 加载的主机环境文件（在 create 前添加 --，可避免较新的 Node 运行时将 --env-file 视为 Node 标志）。启动 Gateway 网关的通道可以引用 scripts/lib/openclaw-e2e-instance.sh，用于入口点解析、模拟 OpenAI 启动、前台/后台启动、就绪探测、状态环境变量导出、日志转储和进程清理。

Control UI、TUI 和扩展通道

• Control UI 模拟 E2E： pnpm test:ui:e2e 运行 Vitest + Playwright 通道，启动 Vite Control UI，并驱动真实 Chromium 页面连接到模拟的 Gateway 网关 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。
• TUI 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。

Gateway 网关和 E2E

• Gateway 网关集成需选择性启用：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：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 tarball，构建/复用裸 Node/Git 运行器镜像，以及将该 tarball 安装到 /app 的功能镜像，然后通过加权调度器运行 Docker 冒烟测试通道。scripts/package-openclaw-for-docker.mjs 是本地/CI 唯一的软件包打包器，并在 Docker 使用 tarball 之前验证该 tarball 和 dist/postinstall-inventory.json。

• 裸镜像（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 容器、在兼容的通道之间共享提供商 CLI 工具缓存，并且在首次失败后停止调度新的池化通道，除非设置了 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

新手引导 E2E（Docker）

可选；仅容器化新手引导冒烟测试需要。在全新 Linux 容器中执行完整的冷启动流程：

scripts/e2e/onboard-docker.sh

通过伪终端驱动交互式向导，验证配置/工作区/会话文件，然后启动 Gateway 网关并运行 openclaw health。

QR 导入冒烟测试（Docker）

确保维护的 QR 运行时辅助程序能够在受支持的 Docker Node 运行时下加载（默认 Node 24，兼容 Node 22）：

pnpm test:docker:qr

相关内容

• 测试
• 实时测试
• 更新和插件测试