發布政策

• stable：現有的已推廣發行通道；在獨立的命令列介面/通道里程碑完成之前，仍會透過 npm latest 解析
• beta：發布到 npm beta 的預發行標籤
• dev：main 的移動最新提交

​

版本命名

• 每月 npm extended-stable 發行版本：YYYY.M.PATCH，其中 PATCH >= 33，git 標籤 vYYYY.M.PATCH
• 每日/一般 final 發行版本：YYYY.M.PATCH，其中 PATCH < 33，git 標籤 vYYYY.M.PATCH
• 一般 fallback 修正發行版本：YYYY.M.PATCH-N，git 標籤 vYYYY.M.PATCH-N
• Beta 預發行版本：YYYY.M.PATCH-beta.N，git 標籤 vYYYY.M.PATCH-beta.N
• Alpha 預發行版本：YYYY.M.PATCH-alpha.N，git 標籤 vYYYY.M.PATCH-alpha.N
• 月份或修補版絕不補零
• PATCH 是每月發行列車的序號，不是日曆日期。一般 final 與 beta 發行會推進目前列車；僅 alpha 的標籤絕不消耗或推進 beta/一般修補版號，因此選擇 beta 或一般列車時，請忽略修補版號較高的舊版僅 alpha 標籤。
• Alpha/nightly 建置使用下一個尚未發行的修補版列車，重複建置時只遞增 alpha.N。一旦該修補版已有 beta，新的 alpha 建置會移到下一個修補版。
• npm 版本不可變：絕不刪除、重新發布或重複使用已發布的標籤。請改切下一個預發行編號或下一個每月修補版。
• latest 繼續跟隨目前的一般/每日 npm 線；beta 是目前的 beta 安裝目標
• extended-stable 表示受支援的前一個月份 npm 套件，從修補版 33 開始；修補版 34 及之後版本是該月線上的維護發行
• 一般 final 與一般修正發行預設發布到 npm beta；發行操作員可以明確指定 latest，或稍後推廣已審核的 beta 建置
• 專用的每月 extended-stable 路徑會以完全相同版本發布核心 npm 套件與每個可發布到 npm 的官方外掛。它不會將外掛發布到 ClawHub，也不會發布 macOS 或 Windows 成品、GitHub Release、私有儲存庫 dist-tag、Docker 映像、行動端成品或網站下載。
• 每個一般 final 發行會一併交付 npm 套件、macOS app 與已簽署的 Windows Hub 安裝程式。Beta 發行通常會先驗證並發布 npm/套件路徑，原生 app 建置/簽署/公證/推廣則保留給一般 final，除非明確要求。

​

發行節奏

• 發行先進入 beta；只有在最新 beta 驗證完成後，stable 才會跟進
• 維護者通常會從目前 main 建立 release/YYYY.M.PATCH 分支來切發行，因此發行驗證與修正不會阻塞 main 上的新開發
• 如果 beta 標籤已推送或發布且需要修正，維護者會切下一個 -beta.N 標籤，而不是刪除或重建舊標籤
• 詳細發行程序、核准、憑證與復原註記僅限維護者

​

每月僅 npm 的 extended-stable 發布

gh workflow run openclaw-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f tag=vYYYY.M.P \
  -f preflight_only=true \
  -f npm_dist_tag=extended-stable

gh workflow run full-release-validation.yml \
  --ref extended-stable/YYYY.M.33 \
  -f ref=extended-stable/YYYY.M.33 \
  -f release_profile=stable

RELEASE_SHA="$(git rev-parse HEAD)"
gh workflow run plugin-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f publish_scope=all-publishable \
  -f ref="$RELEASE_SHA" \
  -f npm_dist_tag=extended-stable

gh workflow run openclaw-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f tag=vYYYY.M.P \
  -f preflight_only=false \
  -f npm_dist_tag=extended-stable \
  -f preflight_run_id=<npm-preflight-run-id> \
  -f full_release_validation_run_id=<full-validation-run-id> \
  -f plugin_npm_run_id=<plugin-npm-run-id>

npm view openclaw@YYYY.M.P version --userconfig "$(mktemp)"
npm view openclaw@extended-stable version --userconfig "$(mktemp)"

​

一般發行操作員檢查清單

