学了个寂寞

Appearance

测试 ​

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

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

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

快速开始 ​

日常使用：

  • 完整门控（推送前的预期操作）：pnpm build && pnpm check && pnpm test
  • 在资源充足的机器上更快的本地全套运行：pnpm test:max

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

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

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

  • 实机套件（模型 + Gateway 工具/图片探测）：pnpm test:live

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

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

可以把这些套件理解为"逐步增加真实感"（同时增加不稳定性/成本）：

单元/集成（默认） ​

  • 命令：pnpm test
  • 配置：scripts/test-parallel.mjs（运行 vitest.unit.config.ts、vitest.extensions.config.ts、vitest.gateway.config.ts）
  • 文件：src/**/*.test.ts、extensions/**/*.test.ts
  • 范围：
    • 纯单元测试
    • 进程内集成测试（Gateway 认证、路由、工具、解析、配置）
    • 已知 bug 的确定性回归测试
  • 预期：
    • 在 CI 中运行
    • 无需真实 API Key
    • 应快速且稳定
  • 快速本地迭代：
    • pnpm test:changed — 仅运行自 origin/main 以来变更文件的测试
    • pnpm test:changed:max — 相同的变更文件过滤，但使用激进的本地计划器 profile
    • pnpm test:max — 完整本地运行的激进计划器

E2E（Gateway 冒烟测试） ​

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

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 守护进程
  • 有用的覆盖：
    • OPENCLAW_E2E_OPENSHELL=1 — 手动运行更广泛的 E2E 套件时启用此测试
    • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell — 指向非默认的 CLI 二进制文件或包装脚本

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

  • 命令：pnpm test:live
  • 配置：vitest.live.config.ts
  • 文件：src/**/*.live.test.ts
  • 默认：由 pnpm test:live 启用（设置 OPENCLAW_LIVE_TEST=1）
  • 范围：
    • "这个提供商/模型今天真的能用真实凭据工作吗？"
    • 捕获提供商格式变化、工具调用异常、认证问题和速率限制行为
  • 预期：
    • 由于真实网络、真实提供商策略、配额、故障，CI 稳定性无法保证
    • 花费真实费用/使用速率限制
    • 优先运行缩小范围的子集，而非"所有测试"
    • 实机运行会从 ~/.profile 读取缺失的 API Key
  • API Key 轮换：设置 *_API_KEYS（逗号/分号格式）或 *_API_KEY_1、*_API_KEY_2；速率限制时重试。

应该运行哪个套件？ ​

使用此决策表：

  • 编辑逻辑/测试：运行 pnpm test（改动较大时加 pnpm test:coverage）
  • 修改 Gateway 网络/WS 协议/配对：加上 pnpm test:e2e
  • 调试"我的 Bot 挂了"/提供商特定失败/工具调用：运行缩小范围的 pnpm test:live

实机测试：模型冒烟（Profile Keys） ​

实机测试分为两层：

  • "直接模型"告诉我们提供商/模型能否用给定 Key 回答。
  • "Gateway 冒烟"告诉我们完整的 Gateway+Agent 流水线对该模型是否有效（会话、历史、工具等）。

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

  • 测试文件：src/agents/models.profiles.live.test.ts
  • 如何选择模型：
    • 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,..."（逗号允许列表）
  • 如何选择提供商：
    • OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"

第二层：Gateway + dev agent 冒烟（"@openclaw"实际执行的内容） ​

  • 测试文件：src/gateway/gateway-models.profiles.live.test.ts
  • 如何选择模型：
    • 默认：现代允许列表
    • OPENCLAW_LIVE_GATEWAY_MODELS=all — 现代允许列表的别名
    • 或 OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"（或逗号列表）进行缩小
  • 如何选择提供商：
    • OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"

探测类型（快速解释失败原因）：

  • read 探测：测试在工作区写入 nonce 文件，让 Agent 读取并回显 nonce。
  • exec+read 探测：测试让 Agent 通过 exec 把 nonce 写入临时文件，再 read 读回。
  • 图片探测：附加生成的 PNG（猫 + 随机代码），期望模型返回 cat <CODE>。

推荐实机配方 ​

缩小的显式允许列表最快且最稳定：

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

查看机器上可测试的内容：

bash
openclaw models list
openclaw models list --json

实机测试：Android 节点能力扫描 ​

  • 测试文件：src/gateway/android-node.capabilities.live.test.ts
  • 脚本：pnpm android:test:integration
  • 目标：调用已连接 Android 节点当前公告的每个命令，断言命令契约行为。
  • 需要预先配置：
    • Android 应用已连接并与 Gateway 配对。
    • 应用保持在前台。
    • 已为期望通过的能力授予权限/采集同意。
  • 可选目标覆盖：
    • OPENCLAW_ANDROID_NODE_ID 或 OPENCLAW_ANDROID_NODE_NAME。

参见 Android 应用。

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

  • 测试文件：src/agents/anthropic.setup-token.live.test.ts
  • 目标：验证 Claude Code CLI setup-token（或粘贴的 setup-token profile）能完成 Anthropic 提示。
  • 启用：OPENCLAW_LIVE_SETUP_TOKEN=1
  • Token 来源（选其一）：
    • Profile：OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test
    • 原始 token：OPENCLAW_LIVE_SETUP_TOKEN_VALUE=sk-ant-oat01-...

设置示例：

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

  • 测试文件：src/gateway/gateway-cli-backend.live.test.ts
  • 目标：使用本地 CLI 后端验证 Gateway + Agent 流水线，不触及你的默认配置。
  • 启用：OPENCLAW_LIVE_CLI_BACKEND=1
  • 默认：
    • 模型：claude-cli/claude-sonnet-4-6
    • 命令：claude
    • 参数：["-p","--output-format","json","--permission-mode","bypassPermissions"]

Docker 配方：

bash
pnpm test:docker:live-cli-backend

Docker 运行器（可选的"在 Linux 上验证"检查） ​

两类 Docker 运行器：

  • 实机模型运行器：test:docker:live-models 和 test:docker:live-gateway 在仓库 Docker 镜像内运行 pnpm test:live。
  • 容器冒烟运行器：test:docker:openwebui、test:docker:onboard、test:docker:gateway-network、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 docs:list。

离线回归（CI 安全） ​

这些是"真实流水线"回归，但不需要真实提供商：

  • Gateway 工具调用（模拟 OpenAI，真实 Gateway + Agent 循环）：src/gateway/gateway.test.ts（用例："runs a mock OpenAI tool call end-to-end via gateway agent loop"）
  • Gateway 向导（WS wizard.start/wizard.next，写入配置 + 认证强制）：src/gateway/gateway.test.ts（用例："runs wizard over ws and writes auth token config"）

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

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

命令 ​

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

何时运行 ​

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

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

添加回归测试（指南） ​

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

  • 如果可能，添加 CI 安全回归（模拟/存根提供商，或捕获确切的请求形状转换）。
  • 如果本质上只能实机测试（速率限制、认证策略），保持实机测试简短并通过环境变量可选加入。
  • 优先针对能捕获 bug 的最小层：
    • 提供商请求转换/重放 bug → 直接模型测试
    • Gateway 会话/历史/工具流水线 bug → Gateway 实机冒烟或 CI 安全 Gateway 模拟测试

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

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策