古法编程

Appearance

测试 ​

OpenClaw 包含三个 Vitest 测试套件（单元/集成、E2E、实机）和一组 Docker 运行器。

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

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

快速开始 ​

日常使用：

  • 完整门控（推送前预期执行）：pnpm build && pnpm check && pnpm test
  • 在大内存机器上更快的本地完整套件运行：pnpm test:max
  • Vitest 监视循环（现代 projects 配置）：pnpm test:watch
  • 直接文件定向（现在也路由 extension/channel 路径）：pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts

修改测试或需要额外信心时：

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

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

  • 实机套件（模型 + gateway 工具/图像探测）：pnpm test:live
  • 静默定向单个实机文件：pnpm test:live -- src/agents/models.profiles.live.test.ts

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

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

将套件理解为"逐渐增加真实性"（同时也增加不稳定性和成本）：

单元/集成（默认） ​

  • 命令：pnpm test
  • 配置：原生 Vitest projects（通过 vitest.config.ts）
  • 文件：src/**/*.test.ts、packages/**/*.test.ts、test/**/*.test.ts，以及 vitest.unit.config.ts 覆盖的白名单 ui node 测试
  • 范围：
    • 纯单元测试
    • 进程内集成测试（gateway 认证、路由、工具、解析、配置）
    • 已知 bug 的确定性回归测试
  • 预期：
    • 在 CI 中运行
    • 不需要真实密钥
    • 应该快速且稳定

E2E（Gateway 冒烟） ​

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

E2E：OpenShell 后端冒烟 ​

  • 命令：pnpm test:e2e:openshell
  • 文件：test/openshell-sandbox.e2e.test.ts
  • 范围：
    • 通过 Docker 在宿主机上启动隔离的 OpenShell gateway
    • 从临时本地 Dockerfile 创建沙盒
    • 通过真实 sandbox ssh-config + SSH exec 测试 OpenClaw 的 OpenShell 后端
  • 预期：
    • 仅选择性启用；不属于默认 pnpm test:e2e 运行
    • 需要本地 openshell CLI 和可用的 Docker 守护进程

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

  • 命令：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 节点当前宣传的每个命令，并断言命令契约行为。
  • 需要预先设置：
    • Android 应用已连接并配对到 gateway。
    • 应用保持在前台。
    • 已为预期通过的能力授予权限/捕获同意。

完整 Android 设置详情：Android App

实机：模型冒烟（配置文件密钥） ​

实机测试分为两层以隔离故障：

  • "直接模型"告诉我们提供商/模型是否能用给定密钥响应。
  • "Gateway 冒烟"告诉我们完整的 gateway + agent 管道是否适用于该模型。

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

  • 测试：src/agents/models.profiles.live.test.ts
  • 目标：枚举已发现的模型，使用 getApiKeyForModel 选择有凭据的模型，对每个模型运行小型补全
  • 如何选择模型：
    • OPENCLAW_LIVE_MODELS=modern 运行现代允许列表（Opus/Sonnet/Haiku 4.5、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）
    • 或 OPENCLAW_LIVE_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-6,..."（逗号允许列表）
  • 为什么存在：将"提供商 API 损坏/密钥无效"与"gateway agent 管道损坏"分离

第二层：Gateway + dev agent 冒烟 ​

  • 测试：src/gateway/gateway-models.profiles.live.test.ts
  • 目标：
    • 启动进程内 gateway
    • 创建/修补 agent:dev:* 会话（每次运行覆盖模型）
    • 对有密钥的模型进行迭代并断言：
      • "有意义"的响应（无工具）
      • 真实工具调用有效（read 探测）
      • 可选的额外工具探测（exec + read 探测）
  • 探测详情：
    • read 探测：测试在工作区写入随机数文件，要求 agent read 并回显。
    • exec+read 探测：要求 agent exec 写入随机数到临时文件，然后 read 回来。
    • 图像探测：附加生成的 PNG（cat + 随机代码）并期望模型返回 cat <CODE>。
  • 如何选择模型：
    • OPENCLAW_LIVE_GATEWAY_MODELS=all 是现代允许列表的别名
    • 或设置 OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"（或逗号列表）缩小范围

查看可在你的机器上测试的内容（以及确切的 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 时设置 OPENCLAW_LIVE_TEST=1）
    • OPENCLAW_LIVE_SETUP_TOKEN=1

设置示例：

bash
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 后端冒烟 ​

  • 测试：src/gateway/gateway-cli-backend.live.test.ts
  • 目标：使用本地 CLI 后端验证 Gateway + agent 管道，不触及默认配置。
  • 启用：
    • OPENCLAW_LIVE_CLI_BACKEND=1
  • 默认：
    • 模型：claude-cli/claude-sonnet-4-6
    • 命令：claude
bash
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

Docker 方案：

bash
pnpm test:docker:live-acp-bind

推荐的实机方案 ​

缩小、明确的允许列表是最快且最不容易出错的：

  • 单个模型，直接（无 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

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

    • 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.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

实机：模型矩阵（覆盖范围） ​

没有固定的"CI 模型列表"（实机测试是选择性启用的），但这些是推荐在有密钥的开发机器上定期覆盖的模型：

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

  • OpenAI（非 Codex）：openai/gpt-5.2
  • OpenAI Codex：openai-codex/gpt-5.4
  • Anthropic：anthropic/claude-opus-4-6（或 anthropic/claude-sonnet-4-6）
  • Google（Gemini API）：google/gemini-3.1-pro-preview 和 google/gemini-3-flash-preview
  • Z.AI（GLM）：zai/glm-4.7
  • MiniMax：minimax/MiniMax-M2.7

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

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

  • OpenAI：openai/gpt-5.2
  • Anthropic：anthropic/claude-opus-4-6
  • Google：google/gemini-3-flash-preview
  • Z.AI（GLM）：zai/glm-4.7
  • MiniMax：minimax/MiniMax-M2.7

聚合器/替代 Gateway ​

如果有密钥，也支持通过以下方式测试：

  • OpenRouter：openrouter/...（数百个模型；使用 openclaw models scan 查找支持工具 + 图像的候选）
  • OpenCode：opencode/... 用于 Zen，opencode-go/... 用于 Go

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

凭据（绝不提交） ​

实机测试发现凭据的方式与 CLI 相同：

  • 配置文件存储：~/.openclaw/credentials/（首选）
  • 配置：~/.openclaw/openclaw.json（或 OPENCLAW_CONFIG_PATH）

如果想依赖环境密钥（在 ~/.profile 中导出的），在 source ~/.profile 后运行本地测试，或使用下方的 Docker 运行器。

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

图像生成实机 ​

  • 测试：src/image-generation/runtime.live.test.ts
  • 命令：pnpm test:live src/image-generation/runtime.live.test.ts
  • 范围：枚举每个注册的图像生成提供商插件，跳过没有可用认证的提供商，运行标准图像生成变体。

Docker 运行器（可选的"在 Linux 上是否正常工作"检查） ​

Docker 运行器分两类：

  • 实机模型运行器：在仓库 Docker 镜像内运行 pnpm test:live，挂载本地配置目录和工作区。
  • 容器冒烟运行器：启动一个或多个真实容器验证更高层次的集成路径。
bash
# 直接模型
pnpm test:docker:live-models

# ACP bind 冒烟
pnpm test:docker:live-acp-bind

# Gateway + dev agent
pnpm test:docker:live-gateway

# Open WebUI 实机冒烟
pnpm test:docker:openwebui

# 引导向导（TTY，完整脚手架）
pnpm test:docker:onboard

# Gateway 网络（两个容器，WS 认证 + 健康）
pnpm test:docker:gateway-network

# 插件（安装冒烟 + /plugin 别名 + Claude 包重启语义）
pnpm test:docker:plugins

有用的环境变量：

  • 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=... 缩小运行范围

文档完整性 ​

文档编辑后运行检查：pnpm check:docs。 完整的 Mintlify 锚点验证（需要页内标题检查时）：pnpm docs:check-links:anchors。

离线回归（CI 安全） ​

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

  • Gateway 工具调用（模拟 OpenAI，真实 gateway + agent 循环）：src/gateway/gateway.test.ts
  • Gateway 向导（WS wizard.start/wizard.next，写入配置 + 强制认证）：src/gateway/gateway.test.ts

契约测试（插件和频道形状） ​

契约测试验证每个已注册的插件和频道是否符合其接口契约。

命令 ​

  • 所有契约：pnpm test:contracts
  • 仅频道契约：pnpm test:contracts:channels
  • 仅提供商契约：pnpm test:contracts:plugins

何时运行 ​

  • 更改 plugin-sdk 导出或子路径后
  • 添加或修改频道或提供商插件后
  • 重构插件注册或发现后

契约测试在 CI 中运行，不需要真实 API 密钥。

添加回归测试（指导方针） ​

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

  • 尽可能添加 CI 安全的回归（模拟/桩提供商，或捕获确切的请求形状转换）
  • 如果本质上只能在实机测试（速率限制、认证策略），通过环境变量保持实机测试缩窄且选择性启用
  • 优先定位能捕获 bug 的最小层：
    • 提供商请求转换/重放 bug → 直接模型测试
    • gateway 会话/历史/工具管道 bug → gateway 实机冒烟或 CI 安全的 gateway 模拟测试

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策