发布策略

• stable：现有的已提升发布频道；在独立 CLI/频道里程碑落地前，它仍通过 npm latest 解析
• beta：发布到 npm beta 的预发布标签
• dev：main 的移动头部

​

版本命名

• 每月 npm extended-stable 发布版本：YYYY.M.PATCH，其中 PATCH >= 33，git 标签 vYYYY.M.PATCH
• 每日/常规最终发布版本：YYYY.M.PATCH，其中 PATCH < 33，git 标签 vYYYY.M.PATCH
• 常规回退修正发布版本：YYYY.M.PATCH-N，git 标签 vYYYY.M.PATCH-N
• Beta 预发布版本：YYYY.M.PATCH-beta.N，git 标签 vYYYY.M.PATCH-beta.N
• Alpha 预发布版本：YYYY.M.PATCH-alpha.N，git 标签 vYYYY.M.PATCH-alpha.N
• 月份或补丁号永远不要补零
• PATCH 是按月发布列车的顺序编号，不是日历日期。常规最终版和 beta 版会推进当前列车；仅 alpha 标签永远不会消耗或推进 beta/常规补丁号，因此选择 beta 或常规列车时，应忽略补丁号更高的旧版仅 alpha 标签。
• Alpha/nightly 构建使用下一个未发布的补丁列车，并且重复构建时只递增 alpha.N。一旦该补丁有了 beta，新的 alpha 构建就移动到后续补丁。
• npm 版本不可变：永远不要删除、重新发布或复用已发布的标签。改为切下一个预发布编号或下一个月度补丁。
• latest 继续跟随当前常规/每日 npm 线；beta 是当前 beta 安装目标
• extended-stable 表示受支持的上一个月份 npm 包，从补丁号 33 开始；补丁号 34 及之后是该月度线上的维护发布
• 常规最终版和常规修正版默认发布到 npm beta；发布操作员可以显式指定 latest，或稍后提升一个已审查的 beta 构建
• 专用的每月 extended-stable 路径会以完全相同的版本发布核心 npm 包以及每个可发布到 npm 的官方插件。它不会将插件发布到 ClawHub，也不会发布 macOS 或 Windows 构件、GitHub Release、私有仓库 dist-tag、Docker 镜像、移动端构件或网站下载项。
• 每个常规最终版都会同时发布 npm 包、macOS 应用和已签名的 Windows Hub 安装器。Beta 版本通常先验证并发布 npm/package 路径，原生应用的构建/签名/公证/提升保留给常规最终版，除非明确要求。

​

发布节奏

• 发布采用 beta 优先；stable 只在最新 beta 验证通过后跟进
• 维护者通常从当前 main 创建 release/YYYY.M.PATCH 分支来切发布，这样发布验证和修复不会阻塞 main 上的新开发
• 如果 beta 标签已经推送或发布并需要修复，维护者会切下一个 -beta.N 标签，而不是删除或重新创建旧标签
• 详细发布流程、审批、凭证和恢复说明仅限维护者

​

每月仅 npm extended-stable 发布

gh workflow run openclaw-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f tag=vYYYY.M.P \
  -f preflight_only=true \
  -f npm_dist_tag=extended-stable

gh workflow run full-release-validation.yml \
  --ref extended-stable/YYYY.M.33 \
  -f ref=extended-stable/YYYY.M.33 \
  -f release_profile=stable

RELEASE_SHA="$(git rev-parse HEAD)"
gh workflow run plugin-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f publish_scope=all-publishable \
  -f ref="$RELEASE_SHA" \
  -f npm_dist_tag=extended-stable

gh workflow run openclaw-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f tag=vYYYY.M.P \
  -f preflight_only=false \
  -f npm_dist_tag=extended-stable \
  -f preflight_run_id=<npm-preflight-run-id> \
  -f full_release_validation_run_id=<full-validation-run-id> \
  -f plugin_npm_run_id=<plugin-npm-run-id>

npm view openclaw@YYYY.M.P version --userconfig "$(mktemp)"
npm view openclaw@extended-stable version --userconfig "$(mktemp)"

​

常规发布操作员清单

