跳到內容
OpenClaw

OpenClaw 發佈指南：macOS 與 npm 版本管理實戰

身為開發者，我們最怕的就是發布流程出包，特別是當你需要同時處理 npm 套件與跨平台應用程式時，手動操作往往容易出錯。透過自動化的發布流程，我們可以確保每次更新都經過嚴格驗證，讓 OpenClaw 的發布流程更穩定、更可預測。

OpenClaw 透過標準化的發布流程來管理其發布版本，確保所有使用者都能獲得高品質的更新。OpenClaw 擁有三種公開的發布通道：

  • stable：預設發布至 npm beta 的標記版本，若有明確需求也可發布至 npm latest。
  • beta：發布至 npm beta 的預發布標記。
  • dev：追蹤 main 分支的最新變動。

版本命名

Section titled “版本命名”

版本命名遵循嚴格的格式，以確保版本控制的清晰度。

  1. 穩定版版本號：YYYY.M.D
    • Git tag：vYYYY.M.D
  2. 穩定修正版版本號：YYYY.M.D-N
    • Git tag：vYYYY.M.D-N
  3. Beta 預發布版本號：YYYY.M.D-beta.N
    • Git tag：vYYYY.M.D-beta.N
  4. 月份與日期請勿使用零填充（zero-pad）。
  5. latest 代表當前推廣的穩定 npm 發布版本。
  6. beta 代表當前的 beta 安裝目標。
  7. 穩定版與穩定修正版預設發布至 npm beta；發布操作員可明確指定 latest，或稍後推廣經過驗證的 beta 建置。
  8. 每次 OpenClaw 發布都會同時釋出 npm 套件與 macOS 應用程式。

發布節奏

Section titled “發布節奏”

發布流程採取先 beta 後穩定的策略，以確保系統穩定性。

  1. 發布流程優先進入 beta 通道。
  2. 只有在最新的 beta 版本經過驗證後，才會進行穩定版發布。
  3. 詳細的發布程序、核准流程、憑證管理及復原說明僅供維護者查閱。

發布前置檢查

Section titled “發布前置檢查”

