测试

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• 完整测试工具包（套件、实时测试、Docker）：测试
• 更新和插件包验证：更新和插件测试
• pnpm test:force：终止任何仍占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整 Vitest 套件，避免服务器测试与正在运行的实例冲突。当前一次 Gateway 网关运行留下端口 18789 被占用时使用。
• pnpm test:coverage：使用 V8 覆盖率运行单元套件（通过 vitest.unit.config.ts）。这是已加载文件的单元覆盖率门禁，不是整个仓库的全文件覆盖率。阈值为行/函数/语句 70%，分支 55%。因为 coverage.all 为 false，该门禁衡量单元覆盖率套件加载的文件，而不是把每个分片通道源文件都视为未覆盖。
• pnpm test:coverage:changed：仅对自 origin/main 以来变更的文件运行单元覆盖率。
• pnpm test:changed：低成本的智能变更测试运行。它会根据直接测试编辑、同级 *.test.ts 文件、显式源映射和本地导入图运行精确目标。广泛/config/package 变更会被跳过，除非它们映射到精确测试。
• OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed：显式的广泛变更测试运行。当测试 harness/config/package 编辑应回退到 Vitest 更广泛的变更测试行为时使用。
• pnpm changed:lanes：显示相对于 origin/main 的 diff 触发的架构通道。
• pnpm check:changed：对相对于 origin/main 的 diff 运行智能变更检查门禁。它会为受影响的架构通道运行类型检查、lint 和守卫命令，但不会运行 Vitest 测试。使用 pnpm test:changed 或显式 pnpm test <target> 提供测试证明。
• pnpm test：将显式文件/目录目标路由到有作用域的 Vitest 通道。无目标运行会使用固定分片组，并展开为叶级配置以进行本地并行执行；扩展组始终展开为每个扩展的分片配置，而不是一个巨大的根项目进程。
• 测试 wrapper 运行会以简短的 [test] passed|failed|skipped ... in ... 摘要结束。Vitest 自己的时长行保留为每个分片的详细信息。
• 共享 OpenClaw 测试状态：当测试需要隔离的 HOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH、配置 fixture、工作区、智能体目录或 auth-profile 存储时，在 Vitest 中使用 src/test-utils/openclaw-test-state.ts。
• 进程 E2E 辅助工具：当 Vitest 进程级 E2E 测试需要在一个位置管理正在运行的 Gateway 网关、CLI 环境、日志捕获和清理时，使用 test/helpers/openclaw-test-instance.ts。
• Docker/Bash E2E 辅助工具：source scripts/lib/docker-e2e-image.sh 的通道可以将 docker_e2e_test_state_shell_b64 <label> <scenario> 传入容器，并用 scripts/lib/openclaw-e2e-instance.sh 解码；多 home 脚本可以传入 docker_e2e_test_state_function_b64，并在每个流程中调用 openclaw_test_state_create <label> <scenario>。较低层调用方可以使用 scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name> 获取容器内 shell 片段，或使用 node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json 生成可 source 的宿主环境文件。create 前面的 -- 会阻止较新的 Node 运行时把 --env-file 视为 Node 标志。启动 Gateway 网关的 Docker/Bash 通道可以在容器内 source scripts/lib/openclaw-e2e-instance.sh，用于入口点解析、模拟 OpenAI 启动、Gateway 网关前台/后台启动、就绪探测、状态环境导出、日志转储和进程清理。
• 完整、扩展和 include-pattern 分片运行会更新 .artifacts/vitest-shard-timings.json 中的本地计时数据；后续 whole-config 运行使用这些计时来平衡慢速和快速分片。Include-pattern CI 分片会把分片名称追加到计时键，这会让过滤后的分片计时保持可见，同时不替换 whole-config 计时数据。设置 OPENCLAW_TEST_PROJECTS_TIMINGS=0 可忽略本地计时 artifact。
• 选定的 plugin-sdk 和 commands 测试文件现在会路由到专用轻量通道，这些通道只保留 test/setup.ts，而运行时较重的用例保留在现有通道中。
• 带有同级测试的源文件会先映射到该同级测试，再回退到更宽的目录 glob。src/channels/plugins/contracts/test-helpers、src/plugin-sdk/test-helpers 和 src/plugins/contracts 下的辅助工具编辑会使用本地导入图运行导入它们的测试，而不是在依赖路径精确时广泛运行每个分片。
• auto-reply 现在也拆分为三个专用配置（core、top-level、reply），这样回复 harness 不会压过较轻量的顶层 status/token/helper 测试。
• 基础 Vitest 配置现在默认使用 pool: "threads" 和 isolate: false，并在仓库配置中启用共享的非隔离 runner。
• pnpm test:channels 运行 vitest.channels.config.ts。
• pnpm test:extensions 和 pnpm test extensions 运行所有扩展/插件分片。重型渠道插件、浏览器插件和 OpenAI 会作为专用分片运行；其他插件组保持批处理。使用 pnpm test extensions/<id> 运行一个内置插件通道。
• pnpm test:perf:imports：启用 Vitest 导入时长 + 导入分解报告，同时仍然对显式文件/目录目标使用有作用域的通道路由。
• pnpm test:perf:imports:changed：相同的导入 profiling，但仅针对自 origin/main 以来变更的文件。
• pnpm test:perf:changed:bench -- --ref <git-ref>：基准测试同一已提交 git diff 下，路由后的 changed-mode 路径相对于原生根项目运行的表现。
• pnpm test:perf:changed:bench -- --worktree：在无需先提交的情况下，对当前 worktree 变更集进行基准测试。
• pnpm test:perf:profile:main：为 Vitest 主线程写入 CPU profile（.artifacts/vitest-main-profile）。
• pnpm test:perf:profile:runner：为单元 runner 写入 CPU + heap profile（.artifacts/vitest-runner-profile）。
• pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json：串行运行每个 full-suite Vitest 叶级配置，并写入分组时长数据以及每个配置的 JSON/log artifact。Test Performance Agent 使用它作为尝试修复慢测试之前的基线。
• pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json：在性能相关变更后比较分组报告。
• Gateway 网关集成：通过 OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test 或 pnpm test:gateway 选择启用。
• pnpm test:e2e：运行 Gateway 网关端到端 smoke 测试（多实例 WS/HTTP/node 配对）。默认使用 threads + isolate: false，并在 vitest.e2e.config.ts 中使用自适应 worker；用 OPENCLAW_E2E_WORKERS=<n> 调整，并设置 OPENCLAW_E2E_VERBOSE=1 输出详细日志。
• pnpm test:live：运行提供商 live 测试（minimax/zai）。需要 API key 和 LIVE=1（或提供商特定的 *_LIVE_TEST=1）才能取消跳过。
• pnpm test:docker:all：构建共享 live-test 镜像，将 OpenClaw 一次打包为 npm tarball，构建/复用一个裸 Node/Git runner 镜像，以及一个把该 tarball 安装到 /app 的功能镜像，然后通过加权调度器以 OPENCLAW_SKIP_DOCKER_BUILD=1 运行 Docker smoke 通道。裸镜像（OPENCLAW_DOCKER_E2E_BARE_IMAGE）用于 installer/update/plugin-dependency 通道；这些通道挂载预构建 tarball，而不是使用复制的仓库源。功能镜像（OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE）用于普通 built-app 功能通道。scripts/package-openclaw-for-docker.mjs 是唯一的本地/CI package packer，并在 Docker 消费前验证 tarball 和 dist/postinstall-inventory.json。Docker 通道定义位于 scripts/lib/docker-e2e-scenarios.mjs；planner 逻辑位于 scripts/lib/docker-e2e-plan.mjs；scripts/test-docker-all.mjs 执行选定计划。node scripts/test-docker-all.mjs --plan-json 会输出调度器拥有的 CI 计划，包含选定通道、镜像类型、package/live-image 需求、状态场景和凭据检查，而不会构建或运行 Docker。OPENCLAW_DOCKER_ALL_PARALLELISM=<n> 控制进程槽位，默认值为 10；OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n> 控制提供商敏感的 tail pool，默认值为 10。重型通道上限默认是 OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9、OPENCLAW_DOCKER_ALL_NPM_LIMIT=10 和 OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7；提供商上限默认通过 OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4、OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4 和 OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4 设置为每个提供商一个重型通道。更大的宿主机可使用 OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT 或 OPENCLAW_DOCKER_ALL_DOCKER_LIMIT。如果某个通道在低并行度宿主机上超过有效权重或资源上限，它仍然可以从空池启动，并会独占运行直到释放容量。通道启动默认错开 2 秒，以避免本地 Docker daemon 创建风暴；可用 OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms> 覆盖。runner 默认预检 Docker，清理陈旧的 OpenClaw E2E 容器，每 30 秒输出 active-lane 状态，在兼容通道之间共享提供商 CLI 工具缓存，默认对瞬态 live-provider 失败重试一次（OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>），并将通道计时存储在 .artifacts/docker-tests/lane-timings.json 中，以便后续运行按最长优先排序。使用 OPENCLAW_DOCKER_ALL_DRY_RUN=1 可打印通道清单而不运行 Docker，使用 OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms> 可调整状态输出，或使用 OPENCLAW_DOCKER_ALL_TIMINGS=0 禁用计时复用。使用 OPENCLAW_DOCKER_ALL_LIVE_MODE=skip 仅运行确定性/本地通道，或使用 OPENCLAW_DOCKER_ALL_LIVE_MODE=only 仅运行 live-provider 通道；package 别名是 pnpm test:docker:local:all 和 pnpm test:docker:live:all。Live-only 模式会把 main 和 tail live 通道合并到一个最长优先池中，这样提供商 bucket 可以把 Claude、Codex 和 Gemini 工作打包在一起。除非设置 OPENCLAW_DOCKER_ALL_FAIL_FAST=0，runner 会在第一次失败后停止调度新的 pooled 通道，并且每个通道都有一个 120 分钟的回退超时，可用 OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS 覆盖；选定的 live/tail 通道使用更严格的每通道上限。CLI 后端 Docker 设置命令有自己的超时，通过 OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS 控制（默认 180）。每通道日志、summary.json、failures.json 和阶段计时会写入 .artifacts/docker-tests/<run-id>/ 下；使用 pnpm test:docker:timings <summary.json> 检查慢通道，使用 pnpm test:docker:rerun <run-id|summary.json|failures.json> 打印低成本的定向重跑命令。
• pnpm test:docker:browser-cdp-snapshot：构建基于 Chromium 的 source E2E 容器，启动原始 CDP 加隔离的 Gateway 网关，运行 browser doctor --deep，并验证 CDP role 快照包含链接 URL、cursor-promoted clickables、iframe refs 和 frame metadata。
• CLI 后端 live Docker 探测可以作为聚焦通道运行，例如 pnpm test:docker:live-cli-backend:codex、pnpm test:docker:live-cli-backend:codex:resume 或 pnpm test:docker:live-cli-backend:codex:mcp。Claude 和 Gemini 有匹配的 :resume 和 :mcp 别名。
• pnpm test:docker:openwebui：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 /api/models，然后通过 /api/chat/completions 运行一次真实的代理聊天。需要可用的 live 模型 key（例如 ~/.profile 中的 OpenAI），会拉取外部 Open WebUI 镜像，并且不预期像普通 unit/e2e 套件一样在 CI 中稳定。
• pnpm test:docker:mcp-channels：启动一个已播种的 Gateway 网关容器和第二个客户端容器，后者会生成 openclaw mcp serve，然后验证路由后的对话发现、transcript 读取、附件 metadata、live event queue 行为、出站发送路由，以及通过真实 stdio bridge 发送的 Claude 风格 channel + permission notifications。Claude 通知断言会直接读取原始 stdio MCP 帧，因此该 smoke 反映 bridge 实际发出的内容。
• pnpm test:docker:upgrade-survivor：将打包后的 OpenClaw tarball 安装到脏的旧用户 fixture 上，运行软件包更新和非交互式 Doctor，不使用实时提供商或渠道密钥，然后启动一个环回 Gateway 网关，并检查智能体、渠道配置、插件允许列表、工作区/会话文件、陈旧的旧版插件依赖状态、启动和 RPC 状态是否保留下来。
• pnpm test:docker:published-upgrade-survivor：默认安装 openclaw@latest，填充不含实时提供商或渠道密钥的真实既有用户文件，使用内置的 openclaw config set 命令配方配置该基线，将该已发布安装更新到打包后的 OpenClaw tarball，运行非交互式 Doctor，写入 .artifacts/upgrade-survivor/summary.json，然后启动一个环回 Gateway 网关，并检查已配置的意图、工作区/会话文件、陈旧的插件配置和旧版依赖状态、启动、/healthz、/readyz 以及 RPC 状态是否保留下来或被干净修复。使用 OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC 覆盖一个基线，使用 OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS 展开精确矩阵，例如 all-since-2026.4.23，或使用 OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues 添加场景 fixture；reported-issues 集合包含 configured-plugin-installs，用于验证已配置的外部 OpenClaw 插件会在升级期间自动安装，还包含 stale-source-plugin-shadow，用于防止仅源码插件影子破坏启动。Package Acceptance 将这些暴露为 published_upgrade_survivor_baseline、published_upgrade_survivor_baselines 和 published_upgrade_survivor_scenarios。
• pnpm test:docker:update-migration：在清理较重的 plugin-deps-cleanup 场景中运行已发布升级幸存者 harness，默认从 openclaw@2026.4.23 开始。单独的“更新迁移”工作流会用 baselines=all-since-2026.4.23 展开此 lane，使从 .23 起的每个稳定已发布软件包都更新到候选版本，并在完整发布 CI 之外证明已配置插件的依赖清理。
• pnpm test:docker:plugins：针对本地路径、file:、带提升依赖的 npm registry 软件包、git 移动引用、ClawHub fixture、marketplace 更新，以及 Claude bundle 启用/检查运行安装/更新 smoke。