1. 從目前的 main 開始：拉取最新版本、確認目標 commit 已推送，並確認 main CI 綠到足以從它建立分支。
2. 從上一個可到達發行標籤之後合併的 PR 與所有直接 commit 產生最上層 CHANGELOG.md 區段。保持條目面向使用者、去除重疊的 PR/直接 commit 條目、提交、推送，並在建立分支前再 rebase/pull 一次。
3. 檢閱 src/plugins/compat/registry.ts 與 src/commands/doctor/shared/deprecation-compat.ts 中的發行相容性記錄。只有在升級路徑仍受涵蓋時才移除已過期相容性，否則記錄為何有意保留。
4. 從目前的 main 建立 release/YYYY.M.PATCH。不要直接在 main 上執行一般發行工作。
5. 為該標籤升版每個必要的版本位置，然後執行 pnpm release:prep。它會依序重新整理外掛版本、npm shrinkwrap、外掛清單、基礎設定 schema、內建通道設定 metadata、設定文件 baseline、外掛 SDK 匯出，以及外掛 SDK API baseline。在標記前提交任何產生的 drift，然後執行本機 deterministic 預檢：pnpm check:test-types、pnpm check:architecture、pnpm build && pnpm ui:build，以及 pnpm release:check。
6. 使用 preflight_only=true 執行 OpenClaw NPM Release。在標籤存在前，可使用完整 40 字元發行分支 SHA 作為僅驗證預檢。預檢會為精確 checkout 的依賴圖產生依賴發行證據，並將其儲存在 npm 預檢 artifact 中。儲存成功的 preflight_run_id。
7. 對發行分支、標籤或完整 commit SHA 以 Full Release Validation 啟動所有預發行測試。這是四個大型發行測試機器的唯一手動進入點：Vitest、Docker、QA Lab 與 Package。儲存 full_release_validation_run_id；它是 OpenClaw NPM Release 與 OpenClaw Release Publish 的必要輸入。
8. 如果驗證失敗，請在發行分支上修正，並重新執行能證明修正的最小失敗檔案、lane、工作流程 job、套件 profile、provider 或 model allowlist。只有在變更的介面讓先前證據過時時，才重新執行完整 umbrella。
9. 對於已標記的 beta 候選版本，從相符的 release/YYYY.M.PATCH 分支執行 pnpm release:candidate -- --tag vYYYY.M.PATCH-beta.N。對於 stable，也傳入必要的 Windows 來源發行：pnpm release:candidate -- --tag vYYYY.M.PATCH --windows-node-tag vX.Y.Z。該 helper 會執行本機產生式發行檢查，dispatch 或驗證完整發行驗證與 npm 預檢證據，針對精確已準備 tarball 加上 Telegram 套件證據執行 Parallels fresh/update 證明，記錄外掛 npm 與 ClawHub 計畫，並且只在證據 bundle 全綠後列印精確的 OpenClaw Release Publish 命令。 OpenClaw Release Publish 會將選取的或所有可發布的外掛套件 dispatch 到 npm，並將同一組套件平行 dispatch 到 ClawHub；接著在外掛 npm 發布成功後，使用相符的 dist-tag 推升已準備好的 OpenClaw npm 預檢成品。OpenClaw npm 發布子流程成功後，它會從完整且相符的 CHANGELOG.md 章節建立或更新對應的 GitHub release/prerelease 頁面：發布到 npm latest 的穩定版會成為 GitHub latest release，保留在 npm beta 的穩定維護版則會以 GitHub latest=false 建立。此工作流程也會將預檢相依性證據、完整驗證 manifest，以及發布後 registry 驗證證據上傳到 GitHub release，以供發布後事件回應使用。它會立即列印子流程 run ID，自動核准 workflow token 允許核准的 release environment gate，以記錄尾端摘要失敗的子工作，在 OpenClaw npm 發布成功後立即完成 GitHub release 與相依性證據，當 OpenClaw npm 正在發布時等待 ClawHub，然後執行 pnpm release:verify-beta，並為 GitHub release、npm 套件、選取的外掛 npm 套件、選取的 ClawHub 套件、子工作流程 run ID，以及選用的 NPM Telegram run ID 上傳發布後證據。ClawHub 路徑會重試暫時性的命令列介面相依性安裝失敗，即使某個 preview cell 發生 flakes 仍會發布通過 preview 的外掛，最後會對每個預期的外掛版本執行 registry 驗證，讓部分發布保持可見且可重試。 然後針對已發布的 openclaw@YYYY.M.PATCH-beta.N 或 openclaw@beta 套件執行發布後套件接受測試。如果已推送或已發布的 prerelease 需要修正，請切出下一個相符的 prerelease 編號；絕不可刪除或重寫舊版本。
10. 對穩定版，只有在已審核的 beta 或 release candidate 具備必要驗證證據後才繼續。穩定版 npm 發布也會透過 OpenClaw Release Publish，使用 preflight_run_id 重用成功的預檢成品。穩定版 macOS 發布就緒也要求已封裝的 .zip、.dmg、.dSYM.zip，以及 main 上更新後的 appcast.xml；macOS 發布工作流程會在 release 資產驗證後，自動將已簽署的 appcast 發布到公開 main，或者在分支保護阻擋直接推送時開啟/更新 appcast PR。穩定版 Windows Hub 就緒要求 OpenClaw GitHub release 上有已簽署的 OpenClawCompanion-Setup-x64.exe、OpenClawCompanion-Setup-arm64.exe 和 OpenClawCompanion-SHA256SUMS.txt 資產。將確切已簽署的 openclaw/openclaw-windows-node release tag 作為 windows_node_tag 傳入，並將其已通過 candidate 核准的安裝程式 digest map 作為 windows_node_installer_digests 傳入；OpenClaw Release Publish 會保留 release draft、dispatch Windows Node Release，並在發布前驗證全部三個資產。
11. 發布後，執行 npm 發布後驗證器；需要發布後通道證據時，執行選用的獨立已發布 npm Telegram E2E；在需要時執行 dist-tag 推升；驗證產生的 GitHub release 頁面；執行 release announcement 步驟；然後完成 穩定版 main 收尾，之後才可稱穩定版發布完成。