1. 从当前 main 开始：拉取最新内容，确认目标提交已推送，并确认 main CI 足够绿色，可以从它创建分支。
2. 根据上一个可达发布标签以来合并的 PR 和所有直接提交生成顶部 CHANGELOG.md 章节。保持条目面向用户，去重重叠的 PR/直接提交条目，提交、推送，并在创建分支前再次 rebase/pull。
3. 审查 src/plugins/compat/registry.ts 和 src/commands/doctor/shared/deprecation-compat.ts 中的发布兼容性记录。仅在升级路径仍被覆盖时移除过期兼容性，或记录为什么有意继续保留。
4. 从当前 main 创建 release/YYYY.M.PATCH。不要直接在 main 上做常规发布工作。
5. 为该标签提升每个必需版本位置，然后运行 pnpm release:prep。它会按顺序刷新插件版本、npm shrinkwrap、插件清单、基础配置 schema、内置渠道配置元数据、配置文档基线、插件 SDK 导出和插件 SDK API 基线。在打标签前提交任何生成的漂移，然后运行本地确定性预检：pnpm check:test-types、pnpm check:architecture、pnpm build && pnpm ui:build 和 pnpm release:check。
6. 使用 preflight_only=true 运行 OpenClaw NPM Release。在标签存在前，允许使用完整 40 字符的发布分支 SHA 进行仅验证预检。预检会为准确检出的依赖图生成依赖发布证据，并将其存储在 npm 预检构件中。保存成功的 preflight_run_id。
7. 使用 Full Release Validation 为发布分支、标签或完整提交 SHA 启动所有预发布测试。这是四个大型发布测试盒的唯一手动入口点：Vitest、Docker、QA Lab 和 Package。保存 full_release_validation_run_id；它是 OpenClaw NPM Release 和 OpenClaw Release Publish 的必填输入。
8. 如果验证失败，在发布分支上修复，并重新运行能证明修复的最小失败文件、lane、工作流作业、包配置、提供商或模型允许列表。仅当更改表面使先前证据过期时，才重新运行完整总控。
9. 对于带标签的 beta 候选版，从匹配的 release/YYYY.M.PATCH 分支运行 pnpm release:candidate -- --tag vYYYY.M.PATCH-beta.N。对于 stable，还要传入必需的 Windows 源发布：pnpm release:candidate -- --tag vYYYY.M.PATCH --windows-node-tag vX.Y.Z。该辅助程序会运行本地生成发布检查，分发或验证完整发布验证和 npm 预检证据，针对准确已准备 tarball 运行 Parallels 全新/更新证明以及 Telegram 包证明，记录插件 npm 和 ClawHub 计划，并且只在证据包为绿色后打印准确的 OpenClaw Release Publish 命令。 OpenClaw Release Publish 会将选定或所有可发布的插件包并行发布到 npm，并将同一组包并行发布到 ClawHub，然后在插件 npm 发布成功后，用匹配的 dist-tag 推送已准备好的 OpenClaw npm 预检工件。OpenClaw npm 发布子任务成功后，它会从完整匹配的 CHANGELOG.md 小节创建或更新对应的 GitHub release/prerelease 页面：发布到 npm latest 的稳定版本会成为 GitHub 最新 release，保留在 npm beta 上的稳定维护版本会以 GitHub latest=false 创建。该工作流还会将预检依赖证据、完整验证清单以及发布后 registry 验证证据上传到 GitHub release，用于发布后事件响应。它会立即打印子运行 ID，自动批准工作流 token 允许批准的发布环境门禁，用日志尾部汇总失败的子任务，在 OpenClaw npm 发布成功后立即完成 GitHub release 和依赖证据，在 OpenClaw npm 正在发布时等待 ClawHub，然后运行 pnpm release:verify-beta，并为 GitHub release、npm 包、选定的插件 npm 包、选定的 ClawHub 包、子工作流运行 ID，以及可选的 NPM Telegram 运行 ID 上传发布后证据。ClawHub 路径会重试临时 CLI 依赖安装失败，即使某个预览单元偶发失败也会发布通过预览的插件，并以每个预期插件版本的 registry 验证结束，使部分发布保持可见且可重试。 然后针对已发布的 openclaw@YYYY.M.PATCH-beta.N 或 openclaw@beta 包运行发布后包验收。如果已推送或已发布的 prerelease 需要修复，请切出下一个匹配的 prerelease 编号；绝不要删除或重写旧版本。
10. 对于稳定版，只有经过审查的 beta 或 release candidate 已具备所需验证证据后，才能继续。稳定版 npm 发布也通过 OpenClaw Release Publish 进行，并通过 preflight_run_id 复用成功的预检工件。稳定版 macOS 发布就绪还要求已打包的 .zip、.dmg、.dSYM.zip，以及 main 上更新后的 appcast.xml；macOS 发布工作流会在发布资产验证通过后自动将已签名的 appcast 发布到公开 main，如果分支保护阻止直接推送，则会打开或更新一个 appcast PR。稳定版 Windows Hub 就绪要求 OpenClaw GitHub release 上存在已签名的 OpenClawCompanion-Setup-x64.exe、OpenClawCompanion-Setup-arm64.exe 和 OpenClawCompanion-SHA256SUMS.txt 资产。将精确签名的 openclaw/openclaw-windows-node release tag 作为 windows_node_tag 传入，并将其候选版已批准的安装器摘要映射作为 windows_node_installer_digests 传入；OpenClaw Release Publish 会保留 release 草稿，分发 Windows Node Release，并在发布前验证全部三个资产。
11. 发布后，运行 npm 发布后验证器；在需要发布后渠道证明时运行可选的独立已发布 npm Telegram E2E；在需要时进行 dist-tag 推进；验证生成的 GitHub release 页面；运行发布公告步骤；然后完成 稳定版 main 收尾，之后才能判定稳定版发布完成。

​

稳定版 main 收尾

1. 从最新的干净 main 开始。对照它审计 release/YYYY.M.PATCH，并将 main 中缺失的真实修复向前移植。不要盲目把仅 release 分支上的兼容、测试或验证适配器合并到更新的 main。
2. 将 main 设置为已发布的稳定版本，而不是推测性的下一列车版本。根版本变更后运行 pnpm release:prep，再运行 pnpm deps:shrinkwrap:generate。
3. 让 main 上 CHANGELOG.md 的 ## YYYY.M.PATCH 小节与带 tag 的 release 分支完全一致。如果 mac release 发布了稳定版 appcast.xml 更新，也要包含该更新。
4. 在操作员明确启动该 release train 之前，不要向 main 添加 YYYY.M.PATCH+1、beta 版本，或空的未来 changelog 小节。
5. 运行 pnpm release:generated:check、pnpm deps:shrinkwrap:check 和 OPENCLAW_TESTBOX=1 pnpm check:changed。推送后，在判定稳定版 release 完成前，验证 origin/main 包含已发布的版本和 changelog。
6. 每次私有回滚演练后，保持仓库变量 RELEASE_ROLLBACK_DRILL_ID 和 RELEASE_ROLLBACK_DRILL_DATE 为最新。

​

Release preflight

