测试

OpenClaw 有三个 Vitest 套件（单元/集成、e2e、实时）和一小套 Docker 运行器。

本文档是"我们如何测试"指南：

每个套件涵盖的内容（以及它故意不涵盖的内容）
常见工作流要运行的命令（本地、预推送、调试）
实时测试如何发现凭据并选择模型/提供商
如何为现实世界的模型/提供商问题添加回归测试

快速开始

大多数时候：

完整检查（推送前预期）：pnpm build && pnpm check && pnpm test

当你修改测试或想要额外信心时：

覆盖率检查：pnpm test:coverage
E2E 套件：pnpm test:e2e

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

实时套件（模型 + gateway 工具/图像探测）：pnpm test:live

提示：当你只需要一个失败用例时，最好通过下面描述的允许列表环境变量来缩小实时测试范围。

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

将套件视为"递增的真实性"（以及递增的脆弱性/成本）：

单元/集成（默认）

命令：pnpm test
配置：scripts/test-parallel.mjs（运行 vitest.unit.config.ts、vitest.extensions.config.ts、vitest.gateway.config.ts）
文件：src/**/*.test.ts、extensions/**/*.test.ts
范围：
- 纯单元测试
- 进程内集成测试（gateway 认证、路由、工具、解析、配置）
- 已知错误的确定性回归测试
预期：
- 在 CI 中运行
- 不需要真实密钥
- 应该快速且稳定
池说明：
- OpenClaw 在 Node 22/23 上使用 Vitest vmForks 以加快单元测试分片。
- 在 Node 24+ 上，OpenClaw 自动回退到常规 forks 以避免 Node VM 链接错误（ERR_VM_MODULE_LINK_FAILURE / module is already linked）。
- 手动覆盖使用 OPENCLAW_TEST_VM_FORKS=0（强制 forks）或 OPENCLAW_TEST_VM_FORKS=1（强制 vmForks）。

E2E（gateway 冒烟测试）

命令：pnpm test:e2e
配置：vitest.e2e.config.ts
文件：src/**/*.e2e.test.ts
运行时默认：
- 使用 Vitest vmForks 以加快文件启动。
- 使用自适应工作器（CI：2-4，本地：4-8）。
- 默认以静默模式运行以减少控制台 I/O 开销。
有用的覆盖：
- OPENCLAW_E2E_WORKERS=<n> 强制工作器数量（上限 16）。
- OPENCLAW_E2E_VERBOSE=1 重新启用详细控制台输出。
范围：
- 多实例 gateway 端到端行为
- WebSocket/HTTP 表面、节点配对和更重的网络
预期：
- 在 CI 中运行（当在流水线中启用时）
- 不需要真实密钥
- 比单元测试有更多的活动部件（可能更慢）

实时（真实提供商 + 真实模型）

命令：pnpm test:live
配置：vitest.live.config.ts
文件：src/**/*.live.test.ts
默认：由 pnpm test:live 启用（设置 OPENCLAW_LIVE_TEST=1）
范围：
- "这个提供商/模型今天用真实凭据实际上能工作吗？"
- 捕获提供商格式变化、工具调用怪癖、认证问题和速率限制行为
预期：
- 按设计不是 CI 稳定的（真实网络、真实提供商策略、配额、中断）
- 花钱/使用速率限制
- 最好运行缩小的子集而不是"所有东西"
- 实时运行将源 ~/.profile 以获取缺失的 API 密钥
API 密钥轮换（特定于提供商）：使用逗号/分号格式设置 *_API_KEYS 或 *_API_KEY_1、*_API_KEY_2（例如 OPENAI_API_KEYS、ANTHROPIC_API_KEYS、GEMINI_API_KEYS）或通过 OPENCLAW_LIVE_*_KEY 进行实时覆盖；测试在速率限制响应时重试。

我应该运行哪个套件？

使用此决策表：

编辑逻辑/测试：运行 pnpm test（如果你改变了很多，运行 pnpm test:coverage）
修改 gateway 网络/WS 协议/配对：添加 pnpm test:e2e
调试"我的机器人宕机了"/特定于提供商的失败/工具调用：运行缩小的 pnpm test:live

实时：Android 节点能力扫描

测试：src/gateway/android-node.capabilities.live.test.ts
脚本：pnpm android:test:integration
目标：调用连接 Android 节点当前广告的每个命令并断言命令契约行为。
范围：
- 预条件/手动设置（套件不安装/运行/配对应用程序）。
- 逐命令 gateway node.invoke 验证所选 Android 节点。
所需预设置：
- Android 应用已连接 + 配对到 gateway。
- 应用保持在前台。
- 为你期望通过的权限/捕获同意授予权限。
可选目标覆盖：
- OPENCLAW_ANDROID_NODE_ID 或 OPENCLAW_ANDROID_NODE_NAME。
- OPENCLAW_ANDROID_GATEWAY_URL / OPENCLAW_ANDROID_GATEWAY_TOKEN / OPENCLAW_ANDROID_GATEWAY_PASSWORD。
完整 Android 设置详情：Android 应用

实时：模型冒烟测试（配置文件密钥）

实时测试分为两层，以便我们可以隔离故障：

"直接模型"告诉我们提供商/模型是否可以用给定密钥回答。
"Gateway 冒烟测试"告诉我们完整的 gateway+agent 管道对该模型有效（会话、历史、工具、沙箱策略等）。

第 1 层：直接模型完成（无 gateway）

测试：src/agents/models.profiles.live.test.ts
目标：
- 枚举发现的模型
- 使用 getApiKeyForModel 选择你有凭据的模型
- 为每个模型运行小型完成（以及在需要时的针对性回归测试）
如何启用：
- pnpm test:live（或直接调用 Vitest 时使用 OPENCLAW_LIVE_TEST=1）
设置 OPENCLAW_LIVE_MODELS=modern（或 all，现代的别名）以实际运行此套件；否则跳过以保持 pnpm test:live 专注于 gateway 冒烟测试
如何选择模型：
- OPENCLAW_LIVE_MODELS=modern 运行现代允许列表（Opus/Sonnet/Haiku 4.5、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.5、Grok 4）
- OPENCLAW_LIVE_MODELS=all 是现代允许列表的别名
- 或 OPENCLAW_LIVE_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-6,..."（逗号允许列表）
如何选择提供商：
- OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"（逗号允许列表）
密钥来源：
- 默认：配置文件存储和环境回退
- 设置 OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 以强制配置文件存储仅限
为什么存在：
- 将"提供商 API 已损坏/密钥无效"与"gateway agent 管道已损坏"分开
- 包含小型、隔离的回归测试（示例：OpenAI Responses/Codex Responses 推理重放 + 工具调用流程）

第 2 层：Gateway + 开发 agent 冒烟测试（"@openclaw"实际做的）

测试：src/gateway/gateway-models.profiles.live.test.ts
目标：
- 启动进程内 gateway
- 创建/修补 agent:dev:* 会话（每次运行的模型覆盖）
- 迭代有密钥的模型并断言：
  - "有意义"的响应（无工具）
  - 真实工具调用有效（读取探测）
  - 可选额外工具探测（exec+read 探测）
  - OpenAI 回归路径（仅工具调用 → 后续）保持工作
探测详情（以便你可以快速解释故障）：
- read 探测：测试在工作区中写入一个 nonce 文件并要求 agent read 它并回显 nonce。
- exec+read 探测：测试要求 agent exec 将 nonce 写入临时文件，然后 read 回它。
- 图像探测：测试附加生成的 PNG（cat + 随机代码）并期望模型返回 cat <CODE>。
- 实现参考：src/gateway/gateway-models.profiles.live.test.ts 和 src/gateway/live-image-probe.ts。
如何启用：
- pnpm test:live（或直接调用 Vitest 时使用 OPENCLAW_LIVE_TEST=1）
如何选择模型：
- 默认：现代允许列表（Opus/Sonnet/Haiku 4.5、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.5、Grok 4）
- OPENCLAW_LIVE_GATEWAY_MODELS=all 是现代允许列表的别名
- 或设置 OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"（或逗号列表）以缩小
如何选择提供商（避免"OpenRouter 所有东西"）：
- OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"（逗号允许列表）
工具和图像探测在此实时测试中始终开启：
- read 探测 + exec+read 探测（工具压力测试）
- 当模型广告图像输入支持时运行图像探测
- 流程（高级）：
  - 测试生成带有"CAT" + 随机代码的小 PNG（src/gateway/live-image-probe.ts）
  - 通过 agent attachments: [{ mimeType: "image/png", content: "<base64>" }] 发送
  - Gateway 将附件解析为 images[]（src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts）
  - 嵌入式 agent 将多模态用户消息转发给模型
  - 断言：回复包含 cat + 代码（OCR 容错：允许小错误）

提示：要查看你可以在机器上测试什么（以及确切的 provider/model id），运行：

openclaw models list
openclaw models list --json

实时：Anthropic setup-token 冒烟测试

测试：src/agents/anthropic.setup-token.live.test.ts
目标：验证 Claude Code CLI setup-token（或粘贴的 setup-token 配置文件）可以完成 Anthropic 提示。
启用：
- pnpm test:live（或直接调用 Vitest 时使用 OPENCLAW_LIVE_TEST=1）
- OPENCLAW_LIVE_SETUP_TOKEN=1
令牌来源（选一个）：
- 配置文件：OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test
- 原始令牌：OPENCLAW_LIVE_SETUP_TOKEN_VALUE=sk-ant-oat01-...
模型覆盖（可选）：
- OPENCLAW_LIVE_SETUP_TOKEN_MODEL=anthropic/claude-opus-4-6

