CI 流水线 - OpenClaw

OpenClaw CI 在每次推送到 main 以及每个拉取请求时运行。preflight 作业会对 diff 进行分类，并在只有无关区域发生变更时关闭成本较高的线路。手动 workflow_dispatch 运行会有意绕过智能作用域，并为候选发布版本和广泛验证展开完整图。Android 线路仍通过 include_android 选择加入。仅发布使用的插件覆盖率位于单独的 插件预发布 工作流中，并且只会从 完整发布验证 或显式手动调度运行。

流水线概览

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

快速失败顺序

preflight 决定哪些线路实际存在。docs-scope 和 changed-scope 逻辑是此作业中的步骤，不是独立作业。
security-scm-fast、security-dependency-audit、security-fast、check、check-additional、check-docs 和 skills-python 会快速失败，不等待更重的产物和平台矩阵作业。
build-artifacts 与快速 Linux 线路重叠执行，因此下游消费者可以在共享构建就绪后立即开始。
更重的平台和运行时线路随后展开：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()，因此它们仍会报告正常的分片失败，但在整个工作流已被取代后不会继续排队。自动 CI 并发键带有版本号（CI-v7-*），因此 GitHub 侧旧队列组中的僵尸任务无法无限阻塞较新的 main 运行。手动全套运行使用 CI-manual-v1-*，并且不会取消正在进行的运行。 ci-timings-summary 作业会为每个非草稿 CI 运行上传一个紧凑的 ci-timings-summary 产物。它记录当前运行的墙钟时间、排队时间、最慢作业和失败作业，因此 CI 健康检查无需反复抓取完整的 Actions payload。

作用域和路由

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

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

最慢的 Node 测试族会被拆分或均衡，使每个作业保持较小规模且不过度预留 runner：渠道契约作为三个加权的 Blacksmith 支持分片运行，并带有标准 GitHub runner fallback；核心单元 fast/support 线路单独运行；核心运行时基础设施拆分为 state、process/config、cron 和 shared 分片；auto-reply 作为均衡 worker 运行（reply 子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片）；agentic Gateway 网关/server 配置拆分到 chat/auth/model/http-plugin/runtime/startup 线路，而不是等待内置产物。广泛的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件 catch-all。Include-pattern 分片使用 CI 分片名称记录 timing 条目，因此 .artifacts/vitest-shard-timings.json 可以区分完整配置和已过滤分片。check-additional 将 package-boundary compile/canary 工作保持在一起，并将运行时拓扑架构与 Gateway 网关 watch 覆盖率分开；边界防护列表被条带化为四个矩阵分片，每个分片并发运行选定的独立防护并打印每项检查的 timing。成本较高的 Codex happy-path prompt snapshot drift 检查作为独立的 additional 作业运行，仅用于手动 CI 和影响提示的变更，因此普通无关 Node 变更不会等待冷 prompt snapshot 生成，同时边界分片保持均衡，而提示漂移仍被固定到导致它的 PR；同一个标志还会在内置产物 core support-boundary 分片中跳过 prompt snapshot Vitest 生成。Gateway 网关 watch、渠道测试和 core support-boundary 分片会在 dist/ 与 dist-runtime/ 已经构建完成后，在 build-artifacts 内并发运行。 Android CI 会同时运行 testPlayDebugUnitTest 和 testThirdPartyDebugUnitTest，随后构建 Play debug APK。第三方 flavor 没有单独的 source set 或 manifest；它的单元测试线路仍会使用 SMS/call-log BuildConfig 标志编译该 flavor，同时避免在每次 Android 相关推送时重复执行 debug APK 打包作业。 check-dependencies 分片运行 pnpm deadcode:dependencies（生产 Knip 仅依赖检查，固定到最新 Knip 版本，并在 dlx 安装时禁用 pnpm 的 minimum release age）和 pnpm deadcode:unused-files，后者会将 Knip 的生产未使用文件发现与 scripts/deadcode-unused-files.allowlist.mjs 进行比较。当 PR 新增未经评审的未使用文件，或留下陈旧 allowlist 条目时，未使用文件防护会失败，同时保留 Knip 无法静态解析的有意动态插件、生成产物、构建、live-test 和包桥接表面。

