本页是 OpenClaw 开发者的测试命令完整参考。涵盖日常开发中常用的 pnpm test、pnpm test:coverage、pnpm test:changed，以及进阶的 pnpm test:live（需要真实 API Key）、pnpm test:e2e（端到端网关测试）、Docker 集成测试和性能基准测试命令。

OpenClaw 测试命令参考

完整测试套件文档：Testing

常用测试命令

命令	说明
pnpm test	运行原生 Vitest 根项目配置，文件过滤跨配置的项目生效
pnpm test:force	终止占用默认控制端口的遗留网关进程，然后在隔离的网关端口运行完整 Vitest 套件（解决 port 18789 被占用的问题）
pnpm test:coverage	以 V8 覆盖率运行单元套件（via vitest.unit.config.ts），全局阈值 70%（行/分支/函数/语句）
pnpm test:coverage:changed	只对 origin/main 以来改动的文件运行单元覆盖率
pnpm test:changed	原生 Vitest 项目配置加 --changed origin/main，配置/wiring 变更时仍会触发广泛重跑
pnpm test:channels	运行 vitest.channels.config.ts
pnpm test:extensions	运行扩展/插件套件（vitest.extensions.config.ts）

Vitest 基础配置

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

性能分析

命令	说明
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）

网关集成测试

# 启用网关集成测试
OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test
# 或
pnpm test:gateway

端到端测试

pnpm test:e2e

运行网关端到端烟雾测试（多实例 WS/HTTP/node pairing）。默认 threads + isolate: false。调优：

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

Live 提供商测试

pnpm test:live

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

本地 PR 门控

提交前运行以下检查：

pnpm check
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

性能基准

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

脚本：scripts/bench-model.ts

source ~/.profile && 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."

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 比较当前结果

高级用法：

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 --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 --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、agents list --json、gateway status、gateway health --json、config get gateway.port
• all：两个 preset 合并

输出包含 avg、p50、p95、min/max、退出码/信号分布和最大 RSS 摘要。可选 --cpu-prof-dir / --heap-prof-dir 在同一测试框架下同时写入 V8 Profile，使计时和 Profile 捕获保持一致。

检入的基准 fixture：

• test/fixtures/cli-startup-bench.json
• 刷新：pnpm test:startup:bench:update
• 对比：pnpm test:startup:bench:check

Docker 测试

OpenWebUI 集成测试

pnpm test:docker:openwebui

启动 Dockerized OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 /api/models，然后通过 /api/chat/completions 运行真实代理聊天。需要可用的 live 模型 Key，拉取外部 Open WebUI 镜像，不如普通单元/e2e 套件稳定。

MCP 渠道 Docker 测试

pnpm test:docker:mcp-channels

启动带种子数据的 Gateway 容器和第二个客户端容器（生成 openclaw mcp serve），然后验证路由对话发现、Transcript 读取、附件元数据、实时事件队列行为、出站发送路由，以及通过真实 stdio 桥接的 Claude 风格渠道和权限通知。

Onboarding Docker 端到端

scripts/e2e/onboard-docker.sh

在干净的 Linux 容器中运行完整冷启动流程，通过伪 TTY 驱动交互式向导，验证 config/workspace/session 文件，然后启动网关并运行 openclaw health。

QR 导入烟雾测试

pnpm test:docker:qr

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

常见问题

Q: pnpm test 总是偶尔失败，是正常的吗？

A: 在高负载机器上偶尔出现不稳定是已知情况，建议先重跑一次再定位是真实回归还是环境问题。用 pnpm test <path/to/test> 隔离具体文件后单独跑，更容易复现和调试。

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

A: 是 CI 检查会跑的阈值，低于 70% 会失败。但覆盖率统计排除了集成测试密集的入口点（CLI wiring、网关/Telegram 桥、WebChat 静态服务器），专注于可单元测试的逻辑。

Q: 什么时候需要运行 pnpm test:live？

A: 改动了提供商集成代码（新模型支持、传输层、用量归一化）时需要运行 live 测试，确认实际 API 行为。普通功能开发不需要，因为需要真实 API Key 且可能产生费用。