设置示例：

openclaw models auth paste-token --provider anthropic --profile-id anthropic:setup-token-test
OPENCLAW_LIVE_SETUP_TOKEN=1 OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test pnpm test:live src/agents/anthropic.setup-token.live.test.ts

实时：CLI 后端冒烟测试（Claude Code CLI 或其他本地 CLI）

测试：src/gateway/gateway-cli-backend.live.test.ts
目标：使用本地 CLI 后端验证 Gateway + agent 管道，不触碰你的默认配置。
启用：
- pnpm test:live（或直接调用 Vitest 时使用 OPENCLAW_LIVE_TEST=1）
- OPENCLAW_LIVE_CLI_BACKEND=1
默认：
- 模型：claude-cli/claude-sonnet-4-6
- 命令：claude
- 参数：["-p","--output-format","json","--dangerously-skip-permissions"]
覆盖（可选）：
- OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-opus-4-6"
- OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.3-codex"
- OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/claude"
- OPENCLAW_LIVE_CLI_BACKEND_ARGS='["-p","--output-format","json","--permission-mode","bypassPermissions"]'
- OPENCLAW_LIVE_CLI_BACKEND_CLEAR_ENV='["ANTHROPIC_API_KEY","ANTHROPIC_API_KEY_OLD"]'
- OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1 发送真实图像附件（路径注入到提示中）。
- OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image" 将图像文件路径作为 CLI 参数传递而不是提示注入。
- OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"（或 "list"）控制在设置 IMAGE_ARG 时如何传递图像参数。
- OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1 发送第二轮并验证恢复流程。
OPENCLAW_LIVE_CLI_BACKEND_DISABLE_MCP_CONFIG=0 保持 Claude Code CLI MCP 配置启用（默认使用临时空文件禁用 MCP 配置）。

示例：

OPENCLAW_LIVE_CLI_BACKEND=1 \
  OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-sonnet-4-6" \
  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts

实时：模型矩阵（我们涵盖的内容）

没有固定的"CI 模型列表"（实时是选择加入的），但这些是推荐的模型，在有密钥的开发机器上定期覆盖。

现代冒烟测试集（工具调用 + 图像）

这是我们期望保持工作的"常见模型"运行：

OpenAI（非 Codex）：openai/gpt-5.2（可选：openai/gpt-5.1）
OpenAI Codex：openai-codex/gpt-5.3-codex（可选：openai-codex/gpt-5.3-codex-codex）
Anthropic：anthropic/claude-opus-4-6（或 anthropic/claude-sonnet-4-5）
Google（Gemini API）：google/gemini-3-pro-preview 和 google/gemini-3-flash-preview（避免旧的 Gemini 2.x 模型）
Google（Antigravity）：google-antigravity/claude-opus-4-6-thinking 和 google-antigravity/gemini-3-flash
Z.AI（GLM）：zai/glm-4.7
MiniMax：minimax/minimax-m2.5

运行 gateway 冒烟测试，带工具 + 图像： OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.3-codex,anthropic/claude-opus-4-6,google/gemini-3-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/minimax-m2.5" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

基线：工具调用（Read + 可选 Exec）

每个提供商家族至少选一个：

OpenAI：openai/gpt-5.2（或 openai/gpt-5-mini）
Anthropic：anthropic/claude-opus-4-6（或 anthropic/claude-sonnet-4-5）
Google：google/gemini-3-flash-preview（或 google/gemini-3-pro-preview）
Z.AI（GLM）：zai/glm-4.7
MiniMax：minimax/minimax-m2.5

可选额外覆盖（最好有）：

xAI：xai/grok-4（或最新可用）
Mistral：mistral/…（选一个你启用的"tools"能力模型）
Cerebras：cerebras/…（如果你有访问权限）
LM Studio：lmstudio/…（本地；工具调用取决于 API 模式）

视觉：图像发送（附件 → 多模态消息）

在 OPENCLAW_LIVE_GATEWAY_MODELS 中至少包含一个图像能力模型（Claude/Gemini/OpenAI 视觉能力变体等）以练习图像探测。

聚合器/替代 gateway

如果你启用了密钥，我们也支持通过以下测试：

OpenRouter：openrouter/...（数百个模型；使用 openclaw models scan 查找工具 + 图像能力候选）
OpenCode Zen：opencode/...（通过 OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY 认证）

如果你有以下凭据/配置，可以在实时矩阵中包含更多提供商：

内置：openai、openai-codex、anthropic、google、google-vertex、google-antigravity、google-gemini-cli、zai、openrouter、opencode、xai、groq、cerebras、mistral、github-copilot
通过 models.providers（自定义端点）：minimax（云/API），以及任何 OpenAI/Anthropic 兼容代理（LM Studio、vLLM、LiteLLM 等）

