CI 流水线

OpenClaw CI 在每次推送到 main 以及每个 pull request 上运行。preflight 作业会对 diff 分类，并在只有无关区域发生变更时关闭昂贵的 lane。手动 workflow_dispatch 运行会有意绕过智能范围限定，并为候选发布版本和广泛验证展开完整图。Android lane 通过 include_android 保持选择加入。仅发布使用的插件覆盖率位于单独的 Plugin Prerelease workflow 中，并且只会从 Full Release Validation 或显式手动 dispatch 运行。

流水线概览

作业	用途	运行时机
`preflight`	检测仅文档变更、变更范围、变更插件，并构建 CI 清单	始终在非 draft 推送和 PR 上运行
`security-scm-fast`	通过 `zizmor` 进行私钥检测和 workflow 审计	始终在非 draft 推送和 PR 上运行
`security-dependency-audit`	针对 npm 公告，对 production lockfile 进行无依赖审计	始终在非 draft 推送和 PR 上运行
`security-fast`	快速安全作业所需的聚合项	始终在非 draft 推送和 PR 上运行
`check-dependencies`	仅 production Knip 依赖检查，加上未使用文件 allowlist 守卫	Node 相关变更
`build-artifacts`	构建 `dist/`、Control UI、构建产物检查，以及可复用的下游产物	Node 相关变更
`checks-fast-core`	快速 Linux 正确性 lane，例如内置插件、插件契约和协议检查	Node 相关变更
`checks-fast-contracts-channels`	分片的渠道契约检查，并提供稳定的聚合检查结果	Node 相关变更
`checks-node-core-test`	Core Node 测试分片，排除渠道、内置、契约和插件 lane	Node 相关变更
`check`	分片的主要本地 gate 等价项：production 类型、lint、守卫、测试类型和严格 smoke	Node 相关变更
`check-additional`	架构、分片边界/提示词漂移、插件守卫、包边界和 Gateway 网关 watch	Node 相关变更
`build-smoke`	已构建 CLI smoke 测试和启动内存 smoke	Node 相关变更
`checks`	构建产物渠道测试的验证器	Node 相关变更
`checks-node-compat-node22`	Node 22 兼容性构建和 smoke lane	发布版手动 CI dispatch
`check-docs`	文档格式化、lint 和断链检查	文档变更
`skills-python`	Python 支撑的 Skills 的 Ruff + pytest	Python Skill 相关变更
`checks-windows`	Windows 专用进程/路径测试，加上共享运行时导入 specifier 回归检查	Windows 相关变更
`macos-node`	使用共享构建产物的 macOS TypeScript 测试 lane	macOS 相关变更
`macos-swift`	macOS 应用的 Swift lint、构建和测试	macOS 相关变更
`android`	两种 flavor 的 Android 单元测试，加上一个 debug APK 构建	Android 相关变更
`test-performance-agent`	可信活动之后的每日 Codex 慢测试优化	主 CI 成功或手动 dispatch
`openclaw-performance`	每日/按需的 Kova 运行时性能报告，包含 mock provider、deep profile 和 GPT 5.4 live lane	定时和手动 dispatch

快速失败顺序

preflight 决定哪些 lane 实际存在。docs-scope 和 changed-scope 逻辑是此作业内部的步骤，而不是独立作业。
security-scm-fast、security-dependency-audit、security-fast、check、check-additional、check-docs 和 skills-python 会快速失败，无需等待更重的产物和平台矩阵作业。
build-artifacts 与快速 Linux lane 重叠运行，使下游消费者可以在共享构建就绪后立即开始。
更重的平台和运行时 lane 随后展开：checks-fast-core、checks-fast-contracts-channels、checks-node-core-test、checks、checks-windows、macos-node、macos-swift 和 android。

当同一个 PR 或 main ref 上有更新的推送落地时，GitHub 可能会将被取代的作业标记为 cancelled。除非同一 ref 的最新运行也失败，否则应将其视为 CI 噪声。聚合分片检查使用 !cancelled() && always()，因此它们仍会报告正常的分片失败，但不会在整个 workflow 已被取代后继续排队。自动 CI 并发键带有版本号（CI-v7-*），因此 GitHub 侧旧队列组中的僵尸项不能无限期阻塞较新的 main 运行。手动全套件运行使用 CI-manual-v1-*，并且不会取消正在进行的运行。

范围和路由

范围逻辑位于 scripts/ci-changed-scope.mjs，并由 src/scripts/ci-changed-scope.test.ts 中的单元测试覆盖。手动 dispatch 会跳过 changed-scope 检测，并让 preflight 清单表现得像每个限定范围区域都发生了变更。

CI workflow 编辑会验证 Node CI 图和 workflow lint，但其本身不会强制运行 Windows、Android 或 macOS native 构建；这些平台 lane 仍限定在平台源代码变更上。
仅 CI 路由编辑、选定的廉价 core-test fixture 编辑，以及窄范围插件契约 helper/test-routing 编辑使用快速 Node-only 清单路径：preflight、security 和单个 checks-fast-core 任务。当变更仅限于快速任务直接覆盖的路由或 helper 表面时，该路径会跳过构建产物、Node 22 兼容性、渠道契约、完整 core 分片、内置插件分片和额外守卫矩阵。
Windows Node 检查限定在 Windows 专用进程/路径 wrapper、npm/pnpm/UI runner helper、包管理器配置，以及执行该 lane 的 CI workflow 表面；无关源代码、插件、install-smoke 和仅测试变更会留在 Linux Node lane 上。

最慢的 Node 测试族会被拆分或均衡，使每个作业保持较小规模而不过度预留 runner：渠道契约作为三个加权分片运行，core unit fast/support lane 单独运行，core runtime infra 在 state 和 process/config 分片之间拆分，auto-reply 作为均衡 worker 运行（reply 子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片），agentic gateway/server 配置则拆分到 chat/auth/model/http-plugin/runtime/startup lane 中，而不是等待构建产物。广泛的浏览器、QA、媒体和杂项插件测试使用其专用 Vitest 配置，而不是共享插件 catch-all。Include-pattern 分片使用 CI 分片名称记录计时条目，因此 .artifacts/vitest-shard-timings.json 可以区分完整配置和过滤后的分片。check-additional 将 package-boundary compile/canary 工作保持在一起，并将运行时拓扑架构与 Gateway 网关 watch 覆盖率分开；边界守卫列表按四个矩阵分片条带化，每个分片并发运行选定的独立守卫并打印每项检查的计时，包括 pnpm prompt:snapshots:check，这样 Codex 运行时 happy-path 提示词漂移会被钉在造成它的 PR 上。Gateway 网关 watch、渠道测试和 core support-boundary 分片会在 dist/ 和 dist-runtime/ 已构建完成后，在 build-artifacts 内部并发运行。 Android CI 会运行 testPlayDebugUnitTest 和 testThirdPartyDebugUnitTest，随后构建 Play debug APK。third-party flavor 没有单独的 source set 或 manifest；它的单元测试 lane 仍会使用 SMS/call-log BuildConfig flag 编译该 flavor，同时避免在每次 Android 相关推送上重复执行 debug APK 打包作业。 check-dependencies 分片运行 pnpm deadcode:dependencies（仅 production Knip 依赖检查，固定到最新 Knip 版本，并在 dlx 安装中禁用 pnpm 的最低发布年龄限制）和 pnpm deadcode:unused-files，后者会将 Knip 的 production 未使用文件发现与 scripts/deadcode-unused-files.allowlist.mjs 进行比较。当 PR 添加新的未经审查的未使用文件，或留下陈旧 allowlist 条目时，未使用文件守卫会失败，同时保留 Knip 无法静态解析的有意动态插件、生成内容、构建、live-test 和包 bridge 表面。

