对于 OpenClaw 开发者，本页提供完整的测试命令配置指南。日常开发用 pnpm test 运行单元测试；端口冲突时用 pnpm test:force 清理旧进程；pnpm test:coverage 使用 V8 覆盖率，阈值 70% 行/函数/语句/分支，可通过 OPENCLAW_VITEST_MAX_WORKERS=1 应对内存受限主机。Docker 端到端测试需要额外配置，例如 pnpm test:docker:openwebui 需要 live 模型 Key，pnpm test:docker:qr 验证 QR 运行时兼容性。性能基准脚本（模型延迟/CLI 启动/网关重启）支持 JSON 输出和 CPU profile，用于对比改动前后的性能变化。

OpenClaw 测试命令完整参考

完整测试套件文档：Testing

更新与插件包验证：Testing updates and plugins

常用测试命令

命令	说明
pnpm test	运行原生 Vitest 配置，文件过滤跨配置生效；未指定目标时使用固定分片组并展开到叶子配置以支持本地并行执行
pnpm test:force	终止占用默认控制端口（通常 18789）的残留网关进程，在隔离端口运行完整 Vitest 套件，避免与运行中的实例冲突
pnpm test:coverage	通过 vitest.unit.config.ts 使用 V8 覆盖率运行单元套件；全局阈值 70%（行/函数/语句），分支 55%。仅统计非快速单元测试及其同名源文件，不包含所有传递性导入
pnpm test:coverage:changed	只对 origin/main 以来改动的文件运行单元覆盖率
pnpm test:changed	智能变更测试，仅运行直接编辑产生的精确目标、同目录 *.test.ts、明确源映射以及本地导入图中的文件。广泛的配置/包变更会被跳过，除非映射到精确测试
OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed	强制走更广泛的变更测试模式，用于测试装备/配置/包编辑应回退到 Vitest 默认行为时
pnpm changed:lanes	显示 origin/main 差异触发的架构层
pnpm check:changed	运行智能变更检查门控（typecheck、lint、guard 命令），不运行 Vitest；测试验证用 pnpm test:changed 或显式 pnpm test <target>

Vitest 基础配置

• 默认使用 pool: "threads" 和 isolate: false，非隔离 runner 在全局配置中启用

性能分析与基准

命令	说明
pnpm test:perf:imports	启用 Vitest import 时长 + 分解报告
pnpm test:perf:imports:changed	同上，只针对 origin/main 以来改动的文件
pnpm test:perf:profile:main	为 Vitest 主线程写入 CPU Profile（.artifacts/vitest-main-profile）
pnpm test:perf:profile:runner	为单元 runner 写入 CPU + 堆内存 Profile（.artifacts/vitest-runner-profile）
pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json	串行运行所有叶子配置并输出分组时长及日志；用于性能优化前的 baseline
pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json	比较改动前后的性能分组报表

网关集成测试

OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test
# 或
pnpm test:gateway

端到端测试

pnpm test:e2e

运行网关端到端烟雾测试（多实例 WS/HTTP/node pairing），包含 Control UI 模拟浏览器 E2E。默认 threads + isolate: false。

调优变量：

• OPENCLAW_E2E_WORKERS=<n>：设置 worker 数量
• OPENCLAW_E2E_VERBOSE=1：详细日志

Live 提供商测试

pnpm test:live

需要 API Key 和 LIVE=1（或提供商特定的 *_LIVE_TEST=1）才能取消跳过。

渠道与扩展测试

pnpm test:channels         # 运行 vitest.channels.config.ts
pnpm test:extensions       # 运行所有扩展/插件分片
pnpm test extensions/<id>  # 运行单个打包插件的独立 lane

专有测试命令

测试状态与辅助工具

• 本地 OpenClaw 测试状态：使用 src/test-utils/openclaw-test-state.ts（需要隔离的 HOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH、配置 fixture、工作区、智能体目录或认证存储）
• Control UI 模拟 E2E：pnpm test:ui:e2e 启动 Vite Control UI 并使用真实 Chromium 页面驱动模拟的 Gateway WebSocket。测试位于 ui/src/**/*.e2e.test.ts
• 进程级 E2E 辅助：test/helpers/openclaw-test-instance.ts 用于需要运行中的 Gateway、CLI 环境、日志捕获和清理的测试
• Docker/Bash E2E 辅助：通过 scripts/lib/docker-e2e-image.sh 注入状态，容器内使用 scripts/lib/openclaw-e2e-instance.sh 管理 Gateway 启动/就绪/清理

分片计时数据

全量/扩展/包含模式的分片运行会更新本地计时文件 .artifacts/vitest-shard-timings.json；后续全配置运行会使用这些计时来平衡分片。留用 OPENCLAW_TEST_PROJECTS_TIMINGS=0 可忽略本地计时。

