openclaw-release-maintainer

OpenClaw 发布维护者

在发布和发布时工作流中使用此技能。普通开发变更和 GHSA 专项安全公告工作不属于此技能的范围。

遵守发布防护措施

• 未经操作员明确批准，请勿更改版本号。
• 执行任何 npm 发布或发行步骤前，请先征求许可。
• 此技能应足以端到端完成常规发行流程。
• 凭据、恢复步骤以及 mac 签名和公证细节，请参考维护者内部发行文档；公开政策请参考 docs/reference/RELEASING.md。
• 核心 openclaw 发布需手动触发 workflow_dispatch；创建或推送标签本身不会触发发布。
• 常规发行工作应在从 main 切出的分支上进行，不要直接在 main 上操作。分支名使用 release/YYYY.M.D。
• 如果操作员要求发行但未说明是稳定版/完整发行，默认只发布 beta 版。只有操作员明确要求完整发行或自动化 beta 和稳定版发行流程时，才从 beta 继续发布稳定版。
• 创建发行分支前，拉取最新的 main 并确认当前 main CI 全部通过。然后从该提交创建分支，以便在运行发行验证的同时，常规开发工作可以继续在 main 上进行。
• 创建发行分支前，按逻辑分组提交所有未提交的文件，推送、拉取/变基，然后在 main 上运行 /changelog，并在创建发行分支前立即提交、推送并拉取这次更新后的变更日志。
• 发行规划期间，创建分支前和最终发布前都要检查 src/plugins/compat/registry.ts 和 src/commands/doctor/shared/deprecation-compat.ts。对于每条已弃用或待移除的兼容性记录，如果其 removeAfter 日期不晚于发行日期，则应在安全的前提下移除兼容路径并验证相关测试；否则，记录阻止移除的原因，并在随发行版本提供已过期兼容路径前取得维护者的明确批准。
• 移除已弃用的运行时或配置兼容性时，应保留受支持的升级路径仍然需要的任何 doctor 迁移、修复或提示。维护者确认不再需要修复前，应继续在 src/commands/doctor/shared/deprecation-compat.ts 中跟踪 doctor 端的兼容性。
• 发行规划期间重新验证兼容性替换文本。随着插件归属、外部化和配置范围的变化，建议的替换项可能会改变，因此不要将过时的替换说明直接照搬到发行说明中。
• 匹配的 npm 软件包发布后，不要删除或重写 beta 标签。如果已推送的 beta 标签在 npm 发布前未通过预检，则删除该标签并在修正后的提交上重新创建标签和预发行版本，以确保 npm 预发行版本号连续。如果已发布的 beta 需要修复，则在发行分支上提交修复，并递增到下一个 -beta.N。
• 对于 beta 发行流程，先运行快速本地预检，将 beta 发布到 npm beta，然后运行耗时的已发布软件包测试集，重点检查安装/更新/Docker/Parallels/NPM Telegram。如果任何一项失败，则在发行分支上修复，提交/推送/拉取，递增 beta 编号并重复流程。晋升到稳定版/latest 前，至少完整运行一次耗时测试集；之后的 beta 尝试中，除非修复涉及广泛的发行、安装/更新、插件、Docker、Parallels 或实时 QA 行为，否则只重新运行证据发生变化的测试通道。每次发布 beta 后，都要扫描当前 main，查找发行分支切出后合入的关键修复，并仅回移植重要且风险低的修复。操作员最多可授权自主尝试 4 次 beta；4 次 beta 尝试均失败后，应停止并报告。
• 准备版本号/标签前使用 /changelog，以便按用户影响去重并排序变更日志顶部的章节。
• 不要创建 beta 专用的 CHANGELOG.md 标题。Beta 发行使用稳定版基础版本章节，例如，v2026.4.20-beta.1 使用 ## 2026.4.20 发行说明。
• 任何 beta 或稳定版发行上线后，都应尽最大努力使用 .profile 中 Peter 的 bot 令牌发布 Discord 公告；即使公告失败，也不要阻止或回滚发行。
• 如果被要求在 X 上发布公告，请使用 ~/Projects/bird/bird，并遵循下文的发行推文风格。

保持发布渠道命名一致

• stable：仅发布正式标签，默认发布到 npm beta；维护人员也可明确指定 npm latest，或之后再晋级
• beta：使用 vYYYY.M.D-beta.N 这类预发布标签，npm dist-tag 为 beta
• 优先使用 -beta.N；不要创建新的 -1 或 -2 beta 后缀
• dev：main 上持续变动的最新代码
• 使用 beta Git 标签时，发布到 npm 的版本也要带匹配的 beta 版本后缀，避免占用或阻止使用不带后缀的版本

