OpenClaw Mac 版本發布

OpenClaw Mac 版本發布 是做什麼的？

當涉及穩定 macOS 資產、發布操作 mac 預檢、公證、Appcast 推廣或 Mac 版本恢復時，請與 $release-openclaw-maintainer、$release-openclaw-ci、$one-password 以及（如果存在的話）$release-private 一起使用。

這是一個常規的穩定版本發布技能。請勿為延伸穩定版本（extended-stable）呼叫此技能；該追蹤的 GitHub Release 帶有共享的驗證證據，但不會繼承 macOS 資產或 Appcast 推廣。

發布授權

明確的穩定或完整版本請求包含 macOS 發布，除非操作者限制其範圍。在驗證、簽署、公證、推廣與驗證過程中繼續進行，無需另外詢問 macOS 的同意。保留確切的發布身份與所有工件校驗碼。macOS 發布與 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

目標 release-ops 倉庫環境：openclaw/releases，環境 mac-release。

僅在本地公證驗證通過後設定：

• APP_STORE_CONNECT_API_KEY_P8
• APP_STORE_CONNECT_KEY_ID
• APP_STORE_CONNECT_ISSUER_ID

請勿從混合來源更新這些 Secrets。所有三個 ASC 欄位必須來自同一個 1Password 項目。

工作流程形狀

• openclaw/openclaw 是公開產品倉庫。其 GitHub Releases 頁面是 macOS 資產最終附加的地方。
• openclaw/openclaw 的 macos-release.yml 僅是公開交接驗證。它從不簽署、公證或上傳 macOS 資產，無論 preflight_only 為何。
• openclaw/releases 是受限制的發布操作倉庫。其 macOS 工作流程負責簽署、公證、驗證並將資產推廣到 openclaw/openclaw 的 GitHub Release 上。
• 公開發布分支在穩定標籤/npm 已經上線後，可能攜帶僅限 Mac 的打包修正。
• 在為該分支變體建置時，對發布操作 mac 預檢/驗證使用 source_ref=release/YYYY.M.PATCH。
• 保持 tag=vYYYY.M.PATCH 指向原始穩定發布提交。
• 真正的 Mac 發布必須重複使用：
  • 針對相同標籤/來源 SHA 的成功發布操作 mac 預檢執行
  • 針對相同標籤/來源 SHA 的成功發布操作 mac 驗證執行
• 發布操作預檢與真正發布使用 mac-release 環境來取得簽署與推廣 Secrets，以及其僅限主分支的部署政策。授權的發布操作者在該環境的當前規則下繼續操作。
• 如果預檢來源 SHA 與標籤 SHA 不同，則驗證也必須使用相同的 source_ref；推廣會拒絕不匹配的證明。

公證

• OpenClaw 使用 scripts/notarize-mac-artifact.sh。
• xcrun notarytool submit 應使用 --no-s3-acceleration；加速上傳即使在 notarytool history 成功時也可能導致誤導性的 401 錯誤。
• 如果簽署成功但公證立即因 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

• 將公開發布分支用作 workflow ref，以便 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 打包、收集器）後重新調度相同的預檢命令，會從失敗或取消的 main 調度中針對相同標籤與來源 SHA 的最新檢查點開始續傳每一個變體；只有沒有檢查點的變體會重新建置。執行日誌會印出 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=<成功的預檢執行 ID> \
  -f validate_run_id=<成功的驗證執行 ID> \
  -f allow_late_calver_recovery=false \
  -f public_release_branch=release/YYYY.M.PATCH

在相同的發布授權與當前環境政策下，跟隨資產上傳與 Appcast 發布過程中的推廣。

• 發布操作倉庫 openclaw/releases 的發布/驗證工作流程從其自身受信任的 main workflow ref 執行。真正發布有一個防護機制，會拒絕任何其他 workflow ref。顯示的 main ref 是預期行為；公開的 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。