ClawSweeper 活动转发

.github/workflows/clawsweeper-dispatch.yml 是从 OpenClaw 仓库活动到 ClawSweeper 的目标侧桥接。它不会检出或执行不受信任的拉取请求代码。该工作流会从 CLAWSWEEPER_APP_PRIVATE_KEY 创建 GitHub App token，然后向 openclaw/clawsweeper 调度紧凑的 repository_dispatch payload。该工作流有四条线路：

clawsweeper_item 用于精确的 issue 和拉取请求评审请求；
clawsweeper_comment 用于 issue 评论中的显式 ClawSweeper 命令；
clawsweeper_commit_review 用于 main 推送上的提交级评审请求；
github_activity 用于 ClawSweeper 智能体可能检查的一般 GitHub 活动。

github_activity 线路只转发规范化元数据：事件类型、操作、actor、仓库、项目编号、URL、标题、状态，以及存在时评论或评审的短摘录。它有意避免转发完整 webhook body。openclaw/clawsweeper 中的接收工作流是 .github/workflows/github-activity.yml，它会将规范化事件发布到 OpenClaw Gateway 网关 hook，供 ClawSweeper 智能体使用。一般活动是观察，不是默认投递。ClawSweeper 智能体会在其提示中收到 Discord 目标，并且只有在事件令人意外、可操作、有风险或对运维有用时，才应发布到 #clawsweeper。常规打开、编辑、机器人 churn、重复 webhook 噪声和普通评审流量应返回 NO_REPLY。将此路径中的 GitHub 标题、评论、正文、评审文本、分支名称和提交消息全程视为不受信任的数据。它们是用于摘要和分流的输入，而不是工作流或 agent 运行时的指令。

手动分派

手动 CI 分派运行与常规 CI 相同的作业图，但会强制开启每个非 Android 作用域的通道：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 通道都不包含在 CI 中。Docker 预发布套件仅在 Full Release Validation 以启用发布验证门禁的方式分派单独的 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-smoke、Linux Node 测试分片、内置插件测试分片、`check-additional` 分片、`android`
`blacksmith-16vcpu-ubuntu-2404`	`build-artifacts`、`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`

Canonical-repo CI 保持 Blacksmith 作为默认运行器路径。在 preflight 期间，scripts/ci-runner-labels.mjs 会检查最近排队和正在进行的 Actions 运行中是否有排队的 Blacksmith 作业。如果某个特定 Blacksmith 标签已经有排队作业，那么本次运行中本会使用该确切标签的下游作业会回退到匹配的 GitHub 托管运行器（ubuntu-24.04、windows-2025 或 macos-latest）。同一 OS 系列中的其他 Blacksmith 规格仍保留在其主标签上。如果 API 探测失败，则不应用回退。

本地等价命令

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 Performance

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 可使用当前工作流实现对发布标签或其他分支进行基准测试。发布的报告路径和最新指针按被测 ref 设键，每个 index.md 都记录被测 ref/SHA、工作流 ref/SHA、Kova ref、profile、通道认证模式、模型、重复次数和场景过滤器。该工作流从固定发布版本安装 OCM，并从固定 kova_ref 输入处的 openclaw/Kova 安装 Kova，然后运行三个通道：

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

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

Full Release Validation

Full Release Validation 是“发布前运行所有内容”的手动总括工作流。它接受分支、标签或完整提交 SHA，使用该目标分派手动 CI 工作流，分派 Plugin Prerelease 以提供仅发布使用的插件/包/静态/Docker 证明，并分派 OpenClaw Release Checks 以运行安装 smoke、包验收、跨 OS 包检查、QA Lab 对等性、Matrix 和 Telegram 通道。稳定/默认运行会将详尽的实时/E2E 和 Docker 发布路径覆盖保留在 run_release_soak=true 后；release_profile=full 会强制开启该 soak 覆盖，因此广泛 advisory 验证仍保持广泛。使用 rerun_group=all 和 release_profile=full 时，它还会针对来自发布检查的 release-package-under-test 构件运行 NPM Telegram Beta E2E。发布后，传递 release_package_spec 可在发布检查、Package Acceptance、Docker、跨 OS 和 Telegram 中复用已发布的 npm 包，而无需重新构建。仅当 Telegram 必须证明不同包时，才使用 npm_telegram_package_spec。有关阶段矩阵、准确的工作流作业名称、profile 差异、构件和定向重跑句柄，请参阅完整发布验证。 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

对于快速变化分支上的固定提交证明，请使用辅助命令，而不是 gh workflow run ... --ref main -f ref=<sha>：

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

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

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

伞形工作流会记录调度出的子运行 ID，最终的 Verify full validation 作业会重新检查当前子运行结论，并为每个子运行追加最慢作业表。如果某个子工作流重新运行并变绿，只需重新运行父验证器作业，以刷新伞形结果和耗时摘要。用于恢复时，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 发布检查通道是建议性的，因此仅 QA 失败会发出警告，但不会阻塞发布检查验证器。 OpenClaw Release Checks 使用受信任的工作流引用，将所选引用解析一次为 release-package-under-test tarball，然后将该工件传递给跨 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 支撑的实时模型/后端分片会为每个所选提交使用单独共享的 ghcr.io/openclaw/openclaw-live-test:<sha> 镜像。实时发布工作流会构建并推送该镜像一次，然后 Docker 实时模型、按提供商分片的 Gateway 网关、CLI 后端、ACP 绑定和 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 工件上传，并在 GitHub 步骤摘要中打印来源、工作流引用、软件包引用、版本、SHA-256 和配置文件。
docker_acceptance 调用 openclaw-live-and-e2e-checks-reusable.yml，并传入 ref=workflow_ref 和 package_artifact_name=package-under-test。可复用工作流会下载该工件，验证 tarball 清单，在需要时准备软件包摘要 Docker 镜像，并针对该软件包运行所选 Docker 通道，而不是打包工作流检出内容。当某个配置文件选择多个定向 docker_lanes 时，可复用工作流会准备一次软件包和共享镜像，然后将这些通道展开为并行的定向 Docker 作业，并使用唯一工件。
package_telegram 可选地调用 NPM Telegram Beta E2E。当 telegram_mode 不是 none 时运行；如果软件包验收解析出了 package-under-test 工件，它会安装同一个工件；独立的 Telegram 调度仍可安装已发布的 npm 规范。
summary 会在软件包解析、Docker 验收或可选 Telegram 通道失败时使工作流失败。

候选来源

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

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

套件配置文件

smoke — npm-onboard-channel-agent、gateway-network、config-reload
package — npm-onboard-channel-agent、doctor-switch、update-channel-switch、skill-install、update-corrupt-plugin、upgrade-survivor、published-upgrade-survivor、update-restart-auth、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 配置文件使用离线插件覆盖，因此已发布软件包验证不会受实时 ClawHub 可用性的限制。可选的 Telegram 通道在 NPM Telegram Beta E2E 中复用 package-under-test 工件，同时为独立调度保留已发布 npm 规范路径。有关专用更新和插件测试策略，包括本地命令、Docker 通道、软件包验收输入、发布默认值和失败分类，请参阅更新和插件测试。发布检查会调用 Package Acceptance，并使用 source=artifact、准备好的发布包构件、suite_profile=custom、

docker_lanes='doctor-switch update-channel-switch skill-install update-corrupt-plugin upgrade-survivor published-upgrade-survivor update-restart-auth plugins-offline plugin-update'