ClawSweeper 活动转发

.github/workflows/clawsweeper-dispatch.yml 是从 OpenClaw 仓库活动到 ClawSweeper 的目标侧 bridge。它不会 checkout 或执行不可信的 pull request 代码。该 workflow 会从 CLAWSWEEPER_APP_PRIVATE_KEY 创建 GitHub App token，然后向 openclaw/clawsweeper dispatch 紧凑的 repository_dispatch payload。该 workflow 有四个 lane：

clawsweeper_item 用于精确 issue 和 pull request review 请求；
clawsweeper_comment 用于 issue comment 中显式的 ClawSweeper 命令；
clawsweeper_commit_review 用于 main 推送上的 commit 级 review 请求；
github_activity 用于 ClawSweeper agent 可能检查的一般 GitHub 活动。

github_activity lane 只转发规范化元数据：事件类型、action、actor、仓库、item 编号、URL、标题、状态，以及存在 comment 或 review 时的简短摘录。它有意避免转发完整 webhook body。openclaw/clawsweeper 中接收方 workflow 是 .github/workflows/github-activity.yml，它会将规范化事件发布到 ClawSweeper agent 的 OpenClaw Gateway 网关 hook。一般活动是观察，而不是默认投递。ClawSweeper agent 会在其提示词中接收 Discord 目标，并且只有在事件令人意外、可行动、有风险或具有运维用途时才应发布到 #clawsweeper。常规打开、编辑、bot churn、重复 webhook 噪声和正常 review 流量应产生 NO_REPLY。在整个路径中，将 GitHub 标题、comment、body、review 文本、分支名称和 commit message 视为不可信数据。它们是摘要和分流的输入，不是 workflow 或 agent 运行时的指令。

手动 dispatch

手动 CI 调度运行与普通 CI 相同的作业图，但会强制开启所有非 Android 作用域的 lane：Linux Node 分片、内置插件分片、渠道合约、Node 22 兼容性、check、check-additional、构建 smoke、文档检查、Python Skills、Windows、macOS 和 Control UI i18n。独立的手动 CI 调度仅在 include_android=true 时运行 Android；完整发布总控通过传入 include_android=true 启用 Android。插件预发布静态检查、仅发布用的 agentic-plugins 分片、完整扩展批量 sweep，以及插件预发布 Docker lane 均不包含在 CI 中。Docker 预发布套件仅在 Full Release Validation 以启用发布验证 gate 的方式调度单独的 Plugin Prerelease 工作流时运行。手动运行使用唯一的并发组，因此候选发布版本的完整套件不会被同一 ref 上的其他 push 或 PR 运行取消。可选的 target_ref 输入允许受信任调用方在使用所选调度 ref 中的工作流文件时，针对分支、标签或完整提交 SHA 运行该作业图。

gh workflow run ci.yml --ref release/YYYY.M.D
gh workflow run ci.yml --ref main -f target_ref=<branch-or-sha> -f include_android=true
gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>

运行器

运行器	作业
`ubuntu-24.04`	`preflight`，快速安全作业和聚合（`security-scm-fast`、`security-dependency-audit`、`security-fast`），快速协议/合约/内置检查，分片渠道合约检查，除 lint 外的 `check` 分片，`check-additional` 分片和聚合，Node 测试聚合验证器，文档检查，Python Skills，workflow-sanity，labeler，auto-response；install-smoke preflight 也使用 GitHub 托管的 Ubuntu，以便 Blacksmith 矩阵可以更早排队
`blacksmith-4vcpu-ubuntu-2404`	`CodeQL Critical Quality`、较低权重的扩展分片、`checks-fast-core`、`checks-node-compat-node22`、`check-prod-types` 和 `check-test-types`
`blacksmith-8vcpu-ubuntu-2404`	`build-artifacts`、build-smoke、Linux Node 测试分片、内置插件测试分片、`android`
`blacksmith-16vcpu-ubuntu-2404`	`check-lint`（对 CPU 足够敏感，8 vCPU 的成本高于节省的时间）；install-smoke Docker 构建（32 vCPU 的排队时间成本高于节省的时间）
`blacksmith-16vcpu-windows-2025`	`checks-windows`
`blacksmith-6vcpu-macos-latest`	`openclaw/openclaw` 上的 `macos-node`；fork 回退到 `macos-latest`
`blacksmith-12vcpu-macos-latest`	`openclaw/openclaw` 上的 `macos-swift`；fork 回退到 `macos-latest`

本地等价命令

pnpm changed:lanes                            # inspect the local changed-lane classifier for origin/main...HEAD
pnpm check:changed                            # smart local check gate: changed typecheck/lint/guards by boundary lane
pnpm check                                    # fast local gate: prod tsgo + sharded lint + parallel fast guards
pnpm check:test-types
pnpm check:timed                              # same gate with per-stage timings
pnpm build:strict-smoke
pnpm check:architecture
pnpm test:gateway:watch-regression
pnpm test                                     # vitest tests
pnpm test:changed                             # cheap smart changed Vitest targets
pnpm test:channels
pnpm test:contracts:channels
pnpm check:docs                               # docs format + lint + broken links
pnpm build                                    # build dist when CI artifact/build-smoke lanes matter
pnpm ci:timings                               # summarize the latest origin/main push CI run
pnpm ci:timings:recent                        # compare recent successful main CI runs
node scripts/ci-run-timings.mjs <run-id>      # summarize wall time, queue time, and slowest jobs
node scripts/ci-run-timings.mjs --latest-main # ignore issue/comment noise and choose origin/main push CI
node scripts/ci-run-timings.mjs --recent 10   # compare recent successful main CI runs
pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json
pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json
pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.json --output .artifacts/kova/summary.md

OpenClaw 性能

OpenClaw Performance 是产品/运行时性能工作流。它每天在 main 上运行，也可以手动调度：

gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3
gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1 -f deep_profile=true -f live_gpt54=true
gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3

手动调度通常会对工作流 ref 进行基准测试。设置 target_ref 可使用当前工作流实现对发布标签或其他分支进行基准测试。已发布的报告路径和 latest 指针按被测试的 ref 编码，每个 index.md 都记录被测试的 ref/SHA、工作流 ref/SHA、Kova ref、profile、lane 认证模式、模型、重复次数和场景过滤器。该工作流从固定发布版本安装 OCM，并从 openclaw/Kova 的固定 kova_ref 输入安装 Kova，然后运行三个 lane：

mock-provider：使用确定性的伪 OpenAI 兼容认证，针对本地构建运行时运行 Kova 诊断场景。
mock-deep-profile：针对启动、Gateway 网关和智能体轮次热点进行 CPU/堆/trace profiling。
live-gpt54：真实的 OpenAI openai/gpt-5.4 智能体轮次，在 OPENAI_API_KEY 不可用时跳过。

mock-provider lane 还会在 Kova 通过后运行 OpenClaw 原生源码 probe：覆盖默认、hook 和 50 插件启动场景下的 Gateway 网关启动时间和内存；重复的模拟 OpenAI channel-chat-baseline hello 循环；以及针对已启动 Gateway 网关的 CLI 启动命令。源码 probe 的 Markdown 摘要位于报告包中的 source/index.md，旁边有原始 JSON。每个 lane 都会上传 GitHub artifacts。配置 CLAWGRIT_REPORTS_TOKEN 后，工作流还会将 report.json、report.md、包、index.md 和源码 probe artifacts 提交到 openclaw/clawgrit-reports 的 openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/ 下。当前被测试 ref 的指针会写为 openclaw-performance/<tested-ref>/latest-<lane>.json。

完整发布验证

Full Release Validation 是用于“发布前运行所有内容”的手动总控工作流。它接受分支、标签或完整提交 SHA，使用该目标调度手动 CI 工作流，调度 Plugin Prerelease 以提供仅发布用的插件/包/静态/Docker 证明，并调度 OpenClaw Release Checks 以运行安装 smoke、包验收、跨 OS 包检查、QA Lab parity、Matrix 和 Telegram lane。稳定版/默认运行会将详尽的 live/E2E 和 Docker 发布路径覆盖保留在 run_release_soak=true 后面；release_profile=full 会强制开启该 soak 覆盖，以便广泛的 advisory 验证保持广泛覆盖。使用 rerun_group=all 和 release_profile=full 时，它还会针对 release checks 生成的 release-package-under-test artifact 运行 NPM Telegram Beta E2E。发布后，传入 npm_telegram_package_spec 可针对已发布的 npm 包重新运行相同的 Telegram 包 lane。请参阅完整发布验证，了解阶段矩阵、确切的工作流作业名称、profile 差异、artifacts，以及聚焦重跑句柄。 OpenClaw Release Publish 是会产生变更的手动发布工作流。请在发布标签存在且 OpenClaw npm preflight 已成功后，从 release/YYYY.M.D 或 main 调度它。它会验证 pnpm plugins:sync:check，为所有可发布插件包调度 Plugin NPM Release，为同一发布 SHA 调度 Plugin ClawHub Release，然后才使用保存的 preflight_run_id 调度 OpenClaw NPM Release。

gh workflow run openclaw-release-publish.yml \
  --ref release/YYYY.M.D \
  -f tag=vYYYY.M.D-beta.N \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f npm_dist_tag=beta

对于快速移动分支上的固定提交证明，请使用 helper，而不是 gh workflow run ... --ref main -f ref=<sha>：

pnpm ci:full-release --sha <full-sha>

GitHub 工作流调度 ref 必须是分支或标签，不能是原始提交 SHA。该 helper 会在目标 SHA 上推送一个临时 release-ci/<sha>-... 分支，从该固定 ref 调度 Full Release Validation，验证每个子工作流的 headSha 都与目标匹配，并在运行完成后删除临时分支。如果任何子工作流在不同 SHA 上运行，总控验证器也会失败。 release_profile 控制传入发布检查的实时/提供商覆盖范围。手动发布工作流默认使用 stable；只有当你有意需要广泛的 advisory 提供商/媒体矩阵时，才使用 full。run_release_soak 控制 stable/default 发布检查是否运行详尽的实时/E2E 和 Docker 发布路径 soak；full 会强制启用 soak。

minimum 保留最快的 OpenAI/核心发布关键通道。
stable 添加 stable 提供商/后端集合。
full 运行广泛的 advisory 提供商/媒体矩阵。

总控工作流会记录已调度的子运行 ID，最终的 Verify full validation 作业会重新检查当前子运行结论，并为每个子运行追加最慢作业表。如果某个子工作流被重新运行并转为绿色，只需重新运行父级 verifier 作业，即可刷新总控结果和耗时摘要。对于恢复，Full Release Validation 和 OpenClaw Release Checks 都接受 rerun_group。发布候选版本使用 all，仅普通完整 CI 子项使用 ci，仅插件预发布子项使用 plugin-prerelease，每个发布子项使用 release-checks，或在总控工作流上使用更窄的组：install-smoke、cross-os、live-e2e、package、qa、qa-parity、qa-live 或 npm-telegram。这样可以在做出聚焦修复后，将失败发布盒子的重新运行范围保持有界。对于单个失败的跨 OS 通道，将 rerun_group=cross-os 与 cross_os_suite_filter 组合使用，例如 windows/packaged-upgrade；长时间运行的跨 OS 命令会发出 heartbeat 行，packaged-upgrade 摘要会包含每阶段耗时。QA 发布检查通道是 advisory，因此仅 QA 失败会发出警告，但不会阻止发布检查 verifier。 OpenClaw Release Checks 使用受信任的工作流 ref，将所选 ref 一次解析为 release-package-under-test tarball，然后把该 artifact 传给跨 OS 检查和软件包验收，以及在运行 soak 覆盖时传给实时/E2E 发布路径 Docker 工作流。这样可以让发布盒子之间的软件包字节保持一致，并避免在多个子作业中重新打包同一个候选版本。 ref=main 和 rerun_group=all 的重复 Full Release Validation 运行会取代较旧的总控工作流。当父级被取消时，父级监控器会取消它已经调度的任何子工作流，因此较新的 main 验证不会卡在陈旧的两小时发布检查运行之后。发布分支/标签验证和聚焦重新运行组会保持 cancel-in-progress: false。

实时和 E2E 分片

发布实时/E2E 子项保留广泛的原生 pnpm test:live 覆盖，但它通过 scripts/test-live-shard.mjs 以命名分片运行，而不是作为一个串行作业运行：

native-live-src-agents
native-live-src-gateway-core
提供商过滤的 native-live-src-gateway-profiles 作业
native-live-src-gateway-backends
native-live-test
native-live-extensions-a-k
native-live-extensions-l-n
native-live-extensions-openai
native-live-extensions-o-z-other
native-live-extensions-xai
拆分的媒体音频/视频分片和提供商过滤的音乐分片