​

穩定版 main 收尾

1. 從全新的最新 main 開始。對照它稽核 release/YYYY.M.PATCH，並 forward-port main 缺少的實際修正。不要盲目將只存在於 release 的相容性、測試或驗證 adapter merge 到較新的 main。
2. 將 main 設為已出貨的穩定版本，而不是推測性的下一列車版本。在根版本變更後執行 pnpm release:prep，然後執行 pnpm deps:shrinkwrap:generate。
3. 讓 main 上 CHANGELOG.md 的 ## YYYY.M.PATCH 章節與已標記的 release 分支完全一致。若 mac release 發布了穩定版 appcast.xml 更新，也要包含它。
4. 在操作者明確開始該 release train 之前，不要將 YYYY.M.PATCH+1、beta 版本，或空白的未來 changelog 章節加入 main。
5. 執行 pnpm release:generated:check、pnpm deps:shrinkwrap:check 和 OPENCLAW_TESTBOX=1 pnpm check:changed。推送後，在稱穩定版 release 完成前，驗證 origin/main 包含已出貨版本與 changelog。
6. 每次私有 rollback drill 後，保持 repository variables RELEASE_ROLLBACK_DRILL_ID 和 RELEASE_ROLLBACK_DRILL_DATE 為最新。

​

Release 預檢

