文档
测试

测试

适用范围

在以下情况使用本页：

  • 在本地或 CI 中运行测试
  • 为模型/提供商错误添加回归
  • 调试 gateway + agent 行为

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

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

  • 每个套件涵盖的内容（以及它故意不涵盖的内容）
  • 用于常见工作流的命令（本地、推送前、调试）
  • 实时测试如何发现凭证和选择模型/提供商
  • 如何为真实的模型/提供商问题添加回归

快速开始

大多数日子：

  • 完整关卡（推送前预期）：pnpm lint && pnpm build && pnpm test

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

  • 覆盖率关卡：pnpm test:coverage
  • E2E 套件：pnpm test:e2e

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

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

提示：当您只需要一个失败的案例时，最好通过下面描述的 allowlist 环境变量来缩小实时测试。

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

将套件视为"越来越真实"（以及越来越不稳定/昂贵）：

单元 / 集成（默认）

  • 命令：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（真实提供商 + 真实模型）

  • 命令：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）
  • 接触 gateway 网络 / WS 协议 / 配对：添加 pnpm test:e2e
  • 调试"我的机器人挂了"/提供商特定的失败/工具调用：运行缩小的 pnpm test:live

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

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

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

第 1 层：直接模型补全（无 gateway）

  • 测试：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 专注于 gateway 冒烟测试
    • 如何选择模型：
    • 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 损坏 / 密钥无效"与"gateway agent 管道损坏"分开
    • 包含小的、隔离的回归（例如：OpenAI Responses/Codex Responses 推理重放 + 工具调用流程）

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

  • 测试：src/gateway/gateway-models.profiles.live.test.ts
  • 目标：
    • 启动进程内 gateway
    • 创建/修补 agent:dev:* 会话（每次运行的模型覆盖）
    • 迭代带密钥的模型并断言：
      • “有意义的"响应（无工具）
      • 真实的工具调用有效（读取探测）
      • 可选的额外工具探测（exec+读取探测）
      • OpenAI 回归路径（仅工具调用 → 后续）保持工作
    • 探测详情（以便您可以快速解释失败）：
    • read 探测：测试在工作区中写入一个 nonce 文件，并要求 agent 读取它并将 nonce 回显。
    • exec+read 探测：测试要求 agent exec-将 nonce 写入临时文件，然后 读取 它。
    • 图像探测：测试附加一个生成的 PNG（cat + 随机代码）并期望模型返回 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>" }] 发送它
      • Gateway 将附件解析为 images[]（src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts）
      • 嵌入式 agent 将多模式用户消息转发给模型
      • 断言：回复包含 cat + 代码（OCR 容差：允许小错误）

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

clawdbot models list
clawdbot 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，则为 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

设置示例：

clawdbot 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 后端冒烟测试（Claude Code CLI 或其他本地 CLI）

  • 测试：src/gateway/gateway-cli-backend.live.test.ts
  • 目标：使用本地 CLI 后端验证 Gateway + agent 管道，而不触及您的默认配置。
  • 启用：
    • pnpm test:live（如果直接调用 Vitest，则为 CLAWDBOT_LIVE_TEST=1）
    • CLAWDBOT_LIVE_CLI_BACKEND=1
  • 默认值：
    • 模型：claude-cli/claude-sonnet-4-5
    • 命令：claude
    • 参数：["-p","--output-format","json","--dangerously-skip-permissions"]
  • 覆盖（可选）：
    • 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 发送真实的图像附件（路径被注入到提示中）。
    • CLAWDBOT_LIVE_CLI_BACKEND_IMAGE_ARG="--image" 将图像文件路径作为 CLI 参数传递，而不是提示注入。
    • CLAWDBOT_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"（或 "list"）在设置 IMAGE_ARG 时控制如何传递图像参数。
    • CLAWDBOT_LIVE_CLI_BACKEND_RESUME_PROBE=1 发送第二轮并验证恢复流程。
    • CLAWDBOT_LIVE_CLI_BACKEND_DISABLE_MCP_CONFIG=0 保持 Claude Code CLI MCP 配置启用（默认使用临时空文件禁用 MCP 配置）。

示例：

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

推荐的实时配方

狭窄、明确的白名单是最快且最不稳定的：

  • 单个模型，直接（无 gateway）：

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

  • 单个模型，gateway 冒烟测试：

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

  • 跨多个提供商的工具调用：

    • 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 焦点（Gemini API 密钥 + Antigravity）：

    • Gemini（API 密钥）：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

注意事项：

  • google/... 使用 Gemini API（API 密钥）。
  • google-antigravity/... 使用 Antigravity OAuth 桥接（Cloud Code Assist 风格的 agent 端点）。
  • google-gemini-cli/... 使用您机器上的本地 Gemini CLI（单独的身份验证 + 工具怪癖）。
  • Gemini API vs Gemini CLI：
    • API：Clawdbot 通过 HTTP 调用 Google 托管的 Gemini API（API 密钥/配置文件身份验证）；这是大多数用户所说的"Gemini"的意思。
    • CLI：Clawdbot 调用本地 gemini 二进制文件；它有自己的身份验证，行为可能不同（流式传输/工具支持/版本偏差）。

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

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

现代冒烟套件（工具调用 + 图像）

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

  • 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 冒烟测试： 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

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

为每个提供商系列至少选择一个：

  • 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/…（选择一个您启用的"工具” capable 模型）
  • Cerebras：cerebras/…（如果您有访问权限）
  • LM Studio：lmstudio/…（本地；工具调用取决于 API 模式）

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

在 CLAWDBOT_LIVE_GATEWAY_MODELS 中至少包含一个支持图像的模型（Claude/Gemini/OpenAI 支持图像的变体等）以运行图像探测。

聚合器 / 备选 gateway

如果您启用了密钥，我们还支持通过以下方式进行测试：

  • OpenRouter：openrouter/...（数百个模型；使用 clawdbot models scan 查找工具+图像 capable 的候选）
  • 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 有效，实时测试应该找到相同的密钥。

  • 如果实时测试说"没有凭证"，请像调试 clawdbot models list / 模型选择那样调试。

  • 配置文件存储：~/.clawdbot/credentials/（首选；测试中"配置文件密钥"的含义）

  • 配置：~/.clawdbot/clawdbot.json（或 CLAWDBOT_CONFIG_PATH）

如果您想依赖环境密钥（例如在 ~/.profile 中导出），请在 source ~/.profile 后运行本地测试，或使用下面的 Docker 运行器（它们可以将 ~/.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 运行器（可选的"在 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）

有用的环境变量：

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

文档完整性

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

离线回归（CI 安全）

这些是"真实管道"回归，没有真实的提供商：

  • 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 可靠性评估（技能）

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

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

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

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

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

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

添加回归（指导）

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

  • 如果可能，添加 CI 安全回归（模拟/存根提供商，或捕获确切的请求形状转换）
  • 如果它本质上是仅实时的（速率限制、身份验证策略），保持实时测试狭窄并通过环境变量可选加入
  • 优先选择捕获 bug 的最小层：
    • 提供商请求转换/重放 bug → 直接模型测试
测试插件 SDK + 运行时重构计划