测试

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

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

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

快速开始

大多数日子：

完整门控（推送前预期）：pnpm lint && pnpm build && pnpm test

当您接触测试或需要额外信心时：

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

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

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

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

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

将套件视为“增加真实性”（以及增加不稳定性/成本）：

单元 / 集成（默认）

命令：pnpm test
配置：vitest.config.ts
文件：src/**/*.test.ts
范围：
- 纯单元测试
- 进程内集成测试（网关身份验证、路由、工具、解析、配置）
- 已知错误的确定性回归测试
期望：
- 在 CI 中运行
- 不需要真实密钥
- 应该快速且稳定

E2E（网关冒烟测试）

命令：pnpm test:e2e
配置：vitest.e2e.config.ts
文件：src/**/*.e2e.test.ts
范围：
- 多实例网关端到端行为
- WebSocket/HTTP 接口、节点配对和更重的网络
期望：
- 在 CI 中运行（当在流水线中启用时）
- 不需要真实密钥
- 比单元测试有更多移动部件（可能更慢）

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

命令：pnpm test:live
配置：vitest.live.config.ts
文件：src/**/*.live.test.ts
默认：由 pnpm test:live 启用（设置 CLAWDBOT_LIVE_TEST=1）
范围：
- “这个提供商/模型今天是否真的能用真实凭据工作？”
- 捕获提供商格式更改、工具调用怪癖、身份验证问题和速率限制行为
期望：
- 设计上不是 CI 稳定的（真实网络、真实提供商策略、配额、中断）
- 花费金钱 / 使用速率限制
- 优先运行缩小的子集而不是“所有内容”
- 实时运行将获取 ~/.profile 以获取缺失的 API 密钥
- Anthropic 密钥轮换：设置 CLAWDBOT_LIVE_ANTHROPIC_KEYS="sk-...,sk-..."（或 CLAWDBOT_LIVE_ANTHROPIC_KEY=sk-...）或多个 ANTHROPIC_API_KEY* 变量；测试将在速率限制时重试

我应该运行哪个套件？

使用此决策表：

编辑逻辑/测试：运行 pnpm test（如果更改很多，则运行 pnpm test:coverage）
接触网关网络 / WS 协议 / 配对：添加 pnpm test:e2e
调试"我的机器人宕机" / 提供商特定故障 / 工具调用：运行缩小的 pnpm test:live

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

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

"直接模型"告诉我们提供商/模型是否能用给定的密钥回答。
"网关冒烟测试"告诉我们完整的网关+智能体管道是否适用于该模型（会话、历史记录、工具、沙箱策略等）。

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

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

第 2 层：网关 + 开发智能体冒烟测试（"@openclaw" 实际做什么）

测试：src/gateway/gateway-models.profiles.live.test.ts
目标：
- 启动进程内网关
- 创建/修补 agent:dev:* 会话（每次运行模型覆盖）
- 迭代有密钥的模型并断言：
  - "有意义"的响应（无工具）
  - 真实的工具调用有效（读取探测）
  - 可选的额外工具探测（执行+读取探测）
  - OpenAI 回归路径（仅工具调用 → 后续）保持工作
探测详情（以便快速解释故障）：
- read 探测：测试在工作区中写入一个随机数文件，并要求智能体 read 它并回显随机数。
- exec+read 探测：测试要求智能体 exec 将随机数写入临时文件，然后 read 它。
- 图像探测：测试附加生成的 PNG（猫 + 随机代码）并期望模型返回 cat <CODE>。
- 实现参考：src/gateway/gateway-models.profiles.live.test.ts 和 src/gateway/live-image-probe.ts。
如何启用：
- pnpm test:live（或如果直接调用 Vitest，则使用 CLAWDBOT_LIVE_TEST=1）
如何选择模型：
- 默认：现代允许列表（Opus/Sonnet/Haiku 4.5、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.1、Grok 4）
- CLAWDBOT_LIVE_GATEWAY_MODELS=all 是现代允许列表的别名
- 或设置 CLAWDBOT_LIVE_GATEWAY_MODELS="provider/model"（或逗号列表）以缩小范围
如何选择提供商（避免"OpenRouter 所有内容"）：
- CLAWDBOT_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>" }] 发送
  - 网关将附件解析为 images[]（src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts）
  - 嵌入式智能体将多模态用户消息转发给模型
  - 断言：回复包含 cat + 代码（OCR 容差：允许轻微错误）

提示：要查看您可以在机器上测试的内容（以及确切的 provider/model ID），请运行：

bash

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，则使用 CLAWDBOT_LIVE_TEST=1）
- CLAWDBOT_LIVE_SETUP_TOKEN=1
令牌来源（选择一个）：
- 配置文件：CLAWDBOT_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test
- 原始令牌：CLAWDBOT_LIVE_SETUP_TOKEN_VALUE=sk-ant-oat01-...
模型覆盖（可选）：
- CLAWDBOT_LIVE_SETUP_TOKEN_MODEL=anthropic/claude-opus-4-5

设置示例：

bash

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

Live: CLI backend smoke (Claude Code CLI or other local CLIs)

Test: src/gateway/gateway-cli-backend.live.test.ts
Goal: validate the Gateway + agent pipeline using a local CLI backend, without touching your default config.
Enable:
- pnpm test:live (or CLAWDBOT_LIVE_TEST=1 if invoking Vitest directly)
- CLAWDBOT_LIVE_CLI_BACKEND=1
Defaults:
- Model: claude-cli/claude-sonnet-4-5
- Command: claude
- Args: ["-p","--output-format","json","--dangerously-skip-permissions"]
Overrides (optional):
- CLAWDBOT_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-opus-4-5"
- CLAWDBOT_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2-codex"
- CLAWDBOT_LIVE_CLI_BACKEND_COMMAND="/full/path/to/claude"
- CLAWDBOT_LIVE_CLI_BACKEND_ARGS='["-p","--output-format","json","--permission-mode","bypassPermissions"]'
- CLAWDBOT_LIVE_CLI_BACKEND_CLEAR_ENV='["ANTHROPIC_API_KEY","ANTHROPIC_API_KEY_OLD"]'
- CLAWDBOT_LIVE_CLI_BACKEND_IMAGE_PROBE=1 to send a real image attachment (paths are injected into the prompt).
- CLAWDBOT_LIVE_CLI_BACKEND_IMAGE_ARG="--image" to pass image file paths as CLI args instead of prompt injection.
- CLAWDBOT_LIVE_CLI_BACKEND_IMAGE_MODE="repeat" (or "list") to control how image args are passed when IMAGE_ARG is set.
- CLAWDBOT_LIVE_CLI_BACKEND_RESUME_PROBE=1 to send a second turn and validate resume flow.
CLAWDBOT_LIVE_CLI_BACKEND_DISABLE_MCP_CONFIG=0 to keep Claude Code CLI MCP config enabled (default disables MCP config with a temporary empty file).

Example:

bash

CLAWDBOT_LIVE_CLI_BACKEND=1 \
  CLAWDBOT_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-sonnet-4-5" \
  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts

Recommended live recipes

Narrow, explicit allowlists are fastest and least flaky:

Single model, direct (no gateway):
- CLAWDBOT_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts
Single model, gateway smoke:
- CLAWDBOT_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
Tool calling across several providers:
- CLAWDBOT_LIVE_GATEWAY_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-flash-preview,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
Google focus (Gemini API key + Antigravity):
- Gemini (API key): CLAWDBOT_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
- Antigravity (OAuth): CLAWDBOT_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-5-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

Notes:

google/... uses the Gemini API (API key).
google-antigravity/... uses the Antigravity OAuth bridge (Cloud Code Assist-style agent endpoint).
google-gemini-cli/... uses the local Gemini CLI on your machine (separate auth + tooling quirks).
Gemini API vs Gemini CLI:
- API: openclaw calls Google’s hosted Gemini API over HTTP (API key / profile auth); this is what most users mean by “Gemini”.
- CLI: openclaw shells out to a local gemini binary; it has its own auth and can behave differently (streaming/tool support/version skew).

Live: model matrix (what we cover)

There is no fixed “CI model list” (live is opt-in), but these are the recommended models to cover regularly on a dev machine with keys.

Modern smoke set (tool calling + image)

This is the “common models” run we expect to keep working:

OpenAI (non-Codex): openai/gpt-5.2 (optional: openai/gpt-5.1)
OpenAI Codex: openai-codex/gpt-5.2 (optional: openai-codex/gpt-5.2-codex)
Anthropic: anthropic/claude-opus-4-5 (or anthropic/claude-sonnet-4-5)
Google (Gemini API): google/gemini-3-pro-preview and google/gemini-3-flash-preview (avoid older Gemini 2.x models)
Google (Antigravity): google-antigravity/claude-opus-4-5-thinking and google-antigravity/gemini-3-flash
Z.AI (GLM): zai/glm-4.7
MiniMax: minimax/minimax-m2.1

Run gateway smoke with tools + image: CLAWDBOT_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-5-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

凭据（切勿提交）

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

