OpenClaw 采用 beta-first 发布节奏，所有版本先发到 npm beta 通道验证，通过后才晋升到 latest。版本格式为 YYYY.M.D（月日不补零），stable 和 beta 通道分别对应不同的发布标签和验证流程。维护者发布版本时需要依次完成 pnpm release:prep、preflight 验证、Full Release Validation 等检查，最后通过 OpenClaw Release Publish 工作流完成发布。npm 预发布必须通过控制 UI 构建检查和依赖证据审核才能继续。

OpenClaw 发布策略：版本命名与通道选择

OpenClaw 有三个公开发布通道：

stable：带标签的发布版，默认发布到 npm beta，或经显式请求发布到 npm latest
beta：预发布标签，发布到 npm beta
dev：main 分支的最新快照

版本命名规则

版本类型	格式	Git 标签
稳定版	`YYYY.M.D`	`vYYYY.M.D`
稳定修正版	`YYYY.M.D-N`	`vYYYY.M.D-N`
Beta 预发布版	`YYYY.M.D-beta.N`	`vYYYY.M.D-beta.N`

月和日不补零（例如 2026.4.2，而非 2026.04.02）
latest：当前晋升的稳定 npm 版本
beta：当前 beta 安装目标
稳定版和修正版默认发布到 npm beta；维护者可显式指定 latest，或后续从 beta 晋升
每个 OpenClaw 稳定版同时发布 npm 包和 macOS 应用；beta 发布默认只验证和发布 npm/package 路径，mac 应用的构建/签名/公证保留给稳定版，除非显式请求

发布节奏

版本走 beta-first 流程：所有更改先进入 beta 通道验证，验证通过后才发布 stable
稳定版只跟随最新 beta 验证通过后发布
维护者通常从当前 main 创建 release/YYYY.M.D 分支，在该分支上做发布验证和修复，不阻塞 main 上的新开发
如果 beta 标签已推送或发布后需要修复，维护者应创建下一个 -beta.N 标签，而不是删除或重新创建旧的 beta 标签
详细的发布步骤、权限审批、凭证和回滚笔记只对维护者开放

发布操作者完整清单

以下清单公开了发布流程的工作步骤。私有凭证、签名、公证、dist-tag 恢复和紧急回滚细节在维护者专用 runbook 中。

从当前 main 开始：拉取最新代码，确认目标提交已推送，确认当前 main 的 CI 足够健康，可以从中创建分支。
更新 CHANGELOG.md：用 /changelog 从真实的提交历史重写顶部 CHANGELOG.md 章节，保留用户可见的条目，提交并推送，在分支前再 rebase/pull 一次。
审查兼容性记录：检查 src/plugins/compat/registry.ts 和 src/commands/doctor/shared/deprecation-compat.ts 中的发布兼容性记录。仅在升级路径仍然覆盖时删除过期的兼容性，否则记录为何特意保留。
创建发布分支：从当前 main 创建 release/YYYY.M.D，不要在 main 上直接做常规发布工作。
版本提升并运行 release:prep：提升所有需要的版本位置，然后运行 pnpm release:prep。它会按顺序刷新插件版本、插件清单、配置 schema、捆绑通道配置元数据、配置文档基线、插件 SDK 导出和插件 SDK API 基线。在打标签前提交任何生成的漂移。然后运行本地确定性预检查：pnpm check:test-types、pnpm check:architecture、pnpm build && pnpm ui:build、pnpm release:check。
运行 OpenClaw NPM Release 预检查：使用 preflight_only=true。在标签存在前，允许使用完整的 40 字符发布分支 SHA 进行仅验证的预检查。预检查生成精确检出依赖图的依赖发布证据，并将其存储在 npm preflight artifact 中。保存成功的 preflight_run_id。
启动所有发布前测试：使用 Full Release Validation 工作流对发布分支、标签或完整提交 SHA 运行。这是四个主要发布测试模块（Vitest、Docker、QA Lab、Package）的唯一手动入口点。
验证失败时修复：在发布分支上修复后，只运行最小范围的失败文件、lane、workflow job、package profile、provider 或 model allowlist 来证明修复。只有当更改范围使之前的证据失效时，才重新运行完整的 umbrella。
打标签并发布：对于 beta，打 vYYYY.M.D-beta.N 标签，然后在匹配的 release/YYYY.M.D 分支上运行 pnpm release:candidate -- --tag vYYYY.M.D-beta.N。该帮助程序运行本地生成的发布检查、调度或验证完整发布验证和 npm preflight 证据、运行 Parallels 和 Telegram 包证明、记录插件 npm 和 ClawHub 计划，并只在证据包通过后打印精确的 OpenClaw Release Publish 命令。OpenClaw Release Publish 调度可选或所有可发布插件包到 npm 和 ClawHub，并在插件 npm 发布成功后晋升准备好的 OpenClaw npm preflight artifact 到匹配的 dist-tag。然后创建或更新匹配的 GitHub release/prerelease 页面，上传依赖证据。如果在发布 beta 后需要修复，创建下一个匹配的 beta 编号，不要删除或重写旧的 beta。
发布后验证：验证 npm 包、可选的 Telegram E2E、dist-tag 晋升（如需），确认生成的 GitHub release 页面，并运行发布公告步骤。

发布前置检查步骤

在发布前必须按顺序完成以下检查：

bash

# 1. 运行测试类型检查（在发布预检查前，确保测试 TypeScript 覆盖）
pnpm check:test-types

# 2. 运行架构检查（在发布预检查前，确保导入循环和架构边界检查通过）
pnpm check:architecture

# 3. 构建以确保 dist/* 工件和 Control UI bundle 存在
pnpm build && pnpm ui:build

# 4. 运行发布预准备（在版本提升后、打标签前）
pnpm release:prep

# 5. 运行发布检查
pnpm release:check

pnpm release:prep 在根版本提升后和打标签前运行。它执行每个确定性发布生成器，这些生成器在版本/配置/API 更改后经常出现漂移：插件版本、插件清单、基础配置 schema、捆绑通道配置元数据、配置文档基线、插件 SDK 导出和插件 SDK API 基线。pnpm release:check 以检查模式重新运行这些守卫，并在运行包发布检查前一次性报告每个发现的生成漂移失败。

bash

# 6. 本地预检查（打标签前）
RELEASE_TAG=vYYYY.M.D-beta.N pnpm release:fast-pretag-check

# 7. npm 发布检查（打标签后、发布前）
RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts

# 8. 发布后验证
node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D

对于稳定修正版（YYYY.M.D-N），发布后验证器还会检查从 YYYY.M.D 到 YYYY.M.D-N 的临时前缀升级路径，确保修正版不会让旧的全局安装静默留在旧基础上。

npm 发布预检查在以下情况会失败并中止：tarball 缺少 dist/control-ui/index.html 或 dist/control-ui/assets/ 为空（防止再次发布空浏览器控制台）。

发布后验证还会检查已发布插件的入口点和包元数据是否存在于安装的 registry 布局中。如果发布缺少插件运行时负载，则无法晋升到 latest。

pnpm test:install:smoke 还会对候选更新 tarball 执行 npm pack unpackedSize 预算检查，因此安装程序 e2e 会在发布路径之前捕获意外的包膨胀。

如果发布工作影响了 CI 规划、扩展时序 manifest 或测试矩阵，需要在审批前从 .github/workflows/plugin-prerelease.yml 重新生成并审查 plugin-prerelease-extension-shard 矩阵输出。

发布测试模块详解

Full Release Validation 是操作者从一个入口点启动所有发布前测试的方式。对于快速移动分支上的固定提交证明，使用以下帮助程序：

bash

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

该帮助程序创建 release-ci/<sha>-... 临时分支，从该分支调度 Full Release Validation，验证每个子工作流的 headSha 匹配目标，然后删除临时分支。

对于发布分支或标签验证，从受信任的 main workflow ref 运行，并将发布分支或标签作为 ref 传入：

bash

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

使用 release_profile 选择 live/provider 广度：

minimum：最快的发布关键 OpenAI/core live 和 Docker 路径
stable：minimum 加上稳定 provider/backend 覆盖，用于发布审批
full：stable 加上广泛的 advisory provider/media 覆盖

使用 run_release_soak=true 与 stable 一起时，在晋升前运行详尽的 live/E2E、Docker 发布路径和有边界的已发布升级幸存者扫描。full 隐含 run_release_soak=true。

不要将完整的 umbrella 用作焦点修复后的首次重试。如果一个盒子失败，使用失败的子工作流、job、Docker lane、package profile、model provider 或 QA lane 进行下一次证明。只有当修复更改了共享发布编排或使之前的所有盒子证据失效时，才重新运行完整的 umbrella。

对于有边界的恢复，将 rerun_group 传递给 umbrella：all、ci、plugin-prerelease、release-checks 以及更窄的组如 install-smoke、cross-os、live-e2e、package、qa、qa-parity、qa-live、npm-telegram。

子工作流从运行 Full Release Validation 的受信任 ref 调度（通常是 --ref main），即使目标 ref 指向较旧的发布分支或标签。

Vitest 测试

CI 子工作流是 Vitest 盒子。手动 CI 绕过变更范围检测，强制对发布候选运行完整的正常测试图：Linux Node 分片、捆绑插件分片、插件和通道合约分片、Node 22 兼容性、check-*、check-additional-*、构建工件烟雾检查、文档检查、Python 技能、Windows、macOS、Android 和 Control UI i18n。

使用这个盒子回答"源代码树是否通过了完整的正常测试套件？"

bash

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

Docker 测试

Docker 盒子位于 OpenClaw Release Checks 中，通过 openclaw-live-and-e2e-checks-reusable.yml 和发布模式的 install-smoke 工作流运行。它通过打包的 Docker 环境验证发布候选，而不仅仅是源代码级测试。

发布 Docker 覆盖包括：

完整的安装烟雾检查（含 slow Bun 全局安装烟雾）
根 Dockerfile 烟雾镜像准备/按目标 SHA 复用
仓库 E2E lanes
发布路径 Docker chunks：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 覆盖（在 plugins-runtime-services chunk 中，请求时）
分拆的捆绑插件安装/卸载 lanes bundled-plugin-install-uninstall-0 到 bundled-plugin-install-uninstall-23
live/E2E provider 套件和 Docker live 模型覆盖

使用 Docker artifacts 进行焦点恢复。发布路径调度器上传 .artifacts/docker-tests/，包含 lane 日志、summary.json、failures.json、阶段时序、调度器计划 JSON 和重试命令。

QA Lab 测试

QA Lab 盒子也是 OpenClaw Release Checks 的一部分。它是智能体行为和通道级别的发布门禁，与 Vitest 和 Docker 包机制分开。

发布 QA Lab 覆盖包括：

mock 奇偶校验 lane（将 OpenAI 候选 lane 与 Opus 4.6 基线比较）
快速 live Matrix QA 配置文件（使用 qa-live-shared 环境）
live Telegram QA lane（使用 Convex CI 凭证租赁）
pnpm qa:otel:smoke（需要显式本地证明发布遥测时运行）

使用这个盒子回答"发布在 QA 场景和 live 通道流程中是否正确运行？"

Package 测试

Package 盒子是可安装产品的门禁。它由 Package Acceptance 和解析器 scripts/resolve-openclaw-package-candidate.mjs 支持。

支持的候选来源：

source=npm：openclaw@beta、openclaw@latest 或精确版本
source=ref：用选定的 workflow_ref harness 打包受信任的 package_ref 分支/标签/SHA
source=url：下载 HTTPS .tgz 并携带所需的 package_sha256
source=artifact：复用另一个 GitHub Actions 运行上传的 .tgz

OpenClaw Release Checks 使用 source=artifact 运行 Package Acceptance，使用准备的发布包 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。

常用 package 配置文件：

smoke：快速包安装/通道/智能体、网关网络和配置重载 lanes
package：安装/更新/重启/插件包合约加 live ClawHub 技能安装证明（发布检查默认）
product：package 加 MCP 通道、cron/subagent 清理、OpenAI web 搜索和 OpenWebUI
full：Docker 发布路径 chunks 加 OpenWebUI
custom：精确的 docker_lanes 列表，用于焦点重试

bash

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

发布发布自动化流程

OpenClaw Release Publish 是正常的可变发布入口点。它按顺序编排受信任的发布者工作流：

检出发布标签并解析其提交 SHA
验证标签可从 main 或 release/* 到达
运行 pnpm plugins:sync:check
使用 publish_scope=all-publishable 调度 Plugin NPM Release
使用相同范围和 SHA 调度 Plugin ClawHub Release
使用发布标签、npm dist-tag 和保存的 preflight_run_id 调度 OpenClaw NPM Release

Beta 发布示例：

bash

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

稳定版发布到默认 beta dist-tag：

bash

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

稳定版直接晋升到 latest：

bash

gh workflow run openclaw-release-publish.yml \
  --ref release/YYYY.M.D \
  -f tag=vYYYY.M.D \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f npm_dist_tag=latest

仅用于焦点修复或重新发布时，才使用底层的 Plugin NPM Release 和 Plugin ClawHub Release 工作流。

NPM 工作流的输入参数

OpenClaw NPM Release 接受以下操作者控制的输入：

参数	说明
`tag`	必填，发布标签如 `v2026.4.2`、`v2026.4.2-1`、`v2026.4.2-beta.1`；`preflight_only=true` 时也可用当前完整 40 字符工作流分支提交 SHA
`preflight_only`	`true` 仅验证/构建/打包，`false` 为真正发布路径
`preflight_run_id`	真正发布路径必填，复用成功 preflight 的已准备 tarball
`npm_dist_tag`	发布目标标签，默认 `beta`

OpenClaw Release Publish 接受以下输入：

参数	说明
`tag`	必填，必须已存在的发布标签
`preflight_run_id`	成功的 `OpenClaw NPM Release` preflight 运行 ID；`publish_openclaw_npm=true` 时必填
`npm_dist_tag`	OpenClaw 包的 npm 目标标签
`plugin_publish_scope`	默认为 `all-publishable`；仅焦点修复用 `selected`
`plugins`	`plugin_publish_scope=selected` 时的逗号分隔 `@openclaw/*` 包名
`publish_openclaw_npm`	默认为 `true`；仅当用作纯插件修复编排器时设 `false`
`wait_for_clawhub`	默认为 `false`；仅当工作流完成必须包括 ClawHub 完成时设 `true`

OpenClaw Release Checks 接受以下输入：

参数	说明
`ref`	要验证的分支、标签或完整提交 SHA。带机密的检查要求解析的提交可从 OpenClaw 分支或发布标签到达
`run_release_soak`	选择加入详尽的 live/E2E、Docker 发布路径和全版本升级幸存者浸泡。`release_profile=full` 时强制开启

规则：

稳定版和修正版标签可发布到 beta 或 latest
Beta 预发布标签只能发布到 beta
OpenClaw NPM Release 允许完整提交 SHA 输入仅当 preflight_only=true
OpenClaw Release Checks 和 Full Release Validation 始终是仅验证的
真正发布路径必须使用与 preflight 相同的 npm_dist_tag；工作流在继续发布前验证该元数据

稳定版 NPM 发布步骤

运行 OpenClaw NPM Release，preflight_only=true
- 在标签存在前，可使用当前完整工作流分支提交 SHA 进行仅验证的干运行
选择 npm_dist_tag=beta 用于正常的 beta-first 流程，或选择 latest 仅当有意直接发布稳定版
运行 Full Release Validation 对发布分支、发布标签或完整提交 SHA（从单个手动工作流获得正常 CI 加 live prompt cache、Docker、QA Lab、Matrix 和 Telegram 覆盖）
如果只需要确定性的正常测试图，运行手动 CI 工作流对发布 ref
保存成功的 preflight_run_id
运行 OpenClaw Release Publish，使用相同的 tag、相同的 npm_dist_tag 和保存的 preflight_run_id；它在晋升 OpenClaw npm 包之前将外部化插件发布到 npm 和 ClawHub
如果发布到了 beta，使用私有 openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml 工作流将该稳定版本从 beta 晋升到 latest
如果发布直接到了 latest 且 beta 应立即跟随相同的稳定构建，使用相同的私有工作流将两个 dist-tag 指向该稳定版本，或让计划的自我修复同步稍后移动 beta

dist-tag 变更位于私有仓库中，因为它仍然需要 NPM_TOKEN，而公共仓库保持仅 OIDC 发布。

macOS 稳定版发布就绪检查

macOS 稳定版发布还需要验证更新分发入口：

GitHub Release 必须包含打包好的 .zip、.dmg 和 .dSYM.zip
发布后 main 分支的 appcast.xml 必须指向新版本的稳定 zip（私有 macOS 发布工作流自动提交它，或当直接推送被阻止时创建 appcast PR）
打包的应用必须满足：
- 非 debug 的 Bundle ID
- 非空的 Sparkle feed URL
- CFBundleVersion 达到或超过该版本的 Sparkle 构建地板值

公开参考文件

维护者使用私有发布文档 openclaw/maintainers/release/README.md 获取实际 runbook。

常见问题

OpenClaw 的 stable、beta、dev 通道有什么区别，我应该用哪个？

稳定版（stable）是经过完整验证的正式发布，发布到 npm latest 或 beta；beta 是预发布版，包含最新功能和修复，发布到 npm beta；dev 是 main 分支的最新快照，未经发布验证。日常使用推荐 beta 通道（npm install -g openclaw@beta），生产环境推荐 latest。

版本号 YYYY.M.D 怎么读，为什么不补零？

格式为 年份.月.日，例如 2026.4.2 表示 2026 年 4 月 2 日发布。月和日不补零（不写成 2026.04.02），这样可以直接从版本号看出发布时间，不需要查日历。

我想运行发布验证，怎么从命令行启动 Full Release Validation？

使用 gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D。对快速移动分支上的固定提交，先运行 pnpm ci:full-release --sha <41 位提交 SHA> 创建固定临时分支。不要直接用 --ref main -f ref=<sha>，原始提交 SHA 不能用作 workflow dispatch ref。

OpenClaw 发布策略：版本命名与通道选择 ​

版本命名规则 ​

发布节奏 ​

发布操作者完整清单 ​

发布前置检查步骤 ​

发布测试模块详解 ​

Vitest 测试 ​

Docker 测试 ​

QA Lab 测试 ​

Package 测试 ​

发布发布自动化流程 ​

NPM 工作流的输入参数 ​

稳定版 NPM 发布步骤 ​

macOS 稳定版发布就绪检查 ​

公开参考文件 ​

常见问题 ​

OpenClaw 的 stable、beta、dev 通道有什么区别，我应该用哪个？ ​

版本号 YYYY.M.D 怎么读，为什么不补零？ ​

我想运行发布验证，怎么从命令行启动 Full Release Validation？ ​

OpenClaw 发布策略：版本命名与通道选择

版本命名规则

发布节奏

发布操作者完整清单

发布前置检查步骤

发布测试模块详解

Vitest 测试

Docker 测试

QA Lab 测试

Package 测试

发布发布自动化流程

NPM 工作流的输入参数

稳定版 NPM 发布步骤

macOS 稳定版发布就绪检查

公开参考文件

常见问题

OpenClaw 的 stable、beta、dev 通道有什么区别，我应该用哪个？

版本号 YYYY.M.D 怎么读，为什么不补零？

我想运行发布验证，怎么从命令行启动 Full Release Validation？