• 在 release preflight 前运行 pnpm check:test-types，以便测试 TypeScript 在更快的本地 pnpm check 门禁之外也保持覆盖。
• 在 release preflight 前运行 pnpm check:architecture，以便更广泛的导入循环和架构边界检查在更快的本地门禁之外保持绿色。
• 在 pnpm release:check 前运行 pnpm build && pnpm ui:build，以便包验证步骤所需的 dist/* release 工件和 Control UI bundle 存在。
• 在根版本提升后、打 tag 前运行 pnpm release:prep。它会运行每个在版本、配置或 API 变更后常见漂移的确定性 release 生成器：插件版本、npm shrinkwrap、插件清单、基础配置 schema、内置渠道配置元数据、配置文档 baseline、插件 SDK 导出，以及插件 SDK API baseline。pnpm release:check 会以检查模式重新运行这些守卫（另加插件 SDK 表面预算检查），并在运行包 release 检查前一次性报告每个生成漂移失败。
• 插件版本同步默认会将可发布的 @openclaw/ai 运行时包、官方插件包版本，以及现有的 openclaw.compat.pluginApi 下限更新为 OpenClaw release 版本。将该字段视为插件 SDK/运行时 API 下限，而不只是包版本的拷贝：对于有意保持与较旧 OpenClaw host 兼容的仅插件 release，请将下限保留为最旧支持的 host API，并在插件 release 证明中记录该选择。
• 在 release 批准前运行手动 Full Release Validation 工作流，从单一入口启动所有预发布测试箱。它接受分支、tag 或完整提交 SHA，分发手动 CI，并为安装 smoke、包验收、跨 OS 包检查、QA Lab parity、Matrix 和 Telegram lane 分发 OpenClaw Release Checks。稳定版和完整运行总是包含详尽的 live/E2E 和 Docker release-path soak；run_release_soak=true 保留用于显式 beta soak。Package Acceptance 在候选验证期间提供标准包 Telegram E2E，避免第二个并发 live poller。 发布 beta 后提供 release_package_spec，以便在 release checks、Package Acceptance 和包 Telegram E2E 中复用已发布的 npm 包，而无需重新构建 release tarball。仅在 Telegram 应使用与其余 release validation 不同的已发布包时，提供 npm_telegram_package_spec。当 Package Acceptance 应使用不同于 release package spec 的已发布包时，提供 package_acceptance_package_spec。当 release 证据报告应证明验证匹配某个已发布 npm 包、但不强制运行 Telegram E2E 时，提供 evidence_package_spec。
  gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.PATCH
  
• 当你希望在 release 工作继续推进的同时，为包候选版本获取侧路证明时，运行手动 Package Acceptance 工作流。对 openclaw@beta、openclaw@latest 或精确 release 版本使用 source=npm；使用 source=ref 以当前 workflow_ref harness 打包受信任的 package_ref 分支、tag 或 SHA；使用 source=url 处理需要 SHA-256 且遵守严格公开 URL 策略的公开 HTTPS tarball；使用 source=trusted-url 处理使用必需 trusted_source_id 和 SHA-256 的具名受信任源策略；或使用 source=artifact 处理由另一个 GitHub Actions 运行上传的 tarball。 该工作流会将候选解析为 package-under-test，针对该 tarball 复用 Docker E2E release scheduler，并可使用 telegram_mode=mock-openai 或 telegram_mode=live-frontier 针对同一 tarball 运行 Telegram QA。当选定的 Docker lane 包含 published-upgrade-survivor 时，包工件就是候选，published_upgrade_survivor_baseline 选择已发布 baseline。update-restart-auth 使用候选包同时作为已安装 CLI 和 package-under-test，因此会演练候选更新命令的托管重启路径。 示例：
  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 published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai
  
  常见配置文件：
  • smoke：安装/渠道/智能体、Gateway 网关网络和配置重载 lane
  • package：工件原生包/更新/重启/插件 lane，不含 OpenWebUI 或 live ClawHub
  • product：package 配置文件，外加 MCP 渠道、cron/子智能体清理、OpenAI web search 和 OpenWebUI
  • full：带 OpenWebUI 的 Docker release-path 分块
  • custom：为聚焦重跑精确选择 docker_lanes
• 当只需要 release candidate 的确定性常规 CI 覆盖时，直接运行手动 CI 工作流。手动 CI 分发会绕过变更范围限定，并强制运行 Linux Node 分片、内置插件分片、插件和渠道契约分片、Node 22 兼容性、check-*、check-additional-*、已构建工件 smoke 检查、文档检查、Python skills、Windows、macOS，以及 Control UI i18n lane。独立手动 CI 运行只有在以 include_android=true 分发时才运行 Android；Full Release Validation 会为其 CI 子任务传入该输入。
  gh workflow run ci.yml --ref release/YYYY.M.PATCH -f include_android=true
  
• 验证发布遥测时运行 pnpm qa:otel:smoke。它通过本地 OTLP/HTTP 接收器运行 QA-lab，并验证 trace、metric 和 log 导出，以及有界 trace 属性和内容/标识符脱敏，而无需 Opik、Langfuse 或其他外部采集器。
• 验证采集器兼容性时运行 pnpm qa:otel:collector-smoke。它先通过真实的 OpenTelemetry Collector Docker 容器路由相同的 QA-lab OTLP 导出，再执行本地接收器断言。
• 验证受保护的 Prometheus 抓取时运行 pnpm qa:prometheus:smoke。它运行 QA-lab，拒绝未认证的抓取，并验证发布关键的 metric family 不包含 prompt 内容、原始标识符、认证 token 和本地路径。
• 运行 pnpm qa:observability:smoke，按顺序执行源码 checkout 的 OpenTelemetry 和 Prometheus smoke lanes。
• 每次标记发布前运行 pnpm release:check。
• OpenClaw NPM Release 预检会在打包 npm tarball 前生成依赖发布证据。npm advisory 漏洞门禁会阻塞发布。传递依赖清单风险、依赖所有权/安装表面以及依赖变更报告仅作为发布证据。依赖变更报告会将发布候选版本与上一个可达的发布 tag 比较。预检会将依赖证据上传为 openclaw-release-dependency-evidence-<tag>，并同时嵌入到准备好的 npm 预检 artifact 内的 dependency-evidence/ 下。真实发布路径会复用该预检 artifact，然后把相同证据作为 openclaw-<version>-dependency-evidence.zip 附加到 GitHub release。
• tag 存在后，运行 OpenClaw Release Publish 执行会产生变更的发布序列。从 release/YYYY.M.PATCH 分支 dispatch（发布 main 可达 tag 时可从 main），传入 release tag、成功的 OpenClaw npm preflight_run_id 和成功的 full_release_validation_run_id，并保持默认插件发布范围 all-publishable，除非你明确在运行聚焦修复。该 workflow 会串行执行插件 npm 发布、插件 ClawHub 发布和 OpenClaw npm 发布，确保核心包不会早于其外部化插件发布。
• 稳定版 OpenClaw Release Publish 要求在匹配的非预发布版 openclaw/openclaw-windows-node release 存在后提供精确的 windows_node_tag，以及候选版本已批准的 windows_node_installer_digests map。在 dispatch 任何发布子流程前，它会验证源 release 已发布、非预发布、包含所需的 x64/ARM64 installer，并且仍与已批准的 map 匹配。随后它会在 OpenClaw release 仍为草稿时 dispatch Windows Node Release，并原样携带固定的 installer digest map。子 workflow 会从该精确 tag 下载已签名的 Windows Hub installer，与固定 digest 匹配，在 Windows runner 上验证其 Authenticode 签名使用预期的 OpenClaw Foundation signer，写入 SHA-256 manifest，并把 installer 和 manifest 上传到规范 OpenClaw GitHub release，然后重新下载已提升的 asset，验证 manifest 成员关系和 hash。父流程会在发布前验证当前 x64、ARM64 和 checksum asset 合约。直接恢复会先拒绝意外的 OpenClawCompanion-* asset 名称，再用固定源字节替换预期合约 asset。 仅在恢复时手动 dispatch Windows Node Release，并且始终传入精确 tag，不要传 latest，同时传入来自已批准源 release 的显式 expected_installer_digests JSON map。网站下载链接应指向当前稳定版 release 的精确 OpenClaw release asset URL，或仅在验证 GitHub 的 latest redirect 指向同一个 release 后使用 releases/latest/download/...；不要只链接到 companion repo release 页面。
• 发布检查现在在单独的手动 workflow 中运行：OpenClaw Release Checks。它还会在发布批准前运行 QA Lab mock parity lane、快速 live Matrix profile 和 Telegram QA lane。live lanes 使用 qa-live-shared environment；Telegram 还使用 Convex CI 凭证租约。需要并行覆盖完整 Matrix 传输、媒体和 E2EE 清单时，运行手动 QA-Lab - All Lanes workflow，并设置 matrix_profile=all 和 matrix_shards=true。
• 跨 OS 安装和升级运行时验证是公开 OpenClaw Release Checks 和 Full Release Validation 的一部分，它们会直接调用可复用 workflow .github/workflows/openclaw-cross-os-release-checks-reusable.yml。这种拆分是有意的：让真实 npm 发布路径保持短、确定且以 artifact 为中心，而较慢的 live 检查保留在自己的 lane 中，避免拖慢或阻塞发布。
• 带 secret 的发布检查应通过 Full Release Validation dispatch，或从 main/release workflow ref dispatch，以确保 workflow 逻辑和 secret 受控。
• OpenClaw Release Checks 接受分支、tag 或完整 commit SHA，只要解析后的 commit 可从 OpenClaw 分支或 release tag 到达。
• OpenClaw NPM Release 的仅验证预检也接受当前完整 40 字符 workflow 分支 commit SHA，而不要求已推送 tag。该 SHA 路径仅用于验证，不能提升为真实发布。在 SHA 模式下，该 workflow 仅为 package metadata 检查合成 v<package.json version>；真实发布仍要求真实 release tag。
• 两个 workflow 都会把真实发布和提升路径保留在 GitHub-hosted runner 上，而非变更型验证路径可以使用更大的 Blacksmith Linux runner。
• 该 workflow 会使用 OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache，并同时使用 OPENAI_API_KEY 和 ANTHROPIC_API_KEY workflow secret。
• npm 发布预检不再等待单独的 release checks lane。
• 在本地标记发布候选版本前，运行 RELEASE_TAG=vYYYY.M.PATCH-beta.N pnpm release:fast-pretag-check。该 helper 会按能在 GitHub 发布 workflow 启动前捕获常见审批阻断错误的顺序，运行快速发布 guardrail、插件 npm/ClawHub 发布检查、构建、UI 构建和 release:openclaw:npm:check。
• 批准前运行 RELEASE_TAG=vYYYY.M.PATCH node --import tsx scripts/openclaw-npm-release-check.ts（或匹配的预发布/修正版 tag）。
• npm 发布后运行 node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.PATCH（或匹配的 beta/修正版 version），以在全新的临时 prefix 中验证已发布 registry 安装路径。
• beta 发布后，运行 OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.PATCH-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live，使用共享租约 Telegram 凭证池，验证已安装 package 的 新手引导、Telegram 设置，以及针对已发布 npm package 的真实 Telegram E2E。本地 maintainer 的一次性操作可以省略 Convex 变量，并直接传入三个 OPENCLAW_QA_TELEGRAM_* 环境变量凭证。
• 要从 maintainer 机器运行完整的发布后 beta smoke，请使用 pnpm release:beta-smoke -- --beta betaN。该 helper 会运行 Parallels npm 更新/全新目标验证、dispatch NPM Telegram Beta E2E、轮询精确 workflow run、下载 artifact，并打印 Telegram 报告。
• Maintainer 可以通过手动 NPM Telegram Beta E2E workflow 从 GitHub Actions 运行相同的发布后检查。它有意仅支持手动运行，不会在每次 merge 时运行。
• Maintainer 发布自动化使用预检后提升：
  • 真实 npm 发布必须通过成功的 npm preflight_run_id。
  • 真实发布必须从与成功预检 run 相同的 main 或 release/YYYY.M.PATCH 分支 dispatch（Tideclaw alpha 分支允许用于 alpha 预发布）。
  • 稳定版 npm release 默认使用 beta；稳定版 npm 发布可以通过 workflow input 显式指向 latest。
  • 基于 token 的 npm dist-tag 变更位于 openclaw/releases/.github/workflows/openclaw-npm-dist-tags.yml，因为 npm dist-tag add 仍需要 NPM_TOKEN，而源码 repo 保持仅 OIDC 发布。
  • 公开 macOS Release 仅用于验证；当 tag 只存在于 release 分支但 workflow 从 main dispatch 时，设置 public_release_branch=release/YYYY.M.PATCH。
  • 真实 macOS 发布必须通过成功的 macOS preflight_run_id 和 validate_run_id。
  • 真实发布路径会提升已准备的 artifact，而不是再次重建它们。
• 对于 YYYY.M.PATCH-N 这样的稳定修正版 release，发布后验证器还会检查从 YYYY.M.PATCH 到 YYYY.M.PATCH-N 的同一临时 prefix 升级路径，确保发布修正不会悄悄让旧的全局安装停留在基础稳定版 payload 上。
• 除非 tarball 同时包含 dist/control-ui/index.html 和非空的 dist/control-ui/assets/ payload，否则 npm 发布预检会 fail closed，这样我们不会再次发布空的浏览器 dashboard。
• 发布后验证还会检查已发布插件入口点和 package metadata 是否存在于已安装 registry 布局中。缺少插件运行时 payload 的 release 会导致 postpublish verifier 失败，且不能提升到 latest。
• pnpm test:install:smoke 还会对候选更新 tarball 强制执行 npm pack unpackedSize 预算，因此 installer e2e 会在发布路径前捕获意外的 pack 膨胀。
• 如果发布工作触及 CI 规划、扩展 timing manifest 或扩展测试 matrix，请在批准前从 .github/workflows/plugin-prerelease.yml 重新生成并审查 planner 拥有的 plugin-prerelease-extension-shard matrix 输出，确保发布说明不会描述过期的 CI 布局。
• 稳定版 macOS 发布就绪还包括 updater 表面：GitHub release 最终必须包含打包后的 .zip、.dmg 和 .dSYM.zip；发布后 main 上的 appcast.xml 必须指向新的稳定版 zip（macOS 发布 workflow 会自动提交它，或在直接 push 被阻止时打开 appcast PR）；打包后的 app 必须保持非 debug bundle id、非空 Sparkle feed URL，以及达到或高于该 release version 规范 Sparkle build floor 的 CFBundleVersion。

​

发布测试机器

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

gh workflow run full-release-validation.yml \
  --ref main \
  -f ref=release/YYYY.M.PATCH \
  -f provider=openai \
  -f mode=both \
  -f release_profile=stable \
  -f evidence_package_spec=openclaw@YYYY.M.PATCH-beta.N

• minimum：最快的发布关键 OpenAI/core live 和 Docker 路径
• stable：minimum 加上用于发布批准的稳定提供商/后端覆盖
• full：stable 加上广泛的 advisory 提供商/媒体覆盖

# Validate an unpublished release candidate branch.
gh workflow run full-release-validation.yml \
  --ref main \
  -f ref=release/YYYY.M.PATCH \
  -f provider=openai \
  -f mode=both \
  -f release_profile=stable

# Validate an exact pushed commit.
gh workflow run full-release-validation.yml \
  --ref main \
  -f ref=<40-char-sha> \
  -f provider=openai \
  -f mode=both

# After publishing a beta, add published-package Telegram E2E.
gh workflow run full-release-validation.yml \
  --ref main \
  -f ref=release/YYYY.M.PATCH \
  -f provider=openai \
  -f mode=both \
  -f release_profile=full \
  -f release_package_spec=openclaw@YYYY.M.PATCH-beta.N \
  -f evidence_package_spec=openclaw@YYYY.M.PATCH-beta.N \
  -f npm_telegram_provider_mode=mock-openai

​

Vitest

• 显示已分发 CI 运行 URL 的 Full Release Validation 摘要
• 精确目标 SHA 上绿色的 CI 运行
• 调查回归时来自 CI 作业的失败或慢速分片名称
• 当运行需要性能分析时的 Vitest 计时工件，例如 .artifacts/vitest-shard-timings.json

gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.PATCH
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.PATCH -f include_android=true

​

Docker

• 启用慢速 Bun 全局安装冒烟的完整安装冒烟
• 按目标 SHA 准备/复用根 Dockerfile 冒烟镜像，其中 QR、root/gateway 和 installer/Bun 冒烟作业作为单独的 install-smoke 分片运行
• 仓库 E2E 线路
• 发布路径 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-services 分块内覆盖 OpenWebUI
• 拆分的内置插件安装/卸载线路 bundled-plugin-install-uninstall-0 到 bundled-plugin-install-uninstall-23
• 当发布检查包含 live 套件时的 live/E2E 提供商套件和 Docker live 模型覆盖

​

QA Lab

• mock parity 线路，使用 agentic parity 包将 OpenAI 候选线路与 anthropic/claude-opus-4-8 基线进行比较
• 使用 qa-live-shared 环境的快速 live Matrix QA profile
• 使用 Convex CI 凭证租约的 live Telegram QA 线路
• 当发布遥测需要显式本地证明时，运行 pnpm qa:otel:smoke、pnpm qa:otel:collector-smoke、pnpm qa:prometheus:smoke 或 pnpm qa:observability:smoke

​

包

• source=npm：openclaw@beta、openclaw@latest 或精确的 OpenClaw 发布版本
• source=ref：使用选定的 workflow_ref harness 打包受信任的 package_ref 分支、标签或完整 commit SHA
• source=url：下载公共 HTTPS .tgz，并要求提供 package_sha256；会拒绝 URL 凭证、非默认 HTTPS 端口、私有/内部/特殊用途主机名或解析地址，以及不安全重定向
• source=trusted-url：从 .github/package-trusted-sources.json 中命名策略下载 HTTPS .tgz，并要求提供 package_sha256 和 trusted_source_id；将其用于维护者拥有的企业镜像或私有包仓库，而不是向 source=url 添加输入级私有网络绕过
• source=artifact：复用另一个 GitHub Actions 运行上传的 .tgz

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 published_upgrade_survivor_baseline=openclaw@2026.4.26

• smoke：快速包安装/频道/智能体、Gateway 网关网络和配置重载通道
• package：安装/更新/重启/插件包契约，加上实时 ClawHub skill 安装证明；这是发布检查默认值
• product：package 加上 MCP 频道、cron/subagent 清理、OpenAI Web 搜索和 OpenWebUI
• full：带 OpenWebUI 的 Docker 发布路径分块
• custom：用于聚焦重跑的精确 docker_lanes 列表

​

常规发布发布自动化

1. 检出发布标签并解析其 commit SHA。
2. 验证该标签可从 main 或 release/* 到达（alpha 预发布则可从 Tideclaw alpha 分支到达）。
3. 运行 pnpm plugins:sync:check。
4. 使用 publish_scope=all-publishable 和 ref=<release-sha> 调度 Plugin NPM Release。
5. 使用相同 scope 和 SHA 调度 Plugin ClawHub Release。
6. 在验证已保存的 full_release_validation_run_id 后，使用发布标签、npm dist-tag 和已保存的 preflight_run_id 调度 OpenClaw NPM Release。
7. 对于稳定版发布，将 GitHub release 创建或更新为草稿，使用显式 windows_node_tag 和候选版本已批准的 windows_node_installer_digests 调度 Windows Node Release，并在发布草稿前验证规范安装器/checksum 资产。

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

gh workflow run openclaw-release-publish.yml \
  --ref release/YYYY.M.PATCH \
  -f tag=vYYYY.M.PATCH \
  -f windows_node_tag=vX.Y.Z \
  -f windows_node_installer_digests='{"OpenClawCompanion-Setup-x64.exe":"sha256:<approved-x64-sha256>","OpenClawCompanion-Setup-arm64.exe":"sha256:<approved-arm64-sha256>"}' \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f full_release_validation_run_id=<successful-full-release-validation-run-id> \
  -f npm_dist_tag=beta

gh workflow run openclaw-release-publish.yml \
  --ref release/YYYY.M.PATCH \
  -f tag=vYYYY.M.PATCH \
  -f windows_node_tag=vX.Y.Z \
  -f windows_node_installer_digests='{"OpenClawCompanion-Setup-x64.exe":"sha256:<approved-x64-sha256>","OpenClawCompanion-Setup-arm64.exe":"sha256:<approved-arm64-sha256>"}' \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f full_release_validation_run_id=<successful-full-release-validation-run-id> \
  -f npm_dist_tag=latest

​

NPM workflow 输入

• tag：必需的发布标签，例如 v2026.4.2、v2026.4.2-1、v2026.4.2-beta.1 或 v2026.4.2-alpha.1；当 preflight_only=true 时，它也可以是当前完整的 40 字符 workflow 分支 commit SHA，用于仅验证 preflight
• preflight_only：true 表示仅验证/构建/打包，false 表示真实发布路径
• preflight_run_id：现有成功 preflight 运行 ID；真实发布路径必需，这样 workflow 会复用已准备的 tarball，而不是重新构建
• full_release_validation_run_id：此标签/SHA 的成功 Full Release Validation 运行 ID；真实发布必需。Beta 发布可以仅基于 preflight 继续并发出警告，但稳定版/latest 提升仍然需要它。
• release_publish_run_id：已批准的 OpenClaw Release Publish 运行 ID；当此 workflow 由该父级调度时必需（bot-actor 真实发布调用）
• plugin_npm_run_id：成功的 exact-head Plugin NPM Release 运行 ID；真实 extended-stable 核心发布必需
• npm_dist_tag：发布路径的 npm 目标标签；接受 alpha、beta、latest 或 extended-stable，默认值为 beta。最终补丁 33 及之后必须使用 extended-stable；默认情况下，extended-stable 会拒绝更早的补丁，并且总是拒绝非最终标签。
• bypass_extended_stable_guard：仅测试用布尔值，默认 false；当 npm_dist_tag=extended-stable 时，绕过每月 extended-stable 资格检查，同时保留发布身份、制品、审批和回读检查。

• tag：必需的发布标签；必须已经存在
• preflight_run_id：成功的 OpenClaw NPM Release preflight 运行 ID；当 publish_openclaw_npm=true 时必需
• full_release_validation_run_id：成功的 Full Release Validation 运行 ID；当 publish_openclaw_npm=true 时必需
• windows_node_tag：精确的非预发布 openclaw/openclaw-windows-node 发布标签；稳定版 OpenClaw 发布必需
• windows_node_installer_digests：候选版本已批准的紧凑 JSON 映射，将当前 Windows 安装器名称映射到其固定 sha256: 摘要；稳定版 OpenClaw 发布必需
• npm_telegram_run_id：可选的成功 NPM Telegram Beta E2E 运行 ID，用于包含在最终发布证据中
• npm_dist_tag：OpenClaw 包的 npm 目标标签，值为 alpha、beta 或 latest 之一
• plugin_publish_scope：默认值为 all-publishable；仅在使用 publish_openclaw_npm=false 进行聚焦的仅插件修复工作时使用 selected
• plugins：当 plugin_publish_scope=selected 时，逗号分隔的 @openclaw/* 包名
• publish_openclaw_npm：默认值为 true；仅当把该 workflow 用作仅插件修复编排器时设置为 false
• release_profile：用于发布证据摘要的发布覆盖配置；默认值为 from-validation，它会从验证清单读取，也可用 beta、stable 或 full 覆盖
• wait_for_clawhub：默认值为 false，这样 npm 可用性不会被 ClawHub sidecar 阻塞；仅当 workflow 完成必须包含 ClawHub 完成时设置为 true

• ref：要验证的分支、标签或完整 commit SHA。带 secret 的检查要求已解析 commit 可从 OpenClaw 分支或发布标签到达。
• run_release_soak：选择加入用于 beta 发布检查的详尽实时/E2E、Docker 发布路径和 all-since upgrade-survivor soak。它会被 release_profile=stable 和 release_profile=full 强制启用。

• 补丁版本低于 33 的常规最终版本和修正版可以发布到 beta 或 latest。补丁版本为 33 或更高的最终版本必须发布到 extended-stable，并且该边界上的修正后缀版本会被拒绝。
• Beta 预发布标签只能发布到 beta；alpha 预发布标签只能发布到 alpha
• 对于 OpenClaw NPM Release，只有在 preflight_only=true 时才允许输入完整提交 SHA
• OpenClaw Release Checks 和 Full Release Validation 始终仅用于验证
• 真实发布路径必须使用预检期间使用的同一个 npm_dist_tag；工作流会在发布继续之前验证该元数据

​

常规 beta/latest 稳定版发布序列

1. 使用 preflight_only=true 运行 OpenClaw NPM Release。在标签存在之前，你可以使用当前完整工作流分支的提交 SHA，对预检工作流进行仅验证的试运行。
2. 对普通的 beta 优先流程选择 npm_dist_tag=beta，或者仅在你有意直接发布稳定版时选择 latest。
3. 当你希望通过一个手动工作流获得普通 CI 以及实时 prompt 缓存、Docker、QA Lab、Matrix 和 Telegram 覆盖时，在发布分支、发布标签或完整提交 SHA 上运行 Full Release Validation。如果你有意只需要确定性的普通测试图，请改为在发布引用上运行手动 CI 工作流。
4. 选择准确的非预发布 openclaw/openclaw-windows-node 发布标签，其签名 x64 和 ARM64 安装程序应随发布交付。将其保存为 windows_node_tag，并将它们经过验证的摘要映射保存为 windows_node_installer_digests。发布候选辅助工具会记录两者，并将它们包含在生成的发布命令中。
5. 保存成功的 preflight_run_id 和 full_release_validation_run_id。
6. 使用相同的 tag、相同的 npm_dist_tag、选定的 windows_node_tag、其已保存的 windows_node_installer_digests、已保存的 preflight_run_id 和已保存的 full_release_validation_run_id 运行 OpenClaw Release Publish。它会先将外部化插件发布到 npm 和 ClawHub，然后再提升 OpenClaw npm 包。
7. 如果发布落在 beta 上，请使用 openclaw/releases/.github/workflows/openclaw-npm-dist-tags.yml 工作流，将该稳定版本从 beta 提升到 latest。
8. 如果发布有意直接发布到 latest，并且 beta 应立即跟随同一个稳定构建，请使用同一个发布工作流将两个 dist-tag 都指向该稳定版本，或者让其计划的自修复同步稍后移动 beta。

​

公开参考

• .github/workflows/full-release-validation.yml
• .github/workflows/package-acceptance.yml
• .github/workflows/openclaw-npm-release.yml
• .github/workflows/openclaw-release-checks.yml
• .github/workflows/openclaw-cross-os-release-checks-reusable.yml
• scripts/resolve-openclaw-package-candidate.mjs
• scripts/openclaw-npm-release-check.ts
• scripts/package-mac-dist.sh
• scripts/make_appcast.sh

​

相关

• 发布频道