本地 PR 门控

提交前运行以下检查：

pnpm check:changed   # 智能变更检查（typecheck/lint/guard）
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

Codex 工作树和链接/稀疏检出

避免在确认 pnpm 不会重新协调依赖之前直接本地运行 pnpm test*、pnpm check* 和 pnpm crabbox:run。需要小范围精确文件验证时使用 node scripts/run-vitest.mjs <path-or-filter>；变更门控或广泛验证使用 node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox ... --shell -- "pnpm check:changed" 让 pnpm 在 Testbox 内部运行。

重检查锁范围

OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command> 将重检查序列化限制在当前工作树而非 Git 公共目录。仅用于高性能主机上需同时运行独立检查的场景。

性能基准

模型延迟基准（需要本地 Key）

脚本：scripts/bench-model.ts

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

可选环境变量：MINIMAX_API_KEY、MINIMAX_BASE_URL、MINIMAX_MODEL、ANTHROPIC_API_KEY

默认 Prompt："Reply with a single word: ok. No punctuation or extra text."

上次运行（2025-12-31，20 次）：

• minimax 中位数 1279ms（最小1114，最大2431）
• opus 中位数 2454ms（最小1224，最大3170）

CLI 启动基准

脚本：scripts/bench-cli-startup.ts

常用命令：

pnpm test:startup:bench               # 运行基准
pnpm test:startup:bench:smoke         # 写入烟雾工件 .artifacts/cli-startup-bench-smoke.json
pnpm test:startup:bench:save          # 写入完整套件工件 .artifacts/cli-startup-bench-all.json（runs=5,warmup=1）
pnpm test:startup:bench:update        # 刷新检入的基准 fixture test/fixtures/cli-startup-bench.json
pnpm test:startup:bench:check         # 与基准 fixture 比较当前结果

高级选项：

• --runs 12：自定义运行次数
• --preset real 或 --preset all：选择预设命令集合
• --case status --case gatewayStatus：只测试特定命令
• --entry openclaw.mjs --entry-secondary dist/entry.js：指定入口
• --output .artifacts/cli-startup-bench-all.json：JSON 输出
• --cpu-prof-dir .artifacts/cli-cpu：同时写入 CPU profile

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：两个 preset 合并

输出包含 sampleCount、avg、p50、p95、min/max、退出码/信号分布和最大 RSS 摘要。可同时使用 --cpu-prof-dir/--heap-prof-dir 捕获 V8 profile。

网关启动基准

脚本：scripts/bench-gateway-startup.ts

默认使用内置 CLI 入口 dist/entry.js；运行前需要 pnpm build。如需测量源码 runner，传递 --entry scripts/run-node.mjs 并单独记录结果。

常用命令：

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 3 --cpu-prof-dir .artifacts/gateway-startup-cpu

Case id：

• default：正常启动
• skipChannels：跳过渠道启动
• oneInternalHook：一个配置的内部 hook
• allInternalHooks：所有内部 hooks
• fiftyPlugins：50 个清单插件
• fiftyStartupLazyPlugins：50 个启动懒加载插件

输出包含：首次输出、/healthz、/readyz、HTTP 监听日志时间、Gateway 就绪日志时间、CPU 时间、CPU 核心比率、max RSS、堆内存、启动 trace 指标、事件循环延迟、插件查找表详情。脚本会自动设置 OPENCLAW_GATEWAY_STARTUP_TRACE=1。

注意：/healthz 反映 HTTP 服务活性，/readyz 反映启动插件 sidecar、渠道和就绪关键的后置附着工作已稳定。Gateway 启动 hook 异步分发，不影响就绪保证。

网关重启基准

脚本：scripts/bench-gateway-restart.ts

仅支持 macOS 和 Linux（使用 SIGUSR1），Windows 直接失败。

默认使用 dist/entry.js；运行前需要 pnpm build。

常用命令：

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

Case id：

• skipChannels：跳过渠道重启
• skipChannelsAcpxProbe：启用 ACPX 启动探测
• skipChannelsNoAcpxProbe：禁用 ACPX 启动探测
• default：正常重启
• fiftyPlugins：50 个清单插件重启

输出包含：下次 /healthz、下次 /readyz、停机时间、重启就绪时间、CPU/RSS、替换进程的启动 trace 指标、信号处理/活跃工作 drain/关闭阶段/下次启动/就绪时间/内存快照的重启 trace 指标。

脚本会自动设置 OPENCLAW_GATEWAY_STARTUP_TRACE=1 和 OPENCLAW_GATEWAY_RESTART_TRACE=1。

Docker 端到端测试

