跳转至

发布策略

OpenClaw 提供用于日常使用的稳定版发布、用于测试的测试版发布, 以及面向偏好较旧 Gateway 维护线的用户的扩展稳定版发布。本页说明这些选择,以及一个发布经过哪些检查。 如需切换渠道,请参阅发布渠道。

发布渠道

渠道 获取内容
稳定版 已提升到 npm latest 的常规发布。
测试版 npm beta 上的候选版本。这可能是预发布版本,也可能是等待提升的最终版本。
扩展稳定版 来自上一个已完成月份的 Gateway 维护发布,位于 npm extended-stable。
开发版 main 的移动头部,用于开发。

扩展稳定版包括 Gateway、官方 npm 插件和 Docker 镜像。 它不包括原生应用或 ClawHub 发布,也不会改变 常规稳定版渠道。其 GitHub 发布不会标记为 Latest。当 main 推进到下一个月份时,月度线退役。

版本命名

发布类型 版本示例
常规正式版 2026.9.6
测试版预发布 2026.9.6-beta.1
常规修正版 2026.9.6-1
扩展稳定版 2026.8.33,其下一个维护发布为 2026.8.34

版本使用 year.month.patch,不补零。patch 是月份内的发布 编号,而不是月份中的日期。常规发布使用低于 33 的 patch;扩展稳定版从 33 开始。Git 标签会添加 v,例如 v2026.9.6。 发布标签是附注标签且经过签名。共享发布工作流会在 检出或证据下载之前验证标签签名,并拒绝轻量级、 未签名或未经验证的标签。这也适用于恢复和重新发布: 历史未签名标签不符合共享发布工作流的条件, 并且恢复必须使用新的已签名发布版本,而不是替换标签。

已发布的 npm 版本和发布标签永远不会被替换。修复会获得一个 新版本。历史性的仅 alpha 版本不会推进常规发布 编号;alpha 发布已退役。

发布节奏

发布通常先进入 beta,验证后移动到稳定版。 对于核心以及每个已发布的官方 npm 插件,beta 必须至少与 latest 一样新;已经更新的 beta 保持不变。预发布版本比 具有相同基础编号的最终版本更旧。

发布到 beta 渠道的最终版本仍须满足以下稳定版 验证要求。仅凭 npm 渠道不能确定适用哪些 检查。

发布验证

稳定版发布需要稳定版或完整验证、运行时间更长的浸泡测试, 以及阻塞性性能检查。这些要求也适用于首次发布在 beta 渠道上的最终版本。Beta 配置的证据不能使稳定版合格。

每个失败的测试都需要发布负责人明确决定:阻塞项或偶发故障。 在同一个 Release SHA 上最多重跑偶发故障两次,在 main 上提交其并行修复 issue 或 PR,并保留原始失败。不要仅为了清除偶发故障而重新切版、更改 工具或启动另一次完整发布验证;仍为红色的选定作业会阻塞发布。

阻塞性作业包括 CI 覆盖率门禁、seal/evidence、 Build Artifacts、安装冒烟、survivor lanes、update-first-hop-compat*、pack/npm 资格验证、包完整性,以及所有 Linux/Windows/macOS Gateway 检查, 包括 Release Checks 中的 Windows 打包安装/升级检查。已取消的 运行仍会阻塞。选定的 openclaw/ci-gate 必须成功;失败、缺失、 跳过或取消的覆盖率会阻塞。发布豁免不能绕过失败 或必需覆盖率。验证覆盖源代码 CI、包、插件、 Gateway 安装和升级,以及选定的应用、UI、Telegram、QA 和 实时提供商检查。全组资格验证包括跨 Linux、Windows 和 macOS 的全部九个 Gateway 安装/升级组合。其他覆盖率 因配置和选定操作系统而异。检查该发布记录的 覆盖率:跳过或延迟的检查不算通过。

对于选定的官方 npm 插件,完整发布验证会打包并验证 拟发布的精确 tarball,并记录其不可变构件描述符。发布过程使用这些相同字节。未解包的源代码 fixture 不 参与,除非 npm 将其包含在已发布的 tarball 中。

依赖项公告永远不会阻塞 CI、本地提交或延迟发布。普通 pull-request、push 和定时 CI 会跳过生产依赖项审计。它 仅对以 full-release-validation- 或 release-native-android- 开头的发布 dispatch ID 运行,其中每个审计失败都是退出代码为 0 的警告。可选的生产审计 pre-commit 钩子遵循相同策略。 独立的每日 Dependency Audit 保持严格用于分诊,并且不是必需的 PR 检查。发布依赖项证据记录每个公告发现,无论 严重程度如何。依赖项修复在发布后通过 main 发布。发布 pnpm deps:vuln:gate 仍会因已知恶意软件而停止发布,这标识 的是受入侵的包,而不是漏洞公告。

main CI 的健康状况不会门禁发布。验证和发布从 发布分支运行,并使用固定的发布工具,因此红色的 main 不是 等待、重新切版或暂停的理由。

请参阅完整发布验证了解按配置 的覆盖范围以及如何解释结果。

冻结的资格身份

新的候选资格记录三个独立身份:

  • C — 候选: 被检查源码和发布字节的确切提交。
  • Q — 资格: 在 C 处的完整工作流闭包,包括可复用工作流、本地操作、脚本、规划器、契约和覆盖数据。默认 Q=C。
  • P — 准入、验证和发布工具: 一个独立受信任的主修订版本或受保护发布标签。P 可能与 C/Q 不同;C/Q 不需要是 P 的祖先。对 P 的信任不能替代对 C 的资格认定。

