发布策略
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 分开包含。
下游打包¶
要使用发布锁:
- 从 GitHub 发布下载
openclaw-<version>-dependency-evidence.zip。打开dependency-evidence/npm-package-locks.json(schemaVersion: 1),并选择与确切包name和version匹配的packages条目。 - 拒绝具有非空
omittedWorkspaceDependencies数组的条目。这些是部分锁:生成器会省略在同一发布中发布的同级workspace:运行时依赖。报告在packagesWithOmittedWorkspaceDependencies中统计这些条目。 - 验证
dependency-evidence/dependency-evidence-manifest.json的releaseSha、报告的sourceSha以及你固定的 OpenClaw 提交全部匹配。报告还记录源pnpm-lock.yaml的 SHA-256。 - 使用两空格 JSON 缩进和末尾换行符将
entry.lock序列化为package-lock.json,然后将其 SHA-256 与entry.lockSha256进行验证。 - 在
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 中。凭据处理和紧急流程仍保留在私有维护者运行手册中。下方旧章节链接指向其对应流程。
每次稳定发布后,在 main 上使用 pnpm plugin-sdk:shipped-surface:gen -- --release <stable tag>
重新生成已提交的已发布 Plugin SDK 接口面,
然后运行 pnpm plugin-sdk:surface:check。将生成的
scripts/lib/plugin-sdk-shipped-surface.json 作为稳定收尾的一部分提交;不要
手动编辑它。该清单记录稳定标签的带类型公共声明,
以便后续导出预算缩减不能授权移除它们。
包验收.
发布要求.
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw