测试

OpenClaw 有三个 Vitest 测试套件(unit/integration、e2e、live)和一组 Docker runner。

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

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

快速开始

日常使用:

  • 完整检查(推送前必须): pnpm lint && pnpm build && pnpm test

当您修改测试或需要额外信心时:

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

调试真实 provider/模型时(需要真实凭证):

  • Live 套件(模型 + gateway 工具/图像探测): pnpm test:live

提示: 当您只需要一个失败的用例时,优先通过下面描述的 allowlist 环境变量缩小 live 测试范围。

测试套件(在哪里运行什么)

将套件视为"不断增加的真实性"(以及不断增加的不稳定性/成本):

Unit / integration (默认)

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

E2E (gateway 冒烟测试)

  • 命令: pnpm test:e2e
  • 配置: vitest.e2e.config.ts
  • 文件: src/**/*.e2e.test.ts
  • 范围:
    • 多实例 gateway 端到端行为
    • WebSocket/HTTP 接口、节点配对和更重的网络操作
  • 期望:
    • 在 CI 中运行(当在管道中启用时)
    • 不需要真实密钥
    • 比单元测试有更多活动部件(可能更慢)

Live (真实 provider + 真实模型)

  • 命令: pnpm test:live
  • 配置: vitest.live.config.ts
  • 文件: src/**/*.live.test.ts
  • 默认: 由 pnpm test:live 启用(设置 OPENCLAW_LIVE_TEST=1)
  • 范围:
    • "这个 provider/模型今天是否真的能用真实凭证工作?"
    • 捕获 provider 格式变化、工具调用怪癖、认证问题和速率限制行为
  • 期望:
    • 设计上不适合 CI(真实网络、真实 provider 策略、配额、故障)
    • 花费金钱/使用速率限制
    • 优先运行缩小的子集而不是"全部"
    • Live 运行会 source ~/.profile 以获取缺失的 API 密钥
    • Anthropic 密钥轮换: 设置 OPENCLAW_LIVE_ANTHROPIC_KEYS="sk-...,sk-..." (或 OPENCLAW_LIVE_ANTHROPIC_KEY=sk-...) 或多个 ANTHROPIC_API_KEY* 变量;测试会在速率限制时重试

我应该运行哪个套件?

使用此决策表:

  • 编辑逻辑/测试: 运行 pnpm test (如果改动很多,加上 pnpm test:coverage)
  • 修改 gateway 网络/WS 协议/配对: 添加 pnpm test:e2e
  • 调试"我的机器人挂了"/provider 特定故障/工具调用: 运行缩小范围的 pnpm test:live

Live: 模型冒烟测试(配置文件密钥)

Live 测试分为两层,以便我们可以隔离故障:

  • "直接模型"告诉我们 provider/模型是否能用给定密钥回答
  • "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,modern 的别名)以实际运行此套件;否则它会跳过以保持 pnpm test:live 专注于 gateway 冒烟测试
  • 如何选择模型:
    • OPENCLAW_LIVE_MODELS=modern 运行现代 allowlist (Opus/Sonnet/Haiku 4.5、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.1、Grok 4)
    • OPENCLAW_LIVE_MODELS=all 是现代 allowlist 的别名
    • 或 OPENCLAW_LIVE_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5,..." (逗号 allowlist)
  • 如何选择 provider:
    • OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" (逗号 allowlist)
  • 密钥来源:
    • 默认: 配置文件存储和环境变量回退
    • 设置 OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 强制仅使用配置文件存储
  • 为什么存在:
    • 将"provider API 损坏/密钥无效"与"gateway agent 管道损坏"分开
    • 包含小型隔离回归(示例: OpenAI Responses/Codex Responses 推理重放 + 工具调用流程)

第 2 层: Gateway + dev agent 冒烟测试("@openclaw"实际执行的操作)

  • 测试: src/gateway/gateway-models.profiles.live.test.ts
  • 目标:
    • 启动进程内 gateway
    • 创建/修补 agent:dev:* 会话(每次运行覆盖模型)
    • 迭代有密钥的模型并断言:
      • "有意义的"响应(无工具)
      • 真实工具调用有效(read 探测)
      • 可选的额外工具探测(exec+read 探测)
      • OpenAI 回归路径(仅工具调用 → 后续)保持正常工作
  • 探测详情(以便您可以快速解释故障):
    • read 探测: 测试在工作区中写入一个 nonce 文件,并要求 agent read 它并回显 nonce。
    • exec+read 探测: 测试要求 agent exec 写入 nonce 到临时文件,然后 read 回来。
    • 图像探测: 测试附加生成的 PNG(猫 + 随机代码)并期望模型返回 cat <CODE>。
    • 实现参考: src/gateway/gateway-models.profiles.live.test.ts 和 src/gateway/live-image-probe.ts。
  • 如何启用:
    • pnpm test:live (或直接调用 Vitest 时使用 OPENCLAW_LIVE_TEST=1)
  • 如何选择模型:
    • 默认: 现代 allowlist (Opus/Sonnet/Haiku 4.5、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.1、Grok 4)
    • OPENCLAW_LIVE_GATEWAY_MODELS=all 是现代 allowlist 的别名
    • 或设置 OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" (或逗号列表)来缩小范围
  • 如何选择 provider (避免"OpenRouter 全部"):
    • OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" (逗号 allowlist)
  • 工具 + 图像探测在此 live 测试中始终开启:
    • 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

