发布策略

• stable：在 npm latest 上提升后的常规发布
• extended-stable：上一个已完成月份的 .33+ 维护线，位于 npm extended-stable
• beta：npm beta 上的预发布标签
• dev：main 的移动头部

​

版本命名

• 每月 Gateway extended-stable 发布版本：YYYY.M.PATCH，其中 PATCH >= 33，git tag 为 vYYYY.M.PATCH
• 每日/常规最终发布版本：YYYY.M.PATCH，其中 PATCH < 33，git tag 为 vYYYY.M.PATCH
• 常规回退修正发布版本：YYYY.M.PATCH-N，git tag 为 vYYYY.M.PATCH-N
• Beta 预发布版本：YYYY.M.PATCH-beta.N，git tag 为 vYYYY.M.PATCH-beta.N
• Alpha 预发布版本：YYYY.M.PATCH-alpha.N，git tag 为 vYYYY.M.PATCH-alpha.N
• 月份或 PATCH 绝不补零
• PATCH 是按顺序递增的每月发布列车编号，不是日历日期。常规最终版和 beta 版会推进当前列车；仅 alpha 的 tag 不会消耗或推进 beta/regular 的 patch 编号，因此在选择 beta 或常规列车时，请忽略 patch 编号更高的历史仅 alpha tag。
• Alpha/nightly 构建使用下一个尚未发布的 patch 列车，并且在重复构建时只递增 alpha.N。一旦该 patch 有了 beta，新 alpha 构建就会移动到下一个 patch。
• npm 版本是不可变的：绝不要删除、重新发布或复用已发布的 tag。应改为切出下一个预发布编号或下一个每月 patch。
• latest 继续跟随当前常规/每日 npm 版本线；beta 是当前 beta 安装目标
• extended-stable 指受支持的跨月 Gateway 分发版本，从 patch 33 开始；patch 34 及之后是在该每月版本线上的维护发布
• 常规最终版和常规修正版默认发布到 npm 的 beta；发布操作员可以显式指定目标为 latest，或者在之后将经过验证的 beta 构建提升为正式版
• Gateway extended-stable 会以一个精确版本同时发布 core、所有可发布到 npm 的官方插件， 以及它的 Docker 镜像；请参阅下面专门的工作流。
• 每个常规最终发布会同时发布 npm 包、macOS 应用、已签名的独立 Android APK，以及已签名的 Windows Hub 安装程序。Beta 发布通常先验证并发布 npm/包路径，而原生应用的构建/签名/公证/提升则保留给常规最终版，除非明确要求。

​

发布节奏

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

​

每月 Gateway extended-stable 发布

​

准备并稳定候选版本

RELEASE_SHA="$(git rev-parse HEAD)"

gh workflow run openclaw-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f tag="$RELEASE_SHA" \
  -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 expected_sha="$RELEASE_SHA" \
  -f release_profile=stable

• 产品：再合并一个已批准的回移 PR。
• 冻结目标工具链：仅回移最小的兼容性修复，并测试旧产品保持不变。
• 提供方、审批、运行器或服务：保持候选版本不变，并使用有边界的重试路径。

​

发布 npm 包

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 full_release_validation_run_attempt=<full-validation-run-attempt> \
  -f plugin_npm_run_id=<plugin-npm-run-id>

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

​

验证与恢复

node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.P
npm view [email protected] version --userconfig "$(mktemp)"
npm view openclaw@extended-stable version --userconfig "$(mktemp)"

gh workflow run openclaw-release-publish.yml \
  --ref main \
  -f tag=vYYYY.M.P \
  -f preflight_run_id=<npm-preflight-run-id> \
  -f full_release_validation_run_id=<full-validation-run-id> \
  -f full_release_validation_run_attempt=<full-validation-run-attempt> \
  -f npm_dist_tag=extended-stable \
  -f publish_openclaw_npm=false \
  -f publish_docker_only=true

​

常规发布操作员检查清单

1. 从当前的 main 开始：拉取最新内容，确认目标提交已推送，并确认 main CI 状态足够良好，可以从中创建分支。
2. 从该提交创建 release/YYYY.M.PATCH。Backports 是可选的；仅应用操作员选定的集合。更新所有必需的版本位置，运行 pnpm release:prep，完成发布修复和必需的 forward-ports，并检查 src/plugins/compat/registry.ts 以及 src/commands/doctor/shared/deprecation-compat.ts。
3. 将产品完整的变更日志前提交冻结为 Code SHA，并记录受信任的 Tooling SHA。运行确定性的源代码预检，然后使用 node scripts/full-release-validation-at-sha.mjs --sha <code-sha> --target-ref release/YYYY.M.PATCH。Beta 发布使用 release_profile=beta，不执行 soak；postpublish-confidence 负责广泛的线上、QA-live、移动端和 Parallels 工作。
4. 在编辑前先将失败归类为产品、harness/tooling/provenance、基础设施/凭据或包装器问题。只有经过确认的产品失败才会创建新的 Code SHA。使用一次诊断、必要时的一次修复以及一次范围狭窄的重试，然后重新评估。
5. 只有在 Code SHA 通过后，才根据自上一个可达的已发布 tag 以来合并的 PR 和直接提交生成顶部的 CHANGELOG.md 部分。条目应面向用户且去重。当分叉的已发布 tag 或后续 forward-port 重新关联已发布的 PR 时，显式传入 --shipped-ref。
6. 仅提交 CHANGELOG.md。此提交就是 Release SHA。从 Code SHA 到 Release SHA 的完整差异必须恰好是 CHANGELOG.md；任何其他变更路径都会使发布返回第 2 步。
7. 对 Release SHA 运行启用证据复用的、固定 SHA 的 Full Release Validation。轻量级父流程必须记录 changelog-only-release-v1，指向通过验证的 Code SHA，并且不分发产品子流程。此步骤复用产品证据，但不会复用软件包字节内容。
8. 针对 Release SHA/tag 运行 OpenClaw NPM Release，并设置 preflight_only=true。保存成功的 preflight_run_id。此步骤会构建并检查包含最终变更日志的确切软件包字节内容。
9. 使用成功的 Release-SHA 验证父流程和 npm 预检运行，针对未打 tag 的 Release SHA 运行候选版本辅助工具，而不是再次分发任一流程：
   pnpm release:candidate -- \
     --tag vYYYY.M.PATCH-beta.N \
     --target-sha <release-sha> \
     --full-release-run <release-sha-validation-run-id> \
     --npm-preflight-run <preflight-run-id> \
     --skip-dispatch
   
   对于稳定版，还要传入 --windows-node-tag vX.Y.Z。Beta 和 alpha 候选版本默认将 Parallels 安装/更新证明延后到发布后的 pnpm release:beta-smoke roster；只有当操作员明确希望在发布前获得该证明时，才传入 --run-parallels。稳定版和完整候选版本默认运行 Parallels。该辅助工具仍会验证发布说明的 provenance、npm 预检字节内容、Telegram 软件包证明以及插件发布计划，然后打印发布命令。确认其成功完成后，在同一个 Release SHA 上创建并推送最终的签名 tag，然后运行打印出的发布命令。 pnpm release:candidate 默认验证当前冻结分支顶端（或显式指定的 --target-sha），并拒绝已存在的标签。它会在推送最终签名标签前记录证据。 OpenClaw Release Publish 会将选定的或所有可发布的插件软件包分发到 npm，并将同一组软件包并行分发到 ClawHub；随后，在插件 npm 发布成功后，使用匹配的 dist-tag 提升已准备好的 OpenClaw npm 预检工件。它会在验证注册表回读时保持 GitHub release 为草稿状态，使用不可变标签和发布 SHA 调用 Docker Release，并且仅在此之后完成 GitHub release。发布检出目录仍是产品/数据根目录，而计划和最终验证则从确切的受信任工作流源代码检出目录执行，因此较旧的发布提交无法悄悄使用过时的发布工具。在任何发布子流程启动前，它都会渲染并缓存确切的 GitHub release 正文。当完整且匹配的 CHANGELOG.md 部分符合 GitHub 的 125,000 个字符限制以及渲染器匹配的 125,000 字节安全上限时，页面会包含该确切的 ## YYYY.M.PATCH 部分，包括其标题。当源部分超出限制时，页面会保留确切的分组编辑说明，并将过大的贡献记录替换为指向标签固定的 CHANGELOG.md 中完整记录的稳定链接；绝不会发布部分记录或截断的项目符号。工作流会在添加 ### Release verification 之前选择完整正文或精简正文；如果证明尾部会超出限制，则保留规范正文，并依赖不可变的附加证据。发布到 npm latest 的稳定版会成为 GitHub 最新发布，而保留在 npm beta 上的稳定维护版本则会以 GitHub latest=false 创建。该工作流还会将预检依赖证据、完整验证清单以及发布后的注册表验证证据上传到 GitHub release，以便进行发布后事故响应。它会立即打印子流程运行 ID，自动批准工作流令牌有权批准的发布环境闸门，使用日志尾部汇总失败的子任务，预先创建 GitHub release 草稿页面，并在 OpenClaw npm 发布的同时并行提升 Windows 和 Android 资源；当 OpenClaw npm 正在发布时等待 ClawHub，然后运行受信任的 main beta 验证器，并将 GitHub release、npm 软件包、选定的插件 npm 软件包、选定的 ClawHub 软件包、子工作流运行 ID 以及可选的 NPM Telegram 运行 ID 的发布后证据上传到 GitHub release。ClawHub 引导验证器要求确切的受信任 main 工作流路径和 SHA、生产者及终端运行尝试、发布 SHA、请求的软件包集合、不可变软件包工件元组以及终端注册表回读工件；成功的旧版发布引用运行不会被接受。 然后针对已发布的 [email protected] 或 openclaw@beta 包运行发布后包接受测试。如果已推送或已发布的预发布版需要修复，请切换到下一个匹配的预发布版本号；切勿删除或重写旧版本。