和 telegram_mode=mock-openai。这会让包迁移、更新、实时 ClawHub Skills 安装、过期插件依赖清理、已配置插件安装修复、离线插件、插件更新和 Telegram 证明都基于同一个已解析的包 tarball。发布 beta 后，在 Full Release Validation 或 OpenClaw Release Checks 上设置 release_package_spec，即可在不重新构建的情况下针对已发布的 npm 包运行同一矩阵；只有当 Package Acceptance 需要使用与其余发布验证不同的包时，才设置 package_acceptance_package_spec。跨操作系统发布检查仍覆盖特定于操作系统的新手引导、安装器和平台行为；包/更新产品验证应从 Package Acceptance 开始。published-upgrade-survivor Docker lane 会在阻塞发布路径中，每次运行验证一个已发布包基线。在 Package Acceptance 中，已解析的 package-under-test tarball 始终是候选包，而 published_upgrade_survivor_baseline 会选择回退的已发布基线，默认是 openclaw@latest；失败 lane 的重跑命令会保留该基线。使用 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，以扩展到最新的四个稳定版 npm 发布，加上固定的插件兼容性边界版本和按问题形态构造的 fixture，覆盖 Feishu 配置、保留的 bootstrap/persona 文件、已配置的 OpenClaw 插件安装、波浪号日志路径，以及过期旧版插件依赖根目录。多基线 published-upgrade survivor 选择会按基线分片到独立的定向 Docker runner 作业。单独的 Update Migration workflow 会在需要穷尽式检查已发布更新清理，而不是常规 Full Release CI 覆盖范围时，使用带有 all-since-2026.4.23 和 plugin-deps-cleanup 的 update-migration Docker lane。本地聚合运行可以通过 OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS 传入精确包规格，通过 OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC 保留单个 lane，例如 openclaw@2026.4.15，或设置 OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS 用于场景矩阵。已发布 lane 会用内置的 openclaw config set 命令配方配置基线，在 summary.json 中记录配方步骤，并在 Gateway 网关启动后探测 /healthz、/readyz 和 RPC 状态。Windows 打包版和安装器全新安装 lane 还会验证已安装的包可以从原始绝对 Windows 路径导入浏览器控制 override。OpenAI 跨操作系统 Agent 轮次 smoke 在设置时默认使用 OPENCLAW_CROSS_OS_OPENAI_MODEL，否则使用 openai/gpt-5.4，因此安装和 Gateway 网关证明会保持在 GPT-5 测试模型上，同时避免使用 GPT-4.x 默认值。

旧版兼容窗口

Package Acceptance 对已发布的包设有有界旧版兼容窗口。直到 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 日志、阶段耗时和重跑命令。优先重跑失败的包 profile 或精确 Docker lane，而不是重跑完整发布验证。

安装 smoke

单独的 Install Smoke workflow 会通过自己的 preflight 作业复用同一个范围脚本。它将 smoke 覆盖拆分为 run_fast_install_smoke 和 run_full_install_smoke。

快速路径会针对触及 Docker/包表面、内置插件包/清单变更，或 Docker smoke 作业会执行的核心插件/渠道/Gateway 网关/插件 SDK 表面的 pull request 运行。仅源码的内置插件变更、仅测试编辑和仅文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents 删除共享工作区 CLI smoke，运行容器 gateway-network e2e，验证内置插件构建参数，并在 240 秒聚合命令超时内运行有界的内置插件 Docker profile（每个场景的 Docker 运行会分别设上限）。
完整路径会为夜间计划运行、手动分发、workflow-call 发布检查，以及确实触及安装器/包/Docker 表面的 pull request 保留 QR 包安装和安装器 Docker/更新覆盖。在完整模式下，install-smoke 会准备或复用一个目标 SHA 的 GHCR 根 Dockerfile smoke 镜像，然后将 QR 包安装、根 Dockerfile/Gateway 网关 smoke、安装器/更新 smoke，以及快速内置插件 Docker E2E 作为独立作业运行，因此安装器工作不会排在根镜像 smoke 后面等待。

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

本地 Docker E2E

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

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

Docker lane 定义位于 scripts/lib/docker-e2e-scenarios.mjs，planner 逻辑位于 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 的主池 slot 数量。
`OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`	10	对提供商敏感的尾部池 slot 数量。
`OPENCLAW_DOCKER_ALL_LIVE_LIMIT`	9	并发实时 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 daemon 创建风暴；设为 `0` 表示不做错峰。
`OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`	7200000	每个 lane 的回退超时（120 分钟）；选定的实时/尾部 lane 使用更严格的上限。
`OPENCLAW_DOCKER_ALL_DRY_RUN`	unset	`1` 会打印调度器计划而不运行 lane。
`OPENCLAW_DOCKER_ALL_LANES`	unset	逗号分隔的精确 lane 列表；跳过清理 smoke，方便 agents 复现一个失败的 lane。

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