Live: 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
  • Token 来源(选择一个):
    • 配置文件: OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test
    • 原始 token: OPENCLAW_LIVE_SETUP_TOKEN_VALUE=sk-ant-oat01-...
  • 模型覆盖(可选):
    • OPENCLAW_LIVE_SETUP_TOKEN_MODEL=anthropic/claude-opus-4-5

设置示例:

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

Live: 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-5
    • 命令: claude
    • 参数: ["-p","--output-format","json","--dangerously-skip-permissions"]
  • 覆盖(可选):
    • OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-opus-4-5"
    • OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2-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-5" \
  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts

推荐的 live 配方

狭窄、显式的 allowlist 是最快和最不易失败的:

  • 单一模型,直接(无 gateway):

    • OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts

  • 单一模型,gateway 冒烟测试:

    • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

  • 跨多个 provider 的工具调用:

    • OPENCLAW_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 重点(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-5-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 vs Gemini CLI:
    • API: OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API (API 密钥/配置文件认证);这是大多数用户所指的"Gemini"。
    • CLI: OpenClaw shell 到本地 gemini 二进制文件;它有自己的认证并且可能表现不同(流式传输/工具支持/版本差异)。

Live: 模型矩阵(我们覆盖的内容)

没有固定的"CI 模型列表"(live 是选择性的),但这些是推荐的模型,应定期在有密钥的开发机器上覆盖。

现代冒烟测试集(工具调用 + 图像)

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

  • OpenAI (非 Codex): openai/gpt-5.2 (可选: openai/gpt-5.1)
  • OpenAI Codex: openai-codex/gpt-5.2 (可选: openai-codex/gpt-5.2-codex)
  • Anthropic: anthropic/claude-opus-4-5 (或 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-5-thinking 和 google-antigravity/gemini-3-flash
  • Z.AI (GLM): zai/glm-4.7
  • MiniMax: minimax/minimax-m2.1

运行带工具 + 图像的 gateway 冒烟测试: OPENCLAW_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

基线: 工具调用(Read + 可选 Exec)

每个 provider 系列至少选择一个:

  • OpenAI: openai/gpt-5.2 (或 openai/gpt-5-mini)
  • Anthropic: anthropic/claude-opus-4-5 (或 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.1

可选的额外覆盖(很好拥有):

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

Vision: 图像发送(附件 → 多模态消息)

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

聚合器/备用 gateway

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

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

您可以包含在 live 矩阵中的更多 provider (如果您有凭证/配置):

  • 内置: 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(...) 返回的内容 + 可用的密钥。

凭证(永远不要提交)

Live 测试以与 CLI 相同的方式发现凭证。实际影响:

  • 如果 CLI 有效,live 测试应找到相同的密钥。

  • 如果 live 测试说"无凭证",以与调试 openclaw models list / 模型选择相同的方式进行调试。

  • 配置文件存储: ~/.openclaw/credentials/ (首选;测试中"配置文件密钥"的含义)

  • 配置: ~/.openclaw/openclaw.json (或 OPENCLAW_CONFIG_PATH)

如果您想依赖环境变量密钥(例如在 ~/.profile 中导出),请在 source ~/.profile 后运行本地测试,或使用下面的 Docker runner (它们可以将 ~/.profile 挂载到容器中)。

Deepgram live (音频转录)

  • 测试: 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 runner (可选的"在 Linux 中工作"检查)

这些在 repo Docker 镜像内运行 pnpm test:live,挂载您的本地配置目录和工作区(并在挂载时 source ~/.profile):

  • 直接模型: pnpm test:docker:live-models (脚本: scripts/test-live-models-docker.sh)
  • Gateway + dev 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)

有用的环境变量:

  • OPENCLAW_CONFIG_DIR=... (默认: ~/.openclaw) 挂载到 /home/node/.openclaw
  • OPENCLAW_WORKSPACE_DIR=... (默认: ~/.openclaw/workspace) 挂载到 /home/node/.openclaw/workspace
  • OPENCLAW_PROFILE_FILE=... (默认: ~/.profile) 挂载到 /home/node/.profile 并在运行测试前 source
  • OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... 缩小运行范围
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 确保凭证来自配置文件存储(而非环境变量)

文档完整性

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

离线回归(CI 安全)

这些是没有真实 provider 的"真实管道"回归:

  • Gateway 工具调用(模拟 OpenAI,真实 gateway + agent 循环): src/gateway/gateway.tool-calling.mock-openai.test.ts
  • Gateway 向导(WS wizard.start/wizard.next,写入配置 + 强制认证): src/gateway/gateway.wizard.e2e.test.ts

Agent 可靠性评估(技能)

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

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

技能仍然缺少的内容(参见 技能):

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

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

  • 使用模拟 provider 断言工具调用 + 顺序、技能文件读取和会话连接的场景运行器。
  • 一套小型技能重点场景(使用 vs 避免、门控、提示注入)。
  • 只有在 CI 安全套件到位后才选择性地进行 live 评估(选择性加入,环境门控)。

添加回归(指导)

当您修复在 live 中发现的 provider/模型问题时:

  • 如果可能,添加 CI 安全回归(模拟/stub provider,或捕获确切的请求形状转换)
  • 如果它本质上是 live-only (速率限制、认证策略),通过环境变量保持 live 测试狭窄且可选
  • 优先针对捕获错误的最小层:
    • provider 请求转换/重放错误 → 直接模型测试
    • gateway 会话/历史/工具管道错误 → gateway live 冒烟测试或 CI 安全 gateway 模拟测试
← 返回文档首页