统一处理版本和发布文件

• 版本所在位置包括：
  • 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 应用。 Beta 版通常先发布 npm/软件包工件，并跳过 mac 应用的 构建、签名和公证，除非维护人员要求进行 mac beta 验证。
• npm 预检通过后，不要让较慢的 macOS 签名/公证流程阻塞 npm 发布。让 mac 验证/发布并行运行，使用通过预检的结果发布 npm，随后开始验证已发布的 npm 安装/更新、Docker 和 Parallels，同时继续处理 mac 工件。
• Beta 版发布后，可在适当情况下并行安排远程/人工发布验证，但避免在同一主机上集中运行本地 Docker、Parallels 和 QA-Lab 工作，以免引入系统负载噪声。失败或修复后可选择性地重新运行，但在晋级到 stable/latest 前，必须保留 Docker、Parallels 和 QA-Lab 各自至少通过一次的验证证据。
• mac 软件包可以从与已标记提交略有不同的发布分支变体构建，前提是差异仅涉及 mac 软件包、签名、工作流或仅用于验证的发布机制。如果 stable npm 包或 GitHub 标签已发布后，mac 软件包仍需要仅存在于发布分支上的修复，不要仅为更改工作流来源而创建 vYYYY.M.D-N 修正标签。对原始 tag=vYYYY.M.D 分派私有 mac 工作流，并设置 source_ref=release/YYYY.M.D 和 public_release_branch=release/YYYY.M.D；来源验证必须证明源 SHA 是标签提交的后代，并且验证/预检使用同一来源。vYYYY.M.D-N 修正标签仅用于必须发布新 npm 包/发布标识的紧急热修复，不用于常规的仅 mac 软件包恢复。
• 生产环境的 Sparkle 更新源位于 https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml，规范的已发布文件是 openclaw 仓库 main 分支上的 appcast.xml。
• 该共享的生产环境 Sparkle 更新源仅用于 stable 版。Beta mac 版可以向 GitHub 预发布版本上传工件，但不得替换共享的 appcast.xml，除非存在单独的 beta 更新源。
• 对于 vYYYY.M.D-N 这类回退修正标签，仓库版本仍保持为 YYYY.M.D，但 mac 发布必须使用严格高于原始发布版本的数字 APP_BUILD / Sparkle 构建号，以便现有安装能识别其为更新版本。

构建基于变更日志的发布说明

• 在创建发布分支或标签之前，根据提交历史重写目标 CHANGELOG.md 章节，而不只是依据现有说明：扫描自上一个可达发布标签 以来的提交，补充遗漏的用户可见变更，合并重复条目，并按对用户 的重要性从高到低排列每个章节中的条目。
• CHANGELOG.md 条目应面向用户，而不是内部发布流程说明。
• GitHub 发布和预发布正文必须使用完整匹配的 CHANGELOG.md 版本章节，而不是亮点或摘录。创建或编辑发布时， 从 ## YYYY.M.D 开始提取到下一个二级标题之前的行，并使用该 完整区块作为发布说明。
• 准备发布说明时，扫描 src/plugins/compat/registry.ts 和 src/commands/doctor/shared/deprecation-compat.ts，查找发布日期后 7 天内 具有 warningStarts 或 removeAfter 的兼容性记录。若存在此类记录， 请在发布说明中添加 Upcoming deprecations 注记，其中包括兼容性代码、 目标日期、替代方案，以及指向该记录 docsPath 的链接；如果没有更具体的 弃用页面，则指向 /plugins/compatibility。
• 创建 mac 版本并使用 beta GitHub 预发布时：
  • 从发布提交创建标签 vYYYY.M.D-beta.N
  • 创建标题为 openclaw YYYY.M.D-beta.N 的预发布
  • 使用稳定基础版 CHANGELOG.md 版本章节 （## YYYY.M.D）中的发布说明，而不是 beta 专用标题
  • 至少附上 zip 和 dSYM zip；如果有 dmg，也一并附上
• 按影响程度排列 CHANGELOG.md 顶部的版本条目：
  • ### Changes 排在最前
  • ### Fixes 去重后，将面向用户的修复排在最前

编写发布推文

使用 OpenClaw 账号现有的发布帖风格：