规范的 SHA 固定辅助工具首先要求 P 在一个不可变准入工件中记录已审查的操作员证明、完整的规范化输入以及仅数据的冻结 Q 覆盖。只有在那之后,同一辅助工具才会从 Q 处的不可变 release-ci/* 引用分发完整发布验证。发布 release-publish/* 标签属于 P,绝不能仅仅为了让验证运行而属于 Q。准入不是成功的测试结果或发布批准。

缺少所需资格契约的候选需要一次有意的回移。辅助工具不会静默使用未来主分支检查或导入仅主分支场景。对资格测试框架的修复会改变 C 和 Q,并要求新绑定的证据;仅针对 P 的验证器/发布者修复可以保留 C/Q 及其原始工件。显式的受信任主分支或受保护标签跨修订验证仅限于诊断、主资格和发布后置信请求。它不能提供新的最终候选资格。现有历史发布请求保留其原始含义并保持可恢复。新的发布资格要求已准入的 Q=C。

证据复用同时保留原始生产者身份和当前消费者身份、输入、覆盖以及工件溯源。它不能将旧运行重新标记为候选所有。对账是只读的;显式恢复仅限于在任何 qualification-ref 变更或 FRV 分发之前的候选请求。不确定的写入永远不会授权另一次分发。所有发布门控、稳定浸泡、阻塞性能、环境批准和精确字节检查均保持不变。

本地契约测试可以证明输入绑定、拒绝和恢复行为。它们不能证明托管工作流准入、环境访问、OIDC、签名或发布。请分别报告托管证据和未测试的部署前提;本地绿色检查不是托管发布回执。

包和应用可能在不同时间可用

已发布的 Gateway 发布并不意味着每个原生应用都已就绪。应用的签名和发布可以独立于 npm、Docker 和 GitHub 发布完成。

请检查每个平台的发布资产和公告。待处理的应用构建或已接受的发布请求不是已完成的应用发布。Extended-stable 是 Gateway 分发,不发布原生应用。

发布说明和验证

发布说明 描述面向用户的变更。GitHub 发布还包含验证结果、依赖报告以及对已发布包的检查。这些记录标识了受测版本和已交付的文件。后续文档更新可以在不重新构建或替换包的情况下改进发布说明。

Beta 发布说明显示自发布前由 npm 的 beta 通道选择的版本以来的变更。当 beta 和 latest 选择同一个包时,该基线可以是一个稳定版本;它不一定是最后一个 GitHub 预发布。每个 beta 冻结其自己的变更日志和贡献记录。稳定发布说明自上一个稳定发布以来保持累积。

有关依赖审查,请参阅依赖锁定。发布依赖归档将 npm 格式锁与包 tarball 分开包含。

下游打包

要使用发布锁:

  1. 从 GitHub 发布下载 openclaw-<version>-dependency-evidence.zip。打开 dependency-evidence/npm-package-locks.json(schemaVersion: 1),并选择与确切包 name 和 version 匹配的 packages 条目。
  2. 拒绝具有非空 omittedWorkspaceDependencies 数组的条目。这些是部分锁:生成器会省略在同一发布中发布的同级 workspace: 运行时依赖。报告在 packagesWithOmittedWorkspaceDependencies 中统计这些条目。
  3. 验证 dependency-evidence/dependency-evidence-manifest.json 的 releaseSha、报告的 sourceSha 以及你固定的 OpenClaw 提交全部匹配。报告还记录源 pnpm-lock.yaml 的 SHA-256。
  4. 使用两空格 JSON 缩进和末尾换行符将 entry.lock 序列化为 package-lock.json,然后将其 SHA-256 与 entry.lockSha256 进行验证。
  5. 在 npm ci 之前,将源 pnpm-workspace.yaml 覆盖项带入消费方 package.json,或将嵌套的 dependencies 和 optionalDependencies 规范重写为其锁定版本。生成的锁编码了工作区覆盖项,因此未修改的规范可能无法通过 npm 的锁同步检查。

配套的 npm-package-locks.md 包含计数和一个包表。每个条目记录 bundleRuntimeDependencies 和直接依赖计数,以便打包者识别需要外部锁的无锁包。每个条目还记录一个按路径排序的 bundledDependencies 数组,包含 path、name、version 和 parent。这些依赖在 npm 锁中带有 inBundle: true;parent 标识最近的包含非捆绑包,其 resolved 和 integrity 验证承载这些依赖字节的 tarball。报告拒绝缺失或不可验证的载体,并保留锁负载。Markdown 表按包统计捆绑依赖并包含其总数。

维护者流程

发布准备、发布命令、批准和恢复位于 release-maintainer skill 中。凭据处理和紧急流程仍保留在私有维护者运行手册中。下方旧章节链接指向其对应流程。

Linux 发布.

发布变更日志.

仅变更日志资格判定.

扩展稳定版准备与发布.

扩展稳定版恢复.

常规发布检查清单.

可恢复的发布编排.

延迟 CI 恢复.

夜间验证复用.

发布工具 CI 范围.

稳定 main 收尾.

每次稳定发布后,在 main 上使用 pnpm plugin-sdk:shipped-surface:gen -- --release <stable tag> 重新生成已提交的已发布 Plugin SDK 接口面, 然后运行 pnpm plugin-sdk:surface:check。将生成的 scripts/lib/plugin-sdk-shipped-surface.json 作为稳定收尾的一部分提交;不要 手动编辑它。该清单记录稳定标签的带类型公共声明, 以便后续导出预算缩减不能授权移除它们。

发布后文档发布.

源代码和包门禁.

旧版更新器验证.

运行时生成设计提案(非已发布行为).

发布验证通道.

包验收.

发布资格判定.

Bootstrap-token 验证.

已准备的发布.

中断的准备与发布.

已发布版本恢复.

常规发布与验证.

发布要求.

发布工作流参考.

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw