發布政策

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• stable：帶標籤的發布版本，預設發布到 npm beta，或在明確要求時發布到 npm latest
• beta：發布到 npm beta 的預發布標籤
• dev：main 的移動最新提交

​

版本命名

• Stable 發布版本：YYYY.M.D
  • Git 標籤：vYYYY.M.D
• Stable 修正發布版本：YYYY.M.D-N
  • Git 標籤：vYYYY.M.D-N
• Beta 預發布版本：YYYY.M.D-beta.N
  • Git 標籤：vYYYY.M.D-beta.N
• 月份或日期不要補零
• latest 表示目前已推廣的 stable npm 發布版本
• beta 表示目前的 beta 安裝目標
• Stable 和 stable 修正發布版本預設發布到 npm beta；發布操作員可以明確指定 latest，或稍後推廣已審核的 beta 建置
• 每個 stable OpenClaw 發布版本都會一起發布 npm 套件和 macOS App； beta 發布版本通常會先驗證並發布 npm/套件路徑，而 mac App 建置/簽署/公證則保留給 stable，除非明確要求

​

發布節奏

• 發布採 beta 優先
• Stable 只會在最新 beta 完成驗證後跟進
• 維護者通常會從目前 main 建立的 release/YYYY.M.D 分支切出發布版本， 讓發布驗證和修正不會阻塞 main 上的新開發
• 如果 beta 標籤已推送或發布後需要修正，維護者會切出下一個 -beta.N 標籤，而不是刪除或重新建立舊的 beta 標籤
• 詳細發布流程、核准、憑證和復原備註僅限維護者使用

​

發布操作員檢查清單

1. 從目前 main 開始：拉取最新內容，確認目標提交已推送， 並確認目前 main CI 足夠綠燈，可以從它建立分支。
2. 使用 /changelog 從真實提交歷史重寫頂部的 CHANGELOG.md 區段， 保持條目面向使用者，提交它、推送它，並在建立分支前再次 rebase/pull。
3. 檢閱 src/plugins/compat/registry.ts 和 src/commands/doctor/shared/deprecation-compat.ts 中的發布相容性記錄。只有在升級路徑仍受涵蓋時才移除過期相容性，或記錄為何刻意保留。
4. 從目前 main 建立 release/YYYY.M.D；不要直接在 main 上進行一般發布工作。
5. 為預期標籤更新所有必要版本位置，然後執行 pnpm release:prep。它會依正確順序重新整理 Plugin 版本、Plugin 清單、設定 schema、內建通道設定中繼資料、設定文件基準、Plugin SDK 匯出，以及 Plugin SDK API 基準。在加標籤前提交任何產生的漂移。然後執行本機 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 進行僅驗證的預檢。保存成功的 preflight_run_id。
7. 使用 Full Release Validation 為發布分支、標籤或完整提交 SHA 啟動所有預發布測試。這是四個大型發布測試盒子的唯一手動入口點：Vitest、Docker、QA Lab 和 Package。
8. 如果驗證失敗，請在發布分支上修正，並重新執行能證明修正的最小失敗檔案、通道、workflow job、套件 profile、provider 或 model 允許清單。只有在變更的表面讓先前證據過期時，才重新執行完整 umbrella。
9. 對於 beta，標記 vYYYY.M.D-beta.N，然後從相符的 release/YYYY.M.D 分支執行 OpenClaw Release Publish。它會驗證 pnpm plugins:sync:check， 將所有可發布的 Plugin 套件平行派送到 npm 和相同集合到 ClawHub，然後在 Plugin npm 發布成功後，立即使用相符的 dist-tag 推廣已準備好的 OpenClaw npm 預檢 artifact。 在 OpenClaw npm 發布子項成功後，它會從完整相符的 CHANGELOG.md 區段建立或更新相符的 GitHub 發布/預發布頁面。發布到 npm latest 的 stable 發布版本會成為 GitHub 最新發布；保留在 npm beta 上的 stable 維護發布版本會以 GitHub latest=false 建立。 ClawHub 發布在 OpenClaw npm 發布時可能仍在執行，但發布 workflow 會立即列印子 run ID。預設情況下，它在派送 ClawHub 後不會等待 ClawHub，因此 OpenClaw npm 可用性不會被較慢的 ClawHub 核准或 registry 工作阻塞；當 ClawHub 必須阻塞 workflow 完成時，請設定 wait_for_clawhub=true。ClawHub 路徑會重試暫時性的 CLI 相依套件安裝失敗，即使某個預覽 cell 偶發失敗也會發布通過預覽的 Plugin，並以每個預期 Plugin 版本的 registry 驗證作結，讓部分發布保持可見且可重試。發布後，執行 pnpm release:verify-beta -- YYYY.M.D-beta.N --openclaw-npm-run <run-id> --plugin-npm-run <run-id> --plugin-clawhub-run <run-id> 以透過單一命令驗證 GitHub 預發布、npm beta dist-tag、npm integrity、 已發布安裝路徑、ClawHub 精確版本、ClawHub artifact 和子 workflow 結論。當 ClawHub sidecar 只在可重試 job 中失敗且應就地重新執行時，加入 --rerun-failed-clawhub。 然後針對已發布的 openclaw@YYYY.M.D-beta.N 或 openclaw@beta 套件執行發布後套件驗收。如果已推送或已發布的預發布需要修正， 請切出下一個相符的預發布編號；不要刪除或重寫舊的預發布。
10. 對於 stable，只有在已審核的 beta 或發布候選具備所需驗證證據後才繼續。 Stable npm 發布也會透過 OpenClaw Release Publish，使用 preflight_run_id 重用成功的預檢 artifact；stable macOS 發布就緒也需要 打包好的 .zip、.dmg、.dSYM.zip 和 main 上已更新的 appcast.xml。 私有 macOS 發布 workflow 會在發布資產通過驗證後，自動將簽署的 appcast 發布到公開 main；如果分支保護阻擋直接推送，它會開啟或更新 appcast PR。
11. 發布後，執行 npm 發布後驗證器、在需要發布後通道證據時執行選用的獨立 已發布 npm Telegram E2E、視需要進行 dist-tag 推廣、驗證產生的 GitHub 發布頁面， 並執行發布公告步驟。

​

發布預檢

• 在發行前預檢前執行 pnpm check:test-types，讓測試 TypeScript 在較快的本機 pnpm check 閘門之外仍維持涵蓋
• 在發行前預檢前執行 pnpm check:architecture，讓更廣泛的匯入循環與架構邊界檢查在較快的本機閘門之外保持綠燈
• 在 pnpm release:check 前執行 pnpm build && pnpm ui:build，讓預期的 dist/* 發行成品與 Control UI 套件包存在，以供套件驗證步驟使用
• 在根版本提升後、標記前執行 pnpm release:prep。它會執行每個在版本、設定或 API 變更後常見漂移的確定性發行產生器：Plugin 版本、Plugin 清單、基礎設定結構描述、內建通道設定中繼資料、設定文件基準、Plugin SDK 匯出，以及 Plugin SDK API 基準。pnpm release:check 會以檢查模式重新執行這些防護，並在執行套件發行檢查前，一次回報它找到的所有已產生漂移失敗。
• 在發行核准前執行手動 Full Release Validation 工作流程，從單一進入點啟動所有發行前測試箱。它接受分支、標籤或完整提交 SHA，派發手動 CI，並派發 OpenClaw Release Checks，用於安裝冒煙、套件驗收、跨 OS 套件檢查、QA Lab 同等性、Matrix，以及 Telegram 路線。穩定版／預設執行會將完整即時／E2E 與 Docker 發行路徑浸泡測試保留在 run_release_soak=true 之後；release_profile=full 會強制開啟浸泡測試。使用 release_profile=full 與 rerun_group=all 時，它也會針對來自發行檢查的 release-package-under-test 成品執行套件 Telegram E2E。在發布 beta 後提供 release_package_spec，即可在發行檢查、Package Acceptance 與套件 Telegram E2E 中重用已出貨的 npm 套件，而不需重新建置發行 tarball。只有在 Telegram 應使用與其餘發行驗證不同的已發布套件時，才提供 npm_telegram_package_spec。當 Package Acceptance 應使用與發行套件規格不同的已發布套件時，提供 package_acceptance_package_spec。當私有證據報告應證明驗證符合已發布 npm 套件，但不強制執行 Telegram E2E 時，提供 evidence_package_spec。 範例： gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D
• 當你想在發行工作繼續進行時，為套件候選版本取得旁路證明，請執行手動 Package Acceptance 工作流程。對 openclaw@beta、openclaw@latest 或精確發行版本使用 source=npm；使用 source=ref 以目前的 workflow_ref 測試框架封裝受信任的 package_ref 分支／標籤／SHA；對需要 SHA-256 的 HTTPS tarball 使用 source=url；或對另一個 GitHub Actions 執行上傳的 tarball 使用 source=artifact。該工作流程會將候選項解析為 package-under-test，針對該 tarball 重用 Docker E2E 發行排程器，並可使用 telegram_mode=mock-openai 或 telegram_mode=live-frontier 針對同一個 tarball 執行 Telegram QA。當選取的 Docker 路線包含 published-upgrade-survivor 時，套件成品就是候選項，而 published_upgrade_survivor_baseline 會選取已發布的基準。update-restart-auth 會將候選套件同時作為已安裝 CLI 與 package-under-test，因此會測試候選更新命令的受管理重新啟動路徑。 範例：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 常用設定檔：
  • smoke：安裝／通道／代理、Gateway 網路，以及設定重新載入路線
  • package：成品原生套件／更新／重新啟動／Plugin 路線，不含 OpenWebUI 或即時 ClawHub
  • product：套件設定檔加上 MCP 通道、cron／子代理清理、OpenAI 網頁搜尋，以及 OpenWebUI
  • full：含 OpenWebUI 的 Docker 發行路徑區塊
  • custom：針對聚焦重新執行的精確 docker_lanes 選取
• 當你只需要發行候選版本的完整一般 CI 涵蓋時，直接執行手動 CI 工作流程。手動 CI 派發會略過變更範圍判定，並強制執行 Linux Node 分片、內建 Plugin 分片、通道合約、Node 22 相容性、check、check-additional、建置冒煙、文件檢查、Python Skills、Windows、macOS、Android，以及 Control UI i18n 路線。 範例：gh workflow run ci.yml --ref release/YYYY.M.D
• 驗證發行遙測時執行 pnpm qa:otel:smoke。它會透過本機 OTLP/HTTP 接收器測試 QA-lab，並驗證匯出的追蹤 span 名稱、有界屬性，以及內容／識別碼遮蔽，不需要 Opik、Langfuse 或其他外部收集器。
• 每次標記發行前執行 pnpm release:check
• 在標籤存在後，執行 OpenClaw Release Publish 以進行會變更狀態的發布序列。從 release/YYYY.M.D 派發它（或在發布可從 main 觸及的標籤時從 main 派發），傳入發行標籤與成功的 OpenClaw npm preflight_run_id，並保留預設 Plugin 發布範圍 all-publishable，除非你刻意執行聚焦修復。該工作流程會序列化 Plugin npm 發布、Plugin ClawHub 發布與 OpenClaw npm 發布，讓核心套件不會在其外部化 Plugin 前發布。
• 發行檢查現在在獨立的手動工作流程中執行： OpenClaw Release Checks
• OpenClaw Release Checks 也會在發行核准前執行 QA Lab 模擬同等性路線，加上快速即時 Matrix 設定檔與 Telegram QA 路線。即時路線使用 qa-live-shared 環境；Telegram 也使用 Convex CI 憑證租約。當你想要並行取得完整 Matrix 傳輸、媒體與 E2EE 清單時，使用 matrix_profile=all 與 matrix_shards=true 執行手動 QA-Lab - All Lanes 工作流程。
• 跨 OS 安裝與升級執行階段驗證是公開 OpenClaw Release Checks 與 Full Release Validation 的一部分，兩者會直接呼叫可重用工作流程 .github/workflows/openclaw-cross-os-release-checks-reusable.yml
• 這個拆分是刻意的：讓真正的 npm 發行路徑保持短小、確定且聚焦於成品，同時讓較慢的即時檢查留在自己的路線中，避免拖慢或阻擋發布
• 帶有秘密的發行檢查應透過 Full Release Validation 派發，或從 main／發行工作流程 ref 派發，讓工作流程邏輯與秘密維持受控
• OpenClaw Release Checks 接受分支、標籤或完整提交 SHA，只要解析出的提交可從 OpenClaw 分支或發行標籤觸及即可
• OpenClaw NPM Release 僅驗證前置預檢也接受目前完整 40 字元的工作流程分支提交 SHA，不需要已推送的標籤
• 該 SHA 路徑僅供驗證，不能提升為真正發布
• 在 SHA 模式中，工作流程只會為套件中繼資料檢查合成 v<package.json version>；真正發布仍需要真正的發行標籤
• 兩個工作流程都將真正發布與提升路徑保留在 GitHub 託管 runner 上，而不變更狀態的驗證路徑可以使用較大的 Blacksmith Linux runner
• 該工作流程會使用 OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache，並同時使用 OPENAI_API_KEY 與 ANTHROPIC_API_KEY 工作流程秘密
• npm 發行前置預檢不再等待獨立的發行檢查路線
• 在本機標記發行候選版本前，執行 RELEASE_TAG=vYYYY.M.D-beta.N pnpm release:fast-pretag-check。該輔助程式會依照可在 GitHub 發布工作流程開始前捕捉常見核准阻擋錯誤的順序，執行快速發行防護、Plugin npm／ClawHub 發行檢查、建置、UI 建置，以及 release:openclaw:npm:check。
• 在核准前執行 RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts（或相符的 beta／修正版標籤）
• npm 發布後，執行 node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D（或相符的 beta／修正版版本），以在全新的暫存前綴中驗證已發布 registry 安裝路徑
• beta 發布後，執行 OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-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_* 環境憑證。
• 若要從維護者機器執行完整發布後 beta 冒煙測試，使用 pnpm release:beta-smoke -- --beta betaN。該輔助程式會執行 Parallels npm 更新／全新目標驗證、派發 NPM Telegram Beta E2E、輪詢精確工作流程執行、下載成品，並列印 Telegram 報告。
• 維護者也可以透過手動 NPM Telegram Beta E2E 工作流程，從 GitHub Actions 執行相同的發布後檢查。它刻意僅限手動，不會在每次合併時執行。
• 維護者發行自動化現在使用先預檢再提升：
  • 真正的 npm 發布必須通過成功的 npm preflight_run_id
  • 真正的 npm 發布必須從與成功預檢執行相同的 main 或 release/YYYY.M.D 分支派發
  • 穩定版 npm 發行預設為 beta
  • 穩定版 npm 發布可透過工作流程輸入明確目標為 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 僅供驗證；當標籤只存在於發行分支但工作流程從 main 派發時，設定 public_release_branch=release/YYYY.M.D
  • 真正的私有 mac 發布必須通過成功的私有 mac preflight_run_id 與 validate_run_id
  • 真正發布路徑會提升已準備好的成品，而不是再次重建它們
• 對於像 YYYY.M.D-N 這樣的穩定版修正發行，發布後驗證器也會檢查從 YYYY.M.D 到 YYYY.M.D-N 的相同暫存前綴升級路徑，讓發行修正不會默默地讓較舊的全域安裝停留在基礎穩定版 payload
• 除非 tarball 同時包含 dist/control-ui/index.html 與非空的 dist/control-ui/assets/ payload，否則 npm 發行前置預檢會封閉失敗，避免我們再次出貨空的瀏覽器儀表板
• 發布後驗證也會檢查已發布 Plugin 進入點與套件中繼資料是否存在於已安裝的 registry 配置中。若發行缺少 Plugin 執行階段 payload，會導致 postpublish 驗證器失敗，且不能提升為 latest。
• pnpm test:install:smoke 也會在候選更新 tarball 上強制執行 npm pack unpackedSize 預算，因此安裝器 e2e 會在發行發布路徑前捕捉意外的封裝膨脹
• 如果發行工作觸及 CI 規劃、extension 時序資訊清單或 extension 測試矩陣，請在核准前重新產生並審查 .github/workflows/plugin-prerelease.yml 中由規劃器擁有的 plugin-prerelease-extension-shard 矩陣輸出，讓發行說明不會描述過期的 CI 版面
• 穩定版 macOS 發行就緒性也包含更新器表面：
  • GitHub 發行最終必須包含封裝好的 .zip、.dmg 與 .dSYM.zip
  • 發布後，main 上的 appcast.xml 必須指向新的穩定版 zip；私有 macOS 發布工作流程會自動提交它，或在直接推送受阻時開啟 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.D \
  -f provider=openai \
  -f mode=both \
  -f release_profile=stable \
  -f evidence_package_spec=openclaw@YYYY.M.D-beta.N

• minimum：最快的發行關鍵 OpenAI/core live 與 Docker 路徑
• stable：minimum 加上用於發行核准的穩定 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.D \
  -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.D \
  -f provider=openai \
  -f mode=both \
  -f release_profile=full \
  -f release_package_spec=openclaw@YYYY.M.D-beta.N \
  -f evidence_package_spec=openclaw@YYYY.M.D-beta.N \
  -f npm_telegram_provider_mode=mock-openai

​

Vitest

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

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

​

Docker

• 啟用慢速 Bun global install smoke 的完整安裝 smoke
• 依目標 SHA 準備/重用 root Dockerfile smoke image，且 QR、root/gateway，以及 installer/Bun smoke jobs 作為獨立 install-smoke shards 執行
• repository E2E lanes
• 發行路徑 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-b、plugins-runtime-install-c、plugins-runtime-install-d、plugins-runtime-install-e、plugins-runtime-install-f、plugins-runtime-install-g 和 plugins-runtime-install-h
• 請求時在 plugins-runtime-services chunk 內執行 OpenWebUI 涵蓋
• 拆分的 bundled Plugin install/uninstall lanes，從 bundled-plugin-install-uninstall-0 到 bundled-plugin-install-uninstall-23
• 當發行檢查包含 live suites 時，live/E2E provider suites 和 Docker live model 涵蓋

​

QA Lab

• mock parity lane，使用 agentic parity pack，比較 OpenAI candidate lane 與 Opus 4.6 baseline
• 使用 qa-live-shared environment 的快速 live Matrix QA profile
• 使用 Convex CI credential leases 的 live Telegram QA lane
• 當發行 telemetry 需要明確本機證明時執行 pnpm qa:otel:smoke

​

套件

• source=npm：openclaw@beta、openclaw@latest，或精確的 OpenClaw 發行版本
• source=ref：使用選定的 workflow_ref harness 打包受信任的 package_ref 分支、標籤，或完整 commit SHA
• source=url：下載需要 package_sha256 的 HTTPS .tgz
• source=artifact：重用另一個 GitHub Actions run 上傳的 .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：快速套件安裝/channel/agent、Gateway 網路與設定重新載入 lanes
• package：安裝/更新/重啟/Plugin 套件合約，加上即時 ClawHub skill 安裝證明；這是發行檢查預設值
• product：package 加上 MCP channels、cron/subagent 清理、OpenAI 網頁搜尋與 OpenWebUI
• full：包含 OpenWebUI 的 Docker 發行路徑區塊
• custom：用於聚焦重新執行的精確 docker_lanes 清單

​

發行發布自動化

1. 簽出發行標籤並解析其 commit SHA。
2. 驗證該標籤可從 main 或 release/* 抵達。
3. 執行 pnpm plugins:sync:check。
4. 以 publish_scope=all-publishable 和 ref=<release-sha> 派送 Plugin NPM Release。
5. 使用相同 scope 與 SHA 派送 Plugin ClawHub Release。
6. 使用發行標籤、npm dist-tag 與已儲存的 preflight_run_id 派送 OpenClaw NPM Release。

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

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

gh workflow run openclaw-release-publish.yml \
  --ref release/YYYY.M.D \
  -f tag=vYYYY.M.D \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f npm_dist_tag=latest

​

NPM workflow 輸入

• tag：必要發行標籤，例如 v2026.4.2、v2026.4.2-1 或 v2026.4.2-beta.1；當 preflight_only=true 時，它也可以是目前完整 40 字元 workflow 分支 commit SHA， 用於僅驗證的 preflight
• preflight_only：true 表示僅驗證/建置/打包，false 表示真正的發布路徑
• preflight_run_id：真正發布路徑上必要，讓 workflow 重用成功 preflight 執行產生的已準備 tarball
• npm_dist_tag：發布路徑的 npm 目標 tag；預設為 beta

• tag：必要發行標籤；必須已存在
• preflight_run_id：成功的 OpenClaw NPM Release preflight run id； 當 publish_openclaw_npm=true 時為必要
• npm_dist_tag：OpenClaw 套件的 npm 目標 tag
• plugin_publish_scope：預設為 all-publishable；只有聚焦修復工作才使用 selected
• plugins：當 plugin_publish_scope=selected 時，為逗號分隔的 @openclaw/* 套件名稱
• publish_openclaw_npm：預設為 true；只有把 workflow 作為僅 Plugin 修復協調器使用時，才設為 false
• wait_for_clawhub：預設為 false，因此 npm 可用性不會被 ClawHub sidecar 阻擋； 只有當 workflow 完成必須包含 ClawHub 完成時，才設為 true

• ref：要驗證的分支、標籤或完整 commit SHA。帶有 secret 的檢查要求已解析 commit 可從 OpenClaw 分支或發行標籤抵達。
• run_release_soak：在穩定版/預設發行檢查中選擇啟用完整 live/E2E、Docker 發行路徑，以及 all-since upgrade-survivor soak。它會由 release_profile=full 強制啟用。

• 穩定版與修正版標籤可以發布到 beta 或 latest
• Beta prerelease 標籤只能發布到 beta
• 對於 OpenClaw NPM Release，只有當 preflight_only=true 時才允許完整 commit SHA 輸入
• OpenClaw Release Checks 和 Full Release Validation 一律僅用於驗證
• 真正的發布路徑必須使用 preflight 期間使用的同一個 npm_dist_tag； workflow 會在發布繼續前驗證該中繼資料

​

穩定 npm 發行順序

1. 以 preflight_only=true 執行 OpenClaw NPM Release
   • 在標籤存在前，你可以使用目前完整 workflow 分支 commit SHA，對 preflight workflow 執行僅驗證的 dry run
2. 一般 beta-first 流程選擇 npm_dist_tag=beta；只有在你刻意要直接發布穩定版時，才選擇 latest
3. 當你想從單一手動 workflow 取得一般 CI 加上 live prompt cache、Docker、QA Lab、Matrix 與 Telegram 涵蓋範圍時， 請在發行分支、發行標籤或完整 commit SHA 上執行 Full Release Validation
4. 如果你刻意只需要確定性的正常測試圖，請改在發行 ref 上執行手動 CI workflow
5. 儲存成功的 preflight_run_id
6. 使用相同 tag、相同 npm_dist_tag 與已儲存的 preflight_run_id 執行 OpenClaw Release Publish；它會先將外部化 Plugin 發布到 npm 和 ClawHub，再提升 OpenClaw npm 套件
7. 如果發行落在 beta，請使用私有 openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml workflow，將該穩定版本從 beta 提升到 latest
8. 如果發行是刻意直接發布到 latest，且 beta 應立即跟隨同一個穩定建置，請使用同一個私有 workflow，將兩個 dist-tags 都指向該穩定版本；或讓其排程自我修復同步稍後移動 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

​

相關

• 發行 channels