• 格式：OpenClaw YYYY.M.D 🦞 或 🦞 OpenClaw YYYY.M.D is live，空一行， 然后是 3-4 条以 emoji 开头的要点，空一行，一句简短点睛之笔，然后是发布 链接。
• 对于测试版：写明 OpenClaw YYYY.M.D-beta.N 🦞 或 OpenClaw YYYY.M.D beta N is live；明确标注为测试版，避免暗示已升级为稳定版。
• 先讲用户可见的功能，再讲重要集成，最后讲可靠性、安全性和安装修复。将“大量 修复”压缩为一条清晰易读的要点。
• 起草前通读完整的变更日志章节。除非本次发布明确聚焦这些内容，否则不要从覆盖率、 CI、验证或内部发布机制写起。Peter 更喜欢具体的用户收益：功能、集成、 工作流改进和实用的可靠性修复。
• 语气：高信噪比、略带俏皮、自信，不要企业腔。一个笑话就 够了。不要贬损他人、侮辱用户，或作出未经验证的承诺。
• Peter 喜欢恰如其分的冷幽默和紧凑标语。不错的示例： Big release, tiny release notes... kidding. 笑话要简短，让功能要点撑起整条推文；不要把 点睛之笔变成第二个段落，也不要强行抖包袱。
• 长度：发布推文始终是少于 280 个字符的标准推文，并且 要为一个 URL 留出空间。精简到 3-4 个要点，并在发布前统计最终文本的字符数。
• 链接／媒体：在第一条发布推文末尾附上 GitHub 发布页或变更日志链接。
• 推文串后续：如果采用推文串形式，第一条发布推文应保持为紧凑的发布帖， 然后每条回复只聚焦一项功能的说明。当推文串上下文已清楚表明版本信息时， 后续回复不要重复“在 VERSION 中新增”或版本号。
• Peter 偏好的推文串工作流：先共同敲定通用的发布推文， 然后逐条编写后续推文。当他说 next 时，只提供或复制下一条后续推文； 除非他要求，否则不要再次输出完整推文串。
• 每条后续推文都应包含该特定功能对应的文档 URL。 优先使用裸 URL，而不是 Docs: <url>，除非为清晰起见需要标签。 后续推文要简洁：通常以 160-220 个原始字符最为合适； 少于 280 个字符是硬性上限。如果 URL 导致推文超限，应先精简正文， 再删除 URL。
• 热修复／更正：要直接且负责任。说明哪里出了问题、修复了什么，以及新的 版本号。事故类帖子不要开玩笑。

可借鉴的示例：

OpenClaw 2026.4.20-beta.1 🦞

🐳 Docker install/update smoke
🖥️ Parallels upgrade checks
🔧 Package verification tightened

Beta first. Stable after the gauntlet.
<release link>

OpenClaw 2026.4.20 🦞

🚀 Faster install + update
🐳 Docker + Parallels verified
🍎 macOS signed + notarized
🔧 Channel/plugin fixes

Good boring release. Best kind.
<release link>

Packaging issue in 2026.4.20-beta.1.

2026.4.20-beta.2 fixes install/update verification. No tag rewrites; beta moves
forward.

Upgrade with the beta channel.
<release link>

运行发布时验证

在打标签或发布前，运行：

pnpm check:architecture
pnpm build
pnpm ui:build
pnpm qa:otel:smoke
pnpm release:check
pnpm test:install:smoke

• 当发布验证需要遥测覆盖时，使用 pnpm qa:otel:smoke。 它会启动本地 OTLP/HTTP 跟踪接收器，运行 QA-lab 的 otel-trace-smoke，并检查跨度名称以及内容和标识符的脱敏情况， 无需外部 Opik 或 Langfuse 凭据。

对于非 root 冒烟测试路径：

  OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke

npm 发布后，运行：

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

• 这会验证在全新临时前缀中从已发布注册表安装的路径。
• 对于形如 YYYY.M.D-N 的稳定版更正发布，它还会验证 从 YYYY.M.D 到 YYYY.M.D-N 的升级路径，确保更正发布不会 悄然让现有全局安装继续使用旧的基础稳定载荷。
• 将安装冒烟测试也视为包体积预算关卡。pnpm test:install:smoke 现在，当 npm 报告 unpackedSize 过大时，会将候选更新 tarball 判定为失败，因此发布阶段的 e2e 不会漏检可能造成低内存机器安装或 启动失败的包体积膨胀。
• 在安装冒烟测试中保留直接使用 npm 进行全局安装的覆盖测试。它会执行普通的 npm install -g <candidate> 全新安装，以及由 npm 驱动的更新安装， 因为即使文档推荐 pnpm，许多用户仍使用 npm 安装。
• 当视频生成属于发布范围时，使用 pnpm test:live:media video 进行有时限的 视频提供商冒烟测试。默认视频冒烟测试会跳过 fal，每个提供商运行一次 文本转视频尝试，提示词要求生成一秒的龙虾视频，并通过 OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS 限制每个提供商操作的时长 （默认 180000）。
• 仅在需要进行 FAL 专项验证时运行 pnpm test:live:media video --video-providers fal。其队列延迟可能占据 大部分发布时间。
• 仅在有意验证速度较慢的图像转视频和视频转视频转换通道时，才设置 OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1。

