测试

• 完整测试套件（测试组、实时测试、Docker）：测试指南

• pnpm test:force：终止占用默认控制端口的残留 gateway 进程，然后在隔离的 gateway 端口上运行完整 Vitest 套件，防止服务器测试与正在运行的实例冲突。当之前的 gateway 运行占用了 18789 端口时使用此命令。

• pnpm test:coverage：通过 vitest.unit.config.ts 运行带 V8 覆盖率的单元套件。全局阈值为行/分支/函数/语句的 70%。覆盖率排除集成密集型入口（CLI 配置、gateway/telegram 桥接、webchat 静态服务器），以保持目标专注于可单元测试的逻辑。

• pnpm test:coverage:changed：仅对自 origin/main 以来变更的文件运行单元覆盖率。

• pnpm test:changed：使用 --changed origin/main 运行包装器。基础 Vitest 配置将包装器清单/配置文件视为 forceRerunTriggers，以便在需要时调度器变更仍能广泛重新运行。

• pnpm test：运行完整包装器。在 git 中只保留一个小的行为覆盖清单，然后使用已签入的计时快照将最重的单元文件分拆到专用通道中。

• 单元文件在包装器中默认使用 threads；将 fork-only 例外情况记录在 test/fixtures/test-parallel.behavior.json 中。

• pnpm test:channels 现在通过 vitest.channels.config.ts 默认使用 threads；2026 年 3 月 22 日的直接完整套件控制运行通过，没有渠道特定的 fork 例外。

• pnpm test:extensions 通过包装器运行，并在 test/fixtures/test-parallel.behavior.json 中保留已记录的扩展 fork-only 例外；共享扩展通道仍默认使用 threads。

• pnpm test:extensions：运行扩展/插件套件。

• pnpm test:perf:imports：为包装器启用 Vitest 导入持续时间 + 导入细分报告。

• pnpm test:perf:imports:changed：相同的导入分析，但仅针对自 origin/main 以来变更的文件。

• pnpm test:perf:profile:main：为 Vitest 主线程写入 CPU 分析文件（.artifacts/vitest-main-profile）。

• pnpm test:perf:profile:runner：为单元运行器写入 CPU + 堆分析文件（.artifacts/vitest-runner-profile）。

• pnpm test:perf:update-timings：刷新 scripts/test-parallel.mjs 使用的已签入慢文件计时快照。

• Gateway 集成：通过 OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test 或 pnpm test:gateway 选择加入。

• pnpm test:e2e：运行 gateway 端到端烟雾测试（多实例 WS/HTTP/node 配对）。在 vitest.e2e.config.ts 中默认使用 forks + 自适应 workers；使用 OPENCLAW_E2E_WORKERS=<n> 调整，设置 OPENCLAW_E2E_VERBOSE=1 获取详细日志。

• pnpm test:live：运行提供商实时测试（minimax/zai）。需要 API 密钥和 LIVE=1（或特定提供商的 *_LIVE_TEST=1）才能取消跳过。

• pnpm test:docker:openwebui：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 /api/models，然后通过 /api/chat/completions 运行真实的代理聊天。需要可用的实时模型密钥（例如 ~/.profile 中的 OpenAI），拉取外部 Open WebUI 镜像，不期望像普通单元/e2e 套件那样在 CI 中稳定运行。

本地 PR 门控

用于本地 PR 合并/门控检查，运行：

• pnpm check
• pnpm build
• pnpm test
• pnpm check:docs

如果 pnpm test 在高负载主机上不稳定，在视为回归之前重新运行一次，然后用 pnpm vitest run <path/to/test> 隔离。对于内存受限的主机，使用：

• OPENCLAW_TEST_PROFILE=low OPENCLAW_TEST_SERIAL_GATEWAY=1 pnpm test
• OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed

模型延迟基准测试（本地密钥）

脚本：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
• 默认提示词："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 tsx scripts/bench-cli-startup.ts
• pnpm tsx scripts/bench-cli-startup.ts --runs 12
• pnpm tsx scripts/bench-cli-startup.ts --entry dist/entry.js --timeout-ms 45000

此基准测试以下命令：

• --version
• --help
• health --json
• status --json
• status

输出包括每个命令的平均值、p50、p95、最小/最大值和退出码/信号分布。

入门 E2E（Docker）

Docker 是可选的；这仅用于容器化入门烟雾测试。

在干净的 Linux 容器中完整冷启动流程：

scripts/e2e/onboard-docker.sh

此脚本通过伪 tty 驱动交互式向导，验证配置/工作区/会话文件，然后启动 gateway 并运行 openclaw health。

QR 导入烟雾测试（Docker）

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

pnpm test:docker:qr