古法编程

Appearance

OpenClaw 提供三套 Vitest 测试套件：单元/集成、E2E 和实机（live）套件，外加 Docker 运行器和 QA 专用运行器。单元套件不带真实密钥、快速稳定；E2E 套件验证网关和浏览器端到端行为；实机套件需要真实 API 密钥，用于确认提供商/模型是否可以正常响应。推荐在修改后先运行 pnpm build && pnpm check && pnpm test 作为全门控。Docker 运行器（pnpm test:docker:live-models 等）在容器内执行实机测试，避免污染本地配置。契约测试（pnpm test:contracts）确保插件和频道符合接口规范，无需真实密钥。

OpenClaw 测试体系：单元、E2E 与实机测试指南 ​

OpenClaw 包含三个 Vitest 套件（单元/集成、E2E、实机）和一组 Docker 运行器。本文是“如何测试”的操作指南：

  • 每个套件覆盖什么（以及故意不覆盖什么）
  • 常见工作流的运行命令（本地、推送前、调试）
  • 实机测试如何发现凭据并选择模型/提供商
  • 如何为真实模型/提供商问题添加回归测试
  • 契约测试和 QA 专用运行器的用法

快速开始 ​

日常开发：

  • 完整门控（推送前推荐）：pnpm build && pnpm check && pnpm test
  • 大机器上更快跑全套：pnpm test:max
  • Vitest 监视模式：pnpm test:watch
  • 直接指定文件（支持 extension/channel 路径）：pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts

需要额外信心时：

  • 覆盖率门控：pnpm test:coverage
  • E2E 套件：pnpm test:e2e

调试真实提供商/模型（需要真实凭据）：

  • 实机套件（模型 + 网关工具/图像探测）：pnpm test:live
  • 静默执行单个实机文件：pnpm test:live -- src/agents/models.profiles.live.test.ts

提示：一次只跑一个失败案例时，优先使用下面提到的允许列表环境变量来缩小实机范围。

测试套件（什么在哪里运行） ​

将套件理解为“真实性递进”（同时不稳定性和成本也递增）。

单元 / 集成（默认） ​

  • 命令：pnpm test
  • 配置：非定向运行时使用 vitest.full-*.config.ts shard 集合，可能将多项目 shard 展开为每个项目的配置以实现并行调度
  • 文件：src/**/*.test.ts、packages/**/*.test.ts、test/**/*.test.ts；UI 单元测试在专用 unit-ui shard 中运行
  • 范围：纯单元测试、进程内集成测试（网关认证、路由、工具、解析、配置）、已知 bug 的确定性回归
  • 预期：CI 中运行，无需真实密钥，应快速稳定

原生依赖策略：默认测试跳过可选的原生 Discord opus 编译。如果打算显式比较原生 opus 构建，使用专用的 Discord 语音性能或实机通道。

E2E（网关冒烟） ​

  • 命令：pnpm test:e2e
  • 配置：vitest.e2e.config.ts
  • 文件：src/**/*.e2e.test.ts、test/**/*.e2e.test.ts，以及bundled-plugin E2E 测试在 extensions/ 下
  • 运行时默认：使用 Vitest threads 加 isolate: false；自适应 worker（CI 最多 2，本地默认 1）；默认静默模式
  • 覆盖：OPENCLAW_E2E_WORKERS=<n> 强制 worker 数（上限 16），OPENCLAW_E2E_VERBOSE=1 输出详细日志
  • 范围：多实例网关端到端行为、WebSocket/HTTP 接口、节点配对、较重网络操作
  • 预期：CI 中运行（管道启用时），无需真实密钥，比单元测试更耗时

E2E：OpenShell 后端冒烟 ​

  • 命令：pnpm test:e2e:openshell
  • 文件：extensions/openshell/src/backend.e2e.test.ts
  • 范围：通过 Docker 在宿主机启动隔离 OpenShell 网关；从临时 Dockerfile 创建沙箱；通过真实 sandbox ssh-config + SSH exec 验证 OpenShell 后端
  • 预期：选择启用，不在默认 pnpm test:e2e 中；需要本地 openshell CLI 和 Docker 守护进程

