release-openclaw-mac

OpenClaw Mac 发布

涉及稳定版 macOS 资源、发布运维 mac 预检、公证、appcast 推广或 mac 发布恢复时，请使用 $release-openclaw-maintainer、$release-openclaw-ci、$one-password，以及存在时的 $release-private。

这是用于常规稳定版发布的技能。扩展稳定版不应调用此技能；该发布轨道的 GitHub Release 会附带共享验证证据，但不会继承 macOS 资源或 appcast 推广。

发布授权

明确要求发布稳定版或完整版本，即包含 macOS 发布，除非操作员限定了范围。请继续执行验证、签名、公证、推广和核验，无需另行征求 macOS 发布许可。保持准确的发布标识，并检查所有制品。macOS 发布与 npm 并行进行，绝不会阻塞 npm；macOS 故障不会阻止 npm/ClawHub 发布、GitHub release 定稿或主要收尾工作。请并行修复故障。

遵循当前所有者配置的环境策略。不要擅自增加审核者要求，也不要恢复已废弃的要求。如果 GitHub 仍强制要求审批，请报告实际规则，并通过规则所有者解决；更改策略需要组织所有者明确指示，并核实其当前具有有效的管理员成员身份。绝不要冒充审核者、伪造审批，或使用其他签名途径绕过强制规则。

凭据

• 从 $release-private 中获取 Peter 所有的 ASC 条目引用、密钥 ID、签发者 ID 和服务令牌来源信息。
• 字段：private_key_p8、key_id、issuer_id。
• 密钥过期或已撤销时的表现：xcrun notarytool submit 失败，并返回 HTTP status code: 401. Unauthenticated。
• 设置 GitHub secrets 前，使用 xcrun notarytool history 验证候选 ASC 凭据。

1Password

• 使用 $one-password：所有 op 操作都必须在同一个持久 tmux 会话中进行，不得输出机密内容。
• 如果 $release-private 中提供了服务令牌指导，请遵循该指导。
• 如果服务令牌失效，只进行状态检查：确认令牌是否存在及其长度，并运行 op whoami；绝不要打印令牌值。
• 如果需要桌面应用认证，但无法使用 Touch ID，请在手动执行 op account add --signin 时设置 OP_BIOMETRIC_UNLOCK_ENABLED=false。

GitHub Secrets

目标发布运维仓库环境：openclaw/releases，环境为 mac-release。

只有在本地验证公证认证后，才能设置以下内容：

• APP_STORE_CONNECT_API_KEY_P8
• APP_STORE_CONNECT_KEY_ID
• APP_STORE_CONNECT_ISSUER_ID

不要从混杂来源更新这些内容。所有三个 ASC 字段必须来自同一个 1Password 条目。

工作流结构

• openclaw/openclaw 是公开产品仓库，其 GitHub Releases 页面是 macOS 资源最终附加的位置。
• openclaw/openclaw 的 macos-release.yml 仅用于公开交接验证。无论 preflight_only 的值如何，它都不会签名、公证或上传 macOS 资源。
• openclaw/releases 是受限的发布运维仓库。其 macOS 工作流会对资源签名、公证、验证，并将资源推广到 openclaw/openclaw 的 GitHub release。
• 稳定版标签/npm 已上线后，公开发布分支仍可包含仅影响 mac 的打包修复。
• 为该分支变体构建时，使用 source_ref=release/YYYY.M.PATCH 运行发布运维 mac 预检/验证。
• 保持 tag=vYYYY.M.PATCH 指向原始稳定版提交。
• 实际 mac 发布必须复用：
  • 相同标签/source SHA 的成功发布运维 mac 预检运行
  • 相同标签/source SHA 的成功发布运维 mac 验证运行
• 发布运维预检和实际发布使用 mac-release 环境中的签名及推广 secrets，并遵循仅限主分支的部署策略。获授权的发布操作员应继续遵循该环境的当前规则。
• 如果预检的 source SHA 与 tag SHA 不同，验证也必须使用相同的 source_ref；推广会拒绝不匹配的证明。

公证