可复用实时/E2E workflow

可复用实时/E2E workflow 会询问 scripts/test-docker-all.mjs --plan-json 需要哪些包、镜像类型、实时镜像、lane 和凭证覆盖。随后 scripts/docker-e2e.mjs 会将该计划转换为 GitHub 输出和摘要。它会通过 scripts/package-openclaw-for-docker.mjs 打包 OpenClaw，下载当前运行的包构件，或从 package_artifact_run_id 下载包构件；验证 tarball 清单；当计划需要已安装包的 lane 时，通过 Blacksmith 的 Docker layer cache 构建并推送带包摘要标签的裸/功能 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 运行道别名仍然是两个提供商安装器运行道的聚合手动重跑别名。当完整发布路径覆盖请求需要时，OpenWebUI 会合并到 plugins-runtime-services 中，并且只在仅 OpenWebUI 调度时保留独立的 openwebui 分块。内置渠道更新运行道会针对临时 npm 网络故障重试一次。每个分块都会上传 .artifacts/docker-tests/，其中包含运行道日志、耗时、summary.json、failures.json、阶段耗时、调度器计划 JSON、慢运行道表格，以及逐运行道重跑命令。工作流 docker_lanes 输入会针对已准备好的镜像运行选定运行道，而不是运行分块作业，这会把失败运行道调试限制在一个有目标的 Docker 作业内，并为该次运行准备、下载或复用包制品；如果选定运行道是 live Docker 运行道，目标作业会在本地为该次重跑构建 live-test 镜像。生成的逐运行道 GitHub 重跑命令会在这些值存在时包含 package_artifact_run_id、package_artifact_name 和已准备镜像输入，因此失败运行道可以复用失败运行中的确切包和镜像。

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 或显式操作员调度的独立工作流。普通拉取请求、main 推送和独立手动 CI 调度都会关闭该套件。它会在八个扩展工作器之间平衡内置插件测试；这些扩展分片作业一次最多运行两个插件配置组，每组使用一个 Vitest 工作器和更大的 Node 堆，因此导入密集型插件批次不会创建额外的 CI 作业。仅发布 Docker 预发布路径会把目标 Docker 运行道按小组批处理，以避免为一到三分钟的作业保留数十个运行器。该工作流还会从 @openclaw/plugin-inspector 上传一个信息性 plugin-inspector-advisory 制品；检查器发现是分诊输入，不会改变阻塞性的插件预发布门禁。

QA 实验室

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

QA-Lab - All Lanes 工作流每晚在 main 上运行，也会在手动调度时运行；它会把 mock parity 运行道、live Matrix 运行道，以及 live Telegram 和 Discord 运行道展开为并行作业。Live 作业使用 qa-live-shared 环境，Telegram/Discord 使用 Convex 租约。

发布检查会使用确定性的 mock 提供商和 mock 限定模型（mock-openai/gpt-5.5 和 mock-openai/gpt-5.5-alt）运行 Matrix 和 Telegram live 传输运行道，因此渠道契约会与 live 模型延迟和普通提供商插件启动隔离。Live 传输 Gateway 网关会禁用记忆搜索，因为 QA parity 会单独覆盖记忆行为；提供商连通性由独立的 live 模型、原生提供商和 Docker 提供商套件覆盖。 Matrix 对定时和发布门禁使用 --profile fast，并且仅在检出的 CLI 支持时添加 --fail-fast。CLI 默认值和手动工作流输入仍然是 all；手动 matrix_profile=all 调度始终会把完整 Matrix 覆盖分片为 transport、media、e2ee-smoke、e2ee-deep 和 e2ee-cli 作业。 OpenClaw Release Checks 也会在发布批准前运行发布关键的 QA 实验室运行道；它的 QA parity 门禁会把候选包和基线包作为并行运行道作业运行，然后把两个制品都下载到一个小型报告作业中，用于最终 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 服务器、进程执行辅助工具、出站投递，以及 agent 工具执行门禁
`/codeql-security-high/plugin-trust-boundary`	插件安装、加载器、清单、注册表、包管理器安装、源码加载，以及插件 SDK 包契约信任表面