这样既保持相同的文件覆盖，又让缓慢的实时提供商失败更容易重新运行和诊断。聚合的 native-live-extensions-o-z、native-live-extensions-media 和 native-live-extensions-media-music 分片名称仍然可用于手动一次性重新运行。原生实时媒体分片在 ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04 中运行，该镜像由 Live Media Runner Image 工作流构建。该镜像预安装了 ffmpeg 和 ffprobe；媒体作业只会在设置前验证这些二进制文件。将 Docker 支持的实时套件保留在普通 Blacksmith runner 上运行——容器作业并不适合启动嵌套 Docker 测试。 Docker 支持的实时模型/后端分片会为每个所选 commit 使用单独的共享 ghcr.io/openclaw/openclaw-live-test:<sha> 镜像。实时发布工作流会构建并推送该镜像一次，然后 Docker 实时模型、按提供商分片的 Gateway 网关、CLI 后端、ACP bind 和 Codex harness 分片会以 OPENCLAW_SKIP_DOCKER_BUILD=1 运行。Gateway 网关 Docker 分片带有明确的脚本级 timeout 上限，低于工作流作业超时，因此卡住的容器或清理路径会快速失败，而不是消耗整个发布检查预算。如果这些分片独立重新构建完整源 Docker 目标，则说明发布运行配置错误，并会在重复镜像构建上浪费实际耗时。

软件包验收

当问题是“这个可安装的 OpenClaw 软件包作为产品能否工作？”时，使用 Package Acceptance。它不同于普通 CI：普通 CI 验证源代码树，而软件包验收会通过用户在安装或更新后实际使用的同一个 Docker E2E harness 验证单个 tarball。

作业

resolve_package 检出 workflow_ref，解析一个软件包候选，写入 .artifacts/docker-e2e-package/openclaw-current.tgz，写入 .artifacts/docker-e2e-package/package-candidate.json，将两者作为 package-under-test artifact 上传，并在 GitHub 步骤摘要中打印来源、工作流 ref、软件包 ref、版本、SHA-256 和 profile。
docker_acceptance 以 ref=workflow_ref 和 package_artifact_name=package-under-test 调用 openclaw-live-and-e2e-checks-reusable.yml。可复用工作流会下载该 artifact，验证 tarball inventory，在需要时准备 package-digest Docker 镜像，并针对该软件包运行所选 Docker 通道，而不是打包工作流检出内容。当某个 profile 选择多个目标 docker_lanes 时，可复用工作流会准备一次软件包和共享镜像，然后将这些通道扇出为并行的目标 Docker 作业，并使用唯一 artifact。
package_telegram 可选调用 NPM Telegram Beta E2E。当 telegram_mode 不是 none 时运行，并且在软件包验收解析出 package-under-test artifact 时安装同一个 artifact；独立 Telegram 调度仍然可以安装已发布的 npm spec。
如果软件包解析、Docker 验收或可选 Telegram 通道失败，summary 会使工作流失败。

候选来源

source=npm 只接受 openclaw@beta、openclaw@latest，或精确的 OpenClaw 发布版本，例如 openclaw@2026.4.27-beta.2。将它用于已发布预发布版/stable 版验收。
source=ref 打包受信任的 package_ref 分支、标签或完整 commit SHA。解析器会获取 OpenClaw 分支/标签，验证所选 commit 可从仓库分支历史或发布标签到达，在 detached worktree 中安装依赖，并使用 scripts/package-openclaw-for-docker.mjs 打包。
source=url 下载 HTTPS .tgz；必须提供 package_sha256。
source=artifact 从 artifact_run_id 和 artifact_name 下载一个 .tgz；package_sha256 是可选的，但对于外部共享的 artifact 应提供。

保持 workflow_ref 和 package_ref 分离。workflow_ref 是运行测试的受信任工作流/harness 代码。package_ref 是在 source=ref 时被打包的源 commit。这样当前测试 harness 就能验证较旧的受信任源 commit，而无需运行旧工作流逻辑。

套件 profile

smoke — npm-onboard-channel-agent、gateway-network、config-reload
package — npm-onboard-channel-agent、doctor-switch、update-channel-switch、upgrade-survivor、published-upgrade-survivor、plugins-offline、plugin-update
product — package 加上 mcp-channels、cron-mcp-cleanup、openai-web-search-minimal、openwebui
full — 带 OpenWebUI 的完整 Docker 发布路径分块
custom — 精确的 docker_lanes；当 suite_profile=custom 时必需

package profile 使用离线插件覆盖，因此已发布软件包验证不会受实时 ClawHub 可用性阻塞。可选 Telegram 通道会在 NPM Telegram Beta E2E 中复用 package-under-test artifact，并为独立调度保留已发布 npm spec 路径。有关专用更新和插件测试策略，包括本地命令、Docker 通道、软件包验收输入、发布默认值和失败分流，请参阅更新和插件测试。发布检查会使用 source=artifact、准备好的发布软件包 artifact、suite_profile=custom、

docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'

和 telegram_mode=mock-openai 调用软件包验收。这样可以在同一个已解析的软件包 tarball 上完成软件包迁移、更新、陈旧插件依赖清理、已配置插件安装修复、离线插件、插件更新和 Telegram 证明。设置 Full Release Validation 或 OpenClaw Release Checks 上的 package_acceptance_package_spec，即可针对已发布的 npm 软件包运行同一矩阵，而不是针对按 SHA 构建的 artifact。跨 OS 发布检查仍会覆盖特定 OS 的新手引导、安装器和平台行为；软件包/更新产品验证应从软件包验收开始。published-upgrade-survivor Docker 通道会在阻塞发布路径中为每次运行验证一个已发布软件包基线。在软件包验收中，已解析的 package-under-test tarball 始终是候选版本，published_upgrade_survivor_baseline 选择 fallback 已发布基线，默认值为 openclaw@latest；失败通道重新运行命令会保留该基线。带有 run_release_soak=true 或 release_profile=full 的 Full Release Validation 会设置 published_upgrade_survivor_baselines='last-stable-4 2026.4.23 2026.5.2 2026.4.15' 和 published_upgrade_survivor_scenarios=reported-issues，以扩展到最新四个 stable npm 版本、固定的插件兼容性边界版本，以及针对 Feishu 配置、保留的 bootstrap/persona 文件、已配置 OpenClaw 插件安装、波浪号日志路径和陈旧旧版插件依赖根的问题形态 fixture。多基线 published-upgrade survivor 选择会按基线分片到单独的目标 Docker runner 作业中。单独的 Update Migration 工作流在问题是详尽的已发布更新清理，而不是普通 Full Release CI 覆盖范围时，使用 update-migration Docker 通道以及 all-since-2026.4.23 和 plugin-deps-cleanup。本地聚合运行可以使用 OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS 传入精确软件包 spec，使用 OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC 保留单个通道，例如 openclaw@2026.4.15，或设置 OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS 以运行场景矩阵。已发布通道会用内置的 openclaw config set 命令 recipe 配置基线，在 summary.json 中记录 recipe 步骤，并在 Gateway 网关启动后探测 /healthz、/readyz 以及 RPC status。Windows packaged 和 installer fresh 通道还会验证已安装软件包能否从原始绝对 Windows 路径导入 browser-control override。OpenAI 跨 OS agent-turn smoke 会在设置时默认使用 OPENCLAW_CROSS_OS_OPENAI_MODEL，否则使用 openai/gpt-5.4，因此安装和 Gateway 网关证明会停留在 GPT-5 测试模型上，同时避免 GPT-4.x 默认值。

旧版兼容窗口

软件包验收为已经发布的软件包提供有界的旧版兼容窗口。直到 2026.4.25 的软件包，包括 2026.4.25-beta.*，都可以使用兼容路径：

dist/postinstall-inventory.json 中已知的私有 QA 条目可能指向 tarball 中省略的文件；
当软件包未暴露 gateway install --wrapper 标志时，doctor-switch 可以跳过其持久化子用例；
update-channel-switch 可以从 tarball 派生的伪 git fixture 中修剪缺失的 pnpm.patchedDependencies，并且可以记录缺失的持久化 update.channel；
插件 smoke 可以读取旧版安装记录位置，或接受缺失的 marketplace 安装记录持久化；
plugin-update 可以允许配置元数据迁移，同时仍要求安装记录和无重新安装行为保持不变。

已发布的 2026.4.26 包也可能会对已经发布的本地构建元数据戳文件发出警告。后续包必须满足现代契约；相同条件会失败，而不是警告或跳过。

示例

# Validate the current beta package with product-level coverage.
gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=npm \
  -f package_spec=openclaw@beta \
  -f suite_profile=product \
  -f telegram_mode=mock-openai

# Pack and validate a release branch with the current harness.
gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=ref \
  -f package_ref=release/YYYY.M.D \
  -f suite_profile=package \
  -f telegram_mode=mock-openai

# Validate a tarball URL. SHA-256 is mandatory for source=url.
gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=url \
  -f package_url=https://example.com/openclaw-current.tgz \
  -f package_sha256=<64-char-sha256> \
  -f suite_profile=smoke

# Reuse a tarball uploaded by another Actions run.
gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=artifact \
  -f artifact_run_id=<run-id> \
  -f artifact_name=package-under-test \
  -f suite_profile=custom \
  -f docker_lanes='install-e2e plugin-update'

调试失败的包验收运行时，先查看 resolve_package 摘要，确认包来源、版本和 SHA-256。然后检查 docker_acceptance 子运行及其 Docker 工件：.artifacts/docker-tests/**/summary.json、failures.json、lane 日志、阶段耗时和重新运行命令。优先重新运行失败的包配置文件或精确的 Docker lane，而不是重新运行完整发布验证。

安装冒烟测试

独立的 Install Smoke 工作流通过自己的 preflight 作业复用同一个范围脚本。它将冒烟覆盖拆分为 run_fast_install_smoke 和 run_full_install_smoke。

快速路径会在 pull request 触及 Docker/包表面、内置插件包/清单变更，或 Docker 冒烟作业会覆盖的核心插件/渠道/Gateway 网关/插件 SDK 表面时运行。仅源码的内置插件变更、仅测试编辑和仅文档编辑不会预留 Docker worker。快速路径会构建一次根 Dockerfile 镜像、检查 CLI、运行 agents delete shared-workspace CLI 冒烟测试、运行容器 Gateway 网关网络 e2e、验证内置扩展构建参数，并在 240 秒聚合命令超时内运行有界的内置插件 Docker 配置文件（每个场景的 Docker 运行单独设置上限）。
完整路径保留 QR 包安装以及安装器 Docker/更新覆盖，用于夜间定时运行、手动分发、workflow-call 发布检查，以及真正触及安装器/包/Docker 表面的 pull request。在完整模式下，install-smoke 会准备或复用一个目标 SHA GHCR 根 Dockerfile 冒烟镜像，然后将 QR 包安装、根 Dockerfile/Gateway 网关冒烟、安装器/更新冒烟，以及快速内置插件 Docker E2E 作为独立作业运行，这样安装器工作就不会被根镜像冒烟阻塞。

main 推送（包括合并提交）不会强制使用完整路径；当变更范围逻辑会在推送上请求完整覆盖时，工作流会保留快速 Docker 冒烟，并将完整安装冒烟留给夜间或发布验证。较慢的 Bun 全局安装 image-provider 冒烟由 run_bun_global_install_smoke 单独控制。它会在夜间计划和发布检查工作流中运行，手动 Install Smoke 分发也可以选择加入，但 pull request 和 main 推送不会运行它。QR 和安装器 Docker 测试保留各自专注于安装的 Dockerfile。

本地 Docker E2E

pnpm test:docker:all 会预构建一个共享 live-test 镜像，将 OpenClaw 打包一次为 npm tarball，并构建两个共享 scripts/e2e/Dockerfile 镜像：

用于安装器/更新/插件依赖 lane 的裸 Node/Git runner；
一个功能镜像，会将同一个 tarball 安装到 /app 中，用于普通功能 lane。

Docker lane 定义位于 scripts/lib/docker-e2e-scenarios.mjs，规划器逻辑位于 scripts/lib/docker-e2e-plan.mjs，runner 只执行选中的计划。调度器通过 OPENCLAW_DOCKER_E2E_BARE_IMAGE 和 OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE 为每个 lane 选择镜像，然后使用 OPENCLAW_SKIP_DOCKER_BUILD=1 运行 lane。

可调项

变量	默认值	用途
`OPENCLAW_DOCKER_ALL_PARALLELISM`	10	普通 lane 的主池槽位数。
`OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`	10	提供商敏感的尾池槽位数。
`OPENCLAW_DOCKER_ALL_LIVE_LIMIT`	9	并发 live lane 上限，避免提供商限流。
`OPENCLAW_DOCKER_ALL_NPM_LIMIT`	10	并发 npm install lane 上限。
`OPENCLAW_DOCKER_ALL_SERVICE_LIMIT`	7	并发多服务 lane 上限。
`OPENCLAW_DOCKER_ALL_START_STAGGER_MS`	2000	lane 启动之间的错峰时间，避免 Docker 守护进程创建风暴；设为 `0` 表示不做错峰。
`OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`	7200000	每个 lane 的兜底超时（120 分钟）；选定的 live/tail lane 使用更严格的上限。
`OPENCLAW_DOCKER_ALL_DRY_RUN`	unset	`1` 会打印调度器计划，而不运行 lane。
`OPENCLAW_DOCKER_ALL_LANES`	unset	逗号分隔的精确 lane 列表；跳过清理冒烟，以便智能体可以复现一个失败 lane。

比有效上限更重的 lane 仍然可以从空池启动，然后独占运行，直到释放容量。本地聚合会预检 Docker、移除陈旧的 OpenClaw E2E 容器、输出活跃 lane 状态、持久化 lane 耗时以便按最长优先排序，并且默认在第一次失败后停止调度新的池化 lane。

可复用 live/E2E 工作流