• OpenClaw 使用 scripts/notarize-mac-artifact.sh。
• xcrun notarytool submit 应使用 --no-s3-acceleration；加速上传可能会显示误导性的 401，即使 notarytool history 成功也是如此。
• 如果签名成功，但公证立即以 401 失败，请先检查 ASC 密钥是否仍有效。
• 如果写入密钥文件后公证持续进行数分钟，这是 Apple 的正常等待时间；不要贸然编辑。

派发

公开交接工作流会在发布前验证标签、源、构建和软件包元数据。它不要求存在 GitHub release 页面，因为它不会上传资源。请将此验证放在正式发布工作流之前。核心发布器负责完成 GitHub release；macOS 晋级会将经过验证的资源附加到该 release，无论它仍是草稿还是已经公开，因此不会等待 npm 切换。

公开交接验证：

gh workflow run macos-release.yml --repo openclaw/openclaw \
  --ref release/YYYY.M.PATCH \
  -f tag=vYYYY.M.PATCH \
  -f preflight_only=true \
  -f public_release_branch=release/YYYY.M.PATCH

• 将公开发布分支用作工作流引用，以便 Actions 列表显示 release/YYYY.M.PATCH，与之前的稳定版 macOS 交接运行相符。
• 不要在此公开交接验证中使用 --ref main 或 --ref vYYYY.M.PATCH。 工作流会在内部根据 tag 输入检出标签。

发布运维预检：

gh workflow run openclaw-macos-publish.yml --repo openclaw/releases --ref main \
  -f tag=vYYYY.M.PATCH \
  -f source_ref=release/YYYY.M.PATCH \
  -f preflight_only=true \
  -f smoke_test_only=false \
  -f allow_late_calver_recovery=false \
  -f public_release_branch=release/YYYY.M.PATCH

根据配置的环境策略，跟进运行直至签名和公证完成。记录成功预检的运行 ID；审批暂停不算成功预检。

恢复是默认行为。在失败后（公证服务中断、DMG 打包、收集器）重新派发相同的预检命令，会从同一标签和源 SHA 对应的失败或取消的 main 派发所留下的最新检查点恢复每个变体；只有没有检查点的变体才会重新构建。运行日志会打印 Resuming <variant> from run <id> attempt <n> 或 Building <variant>。ignore_checkpoints=true 会强制全新构建。仅在需要固定到某个特定运行，或检查点是在恢复索引创建之前生成时（macos-resume-<tag>-<variant>-<sha> 资源），才传入 resume_notarization_run_id、resume_notarization_run_attempt 和 resume_notarization_variant。如果失败的作业仍在当前运行中，优先使用 gh run rerun <run-id> --failed --repo openclaw/releases。

分支变体预检的发布运维验证：

gh workflow run openclaw-macos-validate.yml --repo openclaw/releases --ref main \
  -f tag=vYYYY.M.PATCH \
  -f source_ref=release/YYYY.M.PATCH

记录成功验证的运行 ID。

正式发布：

gh workflow run openclaw-macos-publish.yml --repo openclaw/releases --ref main \
  -f tag=vYYYY.M.PATCH \
  -f preflight_only=false \
  -f smoke_test_only=false \
  -f preflight_run_id=<successful-preflight-run> \
  -f validate_run_id=<successful-validation-run> \
  -f allow_late_calver_recovery=false \
  -f public_release_branch=release/YYYY.M.PATCH

根据相同的发布授权和当前环境策略，跟进晋级过程，直至资源上传和 appcast 发布完成。

• 发布运维的 openclaw/releases 发布/验证工作流会使用其自身受信任的 main 工作流引用运行。正式发布设有防护措施，会拒绝任何其他工作流引用。显示的 main 引用是预期行为；公开的 OpenClaw 源由 tag 和可选的 source_ref 指定。

验证

• gh release view vYYYY.M.PATCH --repo openclaw/openclaw 显示 zip、dmg、dSYM zip；npm 发布器完成切换后：不是草稿，也不是预发布。
• 公开的 main appcast.xml 指向 OpenClaw-YYYY.M.PATCH.zip。
• Appcast 条目包含 sparkle:version、sparkle:shortVersionString、长度和 sparkle:edSignature。