平台特定安全分片

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

关键质量类别

CodeQL Critical Quality 是对应的非安全分片。它只在较小的 Blacksmith Linux 运行器上，对窄范围高价值表面运行错误严重级别、非安全 JavaScript/TypeScript 质量查询。它的拉取请求防护有意小于定时配置文件：非草稿 PR 只会针对 agent 命令/模型/工具执行和回复调度代码、配置 schema/迁移/IO 代码、凭证/密钥/沙箱/安全代码、核心渠道和内置渠道插件运行时、Gateway 网关协议/服务器方法、记忆运行时/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`	记忆主机 SDK、记忆运行时 facade、记忆插件 SDK 别名、记忆运行时激活粘合代码，以及记忆 Doctor 命令
`/codeql-critical-quality/session-diagnostics-boundary`	回复队列内部机制、会话投递队列、出站会话绑定/投递辅助程序、诊断事件/日志包表面，以及会话 Doctor CLI 契约
`/codeql-critical-quality/plugin-sdk-reply-runtime`	插件 SDK 入站回复分发、回复载荷/分块/运行时辅助程序、渠道回复选项、投递队列，以及会话/线程绑定辅助程序
`/codeql-critical-quality/provider-runtime-boundary`	模型目录规范化、提供商凭证和设备发现、提供商运行时注册、提供商默认值/目录，以及 Web/搜索/获取/嵌入注册表
`/codeql-critical-quality/ui-control-plane`	控制 UI 引导、本地持久化、Gateway 网关控制流，以及任务控制平面运行时契约
`/codeql-critical-quality/web-media-runtime-boundary`	核心 Web 获取/搜索、媒体 IO、媒体理解、图像生成，以及媒体生成运行时契约
`/codeql-critical-quality/plugin-boundary`	加载器、注册表、公共表面和插件 SDK 入口点契约
`/codeql-critical-quality/plugin-sdk-package-contract`	已发布包侧插件 SDK 源码和插件包契约辅助程序

质量与安全保持分离，这样质量发现就可以在不遮蔽安全信号的情况下进行排期、度量、禁用或扩展。Swift、Python 和内置插件 CodeQL 扩展只应在这些窄配置文件拥有稳定运行时和信号之后，作为有范围或分片的后续工作加回来。

维护工作流

文档 Agent

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

测试性能 Agent

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

合并后的重复 PR

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

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

本地检查门禁和变更路由

本地变更通道路由逻辑位于 scripts/changed-lanes.mjs，并由 scripts/check-changed.mjs 执行。相比宽泛的 CI 平台范围，该本地检查门禁对架构边界更加严格：

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

本地变更测试路由位于 scripts/test-projects.test-support.mjs，并且刻意比 check:changed 更便宜：直接测试编辑会运行自身，源码编辑优先使用显式映射，然后是同级测试和导入图依赖项。共享群组房间投递配置是显式映射之一：对群组可见回复配置、源回复投递模式或消息工具系统提示的变更，会通过核心回复测试以及 Discord 和 Slack 投递回归测试路由，这样共享默认值变更会在第一次 PR push 前失败。只有当变更覆盖整个 harness，导致便宜的映射集合不是可信代理时，才使用 OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed。

Testbox 验证

Crabbox 是仓库拥有的远程机器包装器，用于维护者 Linux 证明。当检查对本地编辑循环来说过宽、CI 一致性很重要，或者证明需要密钥、Docker、包通道、可复用机器或远程日志时，从仓库根目录使用它。正常的 OpenClaw 后端是 blacksmith-testbox；自有 AWS/Hetzner 容量是在 Blacksmith 中断、配额问题或显式自有容量测试时的后备。 Crabbox 支持的 Blacksmith 运行会 warm、claim、sync、run、report 并清理一次性 Testbox。内置同步完整性检查会在必需根文件（如 pnpm-lock.yaml）消失，或 git status --short 显示至少 200 个已跟踪删除时快速失败。对于有意的大删除 PR，请为远程命令设置 OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1。如果本地 Blacksmith CLI 调用停留在同步阶段超过五分钟且没有同步后输出，Crabbox 也会终止它。设置 CRABBOX_BLACKSMITH_SYNC_TIMEOUT_MS=0 可禁用该 guard，或者为异常大的本地 diff 使用更大的毫秒值。首次运行前，从仓库根目录检查包装器：

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；如果运行被中断或清理情况不明确，请检查 live 机器，并只停止你创建的机器：

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

仅在你有意需要在同一个已 hydrate 的机器上执行多个命令时才使用复用：

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 用于 list、status 和清理等诊断。先修复 Crabbox 路径，再把直接 Blacksmith 运行视为维护者证明。如果 blacksmith testbox list --all 和 blacksmith testbox status 可用，但新的 warmup 在几分钟后仍停留在 queued，没有 IP 或 Actions 运行 URL，则将其视为 Blacksmith 提供商、队列、账单或组织限制压力。停止你创建的 queued id，避免启动更多 Testbox，并将证明移到下面的自有 Crabbox 容量路径，同时让有人检查 Blacksmith 仪表板、账单和组织限制。仅当 Blacksmith 宕机、受配额限制、缺少所需环境，或明确以自有容量为目标时，才升级到自有 Crabbox 容量：

CRABBOX_CAPACITY_REGIONS=eu-west-1,eu-west-2,eu-central-1,us-east-1,us-west-2 \
  pnpm crabbox:warmup -- --provider aws --class standard --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>

在 AWS 容量压力下，除非任务确实需要 48xlarge 级别的 CPU，否则避免使用 class=beast。一次 beast 请求从 192 个 vCPU 起步，是最容易触发区域性 EC2 Spot 或 On-Demand Standard 配额限制的方式。仓库拥有的 .crabbox.yaml 默认使用 standard、多个容量区域和 capacity.hints: true，因此经代理分配的 AWS 租约会打印所选区域/市场、配额压力、Spot 回退，以及高压力规格警告。对更重的广泛检查使用 fast；只有在 standard/fast 不够时才使用 large；beast 仅用于特殊的 CPU 密集型验证通道，例如完整套件或全插件 Docker 矩阵、明确的发布/阻塞问题验证，或高核心数性能分析。不要将 beast 用于 pnpm check:changed、聚焦测试、仅文档工作、普通 lint/typecheck、小型 E2E 复现，或 Blacksmith 故障分诊。容量诊断时使用 --market on-demand，这样 Spot 市场波动就不会混入信号中。 .crabbox.yaml 负责 owned-cloud 验证通道的提供商、同步和 GitHub Actions hydrate 默认值。它会排除本地 .git，因此 hydrate 后的 Actions checkout 会保留自己的远程 Git 元数据，而不是同步维护者本地的远程和对象存储；它也会排除绝不应传输的本地运行时/构建产物。.github/workflows/crabbox-hydrate.yml 负责 checkout、Node/pnpm 设置、origin/main fetch，以及 owned-cloud crabbox run --id <cbx_id> 命令的非机密环境交接。

Documentation Index

​流水线概览

​快速失败顺序

​作用域和路由

​ClawSweeper 活动转发

​手动分派

​运行器

​本地等价命令

​OpenClaw Performance

​Full Release Validation

​实时和 E2E 分片

​软件包验收

​作业

​候选来源

​套件配置文件

​旧版兼容窗口

​示例

​安装 smoke

​本地 Docker E2E

​可调项

​可复用实时/E2E workflow

​发布路径分块

​插件预发布

​QA 实验室

​CodeQL

​安全类别

​平台特定安全分片

​关键质量类别

​维护工作流

​文档 Agent

​测试性能 Agent

​合并后的重复 PR

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

​Testbox 验证

​相关