可复用 live/E2E 工作流会询问 scripts/test-docker-all.mjs --plan-json 需要哪些包、镜像类型、live 镜像、lane 和凭证覆盖。随后 scripts/docker-e2e.mjs 会将该计划转换为 GitHub 输出和摘要。它会通过 scripts/package-openclaw-for-docker.mjs 打包 OpenClaw、下载当前运行的包工件，或从 package_artifact_run_id 下载包工件；验证 tarball 清单；在计划需要已安装包的 lane 时，通过 Blacksmith 的 Docker 层缓存构建并推送带包摘要标签的裸/功能 GHCR Docker E2E 镜像；并复用提供的 docker_e2e_bare_image/docker_e2e_functional_image 输入或现有的包摘要镜像，而不是重新构建。Docker 镜像拉取会使用有界的每次 180 秒超时进行重试，因此卡住的 registry/cache 流会快速重试，而不是消耗 CI 关键路径的大部分时间。

发布路径分块

发布 Docker 覆盖使用较小的分块作业并设置 OPENCLAW_SKIP_DOCKER_BUILD=1，这样每个分块只拉取自己需要的镜像类型，并通过同一个加权调度器执行多个 lane：

OPENCLAW_DOCKER_ALL_PROFILE=release-path
OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h

当前发布 Docker 分块为 core、package-update-openai、package-update-anthropic、package-update-core、plugins-runtime-plugins、plugins-runtime-services，以及从 plugins-runtime-install-a 到 plugins-runtime-install-h。plugins-runtime-core、plugins-runtime 和 plugins-integrations 仍然是聚合的插件/运行时别名。install-e2e lane 别名仍然是两个提供商安装器 lane 的聚合手动重跑别名。当完整发布路径覆盖请求 OpenWebUI 时，它会被并入 plugins-runtime-services，并且只为仅 OpenWebUI 分发保留独立的 openwebui 分块。内置渠道更新 lane 会针对临时 npm 网络故障重试一次。每个分块都会上传 .artifacts/docker-tests/，其中包含 lane 日志、耗时、summary.json、failures.json、阶段耗时、调度器计划 JSON、慢 lane 表和每 lane 重新运行命令。工作流 docker_lanes 输入会针对准备好的镜像运行选定 lane，而不是运行分块作业，这会将失败 lane 调试限制在一个目标 Docker 作业内，并为该运行准备、下载或复用包工件；如果选定 lane 是 live Docker lane，目标作业会为该次重跑在本地构建 live-test 镜像。生成的每 lane GitHub 重新运行命令会在这些值存在时包含 package_artifact_run_id、package_artifact_name 和准备好的镜像输入，因此失败的 lane 可以复用失败运行中的精确包和镜像。

pnpm test:docker:rerun <run-id>      # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary>   # slow-lane and phase critical-path summaries

计划的 live/E2E 工作流每天运行完整发布路径 Docker 套件。

插件预发布

Plugin Prerelease 是成本更高的产品/包覆盖，因此它是一个由 Full Release Validation 或显式操作员分发的独立工作流。普通 pull request、main 推送和独立手动 CI 分发会保持该套件关闭。它会在八个扩展 worker 之间平衡内置插件测试；这些扩展分片作业一次最多运行两个插件配置组，每组使用一个 Vitest worker 和更大的 Node 堆，这样导入密集的插件批次就不会创建额外 CI 作业。仅发布的 Docker 预发布路径会以小组批处理目标 Docker lane，避免为一到三分钟的作业预留数十个 runner。

QA Lab

QA Lab 在主智能范围工作流之外有专用 CI lane。Agentic parity 嵌套在宽泛 QA 和发布 harness 之下，而不是独立的 PR 工作流。当 parity 应随宽泛验证运行一起执行时，使用 Full Release Validation 并设置 rerun_group=qa-parity。

QA-Lab - All Lanes 工作流每晚在 main 上运行，也可手动分发；它会将 mock parity lane、live Matrix lane，以及 live Telegram 和 Discord lane 扇出为并行作业。live 作业使用 qa-live-shared 环境，Telegram/Discord 使用 Convex 租约。

发布检查会使用确定性的 mock 提供商和 mock 限定模型（mock-openai/gpt-5.5 和 mock-openai/gpt-5.5-alt）运行 Matrix 和 Telegram live 传输 lane，这样渠道契约就与 live 模型延迟和普通提供商插件启动隔离。live 传输 Gateway 网关会禁用记忆搜索，因为 QA parity 单独覆盖记忆行为；提供商连通性由独立的 live 模型、原生提供商和 Docker 提供商套件覆盖。 Matrix 在计划和发布 gate 中使用 --profile fast，仅当检出的 CLI 支持时才添加 --fail-fast。CLI 默认值和手动工作流输入仍为 all；手动 matrix_profile=all 分发始终会将完整 Matrix 覆盖分片为 transport、media、e2ee-smoke、e2ee-deep 和 e2ee-cli 作业。 OpenClaw Release Checks 也会在发布批准前运行发布关键的 QA Lab lane；其 QA parity gate 会将候选包和基线包作为并行 lane 作业运行，然后把两个工件下载到一个小型报告作业中，用于最终 parity 对比。对于普通 PR，遵循有范围限定的 CI/检查证据，而不是将 parity 视为必需状态。

CodeQL

CodeQL 工作流有意作为一个范围较窄的第一轮安全扫描器，而不是完整的仓库扫描。每日、手动以及非草稿拉取请求保护运行会扫描 Actions 工作流代码，以及风险最高的 JavaScript/TypeScript 范围，并使用高置信度安全查询，筛选出高/严重 security-severity。拉取请求保护保持轻量：它只会针对 .github/actions、.github/codeql、.github/workflows、packages 或 src 下的变更启动，并运行与定时工作流相同的高置信度安全矩阵。Android 和 macOS CodeQL 不包含在 PR 默认项中。

安全类别

类别	范围
`/codeql-security-high/core-auth-secrets`	认证、密钥、沙箱、cron 和 Gateway 网关基线
`/codeql-security-high/channel-runtime-boundary`	核心渠道实现契约，以及渠道插件运行时、Gateway 网关、插件 SDK、密钥、审计接触点
`/codeql-security-high/network-ssrf-boundary`	核心 SSRF、IP 解析、网络防护、web-fetch 和插件 SDK SSRF 策略范围
`/codeql-security-high/mcp-process-tool-boundary`	MCP 服务器、进程执行辅助工具、出站投递，以及智能体工具执行闸门
`/codeql-security-high/plugin-trust-boundary`	插件安装、加载器、清单、注册表、包管理器安装、源码加载，以及插件 SDK 包契约信任范围

平台特定安全分片

CodeQL Android Critical Security — 定时 Android 安全分片。在工作流完整性检查接受的最小 Blacksmith Linux runner 上手动构建 Android 应用以供 CodeQL 使用。上传到 /codeql-critical-security/android 下。
CodeQL macOS Critical Security — 每周/手动 macOS 安全分片。在 Blacksmith macOS 上手动构建 macOS 应用以供 CodeQL 使用，从上传的 SARIF 中过滤掉依赖构建结果，并上传到 /codeql-critical-security/macos 下。它保留在每日默认项之外，因为即使结果干净，macOS 构建也会主导运行时间。

