如何發佈 OpenClaw macOS 版本並整合 Sparkle 自動更新

搞定 macOS 的發佈流程通常是一場惡夢。你需要處理開發者憑證、公證（Notarization），還要確保使用者能順利拿到自動更新，而不是每次都要手動下載新的 DMG。如果這些流程沒有自動化，開發者的效率會大打折扣。

這份指南會帶你走過 OpenClaw 的 macOS 發佈流程，讓你的 App 具備 Sparkle 自動更新功能。

需要準備的東西

在開始之前，請確保你的開發環境已經準備好以下項目：

• 已安裝 Developer ID Application 憑證（例如：Developer ID Application: <Developer Name> (<TEAMID>)）。
• 環境變數中已設定 Sparkle 私鑰路徑 (SPARKLE_PRIVATE_KEY_FILE)。如果找不到，請檢查你的 ~/.profile。
• 用於 xcrun notarytool 的 Notary 憑證（Keychain profile 或 API key）。
• 已安裝 pnpm 依賴（使用 pnpm install --config.node-linker=hoisted）。
• Sparkle 工具：這些工具會透過 SwiftPM 自動下載至 apps/macos/.build/artifacts/sparkle/Sparkle/bin/。

快速開始

跟著這些步驟，在 5 分鐘內完成打包與發佈準備。

1. 本地打包與簽署

首先，在 repo 根目錄執行腳本。請注意 APP_BUILD 必須是純數字且持續遞增，否則 Sparkle 無法正確比較版本。

BUNDLE_ID=ai.openclaw.mac \
APP_VERSION=2026.3.7 \
BUILD_CONFIG=release \
SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
scripts/package-mac-app.sh

2. 製作發佈壓縮檔與 DMG

使用 ditto 保留資源分叉（Resource forks），這對 Sparkle 的增量更新（Delta support）非常重要。

# 製作 Zip 檔
ditto -c -k --sequesterRsrc --keepParent dist/OpenClaw.app dist/OpenClaw-2026.3.7.zip

# 製作給一般使用者使用的 DMG
scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.3.7.dmg

3. 公證並完成發佈路徑

如果你要正式發佈，建議直接使用 package-mac-dist.sh。它會幫你完成打包、公證與 Staple 的動作。你需要先建立一個 Keychain profile：

# 建立一次性的 Keychain profile
xcrun notarytool store-credentials "openclaw-notary" \
  --apple-id "<apple-id>" --team-id "<team-id>" --password "<app-specific-password>"

# 執行完整發佈流程
NOTARIZE=1 NOTARYTOOL_PROFILE=openclaw-notary \
BUNDLE_ID=ai.openclaw.mac \
APP_VERSION=2026.3.7 \
BUILD_CONFIG=release \
SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
scripts/package-mac-dist.sh

4. 產生 Appcast 進入點

Sparkle 需要 appcast.xml 來得知更新資訊。我們使用腳本將 CHANGELOG.md 轉換為 HTML 格式並嵌入 XML 中。

SPARKLE_PRIVATE_KEY_FILE=/path/to/ed25519-private-key scripts/make_appcast.sh dist/OpenClaw-2026.3.7.zip https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml

疑難排解

APP_BUILD 版本衝突

如果你的 APP_BUILD 包含非數字字元（例如 -beta），Sparkle 會將其視為相等，導致自動更新失效。請確保 APP_BUILD 是純數字。如果你省略此參數，系統會根據 APP_VERSION 自動生成。

找不到 Sparkle 私鑰

如果腳本報錯找不到私鑰，請檢查 SPARKLE_PRIVATE_KEY_FILE 變數是否正確指向你的 ed25519 私鑰檔案。

公證失敗

請確保你的 App Store Connect API key 已正確匯入 Keychain。你可以透過以下指令檢查 openclaw-notary profile 是否存在。

驗證發佈

上傳 OpenClaw-2026.3.7.zip 到 GitHub Release 後，請執行以下檢查：

1. 確認 curl -I <appcast_url> 回傳 200。
2. 在舊版本的 App 中點擊「檢查更新」，確認 Sparkle 能順利安裝新版本。

有任何問題？請詢問 AI Setup Assistant

下一步

• GitHub Actions 自動化發佈流程
• Sparkle 進階配置說明