提示：不要尝试在文档中硬编码"所有模型"。权威列表是你的机器上 discoverModels(...) 返回的内容 + 可用的密钥。

凭据（永不提交）

实时测试发现凭据的方式与 CLI 相同。实际影响：

如果 CLI 有效，实时测试应该找到相同的密钥。
如果实时测试说"无凭据"，以与调试 openclaw models list / 模型选择相同的方式调试。
配置文件存储：~/.openclaw/credentials/（首选；测试中"配置文件密钥"的含义）
配置：~/.openclaw/openclaw.json（或 OPENCLAW_CONFIG_PATH）

如果你想依赖环境密钥（例如在 ~/.profile 中导出），在 source ~/.profile 后运行本地测试，或使用下面的 Docker 运行器（它们可以将 ~/.profile 挂载到容器中）。

Deepgram 实时（音频转录）

测试：src/media-understanding/providers/deepgram/audio.live.test.ts
启用：DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts

BytePlus 编码计划实时

测试：src/agents/byteplus.live.test.ts
启用：BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts
可选模型覆盖：BYTEPLUS_CODING_MODEL=ark-code-latest

Docker 运行器（可选"在 Linux 中工作"检查）

这些在仓库 Docker 镜像内运行 pnpm test:live，挂载你的本地配置目录和工作区（如果挂载则源 ~/.profile）：

直接模型：pnpm test:docker:live-models（脚本：scripts/test-live-models-docker.sh）
Gateway + 开发 agent：pnpm test:docker:live-gateway（脚本：scripts/test-live-gateway-models-docker.sh）
入职向导（TTY，完整脚手架）：pnpm test:docker:onboard（脚本：scripts/e2e/onboard-docker.sh）
Gateway 网络（两个容器，WS 认证 + 健康检查）：pnpm test:docker:gateway-network（脚本：scripts/e2e/gateway-network-docker.sh）
插件（自定义扩展加载 + 注册表冒烟测试）：pnpm test:docker:plugins（脚本：scripts/e2e/plugins-docker.sh）

手动 ACP 纯语言线程冒烟测试（非 CI）：

bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...
将此脚本保留用于回归/调试工作流。ACP 线程路由验证可能需要它，所以不要删除它。

有用的环境变量：

OPENCLAW_CONFIG_DIR=...（默认：~/.openclaw）挂载到 /home/node/.openclaw
OPENCLAW_WORKSPACE_DIR=...（默认：~/.openclaw/workspace）挂载到 /home/node/.openclaw/workspace
OPENCLAW_PROFILE_FILE=...（默认：~/.profile）挂载到 /home/node/.profile 并在运行测试前源
OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... 以缩小运行
OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 确保凭据来自配置文件存储（而非环境）

文档健全性

在文档编辑后运行文档检查：pnpm docs:list。

离线回归（CI 安全）

这些是"真实流水线"回归，没有真实提供商：

Gateway 工具调用（模拟 OpenAI，真实 gateway + agent 循环）：src/gateway/gateway.test.ts（用例："通过 gateway agent 循环端到端运行模拟 OpenAI 工具调用"）
Gateway 向导（WS wizard.start/wizard.next，写入配置 + 强制执行认证）：src/gateway/gateway.test.ts（用例："通过 ws 运行向导并写入认证令牌配置"）

Agent 可靠性评估（技能）

我们已经有几个 CI 安全测试，行为像"agent 可靠性评估"：

通过真实 gateway + agent 循环模拟工具调用（src/gateway/gateway.test.ts）。
端到端向导流程，验证会话布线和配置效果（src/gateway/gateway.test.ts）。

技能仍然缺少什么（见技能）：

决策： 当技能列在提示中时，agent 是否选择正确的技能（或避免无关技能）？
合规： agent 是否在使用前读取 SKILL.md 并遵循所需步骤/参数？
工作流契约： 多轮场景，断言工具顺序、会话历史携带和沙箱边界。

未来评估应首先保持确定性：

使用模拟提供商的场景运行器，断言工具调用 + 顺序、技能文件读取和会话布线。
一小套以技能为中心的场景（使用 vs 避免、门控、提示注入）。
仅在 CI 安全套件到位后，可选实时评估（选择加入，环境门控）。

添加回归测试（指导）

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

如果可能，添加 CI 安全回归测试（模拟/存根提供商，或捕获确切的请求形状转换）
如果它本质上是仅限实时的（速率限制、认证策略），保持实时测试缩小并通过环境变量选择加入
最好针对捕获错误的最小层：
- 提供商请求转换/重放错误 → 直接模型测试
- gateway 会话/历史/工具管道错误 → gateway 实时冒烟测试或 CI 安全 gateway 模拟测试

测试

测试