在正式發布前，必須執行一系列的檢查以確保建置品質。

  1. 在發布前置檢查前執行 pnpm check:test-types，確保 TypeScript 測試涵蓋範圍不受限於較快的本地 pnpm check 閘道。
  2. 在發布前置檢查前執行 pnpm check:architecture，確保架構邊界檢查通過。
  3. 在 pnpm release:check 前執行 pnpm build && pnpm ui:build，確保 dist/* 發布產物與 Control UI bundle 存在。
  4. 每次標記發布前執行 pnpm release:check。
  5. 發布檢查現在於獨立的手動 workflow 中執行：OpenClaw Release Checks。
  6. 跨作業系統的安裝與升級驗證由私有呼叫 workflow 發送：openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml，該流程會呼叫可重複使用的公開 workflow .github/workflows/openclaw-cross-os-release-checks-reusable.yml。
  7. 此拆分是有意為之：保持實際的 npm 發布路徑簡短且確定，同時將較慢的即時檢查留在獨立通道，避免阻塞發布。
  8. 發布檢查必須從 main workflow 參照發送，以保持邏輯與機密的一致性。
  9. 該 workflow 接受現有的發布標記或當前完整的 40 字元 main commit SHA。
  10. 在 commit-SHA 模式下，僅接受當前的 origin/main HEAD；舊的發布提交請使用發布標記。
  11. OpenClaw NPM Release 僅驗證的前置檢查也接受當前完整的 40 字元 main commit SHA，無需推送標記。
  12. 該 SHA 路徑僅供驗證，無法推廣至正式發布。
  13. 在 SHA 模式下，workflow 僅為套件元數據檢查合成 v<package.json version>；正式發布仍需真實的發布標記。
  14. 兩個 workflow 皆將正式發布與推廣路徑保留在 GitHub-hosted runners 上，而非變更的驗證路徑可使用較大的 Blacksmith Linux runners。
  15. 該 workflow 執行：
Terminal window
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache
  1. 使用 OPENAI_API_KEY 與 ANTHROPIC_API_KEY workflow 機密。
  2. npm 發布前置檢查不再等待獨立的發布檢查通道。
  3. 在核准前執行：
Terminal window
RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts

（或對應的 beta/修正標記）。 19. npm 發布後，執行以下指令以驗證新環境中的安裝路徑：

Terminal window
node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D

（或對應的 beta/修正版本）。 20. 維護者發布自動化現在使用「先預檢後推廣」模式：

  • 正式 npm 發布必須通過成功的 npm preflight_run_id。
  • 穩定 npm 發布預設為 beta。
  • 穩定 npm 發布可透過 workflow 輸入明確指定 latest。
  • 基於 token 的 npm dist-tag 變更位於 openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml 以確保安全，因為 npm dist-tag add 仍需 NPM_TOKEN，而公開 repo 僅使用 OIDC 發布。
  • 公開 macOS Release 僅供驗證。
  • 正式的私有 mac 發布必須通過成功的私有 mac preflight_run_id 與 validate_run_id。
  • 正式發布路徑會推廣已準備好的產物，而非重新建置。
  1. 對於像 YYYY.M.D-N 的穩定修正版，發布後驗證器會檢查從 YYYY.M.D 到 YYYY.M.D-N 的升級路徑，確保修正版不會遺留舊的全局安裝。
  2. npm 發布前置檢查若 tarball 未包含 dist/control-ui/index.html 與非空的 dist/control-ui/assets/ 則會失敗，避免發布空的瀏覽器儀表板。
  3. pnpm test:install:smoke 會強制執行 npm pack unpackedSize 預算，確保安裝程式 e2e 能在發布前捕捉到意外的套件膨脹。
  4. 若發布工作涉及 CI 規劃、擴充功能時序清單或測試矩陣，請在核准前重新生成並審查 .github/workflows/ci.yml 中的 checks-node-extensions workflow 矩陣輸出。
  5. 穩定的 macOS 發布就緒狀態包含更新機制：
    • GitHub 發布必須包含打包好的 .zip、.dmg 與 .dSYM.zip。
    • main 分支上的 appcast.xml 在發布後必須指向新的穩定 zip。
    • 打包後的應用程式必須保留非除錯用的 bundle id、非空的 Sparkle feed URL，以及等於或高於該版本 Sparkle 建置底線的 CFBundleVersion。

NPM workflow 輸入

Section titled “NPM workflow 輸入”

OpenClaw NPM Release 接受以下由操作員控制的輸入參數。

  1. tag：必要的發布標記，例如 v2026.4.2、v2026.4.2-1 或 v2026.4.2-beta.1；當 preflight_only=true 時，也可為當前完整的 40 字元 main commit SHA。
  2. preflight_only：true 為僅驗證/建置/打包，false 為正式發布路徑。
  3. preflight_run_id：正式發布路徑所必需，用於重複使用前置檢查產生的 tarball。
  4. npm_dist_tag：發布路徑的 npm 目標標記；預設為 beta。
  5. OpenClaw Release Checks 接受操作員控制的 ref 輸入：現有的發布標記或當前完整的 40 字元 main commit SHA。
  6. 規則：
    • 穩定版與修正版標記可發布至 beta 或 latest。
    • Beta 預發布標記僅可發布至 beta。
    • 僅在 preflight_only=true 時允許使用完整的 commit SHA 輸入。
    • 發布檢查的 commit-SHA 模式亦要求當前的 origin/main HEAD。
    • 正式發布路徑必須使用與前置檢查相同的 npm_dist_tag；workflow 會在發布前驗證此元數據。

穩定 npm 發布順序

Section titled “穩定 npm 發布順序”

當執行穩定 npm 發布時，請遵循以下步驟以確保流程順暢。

  1. 執行 OpenClaw NPM Release 並設定 preflight_only=true。
    • 在標記存在前，可使用當前完整的 main commit SHA 進行驗證性試運行。
  2. 選擇 npm_dist_tag=beta 進行標準的 beta-first 流程，或僅在有意直接發布穩定版時選擇 latest。
  3. 使用相同的標記或完整的 main commit SHA 獨立執行 OpenClaw Release Checks 以取得即時 prompt cache 覆蓋率。
    • 此步驟獨立執行是為了在不耦合長時運行或不穩定檢查的情況下，維持即時覆蓋率。
  4. 儲存成功的 preflight_run_id。
  5. 再次執行 OpenClaw NPM Release，設定 preflight_only=false，並使用相同的 tag、npm_dist_tag 以及儲存的 preflight_run_id。
  6. 若發布落在 beta，請使用私有的 openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml workflow 將該穩定版本從 beta 推廣至 latest。
  7. 若有意直接發布至 latest 且 beta 應立即跟進相同的穩定建置，請使用相同的私有 workflow 將兩個 dist-tags 指向該穩定版本，或等待其排程的自動同步在稍後移動 beta。
  8. dist-tag 的變更位於私有 repo 以確保安全，因為其仍需 NPM_TOKEN，而公開 repo 僅使用 OIDC 發布。
  9. 此舉確保了直接發布路徑與 beta-first 推廣路徑皆有文件記錄且對操作員可見。

公開參考資料

Section titled “公開參考資料”

以下是 OpenClaw 發布流程中使用的公開參考連結。

  1. .github/workflows/openclaw-npm-release.yml
  2. .github/workflows/openclaw-release-checks.yml
  3. .github/workflows/openclaw-cross-os-release-checks-reusable.yml
  4. scripts/openclaw-npm-release-check.ts
  5. scripts/package-mac-dist.sh
  6. scripts/make_appcast.sh

維護者請參考私有發布文件 openclaw/maintainers/release/README.md 進行實際操作。

下一步

Section titled “下一步”

若在發布過程中遇到任何問題，歡迎隨時透過 AI Setup Assistant 尋求協助。

OpenClaw

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。