测试

OpenClaw 拥有三个 Vitest 测试套件(单元/集成、端到端、实时)和少量 Docker 运行器。

本文档是”我们如何测试”的指南:

  • 每个测试套件覆盖什么(以及刻意_不_覆盖什么)
  • 常见工作流(本地、推送前、调试)中应运行哪些命令
  • 实时测试如何发现凭证并选择模型/提供商
  • 如何为真实的模型/提供商问题添加回归测试

快速上手

日常使用:

  • 完整门控(推送前应执行):pnpm build && pnpm check && pnpm test

当你修改了测试或需要更高信心时:

  • 覆盖率门控:pnpm test:coverage
  • 端到端套件:pnpm test:e2e

调试真实提供商/模型时(需要真实凭证):

  • 实时套件(模型 + 网关工具/图片探测):pnpm test:live

提示: 只需要一个失败用例时,优先通过下文描述的白名单环境变量缩小实时测试范围。

测试套件(运行在哪里)

可以把这些套件理解为”逐步增加真实性”(同时也增加不稳定性和成本):

单元/集成测试(默认)

  • 命令:pnpm test
  • 配置:scripts/test-parallel.mjs(运行 vitest.unit.config.tsvitest.extensions.config.tsvitest.gateway.config.ts
  • 文件:src/**/*.test.tsextensions/**/*.test.ts
  • 范围:
    • 纯单元测试
    • 进程内集成测试(网关认证、路由、工具、解析、配置)
    • 已知 bug 的确定性回归测试
  • 要求:
    • 在 CI 中运行
    • 无需真实密钥
    • 应当快速且稳定
  • 线程池说明:
    • OpenClaw 在 Node 22、23 和 24 上使用 Vitest vmForks 以加快单元分片。
    • 在 Node 25+ 上,OpenClaw 自动回退到常规 forks,直到仓库在该版本上重新验证通过。
    • 手动覆盖:OPENCLAW_TEST_VM_FORKS=0(强制 forks)或 OPENCLAW_TEST_VM_FORKS=1(强制 vmForks)。

端到端(网关冒烟测试)

  • 命令: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 重新启用详细控制台输出。
  • 范围:
    • 多实例网关端到端行为
    • 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_KEYSANTHROPIC_API_KEYSGEMINI_API_KEYS),也可通过 OPENCLAW_LIVE_*_KEY 针对实时测试覆盖;测试会在收到速率限制响应时重试。

应该运行哪个套件?