Critical Quality 类别

CodeQL Critical Quality 是对应的非安全分片。它在较小的 Blacksmith Linux runner 上，仅对范围较窄的高价值表面运行错误严重级别、非安全 JavaScript/TypeScript 质量查询。它的拉取请求保护有意小于定时配置：非草稿 PR 只会针对智能体命令/模型/工具执行和回复调度代码、配置 schema/迁移/IO 代码、认证/密钥/沙箱/安全代码、核心渠道和内置渠道插件运行时、Gateway 网关协议/服务器方法、memory 运行时/SDK 胶水层、MCP/进程/出站投递、提供商运行时/模型目录、会话诊断/投递队列、插件加载器、插件 SDK/包契约，或插件 SDK 回复运行时变更，运行匹配的 agent-runtime-boundary、config-boundary、core-auth-secrets、channel-runtime-boundary、gateway-runtime-boundary、memory-runtime-boundary、mcp-process-runtime-boundary、provider-runtime-boundary、session-diagnostics-boundary、plugin-boundary、plugin-sdk-package-contract 和 plugin-sdk-reply-runtime 分片。CodeQL 配置和质量工作流变更会运行全部十二个 PR 质量分片。手动调度接受：

profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary

窄配置是用于单独运行一个质量分片的教学/迭代钩子。

类别	范围
`/codeql-critical-quality/core-auth-secrets`	认证、密钥、沙箱、cron 和 Gateway 网关安全边界代码
`/codeql-critical-quality/config-boundary`	配置 schema、迁移、规范化和 IO 契约
`/codeql-critical-quality/gateway-runtime-boundary`	Gateway 网关协议 schema 和服务器方法契约
`/codeql-critical-quality/channel-runtime-boundary`	核心渠道和内置渠道插件实现契约
`/codeql-critical-quality/agent-runtime-boundary`	命令执行、模型/提供商调度、自动回复调度和队列，以及 ACP 控制平面运行时契约
`/codeql-critical-quality/mcp-process-runtime-boundary`	MCP 服务器和工具桥接、进程监督辅助工具，以及出站投递契约
`/codeql-critical-quality/memory-runtime-boundary`	Memory host SDK、memory 运行时 facade、memory 插件 SDK 别名、memory 运行时激活胶水层，以及 memory doctor 命令
`/codeql-critical-quality/session-diagnostics-boundary`	回复队列内部机制、会话投递队列、出站会话绑定/投递辅助工具、诊断事件/日志包范围，以及会话 doctor CLI 契约
`/codeql-critical-quality/plugin-sdk-reply-runtime`	插件 SDK 入站回复调度、回复载荷/分块/运行时辅助工具、渠道回复选项、投递队列，以及会话/thread 绑定辅助工具
`/codeql-critical-quality/provider-runtime-boundary`	模型目录规范化、提供商认证和设备发现、提供商运行时注册、提供商默认值/目录，以及 web/search/fetch/embedding 注册表
`/codeql-critical-quality/ui-control-plane`	Control UI 引导启动、本地持久化、Gateway 网关控制流，以及任务控制平面运行时契约
`/codeql-critical-quality/web-media-runtime-boundary`	核心 web fetch/search、媒体 IO、媒体理解、图像生成，以及媒体生成运行时契约
`/codeql-critical-quality/plugin-boundary`	加载器、注册表、公共表面，以及插件 SDK 入口点契约
`/codeql-critical-quality/plugin-sdk-package-contract`	已发布包侧插件 SDK 源码和插件包契约辅助工具

质量与安全保持分离，因此质量发现可以被定时、度量、禁用或扩展，而不会遮蔽安全信号。Swift、Python 和内置插件 CodeQL 扩展只应在窄配置具备稳定运行时间和信号之后，作为有范围限定或分片的后续工作加回。

维护工作流

Docs Agent

Docs Agent 工作流是一个事件驱动的 Codex 维护通道，用于让现有文档与最近落地的变更保持一致。它没有纯定时计划：main 上一次成功的非机器人 push CI 运行可以触发它，手动调度也可以直接运行它。当 main 已经前移，或者过去一小时内创建了另一个未跳过的 Docs Agent 运行时，workflow-run 调用会跳过。运行时，它会审查从上一个未跳过 Docs Agent 来源 SHA 到当前 main 的提交范围，因此每小时一次的运行可以覆盖自上次文档处理以来累计的所有 main 变更。

Test Performance Agent

Test Performance Agent 工作流是一个事件驱动的 Codex 维护通道，用于处理慢测试。它没有纯定时计划：main 上一次成功的非机器人 push CI 运行可以触发它，但如果当天 UTC 已经有另一个 workflow-run 调用运行过或正在运行，它会跳过。手动调度会绕过该每日活动闸门。该通道会构建完整测试套件分组 Vitest 性能报告，让 Codex 只做小规模、保持覆盖率的测试性能修复，而不是广泛重构，然后重新运行完整测试套件报告，并拒绝会降低通过基线测试数量的变更。如果基线存在失败测试，Codex 只能修复明显失败，并且 agent 后的完整测试套件报告必须通过后才能提交任何内容。当 main 在机器人 push 落地前前移时，该通道会 rebase 已验证的补丁，重新运行 pnpm check:changed，并重试 push；有冲突的过期补丁会被跳过。它使用 GitHub 托管的 Ubuntu，因此 Codex action 可以保持与 docs agent 相同的 drop-sudo 安全姿态。

合并后的重复 PR

Duplicate PRs After Merge 工作流是一个手动维护者工作流，用于落地后的重复项清理。它默认 dry-run，并且只有在 apply=true 时才关闭明确列出的 PR。在修改 GitHub 之前，它会验证已落地的 PR 已合并，并且每个重复 PR 要么共享被引用的问题，要么存在重叠的变更 hunk。

gh workflow run duplicate-after-merge.yml \
  -f landed_pr=70532 \
  -f duplicate_prs='70530,70592' \
  -f apply=true

本地检查闸门和变更路由

本地 changed-lane 逻辑位于 scripts/changed-lanes.mjs，并由 scripts/check-changed.mjs 执行。这个本地检查闸门在架构边界上比广泛的 CI 平台范围更严格：

核心生产变更会运行核心生产和核心测试类型检查，以及核心 lint/guard；
仅核心测试变更只会运行核心测试类型检查和核心 lint；
插件生产变更会运行插件生产和插件测试类型检查，以及插件 lint；
仅插件测试变更会运行插件测试类型检查和插件 lint；
公共插件 SDK 或插件契约变更会扩展到插件类型检查，因为插件依赖这些核心契约（Vitest 插件扫描仍然是显式测试工作）；
仅发布元数据的版本 bump 会运行有针对性的版本/配置/根依赖检查；
未知的 root/配置变更会故障安全地进入全部检查通道。

