测试参考

本文档涵盖 OpenClaw 项目的所有测试套件、基准测试脚本和 CI 集成流程。

测试命令总览

命令	说明
pnpm test	运行快速核心单元测试（默认，用于本地快速反馈）
pnpm test:force	杀死占用默认控制端口的残留 Gateway 进程，然后使用隔离端口运行完整 Vitest 套件
pnpm test:coverage	运行单元测试并生成 V8 覆盖率报告（通过 vitest.unit.config.ts）
pnpm test:channels	运行渠道相关测试套件
pnpm test:extensions	运行扩展/插件测试套件
pnpm test:gateway	运行 Gateway 集成测试
pnpm test:e2e	运行 Gateway 端到端冒烟测试
pnpm test:live	运行 Provider 实时测试（需要 API Key）

核心测试

基础单元测试

pnpm test

默认运行快速核心单元测试通道（unit lane），提供本地快速反馈。

强制模式

pnpm test:force

当端口 18789 被占用时使用此命令。它会先杀死占用默认控制端口的残留 Gateway 进程，然后使用隔离的 Gateway 端口运行完整 Vitest 套件。

Node 24+ 兼容性

在 Node 24+ 上运行 pnpm test 时，系统会自动禁用 Vitest 的 vmForks 并改用 forks，以避免 ERR_VM_MODULE_LINK_FAILURE / module is already linked 错误。

可通过环境变量强制控制行为：

# 强制禁用 vmForks
OPENCLAW_TEST_VM_FORKS=0 pnpm test

# 强制启用 vmForks
OPENCLAW_TEST_VM_FORKS=1 pnpm test

覆盖率

pnpm test:coverage

通过 vitest.unit.config.ts 运行 V8 覆盖率检测。

全局阈值要求：

指标	阈值
行覆盖率（Lines）	70%
分支覆盖率（Branches）	70%
函数覆盖率（Functions）	70%
语句覆盖率（Statements）	70%

排除项： 集成密集型入口点（CLI wiring、gateway/telegram bridges、webchat 静态服务器）不计入覆盖率统计。

集成测试与 E2E 测试

Gateway 集成测试

Gateway 集成测试默认不运行，需要手动启用：

# 通过环境变量启用
OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test

# 或使用专用命令
pnpm test:gateway

端到端（E2E）测试

pnpm test:e2e

运行 Gateway 端到端冒烟测试，涵盖多实例 WebSocket/HTTP/Node 配对场景。

配置选项：

• 默认使用 vmForks + 自适应 Worker（在 vitest.e2e.config.ts 中配置）
• OPENCLAW_E2E_WORKERS= — 调整 Worker 数量
• OPENCLAW_E2E_VERBOSE=1 — 启用详细日志

渠道与扩展测试

# 渠道相关测试
pnpm test:channels

# 扩展/插件测试
pnpm test:extensions

Provider 实时测试

pnpm test:live

运行 Provider 实时测试（如 MiniMax、ZAI）。需要以下条件：

• 对应 Provider 的 API Key
• 设置 LIVE=1（或 Provider 专用的 *_LIVE_TEST=1）以取消跳过

本地 PR Gate 检查

提交 PR 前，在本地运行以下完整检查流程：

pnpm check
pnpm build
pnpm test
pnpm check:docs

测试抖动处理

如果 pnpm test 在高负载主机上出现 flake（不稳定），先重新运行一次再判断是否为回归问题，然后使用 pnpm vitest run 隔离定位。

内存受限主机

在内存有限的环境中运行测试：

OPENCLAW_TEST_PROFILE=low OPENCLAW_TEST_SERIAL_GATEWAY=1 pnpm test

基准测试

模型延迟基准测试

脚本： scripts/bench-model.ts

用法：

source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10

可选环境变量：

变量	说明
MINIMAX_API_KEY	MiniMax API Key
MINIMAX_BASE_URL	MiniMax Base URL
MINIMAX_MODEL	MiniMax 模型名称
ANTHROPIC_API_KEY	Anthropic API Key

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

参考测试结果（2025-12-31，20 次运行）：

模型	中位数	最小值	最大值
MiniMax	1279ms	1114ms	2431ms
Opus	2454ms	1224ms	3170ms

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

输出指标： 每个命令的 avg、p50、p95、min/max 以及 exit-code/signal 分布。

Docker 测试

引导 E2E 测试（Docker）

Docker 为可选项，仅在需要容器化引导冒烟测试时使用。

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

scripts/e2e/onboard-docker.sh

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

QR 导入冒烟测试（Docker）

确保 qrcode-terminal 在 Docker 环境中的 Node 22+ 上正常加载：

pnpm test:docker:qr

完整测试资源

更多测试套件详情，包括实时测试和 Docker 支持，请参见 Testing。