• 在 release 預檢前執行 pnpm check:test-types，讓測試 TypeScript 在較快的本機 pnpm check gate 之外仍受到涵蓋。
• 在 release 預檢前執行 pnpm check:architecture，讓更廣泛的 import cycle 與架構邊界檢查在較快的本機 gate 之外保持綠燈。
• 在 pnpm release:check 前執行 pnpm build && pnpm ui:build，讓預期的 dist/* release 成品與 Control UI bundle 存在，以供 pack 驗證步驟使用。
• 在根版本 bump 後、標記 tag 前執行 pnpm release:prep。它會執行每個在版本/設定/API 變更後常見漂移的 deterministic release generator：外掛版本、npm shrinkwrap、外掛 inventory、基礎 config schema、bundled channel config metadata、config docs baseline、外掛 SDK exports，以及外掛 SDK API baseline。pnpm release:check 會以 check mode 重新執行這些 guard（另加外掛 SDK surface budget check），並在執行套件 release 檢查前，一次回報每個產生內容漂移失敗。
• 外掛版本同步預設會將可發布的 @openclaw/ai runtime package、官方外掛套件版本，以及既有的 openclaw.compat.pluginApi floors 更新到 OpenClaw release 版本。請將該欄位視為外掛 SDK/runtime API floor，而不只是套件版本的副本：對於刻意維持與較舊 OpenClaw host 相容的僅外掛 release，請將 floor 保持在最舊支援的 host API，並在外掛 release proof 中記錄該選擇。
• 在 release 核准前執行手動 Full Release Validation 工作流程，從單一 entrypoint 啟動所有 pre-release test box。它接受分支、tag 或完整 commit SHA，dispatch 手動 CI，並為 install smoke、package acceptance、cross-OS package checks、QA Lab parity、Matrix 和 Telegram lanes dispatch OpenClaw Release Checks。穩定版與完整 run 一律包含詳盡的 live/E2E 與 Docker release-path soak；run_release_soak=true 保留給明確的 beta soak。Package Acceptance 會在 candidate validation 期間提供 canonical package Telegram E2E，避免第二個並行 live poller。 發布 beta 後提供 release_package_spec，即可在 release checks、Package Acceptance 與 package Telegram E2E 之間重用已出貨的 npm 套件，而不重新建置 release tarball。只有在 Telegram 應使用與其他 release validation 不同的已發布套件時，才提供 npm_telegram_package_spec。當 Package Acceptance 應使用與 release package spec 不同的已發布套件時，提供 package_acceptance_package_spec。當 release evidence report 應證明驗證符合已發布的 npm 套件、但不強制執行 Telegram E2E 時，提供 evidence_package_spec。
  gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.PATCH
  
• 當你希望在 release 工作持續進行時，為套件 candidate 取得 side-channel proof，請執行手動 Package Acceptance 工作流程。對 openclaw@beta、openclaw@latest 或確切 release 版本使用 source=npm；使用 source=ref 以目前的 workflow_ref harness 打包受信任的 package_ref 分支/tag/SHA；對具備必要 SHA-256 與嚴格公開 URL policy 的公開 HTTPS tarball 使用 source=url；對使用必要 trusted_source_id 與 SHA-256 的具名 trusted-source policy 使用 source=trusted-url；或對另一個 GitHub Actions run 上傳的 tarball 使用 source=artifact。 此工作流程會將 candidate 解析為 package-under-test，針對該 tarball 重用 Docker E2E release scheduler，並可用 telegram_mode=mock-openai 或 telegram_mode=live-frontier 對同一 tarball 執行 Telegram QA。當選取的 Docker lanes 包含 published-upgrade-survivor 時，package artifact 是 candidate，而 published_upgrade_survivor_baseline 會選取已發布的 baseline。update-restart-auth 會將 candidate package 同時作為已安裝的命令列介面與 package-under-test，藉此演練 candidate update command 的 managed restart path。 範例：
  gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai
  
  常用 profiles：
  • smoke：install/channel/agent、gateway network 和 config reload lanes
  • package：artifact-native package/update/restart/plugin lanes，不含 OpenWebUI 或 live ClawHub
  • product：package profile，加上 MCP channels、cron/subagent cleanup、OpenAI web search 和 OpenWebUI
  • full：包含 OpenWebUI 的 Docker release-path chunks
  • custom：用於 focused rerun 的確切 docker_lanes 選取
• 當你只需要 release candidate 的 deterministic normal CI coverage 時，直接執行手動 CI 工作流程。手動 CI dispatch 會繞過 changed scoping，並強制執行 Linux 節點 shards、bundled-plugin shards、plugin and channel contract shards、節點 22 compatibility、check-*、check-additional-*、built-artifact smoke checks、docs checks、Python skills、Windows、macOS，以及 Control UI i18n lanes。獨立手動 CI run 只有在以 include_android=true dispatch 時才執行 Android；Full Release Validation 會為其 CI 子流程傳入該 input。
  gh workflow run ci.yml --ref release/YYYY.M.PATCH -f include_android=true
  
• 驗證發布遙測時，執行 pnpm qa:otel:smoke。它會透過本機 OTLP/HTTP 接收器執行 QA-lab，並驗證追蹤、指標與日誌匯出，以及有界限的追蹤屬性和內容/識別碼遮蔽，不需要 Opik、Langfuse 或其他外部收集器。
• 驗證收集器相容性時，執行 pnpm qa:otel:collector-smoke。它會先透過真正的 OpenTelemetry Collector Docker 容器路由相同的 QA-lab OTLP 匯出，再進行本機接收器斷言。
• 驗證受保護的 Prometheus 抓取時，執行 pnpm qa:prometheus:smoke。它會執行 QA-lab、拒絕未驗證的抓取，並驗證發布關鍵的指標族群不含提示內容、原始識別碼、驗證權杖與本機路徑。
• 執行 pnpm qa:observability:smoke，連續跑完原始碼簽出中的 OpenTelemetry 與 Prometheus 煙霧測試通道。
• 每次標記發布前執行 pnpm release:check。
• OpenClaw NPM Release 預檢會在打包 npm tarball 之前產生依賴項發布證據。npm advisory 漏洞閘門會阻擋發布。傳遞性 manifest 風險、依賴項所有權/安裝表面，以及依賴項變更報告僅作為發布證據。依賴項變更報告會比較發布候選版與前一個可到達的發布標籤。預檢會將依賴項證據上傳為 openclaw-release-dependency-evidence-<tag>，也會將它嵌入準備好的 npm 預檢成品內的 dependency-evidence/。真正的發布路徑會重用該預檢成品，然後將同一份證據作為 openclaw-<version>-dependency-evidence.zip 附加到 GitHub 發布。
• 標籤存在後，執行 OpenClaw Release Publish 進行會變更狀態的發布序列。從 release/YYYY.M.PATCH（或發布 main 可到達標籤時的 main）派送它，傳入發布標籤、成功的 OpenClaw npm preflight_run_id，以及成功的 full_release_validation_run_id，並保留預設外掛發布範圍 all-publishable，除非你是刻意執行聚焦修復。此 workflow 會序列化外掛 npm 發布、外掛 ClawHub 發布，以及 OpenClaw npm 發布，確保核心套件不會早於其外部化外掛發布。
• 穩定版 OpenClaw Release Publish 需要在相符的非預發布 openclaw/openclaw-windows-node 發布存在後，提供精確的 windows_node_tag，以及已由候選版核准的 windows_node_installer_digests 映射。在派送任何發布子項目前，它會驗證來源發布已發布、不是預發布、包含必要的 x64/ARM64 安裝程式，且仍符合該核准映射。接著它會在 OpenClaw 發布仍為草稿時派送 Windows Node Release，並原封不動帶入釘選的安裝程式 digest 映射。子 workflow 會從該精確標籤下載已簽署的 Windows Hub 安裝程式，與釘選 digest 比對，在 Windows runner 上驗證其 Authenticode 簽章使用預期的 OpenClaw Foundation 簽署者，寫入 SHA-256 manifest，並將安裝程式與 manifest 上傳到標準 OpenClaw GitHub 發布，然後重新下載已提升的資產並驗證 manifest 成員資格與雜湊值。父 workflow 會在發布前驗證目前的 x64、ARM64 與 checksum 資產合約。直接復原會先拒絕非預期的 OpenClawCompanion-* 資產名稱，再用釘選的來源位元組取代預期的合約資產。 只有在復原時才手動派送 Windows Node Release，且一律傳入精確標籤，絕不要傳 latest，並傳入已核准來源發布中的明確 expected_installer_digests JSON 映射。網站下載連結應指向目前穩定版發布的精確 OpenClaw 發布資產 URL，或只在驗證 GitHub 的 latest 重新導向指向同一個發布後，才使用 releases/latest/download/...；不要只連到 companion repo 發布頁面。
• 發布檢查現在於獨立的手動 workflow 中執行：OpenClaw Release Checks。它也會在發布核准前執行 QA Lab mock parity 通道，以及快速 live Matrix profile 和 Telegram QA 通道。live 通道使用 qa-live-shared 環境；Telegram 也使用 Convex CI 憑證租約。當你想平行執行完整 Matrix 傳輸、媒體與 E2EE 清單時，請以 matrix_profile=all 和 matrix_shards=true 執行手動 QA-Lab - All Lanes workflow。
• 跨作業系統安裝與升級執行階段驗證是公開 OpenClaw Release Checks 和 Full Release Validation 的一部分，它們會直接呼叫可重用 workflow .github/workflows/openclaw-cross-os-release-checks-reusable.yml。這個拆分是刻意的：讓真正的 npm 發布路徑保持短小、確定且聚焦於成品，而較慢的 live 檢查留在自己的通道中，避免拖慢或阻擋發布。
• 帶有祕密的發布檢查應透過 Full Release Validation 派送，或從 main/release workflow ref 派送，讓 workflow 邏輯與祕密維持受控。
• 只要解析出的 commit 可從 OpenClaw 分支或發布標籤到達，OpenClaw Release Checks 接受分支、標籤或完整 commit SHA。
• OpenClaw NPM Release 的僅驗證預檢也接受目前 workflow 分支的完整 40 字元 commit SHA，不需要已推送的標籤。該 SHA 路徑僅供驗證，不能提升為真正發布。在 SHA 模式中，workflow 只會為套件中繼資料檢查合成 v<package.json version>；真正發布仍需要真正的發布標籤。
• 兩個 workflow 都會將真正的發布與提升路徑保留在 GitHub-hosted runner 上，而非變更狀態的驗證路徑可以使用較大的 Blacksmith Linux runner。
• 該 workflow 會使用 OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache，並同時使用 OPENAI_API_KEY 與 ANTHROPIC_API_KEY workflow 祕密。
• npm 發布預檢不再等待獨立的發布檢查通道。
• 在本機標記發布候選版前，執行 RELEASE_TAG=vYYYY.M.PATCH-beta.N pnpm release:fast-pretag-check。此 helper 會依序執行快速發布護欄、外掛 npm/ClawHub 發布檢查、建置、UI 建置，以及 release:openclaw:npm:check，在 GitHub 發布 workflow 開始前捕捉常見會阻擋核准的錯誤。
• 核准前執行 RELEASE_TAG=vYYYY.M.PATCH node --import tsx scripts/openclaw-npm-release-check.ts（或相符的預發布/修正版標籤）。
• npm 發布後，執行 node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.PATCH（或相符的 beta/修正版版本），在全新的暫存 prefix 中驗證已發布 registry 安裝路徑。
• beta 發布後，執行 OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.PATCH-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live，使用共享租用的 Telegram 憑證池，針對已發布的 npm 套件驗證已安裝套件 onboarding、Telegram 設定與真正的 Telegram E2E。本機維護者的一次性操作可以省略 Convex 變數，並直接傳入三個 OPENCLAW_QA_TELEGRAM_* env 憑證。
• 若要從維護者機器執行完整的發布後 beta 煙霧測試，請使用 pnpm release:beta-smoke -- --beta betaN。此 helper 會執行 Parallels npm 更新/全新目標驗證、派送 NPM Telegram Beta E2E、輪詢精確的 workflow run、下載成品，並列印 Telegram 報告。
• 維護者可以透過手動 NPM Telegram Beta E2E workflow，從 GitHub Actions 執行相同的發布後檢查。它刻意只允許手動執行，不會在每次合併時執行。
• 維護者發布自動化使用先預檢後提升：
  • 真正的 npm 發布必須通過成功的 npm preflight_run_id。
  • 真正發布必須從與成功預檢 run 相同的 main 或 release/YYYY.M.PATCH 分支派送（Tideclaw alpha 分支可用於 alpha 預發布）。
  • 穩定版 npm 發布預設為 beta；穩定版 npm 發布可以透過 workflow 輸入明確指定 latest。
  • 以權杖為基礎的 npm dist-tag 變更位於 openclaw/releases/.github/workflows/openclaw-npm-dist-tags.yml，因為 npm dist-tag add 仍需要 NPM_TOKEN，而來源 repo 保持僅使用 OIDC 發布。
  • 公開 macOS Release 僅供驗證；當標籤只存在於發布分支，但 workflow 從 main 派送時，設定 public_release_branch=release/YYYY.M.PATCH。
  • 真正的 macOS 發布必須通過成功的 macOS preflight_run_id 與 validate_run_id。
  • 真正發布路徑會提升已準備好的成品，而不是再次重建它們。
• 對於像 YYYY.M.PATCH-N 這樣的穩定版修正發布，發布後驗證器也會檢查從 YYYY.M.PATCH 到 YYYY.M.PATCH-N 的相同暫存 prefix 升級路徑，確保發布修正不會悄悄讓較舊的全域安裝停留在基礎穩定版 payload。
• 除非 tarball 同時包含 dist/control-ui/index.html 和非空的 dist/control-ui/assets/ payload，否則 npm 發布預檢會失敗關閉，避免我們再次出貨空的瀏覽器儀表板。
• 發布後驗證也會檢查已發布外掛 entrypoint 與套件中繼資料是否存在於已安裝的 registry 版面配置中。若發布缺少外掛執行階段 payload，發布後驗證器會失敗，且不能提升到 latest。
• pnpm test:install:smoke 也會對候選更新 tarball 強制執行 npm pack unpackedSize 預算，因此安裝程式 e2e 能在發布發布路徑前捕捉意外的打包膨脹。
• 如果發布工作觸及 CI 規劃、extension timing manifest 或 extension 測試矩陣，請在核准前重新產生並審查 .github/workflows/plugin-prerelease.yml 中由 planner 擁有的 plugin-prerelease-extension-shard 矩陣輸出，避免發布說明描述過時的 CI 版面配置。
• 穩定版 macOS 發布就緒狀態也包含更新器表面：GitHub 發布最後必須包含打包後的 .zip、.dmg 與 .dSYM.zip；發布後 main 上的 appcast.xml 必須指向新的穩定版 zip（macOS 發布 workflow 會自動提交它，或在直接推送被阻擋時開啟 appcast PR）；打包後的 app 必須保留非除錯 bundle id、非空的 Sparkle feed URL，以及不低於該發布版本標準 Sparkle 建置下限的 CFBundleVersion。

​

發布測試盒

pnpm ci:full-release --sha <full-sha>

gh workflow run full-release-validation.yml \
  --ref main \
  -f ref=release/YYYY.M.PATCH \
  -f provider=openai \
  -f mode=both \
  -f release_profile=stable \
  -f evidence_package_spec=openclaw@YYYY.M.PATCH-beta.N

• minimum：最快的 release-critical OpenAI/core live 與 Docker path
• stable：minimum 加上發行核准所需的 stable provider/backend 涵蓋
• full：stable 加上廣泛的 advisory provider/media 涵蓋

# Validate an unpublished release candidate branch.
gh workflow run full-release-validation.yml \
  --ref main \
  -f ref=release/YYYY.M.PATCH \
  -f provider=openai \
  -f mode=both \
  -f release_profile=stable

# Validate an exact pushed commit.
gh workflow run full-release-validation.yml \
  --ref main \
  -f ref=<40-char-sha> \
  -f provider=openai \
  -f mode=both

# After publishing a beta, add published-package Telegram E2E.
gh workflow run full-release-validation.yml \
  --ref main \
  -f ref=release/YYYY.M.PATCH \
  -f provider=openai \
  -f mode=both \
  -f release_profile=full \
  -f release_package_spec=openclaw@YYYY.M.PATCH-beta.N \
  -f evidence_package_spec=openclaw@YYYY.M.PATCH-beta.N \
  -f npm_telegram_provider_mode=mock-openai

​

Vitest

• 顯示已分派 CI 執行 URL 的 Full Release Validation 摘要
• CI 在精確目標 SHA 上為 green
• 調查 regression 時來自 CI jobs 的失敗或緩慢 shard 名稱
• 當執行需要效能分析時的 Vitest timing artifact，例如 .artifacts/vitest-shard-timings.json

gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.PATCH
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.PATCH -f include_android=true

​

Docker

• 啟用慢速 Bun global install smoke 的完整安裝煙霧測試
• 依目標 SHA 準備/重用 root Dockerfile smoke image，QR、root/gateway 和 installer/Bun smoke jobs 會作為獨立 install-smoke shards 執行
• repository E2E lanes
• release-path Docker chunks：core、package-update-openai、package-update-anthropic、package-update-core、plugins-runtime-plugins、plugins-runtime-services、plugins-runtime-install-a 到 plugins-runtime-install-h
• 要求時在 plugins-runtime-services chunk 內的 OpenWebUI 涵蓋
• 拆分的 bundled 外掛 install/uninstall lanes：bundled-plugin-install-uninstall-0 到 bundled-plugin-install-uninstall-23
• release checks 包含 live suites 時的 live/E2E provider suites 與 Docker live model 涵蓋

​

QA Lab

• mock parity lane，使用 agentic parity pack 將 OpenAI candidate lane 與 anthropic/claude-opus-4-8 baseline 比較
• 使用 qa-live-shared 環境的 fast live Matrix QA profile
• 使用 Convex CI credential leases 的 live Telegram QA lane
• 當發行 telemetry 需要明確本地證明時的 pnpm qa:otel:smoke、pnpm qa:otel:collector-smoke、pnpm qa:prometheus:smoke 或 pnpm qa:observability:smoke

​

Package

• source=npm：openclaw@beta、openclaw@latest，或精確的 OpenClaw 發行版本
• source=ref：使用選取的 workflow_ref harness 打包可信 package_ref 分支、tag 或完整 commit SHA
• source=url：下載需要 package_sha256 的公開 HTTPS .tgz；會拒絕 URL credentials、非預設 HTTPS ports、private/internal/special-use hostnames 或 resolved addresses，以及不安全的 redirects
• source=trusted-url：從 .github/package-trusted-sources.json 中的具名 policy 下載需要 package_sha256 和 trusted_source_id 的 HTTPS .tgz；將此用於 maintainer-owned enterprise mirrors 或 private package repositories，而不是向 source=url 加入 input-level private-network bypass
• source=artifact：重用另一個 GitHub Actions 執行所上傳的 .tgz

gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=npm \
  -f package_spec=openclaw@beta \
  -f suite_profile=product \
  -f published_upgrade_survivor_baseline=openclaw@2026.4.26

• smoke：快速套件安裝／頻道／代理、閘道網路與設定重新載入路徑
• package：安裝／更新／重啟／外掛套件合約，加上即時 ClawHub 技能安裝證明；這是發行檢查預設值
• product：package 加上 MCP 頻道、排程／子代理清理、OpenAI 網頁搜尋與 OpenWebUI
• full：含 OpenWebUI 的 Docker 發行路徑區塊
• custom：用於聚焦重跑的精確 docker_lanes 清單

​

定期發行發佈自動化

1. 簽出發行標籤並解析其提交 SHA。
2. 驗證標籤可從 main 或 release/* 連到（或 alpha 預發行版可從 Tideclaw alpha 分支連到）。
3. 執行 pnpm plugins:sync:check。
4. 以 publish_scope=all-publishable 和 ref=<release-sha> 派送 Plugin NPM Release。
5. 以相同範圍和 SHA 派送 Plugin ClawHub Release。
6. 驗證已儲存的 full_release_validation_run_id 後，以發行標籤、npm dist-tag 和已儲存的 preflight_run_id 派送 OpenClaw NPM Release。
7. 對於穩定版發行，建立或更新 GitHub release 為草稿，使用明確的 windows_node_tag 和候選版本核准的 windows_node_installer_digests 派送 Windows Node Release，並在發佈草稿前驗證標準安裝程式／校驗和成品。

gh workflow run openclaw-release-publish.yml \
  --ref release/YYYY.M.PATCH \
  -f tag=vYYYY.M.PATCH-beta.N \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f full_release_validation_run_id=<successful-full-release-validation-run-id> \
  -f npm_dist_tag=beta

gh workflow run openclaw-release-publish.yml \
  --ref release/YYYY.M.PATCH \
  -f tag=vYYYY.M.PATCH \
  -f windows_node_tag=vX.Y.Z \
  -f windows_node_installer_digests='{"OpenClawCompanion-Setup-x64.exe":"sha256:<approved-x64-sha256>","OpenClawCompanion-Setup-arm64.exe":"sha256:<approved-arm64-sha256>"}' \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f full_release_validation_run_id=<successful-full-release-validation-run-id> \
  -f npm_dist_tag=beta

gh workflow run openclaw-release-publish.yml \
  --ref release/YYYY.M.PATCH \
  -f tag=vYYYY.M.PATCH \
  -f windows_node_tag=vX.Y.Z \
  -f windows_node_installer_digests='{"OpenClawCompanion-Setup-x64.exe":"sha256:<approved-x64-sha256>","OpenClawCompanion-Setup-arm64.exe":"sha256:<approved-arm64-sha256>"}' \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f full_release_validation_run_id=<successful-full-release-validation-run-id> \
  -f npm_dist_tag=latest

​

NPM 工作流程輸入

• tag：必要發行標籤，例如 v2026.4.2、v2026.4.2-1、v2026.4.2-beta.1 或 v2026.4.2-alpha.1；當 preflight_only=true 時，也可以是目前工作流程分支完整 40 字元提交 SHA，用於僅驗證的 preflight
• preflight_only：true 表示僅驗證／建置／封裝，false 表示真正發佈路徑
• preflight_run_id：既有成功 preflight 執行 ID；真正發佈路徑需要此項，讓工作流程重用已準備的 tarball，而不是重新建置
• full_release_validation_run_id：此標籤／SHA 的成功 Full Release Validation 執行 ID；真正發佈需要此項。Beta 發佈可以僅依靠 preflight 繼續並提出警告，但穩定版／latest 提升仍需要它。
• release_publish_run_id：已核准的 OpenClaw Release Publish 執行 ID；當此工作流程由該父工作流程派送時需要（bot-actor 真正發佈呼叫）
• plugin_npm_run_id：成功的 exact-head Plugin NPM Release 執行 ID；真正的 extended-stable 核心發佈需要此項
• npm_dist_tag：發佈路徑的 npm 目標標籤；接受 alpha、beta、latest 或 extended-stable，預設為 beta。最終 patch 33 及之後必須使用 extended-stable；預設情況下，extended-stable 會拒絕更早的 patch，並且一律拒絕非最終標籤。
• bypass_extended_stable_guard：僅供測試的布林值，預設 false；搭配 npm_dist_tag=extended-stable 時，會略過每月 extended-stable 資格檢查，同時保留發行身分、成品、核准與回讀檢查。

• tag：必要發行標籤；必須已經存在
• preflight_run_id：成功的 OpenClaw NPM Release preflight 執行 ID；當 publish_openclaw_npm=true 時需要
• full_release_validation_run_id：成功的 Full Release Validation 執行 ID；當 publish_openclaw_npm=true 時需要
• windows_node_tag：精確的非預發行 openclaw/openclaw-windows-node 發行標籤；穩定版 OpenClaw 發佈需要此項
• windows_node_installer_digests：候選版本核准的精簡 JSON 映射，將目前 Windows 安裝程式名稱對應到其釘選的 sha256: 摘要；穩定版 OpenClaw 發佈需要此項
• npm_telegram_run_id：選用的成功 NPM Telegram Beta E2E 執行 ID，用於納入最終發行證據
• npm_dist_tag：OpenClaw 套件的 npm 目標標籤，為 alpha、beta 或 latest 之一
• plugin_publish_scope：預設為 all-publishable；只有在搭配 publish_openclaw_npm=false 進行聚焦的僅外掛修復工作時，才使用 selected
• plugins：當 plugin_publish_scope=selected 時，逗號分隔的 @openclaw/* 套件名稱
• publish_openclaw_npm：預設為 true；只有在將工作流程作為僅外掛修復協調器使用時，才設為 false
• release_profile：用於發行證據摘要的發行覆蓋範圍設定檔；預設為 from-validation，會從驗證 manifest 讀取，或以 beta、stable 或 full 覆寫
• wait_for_clawhub：預設為 false，因此 npm 可用性不會被 ClawHub sidecar 阻擋；只有當工作流程完成必須包含 ClawHub 完成時，才設為 true

• ref：要驗證的分支、標籤或完整提交 SHA。帶有密鑰的檢查要求已解析提交可從 OpenClaw 分支或發行標籤連到。
• run_release_soak：選擇加入 beta 發行檢查的完整即時／E2E、Docker 發行路徑，以及 all-since upgrade-survivor soak。它會由 release_profile=stable 和 release_profile=full 強制啟用。

• 下方低於修補版 33 的一般最終版本與修正版可發布到 beta 或 latest。修補版 33 或以上的最終版本必須發布到 extended-stable，且該邊界上的修正尾碼版本會被拒絕。
• Beta 預發行標籤只能發布到 beta；alpha 預發行標籤只能發布到 alpha
• 對於 OpenClaw NPM Release，只有在 preflight_only=true 時才允許輸入完整提交 SHA
• OpenClaw Release Checks 與 Full Release Validation 永遠只用於驗證
• 真正的發布路徑必須使用預檢期間所用的同一個 npm_dist_tag；工作流程會在發布繼續前驗證該中繼資料

​

一般 beta/latest 穩定版發布序列

1. 使用 preflight_only=true 執行 OpenClaw NPM Release。在標籤存在之前，你可以使用目前完整工作流程分支的提交 SHA，對預檢工作流程進行僅驗證的試執行。
2. 一般 beta 優先流程請選擇 npm_dist_tag=beta；只有在你刻意想要直接發布穩定版時，才使用 latest。
3. 當你想透過一個手動工作流程取得一般 CI 加上即時提示快取、Docker、QA Lab、Matrix 和 Telegram 覆蓋時，請在發布分支、發布標籤或完整提交 SHA 上執行 Full Release Validation。如果你刻意只需要確定性的常規測試圖，請改在發布參照上執行手動 CI 工作流程。
4. 選取精確的非預發行 openclaw/openclaw-windows-node 發布標籤，其已簽署的 x64 與 ARM64 安裝程式應隨版本發出。將它儲存為 windows_node_tag，並將它們經驗證的摘要對應儲存為 windows_node_installer_digests。發布候選輔助工具會記錄兩者，並將它們包含在產生的發布命令中。
5. 儲存成功的 preflight_run_id 與 full_release_validation_run_id。
6. 使用相同的 tag、相同的 npm_dist_tag、選定的 windows_node_tag、其已儲存的 windows_node_installer_digests、已儲存的 preflight_run_id，以及已儲存的 full_release_validation_run_id 執行 OpenClaw Release Publish。它會先將外部化外掛發布到 npm 與 ClawHub，再提升 OpenClaw npm 套件。
7. 如果版本落在 beta，請使用 openclaw/releases/.github/workflows/openclaw-npm-dist-tags.yml 工作流程，將該穩定版本從 beta 提升到 latest。
8. 如果版本刻意直接發布到 latest，且 beta 應立即跟隨同一個穩定建置，請使用同一個發布工作流程將兩個 dist-tag 都指向該穩定版本，或讓其排程的自我修復同步稍後移動 beta。

​

公開參考

• .github/workflows/full-release-validation.yml
• .github/workflows/package-acceptance.yml
• .github/workflows/openclaw-npm-release.yml
• .github/workflows/openclaw-release-checks.yml
• .github/workflows/openclaw-cross-os-release-checks-reusable.yml
• scripts/resolve-openclaw-package-candidate.mjs
• scripts/openclaw-npm-release-check.ts
• scripts/package-mac-dist.sh
• scripts/make_appcast.sh

​

相關

• 發布通道