openclaw-release-maintainer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenClaw Release Maintainer

OpenClaw 发布维护指南

Use this skill for release and publish-time workflow. Keep ordinary development changes and GHSA-specific advisory work outside this skill.

本指南适用于发布及发布阶段工作流，普通开发改动和GHSA专属安全公告相关工作不在本指南适用范围内。

Respect release guardrails

遵守发布防护规则

Do not change version numbers without explicit operator approval.
Ask permission before any npm publish or release step.
This skill should be sufficient to drive the normal release flow end-to-end.
Use the private maintainer release docs for credentials, recovery steps, and mac signing/notary specifics, and use
```
docs/reference/RELEASING.md
```
for public policy.
Core
```
openclaw
```
publish is manual
```
workflow_dispatch
```
; creating or pushing a tag does not publish by itself.

未经运营人员明确批准，不得修改版本号。
执行任何 npm publish 或发布步骤前需先申请权限。
本指南足以覆盖正常发布流程的全链路需求。
凭证、恢复步骤、mac 签名/公证相关细节请参考私有维护者发布文档，公共发布规则请参考
```
docs/reference/RELEASING.md
```
。
核心
```
openclaw
```
发布需手动触发
```
workflow_dispatch
```
，仅创建或推送标签不会自动触发发布。

Keep release channel naming aligned

统一发布渠道命名规则

```
stable
```
: tagged releases only, with npm dist-tag
```
latest
```
```
beta
```
: prerelease tags like
```
vYYYY.M.D-beta.N
```
, with npm dist-tag
```
beta
```
Prefer
```
-beta.N
```
; do not mint new
```
-1
```
or
```
-2
```
beta suffixes
```
dev
```
: moving head on
```
main
```
When using a beta Git tag, publish npm with the matching beta version suffix so the plain version is not consumed or blocked

```
stable
```
：仅含打标签的正式版本，npm dist-tag 为
```
latest
```
```
beta
```
：预发布标签格式为
```
vYYYY.M.D-beta.N
```
，npm dist-tag 为
```
beta
```
优先使用
```
-beta.N
```
后缀，不要新增
```
-1
```
或
```
-2
```
这类 beta 后缀格式
```
dev
```
：对应
```
main
```
分支的最新头部提交
使用 beta 版 Git 标签时，npm 发布版本需要携带对应的 beta 后缀，避免无后缀的纯版本号被意外拉取或占用。

Handle versions and release files consistently

统一处理版本和发布文件

Version locations include:

```
package.json
```
```
apps/android/app/build.gradle.kts
```
```
apps/ios/Sources/Info.plist
```
```
apps/ios/Tests/Info.plist
```

apps/macos/Sources/OpenClaw/Resources/Info.plist

```
docs/install/updating.md
```
Peekaboo Xcode project and plist version fields

Before creating a release tag, make every version location above match the version encoded by that tag.
For fallback correction tags like
```
vYYYY.M.D-N
```
, the repo version locations still stay at
```
YYYY.M.D
```
.
“Bump version everywhere” means all version locations above except
```
appcast.xml
```
.
Release signing and notary credentials live outside the repo in the private maintainer docs.
Every OpenClaw release ships the npm package and macOS app together.

The production Sparkle feed lives at

https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml

, and the canonical published file is

appcast.xml

main

in the

openclaw

repo.

That shared production Sparkle feed is stable-only. Beta mac releases may upload assets to the GitHub prerelease, but they must not replace the shared
```
appcast.xml
```
unless a separate beta feed exists.
For fallback correction tags like
```
vYYYY.M.D-N
```
, the repo version still stays at
```
YYYY.M.D
```
, but the mac release must use a strictly higher numeric
```
APP_BUILD
```
/ Sparkle build than the original release so existing installs see it as newer.

版本号需同步更新到以下位置：

```
package.json
```
```
apps/android/app/build.gradle.kts
```
```
apps/ios/Sources/Info.plist
```
```
apps/ios/Tests/Info.plist
```

apps/macos/Sources/OpenClaw/Resources/Info.plist

```
docs/install/updating.md
```
Peekaboo Xcode 项目和 plist 版本字段
创建发布标签前，需确保上述所有位置的版本号和标签携带的版本号完全一致。
对于
```
vYYYY.M.D-N
```
这类修复补丁标签，仓库内上述版本位置仍保留
```
YYYY.M.D
```
即可。
“全量更新版本号”指更新上述所有位置的版本号，
```
appcast.xml
```
除外。
发布签名和公证凭证存放在仓库外的私有维护者文档中。
所有OpenClaw发布都会同步推送npm包和macOS应用。

生产环境Sparkle feed地址为

https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml

，官方发布的

appcast.xml

文件存放在

openclaw

仓库的

main

分支。

上述共享的生产Sparkle feed仅用于稳定版。Beta版macOS发布可以将资源上传到GitHub预发布版本中，但除非存在独立的beta feed，否则不得替换共享的
```
appcast.xml
```
文件。
对于
```
vYYYY.M.D-N
```
这类修复补丁标签，仓库版本仍保留
```
YYYY.M.D
```
，但mac发布必须使用比原始版本数值更高的
```
APP_BUILD
```
/Sparkle build号，确保现有安装包能识别到更新。

Build changelog-backed release notes

基于更新日志生成发布说明

Changelog entries should be user-facing, not internal release-process notes.
When cutting a mac release with a beta GitHub prerelease:
- tag
```
vYYYY.M.D-beta.N
```
  from the release commit
- create a prerelease titled
```
openclaw YYYY.M.D-beta.N
```
- use release notes from the matching
```
CHANGELOG.md
```
  version section
- attach at least the zip and dSYM zip, plus dmg if available
Keep the top version entries in
```
CHANGELOG.md
```
sorted by impact:
- ```
### Changes
```
  first
- ```
### Fixes
```
  deduped with user-facing fixes first

更新日志条目应当面向用户，不要包含内部发布流程相关的记录。
发布beta版macOS应用到GitHub预发布版本时：
- 基于发布 commit 打标签
```
vYYYY.M.D-beta.N
```
- 创建标题为
```
openclaw YYYY.M.D-beta.N
```
  的预发布版本
- 发布说明使用
```
CHANGELOG.md
```
  中对应版本章节的内容
- 至少上传zip包和dSYM zip包，如有dmg包也一并上传
```
CHANGELOG.md
```
中最新版本的条目按影响优先级排序：
- 优先放
```
### Changes
```
  章节
- ```
### Fixes
```
  章节去重后，优先放面向用户的修复内容

Run publish-time validation

执行发布前验证

Before tagging or publishing, run:

bash

node --import tsx scripts/release-check.ts
pnpm release:check
pnpm test:install:smoke

For a non-root smoke path:

bash

  OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke

After npm publish, run:

bash

node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>

This verifies the published registry install path in a fresh temp prefix.
For stable correction releases like
```
YYYY.M.D-N
```
, it also verifies the upgrade path from
```
YYYY.M.D
```
to
```
YYYY.M.D-N
```
so a correction publish cannot silently leave existing global installs on the old base stable payload.

打标签或发布前，执行以下命令：

bash

node --import tsx scripts/release-check.ts
pnpm release:check
pnpm test:install:smoke

非root权限冒烟测试执行以下命令：

bash

  OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke

npm发布完成后，执行以下命令：

bash

node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>

该命令会在全新的临时目录下验证发布到Registry的安装路径是否正常。
对于
```
YYYY.M.D-N
```
这类稳定版修复补丁，还会验证从
```
YYYY.M.D
```
升级到
```
YYYY.M.D-N
```
的路径是否正常，避免修复发布后现有全局安装的版本仍停留在旧的稳定版。

Check all relevant release builds

检查所有相关发布构建产物

Always validate the OpenClaw npm release path before creating the tag.

Default release checks:

```
pnpm check
```
```
pnpm build
```

node --import tsx scripts/release-check.ts

```
pnpm release:check
```

OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke

Check all release-related build surfaces touched by the release, not only the npm package.
Include mac release readiness in preflight by running the public validation workflow in
```
openclaw/openclaw
```
and the real mac preflight in
```
openclaw/releases-private
```
for every release.
Treat the
```
appcast.xml
```
update on
```
main
```
as part of mac release readiness, not an optional follow-up.
The workflows remain tag-based. The agent is responsible for making sure preflight runs complete successfully before any publish run starts.
Any fix after preflight means a new commit. Delete and recreate the tag and matching GitHub release from the fixed commit, then rerun preflight from scratch before publishing.
For stable mac releases, generate the signed
```
appcast.xml
```
before uploading public release assets so the updater feed cannot lag the published binaries.
Serialize stable appcast-producing runs across tags so two releases do not generate replacement
```
appcast.xml
```
files from the same stale seed.
For stable releases, confirm the latest beta already passed the broader release workflows before cutting stable.
If any required build, packaging step, or release workflow is red, do not say the release is ready.

创建标签前必须验证OpenClaw npm发布路径是否正常。

默认发布检查项：

```
pnpm check
```
```
pnpm build
```

node --import tsx scripts/release-check.ts

```
pnpm release:check
```

OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke

检查本次发布涉及的所有发布相关构建产物，不要仅检查npm包。
发布前预检需包含macOS发布就绪检查：每次发布都要运行
```
openclaw/openclaw
```
仓库中的公共验证工作流，以及
```
openclaw/releases-private
```
仓库中的正式mac预检工作流。
```
main
```
分支的
```
appcast.xml
```
更新属于macOS发布就绪检查的一部分，不是可选的后续步骤。
工作流仍基于标签触发，Agent需要确保所有预检步骤成功完成后再启动发布流程。
预检后如果有任何修复，需要产生新的commit，删除原有标签和对应的GitHub发布版本，基于修复后的commit重新创建标签和发布版本，发布前重新完整执行所有预检步骤。
稳定版macOS发布需要先生成签名后的
```
appcast.xml
```
再上传公开发布资源，避免更新 feed 滞后于已发布的二进制文件。
不同标签的稳定版appcast生成任务需要串行执行，避免两个发布任务基于同一个旧的基准生成冲突的
```
appcast.xml
```
文件。
稳定版发布前，需确认最新的beta版本已经通过了所有全量发布工作流校验。
如果有任何必填构建、打包步骤或发布工作流失败，不得声明发布已就绪。

Use the right auth flow

使用正确的鉴权流程

OpenClaw publish uses GitHub trusted publishing.
The publish run must be started manually with
```
workflow_dispatch
```
.
The npm workflow and the private mac publish workflow accept
```
preflight_only=true
```
to run validation/build/package steps without uploading public release assets.
The private mac workflow also accepts
```
smoke_test_only=true
```
for branch-safe workflow smoke tests that use ad-hoc signing, skip notarization, skip shared appcast generation, and do not prove release readiness.
```
preflight_only=true
```
on the npm workflow is also the right way to validate an existing tag after publish; it should keep running the build checks even when the npm version is already published.
Validation-only runs may be dispatched from a branch when you are testing a workflow change before merge.
```
.github/workflows/macos-release.yml
```
in
```
openclaw/openclaw
```
is now a public validation-only handoff. It validates the tag/release state and points operators to the private repo; it does not build or publish macOS artifacts.

Real mac preflight and real mac publish both use

openclaw/releases-private/.github/workflows/openclaw-macos-publish.yml

The private mac workflow runs on GitHub's xlarge macOS runner and uses a SwiftPM cache because the Swift build/test/package path is CPU-heavy.
Private mac preflight uploads notarized build artifacts as workflow artifacts instead of uploading public GitHub release assets.
Private smoke-test runs upload ad-hoc, non-notarized build artifacts as workflow artifacts and intentionally skip stable
```
appcast.xml
```
generation.
npm preflight, public mac validation, and private mac preflight must all pass before any real publish run starts.
Real publish runs must be dispatched from
```
main
```
; branch-dispatched publish attempts should fail before the protected environment is reached.
The release workflows stay tag-based; rely on the documented release sequence rather than workflow-level SHA pinning.
The
```
npm-release
```
environment must be approved by
```
@openclaw/openclaw-release-managers
```
before publish continues.
Mac publish uses
```
openclaw/releases-private/.github/workflows/openclaw-macos-publish.yml
```
for build, signing, notarization, packaged mac artifact generation, and stable-feed
```
appcast.xml
```
artifact generation.
Real private mac publish uploads the packaged
```
.zip
```
,
```
.dmg
```
, and
```
.dSYM.zip
```
assets to the existing GitHub release in
```
openclaw/openclaw
```
automatically when
```
OPENCLAW_PUBLIC_REPO_RELEASE_TOKEN
```
is present in the private repo
```
mac-release
```
environment.
For stable releases, the agent must also download the signed
```
macos-appcast-<tag>
```
artifact from the successful private mac workflow and then update
```
appcast.xml
```
on
```
main
```
.
For beta mac releases, do not update the shared production
```
appcast.xml
```
unless a separate beta Sparkle feed exists.
The private repo targets a dedicated
```
mac-release
```
environment. If the GitHub plan does not yet support required reviewers there, do not assume the environment alone is the approval boundary; rely on private repo access and CODEOWNERS until those settings can be enabled.
Do not use
```
NPM_TOKEN
```
or the plugin OTP flow for OpenClaw releases.
```
@openclaw/*
```
plugin publishes use a separate maintainer-only flow.
Only publish plugins that already exist on npm; bundled disk-tree-only plugins stay unpublished.

OpenClaw发布使用GitHub可信发布机制。
发布任务必须手动触发
```
workflow_dispatch
```
启动。
npm工作流和私有mac发布工作流支持传入
```
preflight_only=true
```
参数，仅运行验证/构建/打包步骤，不上传公开发布资源。
私有mac工作流还支持传入
```
smoke_test_only=true
```
参数，用于分支安全的工作流冒烟测试，该模式下使用临时签名，跳过公证、共享appcast生成，不代表发布已就绪。
npm工作流设置
```
preflight_only=true
```
也可以用于发布后验证已有标签，即使npm版本已经发布，仍会继续运行构建检查。
测试工作流改动时，可以基于分支触发仅验证的运行任务，无需合并代码。
```
openclaw/openclaw
```
仓库中的
```
.github/workflows/macos-release.yml
```
现在仅用于公共验证，它会验证标签/发布状态，指引运营人员访问私有仓库，不会构建或发布macOS产物。

正式的mac预检和mac发布都使用

openclaw/releases-private/.github/workflows/openclaw-macos-publish.yml

。

私有mac工作流运行在GitHub的xlarge macOS runner上，使用SwiftPM缓存，因为Swift构建/测试/打包路径CPU占用很高。
私有mac预检会将公证后的构建产物作为工作流产物上传，不会上传到GitHub公开发布资源中。
私有冒烟测试运行会将未公证的临时签名构建产物作为工作流产物上传，会主动跳过稳定版
```
appcast.xml
```
生成。
正式发布启动前，npm预检、公共mac验证、私有mac预检必须全部通过。
正式发布任务必须基于
```
main
```
分支触发，基于分支触发的发布尝试会在到达受保护环境前失败。
发布工作流基于标签触发，请遵循文档中的发布序列，不要依赖工作流层面的SHA锁定。
发布继续前，
```
npm-release
```
环境需要得到
```
@openclaw/openclaw-release-managers
```
的审批。
macOS发布使用
```
openclaw/releases-private/.github/workflows/openclaw-macos-publish.yml
```
完成构建、签名、公证、mac打包产物生成、稳定版feed的
```
appcast.xml
```
产物生成。
当私有仓库
```
mac-release
```
环境中存在
```
OPENCLAW_PUBLIC_REPO_RELEASE_TOKEN
```
时，正式的私有mac发布任务会自动将打包后的
```
.zip
```
、
```
.dmg
```
和
```
.dSYM.zip
```
资源上传到
```
openclaw/openclaw
```
仓库中已有的GitHub发布版本中。
稳定版发布时，Agent还需要从成功的私有mac工作流中下载签名后的
```
macos-appcast-<tag>
```
产物，然后更新
```
main
```
分支的
```
appcast.xml
```
。
beta版macOS发布时，除非存在独立的beta Sparkle feed，否则不要更新共享的生产
```
appcast.xml
```
。
私有仓库指向专属的
```
mac-release
```
环境，如果GitHub计划暂不支持该环境的必需审核者设置，不要仅依赖环境作为审批边界，在相关设置启用前，请依赖私有仓库访问权限和CODEOWNERS规则进行管控。
OpenClaw发布不要使用
```
NPM_TOKEN
```
或插件OTP流程。
```
@openclaw/*
```
插件发布使用单独的维护者专属流程。
仅发布npm上已存在的插件，仅存于本地disk-tree的捆绑插件不要发布。

Fallback local mac publish

备选本地mac发布流程

Keep the original local macOS publish workflow available as a fallback in case CI/CD mac publishing is unavailable or broken.
Preserve the existing maintainer workflow Peter uses: run it on a real Mac with local signing, notary, and Sparkle credentials already configured.
Follow the private maintainer macOS runbook for the local steps:
```
scripts/package-mac-dist.sh
```
to build, sign, notarize, and package the app; manual GitHub release asset upload; then
```
scripts/make_appcast.sh
```
plus the
```
appcast.xml
```
commit to
```
main
```
.
```
scripts/package-mac-dist.sh
```
now fails closed for release builds if the bundled app comes out with a debug bundle id, an empty Sparkle feed URL, or a
```
CFBundleVersion
```
below the canonical Sparkle build floor for that short version. For correction tags, set a higher explicit
```
APP_BUILD
```
.
```
scripts/make_appcast.sh
```
first uses
```
generate_appcast
```
from
```
PATH
```
, then falls back to the SwiftPM Sparkle tool output under
```
apps/macos/.build
```
.
For stable tags, the local fallback may update the shared production
```
appcast.xml
```
.
For beta tags, the local fallback still publishes the mac assets but must not update the shared production
```
appcast.xml
```
unless a separate beta feed exists.
Treat the local workflow as fallback only. Prefer the CI/CD publish workflow when it is working.
After any stable mac publish, verify all of the following before you call the release finished:
- the GitHub release has
```
.zip
```
  ,
```
.dmg
```
  , and
```
.dSYM.zip
```
  assets
- ```
appcast.xml
```
  on
```
main
```
  points at the new stable zip
- the packaged app reports the expected short version and a numeric
```
CFBundleVersion
```
  at or above the canonical Sparkle build floor

保留原有的本地macOS发布工作流作为备选，应对CI/CD mac发布不可用或故障的场景。
保留Peter使用的现有维护者工作流：在真实Mac设备上运行，本地已配置好签名、公证和Sparkle凭证。
本地步骤请遵循私有维护者macOS操作手册：运行
```
scripts/package-mac-dist.sh
```
完成应用构建、签名、公证和打包；手动上传GitHub发布资源；然后运行
```
scripts/make_appcast.sh
```
并将
```
appcast.xml
```
提交到
```
main
```
分支。
如果打包后的应用使用了调试bundle id、Sparkle feed URL为空、或
```
CFBundleVersion
```
低于对应短版本的官方Sparkle build最低值，
```
scripts/package-mac-dist.sh
```
在发布构建时会主动失败。对于补丁标签，请显式设置更高的
```
APP_BUILD
```
。
```
scripts/make_appcast.sh
```
会优先使用
```
PATH
```
中的
```
generate_appcast
```
， fallback 到
```
apps/macos/.build
```
下的SwiftPM Sparkle工具输出。
稳定版标签的本地备选发布可以更新共享的生产
```
appcast.xml
```
。
beta版标签的本地备选发布仍可以发布mac资源，但除非存在独立的beta feed，否则不得更新共享的生产
```
appcast.xml
```
。
本地工作流仅作为备选，CI/CD发布工作流正常时优先使用CI/CD流程。
任何稳定版mac发布完成后，声明发布结束前请验证以下所有项：
- GitHub发布版本包含
```
.zip
```
  、
```
.dmg
```
  和
```
.dSYM.zip
```
  资源
- ```
main
```
  分支的
```
appcast.xml
```
  指向新的稳定版zip包
- 打包后的应用显示的短版本符合预期，且数值型
```
CFBundleVersion
```
  不低于官方Sparkle build最低值

Run the release sequence

执行发布序列

Confirm the operator explicitly wants to cut a release.
Choose the exact target version and git tag.
Make every repo version location match that tag before creating it.
Update
```
CHANGELOG.md
```
and assemble the matching GitHub release notes.
Run the full preflight for all relevant release builds, including mac readiness.
Confirm the target npm version is not already published.
Create and push the git tag.
Create or refresh the matching GitHub release.

Start

.github/workflows/openclaw-npm-release.yml

with

preflight_only=true

and wait for it to pass.

Start
```
.github/workflows/macos-release.yml
```
in
```
openclaw/openclaw
```
and wait for the public validation-only run to pass.

Start

openclaw/releases-private/.github/workflows/openclaw-macos-publish.yml

with

preflight_only=true

and wait for it to pass.

If any preflight or validation run fails, fix the issue on a new commit, delete the tag and matching GitHub release, recreate them from the fixed commit, and rerun all relevant preflights from scratch before continuing. Never reuse old preflight results after the commit changes.
Start
```
.github/workflows/openclaw-npm-release.yml
```
with the same tag for the real publish.

Wait for

npm-release

approval from

@openclaw/openclaw-release-managers

Start

openclaw/releases-private/.github/workflows/openclaw-macos-publish.yml

for the real publish and wait for success.

Verify the successful real private mac run uploaded the
```
.zip
```
,
```
.dmg
```
, and
```
.dSYM.zip
```
artifacts to the existing GitHub release in
```
openclaw/openclaw
```
.
For stable releases, download
```
macos-appcast-<tag>
```
from the successful private mac run, update
```
appcast.xml
```
on
```
main
```
, and verify the feed.
For beta releases, publish the mac assets but expect no shared production
```
appcast.xml
```
artifact and do not update the shared production feed unless a separate beta feed exists.
After publish, verify npm and the attached release artifacts.

确认运营人员明确要求发起发布。
确定准确的目标版本和git标签。
创建标签前，确保仓库内所有版本位置的版本号和标签匹配。
更新
```
CHANGELOG.md
```
，整理对应的GitHub发布说明。
为所有相关发布构建运行全量预检，包括macOS就绪检查。
确认目标npm版本尚未发布。
创建并推送git标签。
创建或更新对应的GitHub发布版本。

启动

.github/workflows/openclaw-npm-release.yml

，设置

preflight_only=true

，等待运行通过。

启动
```
openclaw/openclaw
```
仓库中的
```
.github/workflows/macos-release.yml
```
，等待公共验证任务运行通过。

启动

openclaw/releases-private/.github/workflows/openclaw-macos-publish.yml

，设置

preflight_only=true

，等待运行通过。

如果任何预检或验证任务失败，在新的commit上修复问题，删除标签和对应的GitHub发布版本，基于修复后的commit重新创建标签和发布版本，继续流程前重新完整运行所有相关预检。commit变更后绝对不要复用旧的预检结果。
基于相同标签启动
```
.github/workflows/openclaw-npm-release.yml
```
执行正式发布。

等待

@openclaw/openclaw-release-managers

审批

npm-release

环境。

启动

openclaw/releases-private/.github/workflows/openclaw-macos-publish.yml

执行正式发布，等待运行成功。

验证正式私有mac运行任务已将
```
.zip
```
、
```
.dmg
```
和
```
.dSYM.zip
```
资源上传到
```
openclaw/openclaw
```
仓库中对应的GitHub发布版本。
稳定版发布时，从成功的私有mac运行任务中下载
```
macos-appcast-<tag>
```
，更新
```
main
```
分支的
```
appcast.xml
```
并验证feed。
beta版发布时，发布mac资源即可，不会生成共享生产
```
appcast.xml
```
产物，除非存在独立的beta feed，否则不要更新共享生产feed。
发布完成后，验证npm包和所有关联的发布资源是否正常。

GHSA advisory work

GHSA公告相关工作

Use
```
openclaw-ghsa-maintainer
```
for GHSA advisory inspection, patch/publish flow, private-fork validation, and GHSA API-specific publish checks.

GHSA公告检查、补丁/发布流程、私有fork验证、GHSA API专属发布检查请使用
```
openclaw-ghsa-maintainer
```
工作流。