检查所有相关的发布构建

• 在创建标签之前，务必验证 OpenClaw npm 发布流程。
• 在进行实时发布验证之前，先加载 Peter 的配置文件，以便使用 OpenAI 和 Anthropic 凭据，同时不打印机密： set -a; source "$HOME/.profile"; set +a。
• 本次发布的 Parallels 验证以及任何本地实时模型 QA 都必须同时使用 OPENAI_API_KEY 和 ANTHROPIC_API_KEY。如果加载 .profile 后缺少任一密钥，请在启动这些耗时的本地流程之前停止，并报告缺少的密钥。
• 需要凭据的实时渠道 QA 必须通过 GitHub Actions 工作流 QA-Lab - All Lanes（.github/workflows/qa-live-telegram-convex.yml）运行，不能用本地测试替代。从 Actions 中针对发布标签触发该工作流，并等待其通过后，再进行 npm 预检／发布就绪检查。只有满足工作流密钥信任门槛的 SHA 才可使用：它必须是 main 的祖先，或开放 PR 的 head。该工作流会运行 QA Lab 模拟对等检查，以及实时 Matrix 和实时 Telegram 流程，并使用 qa-live-shared 环境；Telegram 使用 Convex CI 凭据租约。
• 默认发布检查：
  • pnpm check
  • pnpm check:test-types
  • pnpm check:architecture
  • pnpm build
  • pnpm ui:build
  • pnpm release:check
  • OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke
• npm 预检前完整 beta 测试清单：
  • 上述默认发布检查
  • 所有 Docker 测试：pnpm test:docker:all；如果操作人员要求“所有 Docker 测试”，还要运行聚合测试未涵盖的独立 Docker 实时流程： pnpm test:docker:live-acp-bind、pnpm test:docker:live-cli-backend 和 pnpm test:docker:live-codex-harness
  • 所有 Parallels 安装／更新测试： pnpm test:parallels:npm-update -- --json，以及 openclaw-parallels-smoke 中任何必要的单独重跑流程
  • 所有 QA 发布验证：在 GitHub Actions 中针对发布标签触发 QA-Lab - All Lanes，并要求其成功。这是实时且需要凭据的 Matrix／Telegram 渠道覆盖发布门槛。只有满足工作流信任门槛的 SHA 才可使用。仅当操作人员要求增加模型覆盖，或需要在本地调试故障时，才运行本地 OpenAI／Anthropic 测试套件或基于仓库的角色评估。
• beta 发布后的验证清单：
  • node --import tsx scripts/openclaw-npm-postpublish-verify.ts <beta-version>
  • 针对已发布 beta 渠道进行安装／更新冒烟测试
  • 覆盖已发布 beta 包的 Docker 安装／更新测试
  • 已发布 npm 包的 Telegram 验证：从 main 触发 Actions > NPM Telegram Beta E2E，设置 package_spec=openclaw@<beta-version> 和 provider_mode=mock-openai，并要求其成功。此工作流由维护者手动触发，且有意不设置 npm-release 审批门槛；qa-live-shared 仅提供共享 QA 机密。这是针对已安装包引导、Telegram 设置以及基于已发布 npm 包进行真实 Telegram E2E 测试的默认触发方式。 只有作为备用或调试方案时，才使用本地 pnpm test:docker:npm-telegram-live 流程，并设置匹配的 OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC 和 Convex CI 环境变量。
  • 使用 OpenAI 和 Anthropic 提供方密钥，对已发布 beta 版进行 Parallels 安装／更新覆盖测试
  • Parallels 安装／更新验证必须保持插件安装启用，除非操作人员明确将测试限定为仅隔离检查测试框架；禁用内置插件安装的流程不能作为有效的插件／依赖发布证据。
  • 完成 npm 预检前完整测试清单后，仅针对修复涉及的区域重新运行目标 QA，除非操作人员要求再次运行完整 QA 清单。如果修复涉及实时渠道 QA、凭据配置、Matrix、Telegram 或 QA 测试框架，则重新运行 Actions > QA-Lab - All Lanes。
• 检查发布涉及的所有构建相关表面，不要只检查 npm 包。
• 对于 beta 式完整 E2E 测试套件，必须为顶层耗时流程设置硬性时限，不能让它们无限运行。使用主机上的 timeout --foreground／gtimeout --foreground 设置时限，例如：
  • 对 OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke 设置 45m
  • 对 pnpm test:docker:all 设置 90m
  • 对每个独立的 Docker 实时流程设置 60m
  • 对明确要求运行的本地完整 QA 实时 OpenAI + Anthropic 测试清单设置 180m；默认发布渠道 QA 门槛是 Actions > QA-Lab - All Lanes
  • Parallels 时限参见 openclaw-parallels-smoke 技能 如果流程达到时限，请停止并检查／修复受影响的流程后再继续；不要继续等待同一进程。
• 实际 npm 安装／更新阶段的时限为 5 分钟。如果发布 E2E 测试中的 npm install -g、安装程序包安装或 openclaw update 耗时超过 300s，请不要再将运行视为正常进展，应调试安装程序／更新程序或测试框架。
• 在 VM 流程之前，先串行完成主机上的构建／打包变更。启动 Parallels npm pack 流程之前，应完成 pnpm build、pnpm ui:build、pnpm release:check、安装冒烟测试以及任何 Docker／打包准备流程；否则 dist 可能会在 VM 打包准备期间消失，导致虚假失败。
• 发布预检必须包含 mac 发布就绪检查：每次发布都要在 openclaw/openclaw 中运行公开验证工作流，并在 openclaw/releases-private 中运行真实 mac 预检。
• 将 main 上的 appcast.xml 更新视为 mac 发布就绪流程的一部分，而非可选的后续步骤。
• 工作流仍以标签为基础。Agent 负责确保所有预检运行成功完成后，才启动任何发布运行。
• 预检后如有任何修复，都必须创建新的提交。删除并从修复后的提交重新创建标签和对应的 GitHub 发布，然后从头重新运行预检，再进行发布。 例外：如果对应的 npm 包已经发布，绝不能删除或重新创建 beta 标签；应递增到下一个 beta 版本号。如果只推送了标签／预发布版本，尚未发布 npm 包，则应在修复后的提交上重新创建同一个 beta 标签。
• 对于稳定版 mac 发布，请在上传公开发布资源之前生成已签名的 appcast.xml，避免更新器信息流落后于已发布的二进制文件。
• 不同标签的稳定版 appcast 生成流程必须串行运行，避免两个发布流程使用同一份过时的种子生成替换版 appcast.xml 文件。
• 对于稳定版发布，主要依赖最新 beta 版本提供的全面发布流程可信度。将匹配的非 beta 构建推广到 npm latest 时，优先进行耗时受限的轻量验证：已发布 npm 发布后验证、Docker 安装／更新冒烟测试、仅限 macOS 的 Parallels 安装／更新冒烟测试，以及必要的 QA 信号。除非 beta 测试证据已过时、稳定版构建与 beta 版有实质差异，或操作人员明确要求完整重新测试，否则不要重新运行完整的 Docker／Parallels 测试矩阵。
• 如果任何必需的构建、打包步骤或发布工作流失败，不要声称发布已就绪。

使用正确的身份验证流程

• OpenClaw 发布使用 GitHub 可信发布。
• 将稳定版从 beta 提升到 latest 的 npm 操作使用私有的 openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml 工作流，因为管理 npm dist-tag 需要 NPM_TOKEN，而公开的 npm 发布工作流仍仅使用 OIDC。
• 优先修复私有工作流的令牌路径，而不是使用任何本地 1Password 备用方案。理想配置是将细粒度 npm 令牌存储为私有仓库的 NPM_TOKEN 密钥， 仅授予 openclaw 包的读写权限，并为自动化绕过 2FA。
• 如果私有 dist-tag 工作流因缺少或过期的 NPM_TOKEN 而无法提升版本，请使用本地 tmux + 1Password 备用方案：
  • 启动或复用一个 tmux 会话，以便查看并恢复交互式 npm login 和 OTP 提示。
  • 硬性规则：发布期间，绝不能在主 Agent shell 中直接运行 op。任何 1Password CLI 操作都必须在该 tmux 会话中执行，以确保提示和警报受到隔离且可见。
  • 使用 1Password 条目 op://Private/Npmjs 获取 npm 凭据和 OTP。不要将密码、令牌或 OTP 打印到记录中；请通过 tmux 缓冲区、限定在 tmux 命令作用域内的环境变量，或设置了 log_user 0 的 expect 传递。
  • 在该 tmux 会话中重新验证 npm 身份，运行 npm login --auth-type=legacy，然后确认 npm whoami 返回 steipete。
  • 使用新生成的 OTP 提升版本： npm dist-tag add [email protected] latest --otp "$OTP"。
  • 使用绕过缓存的注册表读取进行验证，例如： npm view openclaw dist-tags --json --prefer-online --cache /tmp/openclaw-npm-cache-verify-$$ 和 npm view openclaw@latest version dist.tarball --json --prefer-online。