​

本地 PR 门禁

• pnpm check:changed
• pnpm check
• pnpm check:test-types
• pnpm build
• pnpm test
• pnpm check:docs

• OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
• OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed

​

模型延迟基准测试（本地密钥）

• source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10
• 可选环境变量：MINIMAX_API_KEY、MINIMAX_BASE_URL、MINIMAX_MODEL、ANTHROPIC_API_KEY
• 默认提示词：“只回复一个单词：ok。不要标点或额外文本。”

• minimax 中位数 1279ms（最小 1114，最大 2431）
• opus 中位数 2454ms（最小 1224，最大 3170）

​

CLI 启动基准测试

• pnpm test:startup:bench
• pnpm test:startup:bench:smoke
• pnpm test:startup:bench:save
• pnpm test:startup:bench:update
• pnpm test:startup:bench:check
• pnpm tsx scripts/bench-cli-startup.ts
• pnpm tsx scripts/bench-cli-startup.ts --runs 12
• pnpm tsx scripts/bench-cli-startup.ts --preset real
• pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --case gatewayStatus --runs 3
• pnpm tsx scripts/bench-cli-startup.ts --preset real --case tasksJson --case tasksListJson --case tasksAuditJson --runs 3
• pnpm tsx scripts/bench-cli-startup.ts --entry openclaw.mjs --entry-secondary dist/entry.js --preset all
• pnpm tsx scripts/bench-cli-startup.ts --preset all --output .artifacts/cli-startup-bench-all.json
• pnpm tsx scripts/bench-cli-startup.ts --preset real --case gatewayStatusJson --output .artifacts/cli-startup-bench-smoke.json
• pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
• pnpm tsx scripts/bench-cli-startup.ts --json

• startup：--version、--help、health、health --json、status --json、status
• real：health、status、status --json、sessions、sessions --json、tasks --json、tasks list --json、tasks audit --json、agents list --json、gateway status、gateway status --json、gateway health --json、config get gateway.port
• all：两个预设

• pnpm test:startup:bench:smoke 将目标 smoke artifact 写入 .artifacts/cli-startup-bench-smoke.json
• pnpm test:startup:bench:save 使用 runs=5 和 warmup=1 将全套 artifact 写入 .artifacts/cli-startup-bench-all.json
• pnpm test:startup:bench:update 使用 runs=5 和 warmup=1 刷新已签入的基线 fixture：test/fixtures/cli-startup-bench.json

• test/fixtures/cli-startup-bench.json
• 使用 pnpm test:startup:bench:update 刷新
• 使用 pnpm test:startup:bench:check 将当前结果与 fixture 比较

​

新手引导 E2E（Docker）

scripts/e2e/onboard-docker.sh

​

QR 导入 smoke（Docker）

pnpm test:docker:qr

​

相关

• 测试
• 实时测试
• 更新和插件测试