决策指南:

  • 修改逻辑/测试:运行 pnpm test(如果改动较大则加上 pnpm test:coverage
  • 涉及网关网络 / WS 协议 / 配对:加上 pnpm test:e2e
  • 调试”我的机器人挂了” / 提供商相关故障 / 工具调用:运行缩小范围的 pnpm test:live

实时测试:Android 节点能力扫描

  • 测试文件:src/gateway/android-node.capabilities.live.test.ts
  • 脚本:pnpm android:test:integration
  • 目标:调用已连接 Android 节点当前公布的所有命令,并断言命令契约行为。
  • 范围:
    • 需要预设条件/手动配置(套件不会安装/运行/配对应用)。
    • 对所选 Android 节点逐命令进行网关 node.invoke 验证。
  • 前置条件:
    • Android 应用已连接并与网关配对。
    • 应用保持在前台。
    • 已授予你期望通过的能力所需的权限/截屏同意。
  • 可选的目标覆盖:
    • OPENCLAW_ANDROID_NODE_IDOPENCLAW_ANDROID_NODE_NAME
    • OPENCLAW_ANDROID_GATEWAY_URL / OPENCLAW_ANDROID_GATEWAY_TOKEN / OPENCLAW_ANDROID_GATEWAY_PASSWORD
  • 完整 Android 设置详情:Android App

实时测试:模型冒烟测试(配置密钥)

实时测试分为两层,以便隔离故障:

  • “直连模型”测试告诉我们提供商/模型能否用给定密钥进行响应。
  • “网关冒烟”测试告诉我们完整的网关+agent 流水线对该模型是否正常工作(会话、历史、工具、沙盒策略等)。

第一层:直连模型补全(无网关)

  • 测试文件:src/agents/models.profiles.live.test.ts
  • 目标:
    • 枚举已发现的模型
    • 使用 getApiKeyForModel 选择你有凭证的模型
    • 对每个模型运行小型补全(需要时加入针对性回归测试)
  • 启用方式:
    • pnpm test:live(或直接调用 Vitest 时设置 OPENCLAW_LIVE_TEST=1
  • 设置 OPENCLAW_LIVE_MODELS=modern(或 all,等价于 modern)来实际运行此套件;否则会跳过以保持 pnpm test:live 专注于网关冒烟测试
  • 模型选择:
    • 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 故障/密钥无效”与”网关 agent 流水线故障”区分开来
    • 包含小型、独立的回归测试(例如:OpenAI Responses/Codex Responses 推理重放 + 工具调用流程)

第二层:网关 + 开发 agent 冒烟测试(“@openclaw”的实际行为)

  • 测试文件:src/gateway/gateway-models.profiles.live.test.ts
  • 目标:
    • 启动一个进程内网关
    • 创建/修补 agent:dev:* 会话(每次运行覆盖模型)
    • 遍历有密钥的模型并断言:
      • “有意义”的响应(无工具)
      • 真实的工具调用可用(read 探测)
      • 可选的额外工具探测(exec+read 探测)
      • OpenAI 回归路径(仅工具调用 → 后续)保持正常
  • 探测详情(方便你快速解释失败原因):
    • read 探测:测试在工作区写入一个 nonce 文件,要求 agent 读取并回显 nonce。
    • exec+read 探测:测试要求 agent 通过 exec 将 nonce 写入临时文件,然后读取。
    • 图片探测:测试附加一张生成的 PNG(猫 + 随机代码),期望模型返回 cat <CODE>
    • 实现参考:src/gateway/gateway-models.profiles.live.test.tssrc/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>" }] 发送
      • 网关将附件解析为 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 后端验证网关 + 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","--permission-mode","bypassPermissions"]
  • 可选覆盖:
    • OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-opus-4-6"
    • OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"
    • 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

推荐的实时测试组合

精确的显式白名单最快且最稳定:

  • 单模型直连(无网关):

    • 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="openai/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/minimax-m2.5" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
  • Google 专项(Gemini API 密钥 + Antigravity):

    • Gemini(API 密钥):OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
    • Antigravity(OAuth):OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

说明:

  • google/... 使用 Gemini API(API 密钥)。
  • google-antigravity/... 使用 Antigravity OAuth 桥接(Cloud Code Assist 风格的 agent 端点)。
  • google-gemini-cli/... 使用本机上的 Gemini CLI(独立的认证和工具差异)。
  • Gemini API 与 Gemini CLI 的区别:
    • API:OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API(API 密钥/配置认证);大多数用户说的”Gemini”指的就是这个。
    • CLI:OpenClaw 调用本地的 gemini 二进制文件;它有自己的认证方式,行为可能不同(流式/工具支持/版本偏差)。

实时测试:模型矩阵(覆盖范围)

没有固定的”CI 模型列表”(实时测试是可选参与的),以下是在拥有密钥的开发机上推荐定期覆盖的模型。

现代冒烟集(工具调用 + 图片)

这是我们期望持续保持正常的”常用模型”运行集:

  • OpenAI(非 Codex):openai/gpt-5.2(可选:openai/gpt-5.1
  • OpenAI Codex:openai-codex/gpt-5.4
  • Anthropic:anthropic/claude-opus-4-6(或 anthropic/claude-sonnet-4-5
  • Google(Gemini API):google/gemini-3.1-pro-previewgoogle/gemini-3-flash-preview(避免使用旧版 Gemini 2.x 模型)
  • Google(Antigravity):google-antigravity/claude-opus-4-6-thinkinggoogle-antigravity/gemini-3-flash
  • Z.AI(GLM):zai/glm-4.7
  • MiniMax:minimax/minimax-m2.5

运行带工具和图片的网关冒烟测试: OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-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.1-pro-preview
  • Z.AI(GLM):zai/glm-4.7
  • MiniMax:minimax/minimax-m2.5

可选的额外覆盖(有则更好):

  • xAI:xai/grok-4(或最新可用版本)
  • Mistral:mistral/…(选择一个支持工具的模型)
  • Cerebras:cerebras/…(如有访问权限)
  • LM Studio:lmstudio/…(本地;工具调用取决于 API 模式)

视觉:图片发送(附件 → 多模态消息)

OPENCLAW_LIVE_GATEWAY_MODELS 中至少包含一个支持图片的模型(Claude/Gemini/OpenAI 视觉变体等)以测试图片探测。

聚合器/替代网关

如果你启用了密钥,我们还支持通过以下方式测试:

  • OpenRouter:openrouter/...(数百个模型;使用 openclaw models scan 查找支持工具+图片的候选模型)
  • OpenCode:opencode/... 用于 Zen,opencode-go/... 用于 Go(通过 OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY 认证)

你可以在实时矩阵中包含更多提供商(如果有凭证/配置):

  • 内置:openaiopenai-codexanthropicgooglegoogle-vertexgoogle-antigravitygoogle-gemini-clizaiopenrouteropencodeopencode-goxaigroqcerebrasmistralgithub-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
  • 网关 + 开发 agent: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

实时模型 Docker 运行器还会以只读方式挂载当前代码检出,并将其暂存到容器内的临时工作目录中。这保持运行时镜像精简,同时仍对你的本地源码/配置运行 Vitest。

手动 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 安全)

这些是无需真实提供商的”真实流水线”回归测试:

  • 网关工具调用(模拟 OpenAI,真实网关 + agent 循环):src/gateway/gateway.test.ts(用例:“runs a mock OpenAI tool call end-to-end via gateway agent loop”)
  • 网关向导(WS wizard.start/wizard.next,写入配置 + 强制认证):src/gateway/gateway.test.ts(用例:“runs wizard over ws and writes auth token config”)

Agent 可靠性评估(技能)

我们已有一些类似”agent 可靠性评估”的 CI 安全测试:

  • 通过真实网关 + agent 循环的模拟工具调用(src/gateway/gateway.test.ts)。
  • 验证会话连接和配置效果的端到端向导流程(src/gateway/gateway.test.ts)。

技能方面仍然缺失的内容(参见 技能):

  • 决策: 当技能列在提示中时,agent 是否选择了正确的技能(或避开了不相关的技能)?
  • 合规性: agent 是否在使用前读取了 SKILL.md 并遵循了必需的步骤/参数?
  • 工作流契约: 多轮场景中断言工具顺序、会话历史延续和沙盒边界。

未来的评估应优先保持确定性:

  • 使用模拟提供商的场景运行器来断言工具调用 + 顺序、技能文件读取和会话连接。
  • 一组小型的技能专项场景(使用 vs 避免、门控、提示注入)。
  • 可选的实时评估(可选参与,环境变量门控)仅在 CI 安全套件就位后添加。

添加回归测试(指导原则)

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

  • 尽可能添加 CI 安全的回归测试(模拟/桩提供商,或捕获确切的请求格式转换)
  • 如果本质上是仅限实时的(速率限制、认证策略),保持实时测试精确且通过环境变量可选参与
  • 优先针对能捕获 bug 的最小层级:
    • 提供商请求转换/重放 bug → 直连模型测试
    • 网关会话/历史/工具流水线 bug → 网关实时冒烟测试或 CI 安全的网关模拟测试
  • SecretRef 遍历护栏:
    • src/secrets/exec-secret-ref-id-parity.test.ts 从注册表元数据(listSecretTargetRegistryEntries())中为每个 SecretRef 类派生一个采样目标,然后断言遍历段 exec id 被拒绝。
    • 如果你在 src/secrets/target-registry-data.ts 中添加了新的 includeInPlan SecretRef 目标族,请更新该测试中的 classifyTargetClass。测试会在遇到未分类的目标 id 时故意失败,确保新类不会被悄悄跳过。