如果 CLI 正常工作，实时测试应该能找到相同的密钥。
如果实时测试显示"没有凭据"，请按照调试 openclaw models list / 模型选择的相同方式进行调试。
配置文件存储：~/.clawdbot/credentials/（首选；测试中"profile keys"的含义）
配置：~/.clawdbot/openclaw.json（或 CLAWDBOT_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

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

这些命令在仓库 Docker 镜像内运行 pnpm test:live，挂载您的本地配置目录和工作空间（如果挂载了 ~/.profile 则会在运行前 source）：

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

有用的环境变量：

CLAWDBOT_CONFIG_DIR=...（默认：~/.clawdbot）挂载到 /home/node/.clawdbot
CLAWDBOT_WORKSPACE_DIR=...（默认：~/clawd）挂载到 /home/node/clawd
CLAWDBOT_PROFILE_FILE=...（默认：~/.profile）挂载到 /home/node/.profile 并在运行测试前 source
CLAWDBOT_LIVE_GATEWAY_MODELS=... / CLAWDBOT_LIVE_MODELS=... 用于缩小测试范围
CLAWDBOT_LIVE_REQUIRE_PROFILE_KEYS=1 确保凭据来自配置文件存储（而非环境变量）

文档完整性检查

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

离线回归测试（CI 安全）

这些是"真实管道"回归测试，无需真实提供商：

网关工具调用（模拟 OpenAI，真实网关 + 代理循环）：src/gateway/gateway.tool-calling.mock-openai.test.ts
网关向导（WS wizard.start/wizard.next，写入配置 + 强制认证）：src/gateway/gateway.wizard.e2e.test.ts

代理可靠性评估（技能）

我们已经有一些 CI 安全的测试，其行为类似于"代理可靠性评估"：

通过真实网关 + 代理循环进行模拟工具调用（src/gateway/gateway.tool-calling.mock-openai.test.ts）。
端到端向导流程，验证会话连接和配置效果（src/gateway/gateway.wizard.e2e.test.ts）。

技能方面仍然缺失的内容（参见技能）：

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

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

使用模拟提供商的场景运行器，断言工具调用 + 顺序、技能文件读取和会话连接。
一小套专注于技能的场景（使用与避免、门控、提示注入）。
可选的实时评估（选择加入，环境变量控制）仅在 CI 安全套件就位后进行。

添加回归测试（指南）

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

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

测试

快速开始

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

单元 / 集成（默认）

E2E（网关冒烟测试）

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

我应该运行哪个套件？

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

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

第 2 层：网关 + 开发智能体冒烟测试（"@openclaw" 实际做什么）

实时：Anthropic setup-token 冒烟测试

Live: CLI backend smoke (Claude Code CLI or other local CLIs)

Recommended live recipes

Live: model matrix (what we cover)

Modern smoke set (tool calling + image)

推荐的实时测试方案

基础：工具调用（读取 + 可选执行）

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

聚合器 / 替代网关

凭据（切勿提交）

Deepgram 实时测试（音频转录）

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

文档完整性检查

离线回归测试（CI 安全）

代理可靠性评估（技能）

添加回归测试（指南）

测试 ​

快速开始 ​

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

单元 / 集成（默认） ​

E2E（网关冒烟测试） ​

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

我应该运行哪个套件？ ​

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

第 1 层：直接模型完成（无网关） ​

第 2 层：网关 + 开发智能体冒烟测试（"@openclaw" 实际做什么） ​

实时：Anthropic setup-token 冒烟测试 ​

Live: CLI backend smoke (Claude Code CLI or other local CLIs) ​

Recommended live recipes ​

Live: model matrix (what we cover) ​

Modern smoke set (tool calling + image) ​

推荐的实时测试方案 ​

基础：工具调用（读取 + 可选执行） ​

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

聚合器 / 替代网关 ​

凭据（切勿提交） ​

Deepgram 实时测试（音频转录） ​

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

文档完整性检查 ​

离线回归测试（CI 安全） ​

代理可靠性评估（技能） ​

添加回归测试（指南） ​

测试

快速开始

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

单元 / 集成（默认）

E2E（网关冒烟测试）

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

我应该运行哪个套件？

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

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

第 2 层：网关 + 开发智能体冒烟测试（"@openclaw" 实际做什么）

实时：Anthropic setup-token 冒烟测试

Live: CLI backend smoke (Claude Code CLI or other local CLIs)

Recommended live recipes

Live: model matrix (what we cover)

Modern smoke set (tool calling + image)

推荐的实时测试方案

基础：工具调用（读取 + 可选执行）

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

聚合器 / 替代网关

凭据（切勿提交）

Deepgram 实时测试（音频转录）

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

文档完整性检查

离线回归测试（CI 安全）

代理可靠性评估（技能）

添加回归测试（指南）