10. 在发布尝试失败时，保持发布 SHA 不变，除非失败证明存在产品或变更日志缺陷。恢复成功的不可变子流程和工件；切勿重建或重新发布已成功的软件包版本。
11. 对于稳定版，只有在经过审查的 beta 或候选发布版本具备所需验证证据后，才继续。稳定版 npm 发布也通过 OpenClaw Release Publish 进行，并通过 preflight_run_id 复用成功的预检工件。稳定版 macOS 发布就绪还要求在 main 上提供打包的 .zip、.dmg、.dSYM.zip 以及更新后的 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，并在发布前验证这三项资源。
12. 发布后，运行 npm 发布后验证器，在需要发布后渠道证明时可选运行独立的已发布 npm Telegram E2E，在需要时进行 dist-tag 推广，验证生成的 GitHub release 页面，运行发布公告步骤，然后在将稳定发布标记为完成之前，先完成稳定版 main 收尾。

​

Stable 主线收尾

1. 从最新的干净 main 开始。将 release/YYYY.M.PATCH 与其进行审计，并将 main 中缺失的真实修复前向移植过来。不要把仅用于发布分支的兼容性、测试或验证适配器盲目合并到更新的 main 中。
2. 对于正常路径，将 main 设置为已发布的稳定版本。较晚的收尾可能会使用已经推进到更晚的稳定 OpenClaw CalVer 的 main；不要仅仅为了关闭前一个发布而把已经开始的发布列车降级。验证器仍然要求精确的已发布 changelog 章节和 appcast 条目，并记录 main 的实际版本和 SHA。任何根版本变更后都要运行 pnpm release:prep。
3. 使 main 上的 CHANGELOG.md 中 ## YYYY.M.PATCH 章节与已打标签的发布分支完全一致。如果 mac 发行版发布了稳定的 appcast.xml 更新，也要包含进去。
4. 在操作员明确开始该发布列车之前，不要向 main 添加 YYYY.M.PATCH+1、beta 版本或空的未来 changelog 章节。
5. 运行 pnpm release:generated:check、pnpm deps:npm-lock:check 和 OPENCLAW_TESTBOX=1 pnpm check:changed。推送，然后在调用稳定发布完成之前，确认 origin/main 包含已发布版本和 changelog。
6. 在每次私有回滚演练之后，保持仓库变量 RELEASE_ROLLBACK_DRILL_ID 和 RELEASE_ROLLBACK_DRILL_DATE 为最新。

​

发布预检

• 在发布预检之前运行 pnpm check:test-types，以确保测试 TypeScript 检查在更快的本地 pnpm check 门禁之外也得到覆盖。
• 在发布预检之前运行 pnpm check:architecture，以确保更广泛的导入循环和架构边界检查在更快的本地门禁之外保持通过。
• 在 pnpm release:check 之前运行 pnpm build && pnpm ui:build，以确保预期的 dist/* 发布产物和 Control UI 包在打包验证步骤中存在。
• 在根版本号提升之后、打标签之前运行 pnpm release:prep。它会运行所有通常会在版本/配置/API 变更后漂移的确定性发布生成器：插件版本、插件清单、基础配置 schema、打包后的 channel 配置元数据、配置文档基线、插件 SDK 导出、Plugin SDK API 合同清单，以及 Control UI 语言包。它还会阻塞直到原生应用翻译和平台生成的语言资源与源码清单一致；如果它们滞后，请等待或触发 Native App Locale Refresh，然后再冻结 Code SHA。pnpm release:check 会在检查模式下重新运行这些门禁以及临时 npm package-lock 验证（包括严格的语言门禁和插件 SDK 表面预算），并在运行包发布检查前一次性报告所有失败。
• 默认情况下，插件版本同步会将可发布的 @openclaw/ai 运行时包、官方插件包版本，以及现有的 openclaw.compat.pluginApi 下限更新为 OpenClaw 发布版本。请将该字段视为插件 SDK/运行时 API 下限，而不仅仅是包版本的拷贝：对于故意保持与旧版 OpenClaw 主机兼容的仅插件发布，请将下限保留为最旧受支持主机 API，并在插件发布证据中记录该决定。
• 在发布批准之前运行手动 Full Release Validation 工作流，以便从一个入口触发所有预发布测试盒。它接受分支、标签或完整 commit SHA，分发手动 CI，并分发 OpenClaw Release Checks，覆盖安装烟雾测试、包验收、跨操作系统包检查、QA Lab 对齐、Matrix 和 Telegram 任务线。稳定版和完整版运行始终包含详尽的 live/E2E 和 Docker 发布路径 soak；run_release_soak=true 保留用于显式的 beta soak。Package Acceptance 在候选验证期间提供规范的包 Telegram E2E，避免第二个并发的 live 轮询器。 在发布 beta 后提供 release_package_spec，即可在发布检查、Package Acceptance 和包 Telegram E2E 中复用已发布的 npm 包，而无需重新构建发布 tarball。只有当 Telegram 需要使用与其余发布验证不同的已发布包时，才提供 npm_telegram_package_spec。当 Package Acceptance 需要使用与发布包规格不同的已发布包时，提供 package_acceptance_package_spec。当发布证据报告应证明验证与已发布的 npm 包一致、但不强制 Telegram E2E 时，提供 evidence_package_spec。
  node scripts/full-release-validation-at-sha.mjs \
    --sha <code-sha> \
    --target-ref release/YYYY.M.PATCH
  
• 当你希望在发布工作继续进行时，为某个包候选获取侧信道证明，请运行手动 Package Acceptance 工作流。对 openclaw@beta、openclaw@latest 或精确发布版本使用 source=npm；对使用当前 workflow_ref 运行时打包可信 package_ref 分支/标签/SHA 使用 source=ref；对带必需 SHA-256 和严格公共 URL 策略的公共 HTTPS tarball 使用 source=url；对使用必需 trusted_source_id 和 SHA-256 的命名可信来源策略使用 source=trusted-url；或者对由另一个 GitHub Actions 运行上传的 tarball 使用 source=artifact。 该工作流会将候选解析为 package-under-test，对该 tarball 复用 Docker E2E 发布调度器，并且可以使用 telegram_mode=mock-openai 或 telegram_mode=live-frontier 对同一 tarball 运行 Telegram QA。当所选 Docker 任务线包含 published-upgrade-survivor 时，包产物是候选包，而 published_upgrade_survivor_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 [email protected] -f telegram_mode=mock-openai
  
  常见配置：
  • smoke：安装/通道/代理、gateway 网络和配置重载任务线
  • package：原生包/更新/重启/插件任务线，不包含 OpenWebUI 或 live ClawHub
  • product：包配置文件加上 MCP 通道、cron/subagent 清理、OpenAI web search 和 OpenWebUI
  • full：带 OpenWebUI 的 Docker 发布路径分块
  • custom：用于有针对性重跑的精确 docker_lanes 选择
• 当你只需要发布候选的确定性常规 CI 覆盖时，直接运行手动 CI 工作流。手动 CI 调度会绕过变更范围控制，并强制执行 Linux Node 分片、捆绑插件分片、插件和 channel 合同分片、Node 22 兼容性、check-*、check-additional-*、已构建产物烟雾检查、文档检查、Python skills、Windows、macOS 以及 Control UI i18n 任务线。独立手动 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 receiver 对 QA-lab 进行演练，并在不需要 Opik、Langfuse 或其他外部收集器的情况下，验证 trace、metric 和 log 导出，以及受限的 trace 属性和内容/标识符去标识化。
• 在验证收集器兼容性时运行 pnpm qa:otel:collector-smoke。它先将相同的 QA-lab OTLP 导出路由到一个真实的 OpenTelemetry Collector Docker 容器，然后再进行本地 receiver 断言。
• 在验证受保护的 Prometheus 抓取时运行 pnpm qa:prometheus:smoke。它会演练 QA-lab，拒绝未认证抓取，并验证发布关键的指标族保持不包含提示内容、原始标识符、认证令牌和本地路径。
• 将 pnpm qa:observability:smoke 用于源代码检出状态下的 OpenTelemetry 和 Prometheus 烟雾任务线，连续运行。
• 在每次打标签发布之前运行 pnpm release:check。
• OpenClaw NPM Release 预检在打包 npm tarball 之前生成依赖发布证据。npm advisory 漏洞门禁是发布阻断项。传递依赖清单风险、依赖所有权/安装表面，以及依赖变更报告仅作为发布证据。依赖变更报告会将发布候选与之前可达的发布标签进行比较。预检会将依赖证据作为 openclaw-release-dependency-evidence-<tag> 上传，并且还会将其嵌入到准备好的 npm 预检产物内的 dependency-evidence/ 下。实际发布路径会复用该预检产物，然后将同样的证据作为 openclaw-<version>-dependency-evidence.zip 附加到 GitHub release。
• 在标签存在后运行 OpenClaw Release Publish 执行有变更的发布序列。将常规 beta 和 stable 发布从受信任的 main 分发；发布标签仍会选择精确目标 commit，并且可能指向 release/YYYY.M.PATCH。Tideclaw alpha 发布仍保留在其匹配的 alpha 分支上。传入成功的 OpenClaw npm preflight_run_id、成功的 full_release_validation_run_id 和精确的 full_release_validation_run_attempt，并保持默认插件发布范围 all-publishable，除非你有意进行有针对性的修复。该工作流会串行化插件 npm 发布、插件 ClawHub 发布和 OpenClaw npm 发布，因此核心包不会在外部化插件之前发布；Windows 和 Android 推广会与核心 npm 发布并行运行，目标是草稿 release 页面。发布重跑支持断点续跑：一旦工作流证明 registry tarball 与标签的预检产物匹配，已经发布过的核心 npm 版本会跳过核心分发；如果 release 已经携带已验证的资产合同，则会跳过 Windows/Android 推广，因此重试只会重新执行失败的阶段。仅插件的有针对性的修复需要 plugin_publish_scope=selected 且非空插件列表。仅插件的 all-publishable 运行需要完整不可变预检和 Full Release Validation 证据；部分证据会被拒绝。
• Stable 的 OpenClaw Release Publish 需要精确的 windows_node_tag，且对应的非预发布 openclaw/openclaw-windows-node release 已存在，同时还需要候选批准的 windows_node_installer_digests 映射。在分发任何发布子任务之前，它会验证源 release 已发布、非预发布、包含所需的 x64/ARM64 安装程序，并且仍与该批准映射一致。然后在 OpenClaw release 仍处于草稿状态时分发 Windows Node Release，并原样携带固定的安装程序摘要映射。子工作流会从该精确标签下载已签名的 Windows Hub 安装程序，将它们与固定摘要进行比对，在 Windows runner 上验证其 Authenticode 签名使用的是预期的 OpenClaw Foundation 签名者，写入 SHA-256 清单，然后将安装程序及清单上传到规范的 OpenClaw GitHub release，接着重新下载已推广的资产并验证清单成员关系和哈希。父工作流在发布前验证当前的 x64、ARM64 和 checksum 资产合同。直接恢复会在用固定的源字节替换预期合同资产之前，拒绝意外的 OpenClawCompanion-* 资产名称。 仅在恢复场景下手动分发 Windows Node Release，并且始终传入精确标签，绝不要用 latest，再加上来自已批准源 release 的显式 expected_installer_digests JSON 映射。网站下载链接应针对当前 stable 版的精确 OpenClaw release 资产 URL，或者仅在验证 GitHub 的 latest 重定向指向同一 release 后，使用 releases/latest/download/...；不要只链接到 companion 仓库 release 页面。
• 发布检查现在在单独的手动工作流中运行：OpenClaw Release Checks。它始终运行 QA Lab mock parity 任务线。Matrix catalog 和 Telegram QA-live 任务线会在 stable/full 验证、启用 soak 的验证，或显式的 qa/qa-live 重跑组中运行。没有启用 soak 的有界 beta-publish all 会将这些 live 任务线推迟到 postpublish-confidence。live 任务线使用 qa-live-shared 环境；Telegram 还使用 Convex CI credential leases。
• 跨操作系统安装和升级运行时验证属于公共的 OpenClaw Release Checks 和 Full Release Validation，它们会直接调用可复用工作流 .github/workflows/openclaw-cross-os-release-checks-reusable.yml。这种拆分是有意的：保持真实 npm 发布路径简短、确定且以产物为重点，同时让较慢的 live 检查保留在自己的任务线中，避免拖慢或阻塞发布。
• 应通过 Full Release Validation，或从 main/release 工作流引用分发包含 secret 的发布检查，以便工作流逻辑和 secret 保持受控。
• OpenClaw Release Checks 接受分支、标签或完整 commit SHA，只要解析出的 commit 可从 OpenClaw 分支或 release 标签访问即可。
• OpenClaw NPM Release 仅验证预检也接受当前完整的 40 字符工作流分支 commit SHA，无需推送标签。该 SHA 路径仅用于验证，不能提升为真实发布。在 SHA 模式下，工作流仅为包元数据检查合成 v<package.json version>；真实发布仍需要真实的 release 标签。
• 两个工作流都将真实发布和推广路径保留在 GitHub-hosted runner 上，而不修改状态的验证路径可以使用更大的 Blacksmith Linux runner。
• 该工作流使用 OPENAI_API_KEY 和 ANTHROPIC_API_KEY 工作流 secret 运行 OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache。
• npm 发布预检不再等待单独的发布检查任务线。
• 在本地为发布候选打标签之前，运行 RELEASE_TAG=vYYYY.M.PATCH-beta.N pnpm release:fast-pretag-check。该辅助程序会按能够在 GitHub 发布工作流启动前发现常见审批阻断错误的顺序，运行快速发布护栏、插件 npm/ClawHub 发布检查、构建、UI 构建和 release:openclaw:npm:check。
• 在批准之前运行 RELEASE_TAG=vYYYY.M.PATCH node --import tsx scripts/openclaw-npm-release-check.ts（或匹配的预发布/修正版标签）。
• npm 发布后，运行 node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.PATCH（或匹配的 beta/修正版版本），以在全新的临时前缀中验证已发布的 registry 安装路径。
• beta 发布后，运行 [email protected] OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live，以使用共享租用的 Telegram credential pool，针对已发布的 npm 包验证已安装包的引导、Telegram 设置和真实 Telegram E2E。本地维护者的一次性运行可以省略 Convex 变量，直接传入三个 OPENCLAW_QA_TELEGRAM_* 环境凭据。
• 要在维护者机器上运行完整的发布后 beta 烟雾测试，请使用 pnpm release:beta-smoke -- --beta betaN。该辅助程序会运行 Parallels npm 更新/新目标验证，分发 NPM Telegram Beta E2E，轮询精确的工作流运行，下载产物，并打印 Telegram 报告。
• 维护者可以通过手动的 NPM Telegram Beta E2E 工作流，从 GitHub Actions 运行相同的发布后检查。它特意仅支持手动运行，不会在每次合并时运行。
• 维护者发布自动化采用预检后推广：
  • 真实 npm 发布必须通过成功的 npm preflight_run_id。
  • 常规 beta 和 stable 发布编排及预检使用精确目标标签对应的受信任 main。Tideclaw alpha 发布和预检使用匹配的 alpha 分支。
  • Stable npm 发布默认为 beta；stable npm 发布可以通过工作流输入显式指定为 latest。
  • 基于令牌的 npm dist-tag 变更位于 openclaw/releases/.github/workflows/openclaw-npm-dist-tags.yml，因为 npm dist-tag add 仍需要 NPM_TOKEN，而源代码仓库保持仅使用 OIDC 的发布方式。
  • 公共的 macOS Release 仅用于验证；当标签只存在于 release 分支、但工作流从 main 分发时，请设置 public_release_branch=release/YYYY.M.PATCH。
  • 真实 macOS 发布必须通过成功的 macOS preflight_run_id 和 validate_run_id。
  • 真实发布路径会推广已准备好的产物，而不是再次构建它们。
• 对于 YYYY.M.PATCH-N 等 stable 修正版发布，发布后验证器还会检查从 YYYY.M.PATCH 到 YYYY.M.PATCH-N 的相同临时前缀升级路径，以确保发布修正不会悄然让较旧的全局安装继续使用基础 stable 载荷。
• npm 发布预检会在 tarball 未同时包含 dist/control-ui/index.html 和非空的 dist/control-ui/assets/ 载荷时失败关闭，因此我们不会再次发布空的浏览器仪表板。
• 发布后验证还会检查已发布的插件入口点和包元数据是否存在于已安装的 registry 布局中。若发布缺少插件运行时载荷，发布后验证器将失败，并且无法推广到 latest。
• pnpm test:install:smoke 还会对候选更新 tarball 强制执行 npm pack unpackedSize 预算，因此安装程序 e2e 可以在发布路径前捕获意外的包体积膨胀。
• 如果发布工作涉及 CI 规划、扩展时间清单或扩展测试矩阵，请在批准前从 .github/workflows/plugin-prerelease.yml 重新生成并审查由规划器负责的 plugin-prerelease-extension-shard 矩阵输出，以免发布说明描述过时的 CI 布局。
• Stable macOS 发布就绪性还包括更新器界面：GitHub release 最终必须包含已打包的 .zip、.dmg 和 .dSYM.zip；发布后，main 上的 appcast.xml 必须指向新的 stable zip（macOS 发布工作流会自动提交它，或者在直接推送受阻时创建 appcast PR）；已打包的应用必须保留非 debug bundle id、非空的 Sparkle feed URL，以及不低于该发布版本规范 Sparkle 构建下限的 CFBundleVersion。

​

发布测试箱

pnpm ci:full-release \
  --sha <code-sha> \
  --target-ref release/YYYY.M.PATCH

pnpm ci:full-release \
  --sha <release-sha> \
  --target-ref release/YYYY.M.PATCH

• beta：最快的发布关键 OpenAI/core live 和 Docker 路径
• stable：在 beta 基础上增加 stable 提供方/后端覆盖，以用于发布批准
• full：在 stable 基础上增加更广泛的顾问型提供方/媒体覆盖

# 验证产品完整的 Code SHA。
pnpm ci:full-release \
  --sha <code-sha> \
  --target-ref release/YYYY.M.PATCH

# 通过复用 Code SHA 的产品证据来验证仅变更 changelog 的 Release SHA。
pnpm ci:full-release \
  --sha <release-sha> \
  --target-ref release/YYYY.M.PATCH

# 在发布 beta 后，增加已发布包的 Telegram E2E。
pnpm ci:full-release \
  --sha <release-sha> \
  --target-ref release/YYYY.M.PATCH \
  -f [email protected] \
  -f [email protected] \
  -f run_release_soak=true \
  -f npm_telegram_provider_mode=mock-openai

​

Vitest

• Full Release Validation 摘要中显示的已派发 CI 运行 URL
• 精确目标 SHA 上绿色通过的 CI 运行
• 在调查回归时，CI jobs 中失败或耗时过长的分片名称
• 当运行需要性能分析时，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 全局安装 smoke 的完整安装 smoke
• 按目标 SHA 复用的 root Dockerfile smoke 镜像准备，以及 QR、root/gateway、installer/Bun smoke 作业作为独立的 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，以及 openwebui
• 在请求时，于专用大磁盘运行器上提供 OpenWebUI 覆盖
• 拆分的 bundled plugin 安装/卸载线路 bundled-plugin-install-uninstall-0 到 bundled-plugin-install-uninstall-23
• 当发布检查包含 live 套件时，live/E2E 提供方套件和 Docker live 模型覆盖

​

QA 实验室

• 模拟一致性通道，将 OpenAI 候选通道与 anthropic/claude-opus-4-8 基线进行比较，使用代理行为一致性测试包
• 使用 qa-live-shared 环境的 Matrix 实时适配器目录通道
• 使用 Convex CI 凭证租约的 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 [email protected]

• smoke：快速的软件包安装／通道／代理、gateway 网络和配置重载线路
• package：安装／更新／重启／插件软件包契约，以及实时 ClawHub skill 安装证明；这是发布检查的默认值
• product：package 加上 MCP 通道、cron/subagent 清理、OpenAI 网页搜索和 OpenWebUI
• full：带有 OpenWebUI 的 Docker 发布路径分块
• custom：用于定向重跑的精确 docker_lanes 列表

​

常规发布发布自动化

1. 检出发布标签并解析其提交 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 和准确的运行 attempt 后，使用发布标签、npm dist-tag 以及已保存的 preflight_run_id 调度 OpenClaw NPM Release。
7. 验证已发布的 npm 包和 selector 回读，然后使用不可变标签和 SHA 调用可复用的 Docker Release。对于稳定版本，将 GitHub release 创建或更新为草稿，使用明确的 windows_node_tag 和候选版本已批准的 windows_node_installer_digests 调度 Windows Node Release，并验证规范的 Windows 安装程序／校验和资产。同时调度 Android Release，以构建精确标签对应的已签名 APK 及其校验和和来源证明。只有在 Docker 和两个原生资产契约均成功后，才最终确定 GitHub release。

gh workflow run openclaw-release-publish.yml \
  --ref main \
  -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 full_release_validation_run_attempt=<successful-full-release-validation-run-attempt> \
  -f npm_dist_tag=beta

gh workflow run openclaw-release-publish.yml \
  --ref main \
  -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 full_release_validation_run_attempt=<successful-full-release-validation-run-attempt> \
  -f npm_dist_tag=beta

gh workflow run openclaw-release-publish.yml \
  --ref main \
  -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 full_release_validation_run_attempt=<successful-full-release-validation-run-attempt> \
  -f npm_dist_tag=latest

gh workflow run plugin-clawhub-new.yml \
  --ref main \
  -f plugins=@openclaw/name \
  -f ref=<full-40-character-release-sha> \
  -f pretag_validation=true \
  -f dry_run=true

​

NPM 工作流输入

• tag：必需的发布标签，例如 v2026.4.2、v2026.4.2-1、v2026.4.2-beta.1 或 v2026.4.2-alpha.1；当 preflight_only=true 时，也可以使用当前完整 40 字符的 workflow-branch commit SHA 进行仅验证预检
• preflight_only：true 表示仅验证／构建／打包，false 表示真正的发布路径
• preflight_run_id：已存在且成功的预检运行 id，在真正发布路径中必需，以便工作流复用已准备好的 tarball 而不是重新构建
• full_release_validation_run_id：该 tag／SHA 对应的成功 Full Release Validation 运行 id，真实发布时必需。Beta 发布可以仅基于预检并带警告继续，但稳定版／latest 推送仍然需要它。
• full_release_validation_run_attempt：与 full_release_validation_run_id 配对的精确正整数运行尝试次数；只要提供了运行 id 就必需，这样重跑就不能在发布期间改变授权证据
• release_publish_run_id：已批准的 OpenClaw Release Publish 运行 id；当该工作流由其父级触发时必需（bot-actor 真实发布调用）
• plugin_npm_run_id：成功且与精确 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 预检运行 id；当 publish_openclaw_npm=true 或 plugin_publish_scope=all-publishable 时必需
• full_release_validation_run_id：成功的 Full Release Validation 运行 id；当 publish_openclaw_npm=true 或 plugin_publish_scope=all-publishable 时必需
• full_release_validation_run_attempt：与 full_release_validation_run_id 配对的精确正整数运行尝试次数；只要提供了运行 id 就必需
• 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 或 extended-stable
• publish_docker_only：仅适用于 extended-stable 的恢复／收尾路径。它要求 publish_openclaw_npm=false，并提供完整的预检和 Full Release Validation 证据，然后在调用 Docker 发布前验证精确的 npm 软件包、选择器和 tarball 摘要。
• plugin_publish_scope：默认为 all-publishable；仅在 publish_openclaw_npm=false 时，将其设为 selected 用于针对特定插件的修复工作
• plugins：当 plugin_publish_scope=selected 时，以逗号分隔的 @openclaw/* 软件包名称
• publish_openclaw_npm：默认为 true；仅在将该工作流用作仅插件修复编排器时设为 false
• release_profile：用于发布证据摘要的发布覆盖范围配置；默认为 from-validation，从验证清单中读取，或改为 beta、stable 或 full
• wait_for_clawhub：默认为 false，因此 npm 可用性不会受到 ClawHub 旁路流程的阻塞；仅当工作流完成必须包含 ClawHub 完成状态时设为 true

• ref：要验证的分支、标签或完整 commit SHA。涉及密钥的检查要求解析后的 commit 必须可从 OpenClaw 分支或发布标签到达。
• run_release_soak：为 beta 发布检查启用全面的实时／E2E、Docker 发布路径，以及所有自首次以来升级存活者 soak。它会被 release_profile=stable 和 release_profile=full 强制开启。

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

​

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

1. 运行带有 preflight_only=true 的 OpenClaw NPM Release。在尚未存在标签之前，你可以使用当前完整 workflow 分支的 commit SHA，对 preflight workflow 进行仅验证的 dry run。
2. 正常的 beta-first 流程请选择 npm_dist_tag=beta，只有在你有意直接发布稳定版时才选择 latest。
3. 当你希望通过一次手动 workflow 同时获得正常 CI、实时 prompt cache、Docker、QA Lab、Matrix 和 Telegram 覆盖时，在 release branch、release tag 或完整 commit SHA 上运行 Full Release Validation。如果你有意只需要确定性的正常测试图，则改为在 release ref 上手动运行 CI workflow。
4. 选择精确的非预发布 openclaw/openclaw-windows-node release tag，其签名过的 x64 和 ARM64 安装包应当发布。将其保存为 windows_node_tag，并将它们经过验证的 digest map 保存为 windows_node_installer_digests。release-candidate helper 会记录这两项，并将它们包含在其生成的发布命令中。
5. 保存成功的 preflight_run_id、full_release_validation_run_id 和精确的 full_release_validation_run_attempt。
6. 从受信任的 main 运行 OpenClaw Release Publish，使用相同的 tag、相同的 npm_dist_tag、所选的 windows_node_tag、其已保存的 windows_node_installer_digests、已保存的 preflight_run_id、full_release_validation_run_id 和 full_release_validation_run_attempt。它会先将外部化插件发布到 npm 和 ClawHub，然后再推进 OpenClaw npm 包。
7. 如果发布落在 beta 上，使用 openclaw/releases/.github/workflows/openclaw-npm-dist-tags.yml workflow 将该稳定版本从 beta 提升到 latest。
8. 如果发布有意直接发布到 latest，并且 beta 应立即跟随同一个稳定构建，则使用相同的 release workflow 将两个 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
• .github/workflows/docker-release.yml
• scripts/resolve-openclaw-package-candidate.mts
• scripts/openclaw-npm-release-check.ts
• scripts/package-mac-dist.sh
• scripts/make_appcast.sh

​

相关

• 发布渠道