• 直接发布稳定版时，也可以使用该私有 dist-tag 工作流，将 beta 指向已发布的 latest 版本，以便操作人员立即对齐两个标签。
• 必须手动通过 workflow_dispatch 启动发布运行。
• npm 工作流和私有 macOS 发布工作流接受 preflight_only=true，可运行验证、构建和打包步骤，而不上传公开发布资产。
• 实际发布 npm 前，必须先有一次成功的 npm 预检运行 ID，以便发布任务提升已准备好的压缩包，而不是重新构建。
• 实际进行私有 macOS 发布前，必须先有一次成功的私有 macOS 预检运行 ID，以便发布任务提升已准备好的制品，而不是重新构建或再次进行公证。
• 私有 macOS 工作流还接受 smoke_test_only=true，用于可在分支上安全运行的工作流冒烟测试；测试使用临时签名、跳过公证、跳过共享 appcast 生成，且不能证明已具备发布条件。
• npm 工作流中的 preflight_only=true 也适用于发布后验证现有标签；即使 npm 版本已发布，也应继续运行构建检查。
• 测试合并前的工作流更改时，可以从普通分支派发仅用于验证的 npm 预检。发布检查和实际发布只能使用 main 或 release/YYYY.M.D。
• openclaw/openclaw 中的 .github/workflows/macos-release.yml 现为仅用于公开验证的交接流程。它会验证标签和发布状态，并指引操作人员前往私有仓库。它仍会重新构建发布验证所需的 JS 输出，但不会对 macOS 制品签名、公证或发布。
• openclaw/releases-private/.github/workflows/openclaw-macos-validate.yml 是必需的私有 macOS 验证流程，用于运行 swift test；开始任何实际稳定版 macOS 发布前，必须确保此流程通过。
• 实际 macOS 预检和实际 macOS 发布均使用 openclaw/releases-private/.github/workflows/openclaw-macos-publish.yml。
• 私有 macOS 验证流程在 GitHub 标准 macOS 运行器上运行。
• 私有 macOS 预检流程在 GitHub xlarge macOS 运行器上运行，并使用 SwiftPM 缓存，因为构建、签名、公证和打包流程需要大量 CPU 资源。
• 私有 macOS 预检会将已公证的构建制品作为工作流制品上传，而不是上传公开 GitHub 发布资产。
• 私有冒烟测试运行会将临时签名、未经公证的构建制品作为工作流制品上传，并有意跳过稳定版 appcast.xml 生成。
• 对于稳定版发布，必须先通过 npm 预检、公开 macOS 验证、私有 macOS 验证和私有 macOS 预检，才能开始任何实际发布运行。对于 beta 发布，除非明确要求进行 macOS beta 验证，否则通过 npm 预检以及选定的 Docker、安装/更新、Parallels 和发布检查流程即可。
• 可从 main 或 release/YYYY.M.D 分支派发实际发布运行。对于从发布分支运行的情况，标签必须包含在该发布分支中，且实际发布必须复用同一分支上成功的预检。
• 发布工作流仍基于标签；请遵循文档所述的发布顺序，而不要依赖工作流级别的 SHA 固定。
• 发布继续进行前，必须由 @openclaw/openclaw-release-managers 批准 npm-release 环境。
• Mac 发布使用 openclaw/releases-private/.github/workflows/openclaw-macos-publish.yml， 负责准备私有 macOS 预检制品并提升实际发布制品。
• 如果私有仓库的 mac-release 环境中存在 OPENCLAW_PUBLIC_REPO_RELEASE_TOKEN，实际私有 macOS 发布会自动将打包后的 .zip、.dmg 和 .dSYM.zip 资产上传到 openclaw/openclaw 中现有的 GitHub 发布。
• 对于稳定版发布，Agent 还必须从成功的私有 macOS 工作流下载已签名的 macos-appcast-<tag> 制品，然后在 main 上更新 appcast.xml。
• 对于 macOS beta 发布，除非存在单独的 beta Sparkle 源，否则不要更新共享的生产环境 appcast.xml。
• 私有仓库使用专用的 mac-release 环境。如果 GitHub 计划尚不支持在该环境中设置必需审核者，不要假设仅凭环境本身就能构成审批边界；在启用这些设置前，请依赖私有仓库访问权限和 CODEOWNERS。
• OpenClaw 包发布流程不得使用 NPM_TOKEN 或插件 OTP 流程；包发布使用可信发布。
• 仅在明确需要管理 npm dist-tag 时使用 NPM_TOKEN，因为 npm 不支持通过可信发布运行 npm dist-tag add。
• @openclaw/* 插件发布使用单独的、仅限维护者的流程。
• 仅发布 npm 上已存在的插件；仅存在于捆绑磁盘目录树中的插件保持未发布状态。

本地 macOS 发布回退方案

• 保留原有的本地 macOS 发布工作流作为回退方案，以便在 CI/CD mac 发布不可用或损坏时使用。
• 保留 Peter 正在使用的现有维护者工作流：在真实 Mac 上运行， 并预先配置好本地签名、公证和 Sparkle 凭据。
• 按照私有维护者 macOS 操作手册执行本地步骤： scripts/package-mac-dist.sh 用于构建、签名、公证和打包应用； 手动上传 GitHub 发布资产；然后运行 scripts/make_appcast.sh，并将 appcast.xml 提交到 main。
• scripts/package-mac-dist.sh 现在会在发布构建出现以下情况时执行失败并停止： 生成的应用带有调试捆绑 ID、Sparkle 更新源 URL 为空，或者 其 CFBundleVersion 低于该短版本对应的规范 Sparkle 构建版本下限。 对于修正标签，请显式设置更高的 APP_BUILD。
• scripts/make_appcast.sh 首先使用 PATH 中的 generate_appcast，然后 回退使用 apps/macos/.build 下的 SwiftPM Sparkle 工具输出。
• 对于稳定版标签，本地回退方案可以更新共享的生产环境 appcast.xml。
• 对于测试版标签，本地回退方案仍会发布 mac 资产，但除非存在独立的测试版源，否则不得 更新共享的生产环境 appcast.xml。
• 仅将本地工作流视为回退方案。CI/CD 发布工作流 正常工作时，应优先使用。
• 每次稳定版 mac 发布后，在宣布发布完成之前，请验证以下所有内容：
  • GitHub 发布中包含 .zip、.dmg 和 .dSYM.zip 资产
  • main 上的 appcast.xml 指向新的稳定版 zip
  • 打包后的应用报告预期的短版本号和数值形式的 CFBundleVersion，且其值达到或高于规范 Sparkle 构建版本下限

执行发布流程

1. 确认操作人员明确要求发布版本。
2. 选定准确的目标版本和 Git 标签。
3. 将所有未提交文件按合理分组提交，推送，拉取并变基，然后确认工作区干净。
4. 拉取最新的 main，并确认当前 main 的 CI 通过。
5. 在 main 上针对稳定版本基准目标运行 /changelog，立即提交变更后的更新日志，推送并拉取、变基。对于 Beta 版，更新日志标题保留为 ## YYYY.M.D，而不是 ## YYYY.M.D-beta.N。
6. 从更新日志提交后的 main 创建 release/YYYY.M.D。
7. 在创建 Beta 标签前，确保仓库中的所有版本位置都与该 Beta 标签一致。
8. 在发布分支上提交发布准备变更，并推送分支。
9. 在发布分支上运行快速本地 Beta 预检，然后再运行任何 npm 预检或发布。除非操作人员要求在发布 Beta 前运行，否则将耗时的 Docker、Parallels 和已发布软件包安装／更新测试留到 Beta 正式发布后。
10. 对于 Beta 版，除非 Beta 范围或发布阻塞问题明确要求，否则跳过 Mac 应用构建／签名／公证。对于稳定版，包含 Mac 应用、签名、公证和 appcast 流程。
11. 确认目标 npm 版本尚未发布。
12. 从发布分支创建并推送 Git 标签。
13. 创建或更新匹配的 GitHub 发布。
14. 针对发布标签触发 Actions > QA-Lab - All Lanes，并等待 mock parity、live Matrix 和 live Telegram 需要凭据的频道测试通道通过。
15. 从发布分支启动 .github/workflows/openclaw-npm-release.yml，设置 preflight_only=true， 并选择预期的 npm_dist_tag（默认值为 beta；仅在有意直接发布稳定版时使用 latest）。等待运行通过。保存该次运行的 ID，因为实际发布需要复用预先准备的 npm tarball。
16. 对于稳定版，在 openclaw/openclaw 中启动 .github/workflows/macos-release.yml，并等待公开的仅验证运行通过。
17. 对于稳定版，使用相同的标签启动 openclaw/releases-private/.github/workflows/openclaw-macos-validate.yml， 并等待私有 Mac 验证通道通过。
18. 对于稳定版，设置 preflight_only=true，启动 openclaw/releases-private/.github/workflows/openclaw-macos-publish.yml， 并等待运行通过。保存该次运行的 ID，因为实际发布需要复用经过公证的 Mac 构建产物。
19. 如果任何预检或验证运行失败，请在新提交中修复问题，删除标签和匹配的 GitHub 发布，从修复后的提交重新创建它们，并从头重新运行所有相关预检，然后再继续。提交发生变化后，绝不复用旧的预检结果。对于已推送或已发布的 Beta 标签，不要删除并重新创建；递增到下一个 Beta 标签。如果仅预检失败，且 npm 尚未发布该 Beta 版本，则在修复后的提交上删除并重新创建相同的 Beta 标签和预发布版本，而不是跳过一个预发布序号。
20. 从同一分支、使用相同标签启动 .github/workflows/openclaw-npm-release.yml 进行实际发布，选择 npm_dist_tag（默认为 beta；仅在有意直接发布稳定版时使用 latest），保持其值与预检运行一致，并传入成功的 npm preflight_run_id。
21. 等待 @openclaw/openclaw-release-managers 批准 npm-release。
22. 运行发布后验证： node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>。
23. 运行 Beta 发布后的验证清单。首先检查当前 main，查看发布分支切出后是否有重要修复合入；在启动耗时测试通道前，只回移重要且风险较低的修复；如果修复必须更改已发布的软件包，则递增到下一个 Beta 版本。如果 Beta 软件包发布后任何测试通道失败，则修复问题，提交／推送／拉取，递增到下一个 Beta 标签，并重新运行受影响的 Beta 验证。Beta 正式发布后，可安全并行启动远程／手动测试清单，但要控制本地 Docker 和 Parallels 的负载。在升级到稳定版／latest 前，确保完整的高耗时测试清单至少通过一次。该清单包括针对确切的已发布 Beta 软件包手动运行 Actions > NPM Telegram Beta E2E 工作流。如果 npm 发布前的测试通道失败，且尚未有任何标签／软件包离开本机，则修复问题并重新运行同一次预定的 Beta 尝试。在操作人员授权的 Beta 尝试次数上限内重复，通常为 4 次。
24. 尽力使用 .profile 中 Peter 的机器人令牌，在 Discord 上宣布 Beta／稳定版发布。
25. 如果操作人员只要求发布 Beta，则在 Beta 验证和公告后停止。
26. 如果稳定版发布到了 beta，且对应的 Beta 版已通过完整的信心验证，则运行轻量级稳定版升级清单：已发布 npm 版本发布后验证、Docker 安装／更新冒烟测试、仅限 macOS 的 Parallels 安装／更新冒烟测试，以及所需的 QA 信号。然后启动私有工作流 openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml， 将该稳定版从 beta 升级到 latest，然后确认 latest 现已指向该版本。
27. 如果稳定版直接发布到了 latest，且 beta 也应跟随，则启动同一私有分发标签工作流，将 beta 指向稳定版，然后确认 latest 和 beta 都指向该版本。
28. 对于稳定版，使用成功的私有 Mac preflight_run_id 启动 openclaw/releases-private/.github/workflows/openclaw-macos-publish.yml， 执行实际发布并等待成功。
29. 确认成功的私有 Mac 实际运行已将 .zip、.dmg 和 .dSYM.zip 构建产物上传到 openclaw/openclaw 中现有的 GitHub 发布。
30. 对于稳定版，从成功的私有 Mac 运行中下载 macos-appcast-<tag>，在 main 上更新 appcast.xml，并验证 Feed。稳定版发布成功后，将发布分支变更合并或拣选到 main。
31. 对于 Beta 版，仅在有意要求时发布 Mac 资源；预期不会有共享的生产环境 appcast.xml 构建产物，除非另有独立 Beta Feed，否则不要更新共享的生产环境 Feed。
32. 发布后，验证 npm 和附加的发布构建产物。

GHSA 安全公告工作

• 使用 openclaw-ghsa-maintainer 进行 GHSA 安全公告检查、补丁/发布流程、私有 fork 验证以及 GHSA API 专用发布检查。