实机（真实提供商 + 真实模型） ​

  • 命令：pnpm test:live
  • 配置：vitest.live.config.ts
  • 文件：src/**/*.live.test.ts、test/**/*.live.test.ts，以及 extensions/ 下的 bundled-plugin 实机测试
  • 默认启用：OPENCLAW_LIVE_TEST=1
  • 范围：“提供商/模型今天用真实凭据是否工作？”捕获提供商格式变化、工具调用问题、认证问题和速率限制行为
  • 预期：设计上不 CI 稳定（真实网络、提供商策略、配额、故障）；花钱/消耗速率限制；优先缩小范围子集
  • API 密钥轮换：设置 *_API_KEYS（逗号/分号格式）或 *_API_KEY_1、*_API_KEY_2（如 OPENAI_API_KEYS、ANTHROPIC_API_KEYS）或每实机覆盖 OPENCLAW_LIVE_*_KEY；测试在速率限制响应时重试

我应该运行哪个套件？ ​

你的操作推荐命令
编辑逻辑/测试pnpm test（大量改动可加 pnpm test:coverage）
触及网关网络 / WS 协议 / 配对添加 pnpm test:e2e
调试“机器人挂了” / 提供商特定故障 / 工具调用运行缩小的 pnpm test:live

实机（网络接触）测试 ​

实机测试分为两层以隔离故障：

第一层：直接模型补全（无网关） ​

  • 测试：src/agents/models.profiles.live.test.ts
  • 目标：枚举已发现模型，对有密钥的模型运行小型补全
  • 模型选择：
    • OPENCLAW_LIVE_MODELS=modern 运行现代允许列表（Opus/Sonnet/Haiku 4.5、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）
    • 或 OPENCLAW_LIVE_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-6,..."（逗号列表）
  • 为什么存在：分离“提供商 API 损坏/密钥无效”与“网关 agent 管道损坏”

第二层：网关 + dev agent 冒烟 ​

  • 测试：src/gateway/gateway-models.profiles.live.test.ts
  • 目标：启动进程内网关；创建/修补 agent:dev:* 会话；对有密钥的模型迭代并断言：
    • “有意义”的响应（无工具）
    • 真实工具调用有效（read 探测）
    • 可选额外工具探测（exec+read 探测）
  • 探测详情：read 探测在工作区写入随机数文件，要求 agent 读回；exec+read 探测要求 agent 执行写文件再读回；图像探测附加生成的 PNG 并期望模型返回 cat 代码
  • 模型选择：OPENCLAW_LIVE_GATEWAY_MODELS=all 是现代允许列表别名，或设置 OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" 逗号列表

查看可测试的内容及精确 provider/model ID：

bash
openclaw models list
openclaw models list --json

推荐的实机方案 ​

  • 单个模型、直接（无网关）：OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts
  • 单个模型、网关冒烟：OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
  • 跨多个提供商的工具调用：设置 OPENCLAW_LIVE_GATEWAY_MODELS 为逗号列表

凭据（绝不提交） ​

实机测试与 CLI 相同的方式发现凭据：

  • 配置文件存储：~/.openclaw/credentials/（首选）
  • 配置：~/.openclaw/openclaw.json（或 OPENCLAW_CONFIG_PATH）
  • 如果想依赖环境密钥（在 ~/.profile 中导出），source 后运行本地测，或使用 Docker 运行器

Docker 运行器（可选“在 Linux 上是否正常工作”检查） ​

Docker 运行器分为两类：

  • 实机模型运行器：在仓库 Docker 镜像内运行 pnpm test:live，挂载本地配置目录和工作区
  • 容器冒烟运行器：启动一个或多个真实容器验证高层次集成路径

常用命令：

bash
# 直接模型
pnpm test:docker:live-models

# ACP bind 冒烟
pnpm test:docker:live-acp-bind

# 网关 + dev agent
pnpm test:docker:live-gateway

# Open WebUI 实机冒烟
pnpm test:docker:openwebui

# 引导向导（TTY，完整脚手架）
pnpm test:docker:onboard

# 网关网络（两个容器，WS 认证 + 健康）
pnpm test:docker:gateway-network