总览

使用 pnpm test:docker:all 构建共享 live 测试镜像、打包 OpenClaw tarball、构建裸 Node/Git 运行镜像和功能镜像，然后通过加权调度器运行 Docker 烟雾 lane。更多细节见上游文档。

常用环境变量：

• OPENCLAW_DOCKER_ALL_PARALLELISM=<n>：进程槽（默认 10）
• OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>：尾部池（默认 10）
• OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>：live 失败重试次数（默认 1）
• OPENCLAW_DOCKER_ALL_DRY_RUN=1：仅打印 lane 清单，不运行 Docker
• OPENCLAW_DOCKER_ALL_LIVE_MODE=skip 或 only：跳过或只运行 live lane

别名命令：

• pnpm test:docker:local:all：运行本地/deterministic lane
• pnpm test:docker:live:all：运行 live-provider lane

日志和结果存储在 .artifacts/docker-tests/<run-id>/ 下，包含 summary.json、failures.json、每个 lane 的日志和阶段计时。

重要 Docker 测试子命令

命令	说明
pnpm test:docker:browser-cdp-snapshot	构建 Chromium 容器，启动 CDP + 隔离 Gateway，运行 browser doctor --deep，验证 CDP 角色快照包含链接、光标可点击元素、iframe 引用和帧元数据
pnpm test:docker:skill-install	打包 tarball 后安装到裸容器，禁用 skills.install.allowUploadedArchives，从实时 ClawHub 搜索技能 slug，安装并验证 SKILL.md、.clawhub/origin.json、.clawhub/lock.json 和 skills info --json
pnpm test:docker:openwebui	启动 Dockerized OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 /api/models，运行代理聊天。需要 live 模型 Key，依赖外部镜像，CI 稳定性不如单元套件
pnpm test:docker:mcp-channels	启动种子 Gateway 容器 + 客户端容器（生成 openclaw mcp serve），验证路由对话、transcript、附件元数据、事件队列、出站路由和 Claude 风格通知
pnpm test:docker:upgrade-survivor	在脏旧用户 fixture 上覆盖安装 tarball，运行更新 + 非交互式 doctor，启动 loopback Gateway，验证 agent、渠道配置、插件允许列表、工作区/会话文件和 RPC 状态存活
pnpm test:docker:published-upgrade-survivor	使用 openclaw@latest 作为基线，生成现有用户文件，通过命令配置，然后升级到打包 tarball，验证升级生存能力
pnpm test:docker:update-migration	使用 openclaw@2026.4.23 作为基线运行升级生存者测试，专门测试 plugin-deps-cleanup 场景
pnpm test:docker:plugins	运行插件安装/更新烟雾测试（本地路径、file:、npm 注册表、git 引用、ClawHub 等）

CLI 后端 live Docker 探测

使用 pnpm test:docker:live-cli-backend:claude、pnpm test:docker:live-cli-backend:claude:resume、pnpm test:docker:live-cli-backend:claude:mcp 等别名运行有针对性的 lane。Gemini 有对应的 :resume 和 :mcp 别名。

Onboarding E2E（Docker）

完整冷启动流程：

scripts/e2e/onboard-docker.sh

通过伪 TTY 驱动交互式向导，验证 config/workspace/session 文件，然后启动网关并运行 openclaw health。

QR 导入烟雾测试

pnpm test:docker:qr

确保 qrcode-terminal 在支持的 Docker Node 运行时（Node 24 默认，Node 22 兼容）下正常加载。

常见问题

pnpm test 偶尔失败是正常的吗？

在高负载机器上偶发不稳定是已知现象。先重跑一次，如果仍然失败再用 pnpm test <path/to/test> 隔离具体文件复现。内存受限时使用 OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test 或设置缓存路径。

pnpm test:coverage 的 70% 阈值是硬性要求吗？

是 CI 检查会执行的硬性阈值，低于 70% 会失败。但覆盖率统计排除了集成测试密集的入口点（CLI wiring、网关/Telegram 桥、WebChat 静态服务器等），只统计可单元测试的逻辑。分支阈值是 55%。

什么时候需要运行 live 测试或 Docker 测试？

• pnpm test:live：改动了提供商集成代码（新模型支持、传输层、用量归一化）时需要确认实际 API 行为。需要真实 API Key 且可能产生费用。
• pnpm test:docker:all：改动了安装流程、升级迁移、插件安装、OpenWebUI 集成等依赖于完整运行环境的代码时使用。本地开发一般不需要，因为需要 Docker 和大量资源。
• scripts/e2e/onboard-docker.sh：确认冷启动交互式向导在干净 Linux 容器中正常工作。

相关文档

• Testing
• Testing live
• Testing updates and plugins