本地 changed-test 路由位于 scripts/test-projects.test-support.mjs，并且有意比 check:changed 更便宜：直接测试编辑会运行自身，源码编辑优先使用显式映射，然后运行同级测试和导入图依赖项。共享 group-room 投递配置是显式映射之一：对 group visible-reply 配置、源码回复投递模式或 message-tool 系统提示词的变更，会路由到核心回复测试，以及 Discord 和 Slack 投递回归测试，因此共享默认值变更会在第一次 PR push 之前失败。只有当变更影响范围足够覆盖整个 harness，以至于廉价映射集合不是可信代理时，才使用 OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed。

Testbox 验证

从仓库根目录运行 Testbox，并优先为广泛验证使用全新预热的 box。在一个被复用、已过期，或刚刚报告了意外大规模同步的 box 上运行耗时检查前，先在 box 内运行 pnpm testbox:sanity。当 pnpm-lock.yaml 等必需的根文件消失，或 git status --short 显示至少 200 个已跟踪删除时，完整性检查会快速失败。这通常意味着远程同步状态不是 PR 的可信副本；停止该 box 并预热一个新的，而不是调试产品测试失败。对于有意进行大规模删除的 PR，请为该完整性检查设置 OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1。如果本地 Blacksmith CLI 调用在同步阶段停留超过五分钟且没有同步后输出，pnpm testbox:run 也会终止它。设置 OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0 可禁用该保护，或为异常大的本地差异使用更大的毫秒值。 Crabbox 是仓库自有的远程 box 包装器，用于维护者 Linux 验证。当某项检查对本地编辑循环来说过于宽泛、需要 CI 一致性，或验证需要密钥、Docker、包验证通道、可复用 box 或远程日志时使用它。正常的 OpenClaw 后端是 blacksmith-testbox；自有 AWS/Hetzner 容量是 Blacksmith 中断、配额问题或明确进行自有容量测试时的后备方案。首次运行前，从仓库根目录检查包装器：

pnpm crabbox:run -- --help | sed -n '1,120p'

如果 Crabbox 二进制文件过旧且未声明 blacksmith-testbox，仓库包装器会拒绝使用。即使 .crabbox.yaml 有自有云默认值，也要显式传入提供商。变更检查门：

pnpm crabbox:run -- --provider blacksmith-testbox \
  --blacksmith-org openclaw \
  --blacksmith-workflow .github/workflows/ci-check-testbox.yml \
  --blacksmith-job check \
  --blacksmith-ref main \
  --idle-timeout 90m \
  --ttl 240m \
  --timing-json \
  --shell -- \
  "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"

聚焦测试重跑：

pnpm crabbox:run -- --provider blacksmith-testbox \
  --blacksmith-org openclaw \
  --blacksmith-workflow .github/workflows/ci-check-testbox.yml \
  --blacksmith-job check \
  --blacksmith-ref main \
  --idle-timeout 90m \
  --ttl 240m \
  --timing-json \
  --shell -- \
  "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test <path-or-filter>"

完整套件：

pnpm crabbox:run -- --provider blacksmith-testbox \
  --blacksmith-org openclaw \
  --blacksmith-workflow .github/workflows/ci-check-testbox.yml \
  --blacksmith-job check \
  --blacksmith-ref main \
  --idle-timeout 90m \
  --ttl 240m \
  --timing-json \
  --shell -- \
  "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test"

阅读最终 JSON 摘要。有用字段是 provider、leaseId、syncDelegated、exitCode、commandMs 和 totalMs。一次性的 Blacksmith 后端 Crabbox 运行应自动停止 Testbox；如果运行被中断或清理状态不明确，请检查实时 box，并只停止你创建的 box：

blacksmith testbox list
blacksmith testbox stop --id <tbx_id>

仅在你有意需要在同一个已补水 box 上运行多个命令时使用复用：

pnpm crabbox:run -- --provider blacksmith-testbox --id <tbx_id> --no-sync --timing-json --shell -- "pnpm test <path-or-filter>"
pnpm crabbox:stop -- <tbx_id>

如果 Crabbox 是出问题的层，但 Blacksmith 本身可用，请使用直接 Blacksmith 作为窄范围后备方案：

blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
blacksmith testbox stop --id <tbx_id>

仅当 Blacksmith 不可用、受配额限制、缺少所需环境，或明确目标是自有容量时，才升级到自有 Crabbox 容量：

pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m
pnpm crabbox:hydrate -- --id <cbx_id-or-slug>
pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
pnpm crabbox:stop -- <cbx_id-or-slug>

.crabbox.yaml 负责自有云通道的提供商、同步和 GitHub Actions 补水默认值。它会排除本地 .git，因此已补水的 Actions checkout 会保留自己的远程 Git 元数据，而不是同步维护者本地的 remotes 和对象存储；它还会排除绝不应传输的本地运行时/构建产物。.github/workflows/crabbox-hydrate.yml 负责自有云 crabbox run --id <cbx_id> 命令的 checkout、Node/pnpm 设置、origin/main 拉取，以及非密钥环境交接。

Overview

First steps

Guides

流水线概览

快速失败顺序

范围和路由

ClawSweeper 活动转发

手动 dispatch

运行器

本地等价命令

OpenClaw 性能

完整发布验证

实时和 E2E 分片

软件包验收

作业

候选来源

套件 profile

旧版兼容窗口

示例

安装冒烟测试

本地 Docker E2E

可调项

可复用 live/E2E 工作流

发布路径分块

插件预发布

QA Lab

CodeQL

安全类别

平台特定安全分片

Critical Quality 类别

维护工作流

Docs Agent

Test Performance Agent

合并后的重复 PR

本地检查闸门和变更路由

Testbox 验证

相关

Overview

First steps

Guides

Documentation Index

​流水线概览

​快速失败顺序

​范围和路由

​ClawSweeper 活动转发

​手动 dispatch

​运行器

​本地等价命令

​OpenClaw 性能

​完整发布验证

​实时和 E2E 分片

​软件包验收

​作业

​候选来源

​套件 profile

​旧版兼容窗口

​示例

​安装冒烟测试

​本地 Docker E2E

​可调项

​可复用 live/E2E 工作流

​发布路径分块

​插件预发布

​QA Lab

​CodeQL

​安全类别

​平台特定安全分片

​Critical Quality 类别

​维护工作流

​Docs Agent

​Test Performance Agent

​合并后的重复 PR

​本地检查闸门和变更路由

​Testbox 验证

​相关

流水线概览

快速失败顺序

范围和路由

ClawSweeper 活动转发

手动 dispatch

运行器

本地等价命令

OpenClaw 性能

完整发布验证

实时和 E2E 分片

软件包验收

作业

候选来源

套件 profile

旧版兼容窗口

示例

安装冒烟测试

本地 Docker E2E

可调项

可复用 live/E2E 工作流

发布路径分块

插件预发布

QA Lab

CodeQL

安全类别

平台特定安全分片

Critical Quality 类别

维护工作流

Docs Agent

Test Performance Agent

合并后的重复 PR

本地检查闸门和变更路由

Testbox 验证

相关