# 插件（安装冒烟 + /plugin 别名 + Claude 包重启语义）
pnpm test:docker:plugins

有用环境变量：

  • OPENCLAW_CONFIG_DIR=...（默认 ~/.openclaw）挂载到 /home/node/.openclaw
  • OPENCLAW_WORKSPACE_DIR=...（默认 ~/.openclaw/workspace）挂载到 /home/node/.openclaw/workspace
  • OPENCLAW_PROFILE_FILE=... 挂载并 source
  • OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... 缩小范围
  • OPENCLAW_SKIP_DOCKER_BUILD=1 复用已存在的镜像

Docker 实机模型运行器默认将当前检出目录只读挂载到容器内临时工作目录，跳过大型本地缓存。还设置 OPENCLAW_SKIP_CHANNELS=1 以防止容器内启动真实 Telegram/Discord 等工作器。

QA 专用运行器 ​

这些命令与主测试套件并列，当需要 QA lab 的真实感时使用：

bash
# 直接在宿主机运行 repo 支持的 QA 场景
pnpm openclaw qa suite

# 在 disposable Multipass Linux VM 内运行
pnpm openclaw qa suite --runner multipass

# 启动 Docker 支持的 QA 站点
pnpm qa:lab:up

# Matrix 实机 QA 通道
pnpm openclaw qa matrix

# Telegram 实机 QA 通道
pnpm openclaw qa telegram

详细说明（包括 Convex 共享凭据池）请参考 QA overview 和 Matrix QA。

契约测试（插件和频道形状） ​

契约测试验证每个已注册的插件和频道是否符合接口契约。默认 pnpm test 单元套件故意跳过这些共享 seam 和冒烟文件；当触及共享频道或提供商接口时，请显式运行契约命令。

命令：

  • 所有契约：pnpm test:contracts
  • 仅频道契约：pnpm test:contracts:channels
  • 仅提供商契约：pnpm test:contracts:plugins

何时运行：

  • 修改 plugin-sdk 导出或子路径后
  • 添加或修改频道/提供商插件后
  • 重构插件注册或发现后

契约测试在 CI 中运行，无需真实 API 密钥。

添加回归测试（指导方针） ​

修复实机中发现的提供商/模型问题时：

  • 尽可能添加 CI 安全的回归（mock/stub 提供商，或捕获确切请求形状转换）
  • 如果本质上只能实机测试（速率限制、认证策略），通过环境变量保持实机测试缩窄且选择性启用
  • 优先定位能捕获 bug 的最小层：
    • 提供商请求转换/重放 bug → 直接模型测试
    • 网关会话/历史/工具管道 bug → 网关实机冒烟或 CI 安全的网关 mock 测试
  • SecretRef 遍历防护：如果添加新的 includeInPlan SecretRef 目标家族，更新 src/secrets/exec-secret-ref-id-parity.test.ts 中的 classifyTargetClass。

文档完整性 ​

文档编辑后运行检查：pnpm check:docs。需要页面内标题检查时：pnpm docs:check-links:anchors。

常见问题 ​

如何运行 OpenClaw 的实机测试？ ​

使用 pnpm test:live。需要设置真实 API 密钥环境变量（如 OPENAI_API_KEY）或配置文件中已有凭据。推荐先缩小范围到单个模型或提供商，例如 OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts。Docker 环境可用 pnpm test:docker:live-models 避免污染本机配置。

我的测试很慢，有什么优化建议？ ​

使用 pnpm test:max（更高 worker 上限）或 pnpm test:watch 监视模式迭代。避免跑全部套件，使用允许列表环境变量缩小实机范围。Docker 运行器默认设置了较小的冒烟上限（如 OPENCLAW_LIVE_MAX_MODELS=12），可通过覆盖 OPENCLAW_LIVE_MAX_MODELS 调整。查看 shard 时间数据写入 .artifacts/vitest-shard-timings.json，定位最慢的 shard。

契约测试什么时候需要跑一次？ ​

在修改 plugin-sdk 导出/子路径、添加新插件或频道、重构插件注册或发现后都应该运行 pnpm test:contracts。CI 会默认运行契约测试，本地开发时记得执行。不需要真实 API 密钥。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策