CI 流水線

OpenClaw CI 會在推送至 main 時執行（Markdown 和 docs/** 路徑在觸發條件中會被忽略）、在每個非草稿 PR 上執行，以及透過手動分派執行。 標準 main 推送採單一執行：CI 並行群組允許一個 完整的整合週期執行，同時 GitHub 僅保留最新的待處理推送。 新的合併會取代該待處理執行，而不會取消已經 註冊 Blacksmith 矩陣的工作。PR 仍會取消已被取代的分支最新提交， 而手動分派則使用隔離的群組。preflight 會分類差異，並在 只有不相關區域發生變更時關閉高成本工作路徑。手動 workflow_dispatch 執行會刻意略過智慧範圍限定，並展開 完整工作圖，以供候選版本與廣泛驗證使用。Android 工作路徑仍須透過 include_android（或 release_gate 輸入）選擇啟用。僅限發行版的 外掛涵蓋範圍位於獨立的 Plugin Prerelease 工作流程中，且只會從 Full Release Validation 或明確的手動 分派執行。

流水線概覽

獨立的 Periphery 工作流程會強制要求 iOS 與 macOS App 的無用程式碼發現數量為零。共用 OpenClawKit 工作流程會平行掃描兩個使用端，且只有當 Periphery 在兩次建置中輸出相同的 Swift USR 時，才會回報該宣告。其產生的 OpenClawProtocol/GatewayModels.swift 結構描述契約會保留為產生器擁有的程式碼，而不會被視為 App 本機的無用程式碼。

快速失敗順序

1. preflight 會決定哪些工作路徑存在。docs-scope 與 changed-scope 邏輯是此工作內的步驟，而非獨立工作。標準 main 會立即啟動，但其並行群組只允許一個完整執行，並將之後的推送合併為一個最新的待處理執行。與 Node 相關的 main 推送也會在此處依序執行唯一的相依套件磁碟寫入器及其大小維護，之後下游工作才能掛載該金鑰；Blacksmith 可能要到後續的工作流程執行才會公開新的提交，因此同一次執行的使用端仍會保留經標記檢查的本機後備機制。
2. security-fast、check-*、check-additional-*、check-docs 和 skills-python 會快速失敗，不必等待較繁重的成品與平台矩陣工作。
3. build-artifacts 與語系檢查會和快速 Linux 工作路徑重疊執行。Control UI 與原生 App 原始碼 PR 會排除產生的語系快照／資源；其序列化的重新整理工作流程會在背景修復並自動合併隔離的產生型 PR。原始碼 CI 仍會阻擋過時的來源清冊與不安全的在地化呼叫。產生型 PR、手動 CI 與發行準備會強制要求完整翻譯內容與平台產生內容一致。標準 release/YYYY.M.PATCH 分支可能會將發行準備語系修復與其他產生的發行輸出一併納入。
4. 之後會展開較繁重的平台與執行階段工作路徑：checks-fast-core、checks-fast-contracts-plugins-*、checks-fast-contracts-channels-*、checks-node-*、checks-windows、macos-node、macos-swift、ios-build 和 android。
5. openclaw/ci-gate 會等待所有已選取的工作路徑。預檢與安全性檢查必須成功；只有資訊清單未選取下游工作時，該工作才可略過。任何失敗或取消的已選取工作路徑都會使彙總失敗。

合併協調器可以重複使用同一 PR 分支最新提交中已通過驗證且成功的 openclaw/ci-gate， 最長可達 24 小時。這可避免在發生不相關的 main 變更後， 重寫貢獻者分支。可重複使用的結果不會取代另一項由 App 擁有、針對目前 main 執行的嚴格測試合併檢查。 在有效期限內，只要該分支最新提交未變更，之後待處理或失敗的重新執行 不會抹除較早的成功結果。

預設分支規則集要求由 GitHub Actions 擁有的 openclaw/ci-gate 檢查。儲存庫維護者與管理員擁有經稽核的緊急繞過機制，僅供已簽署的直接快轉合併使用；組織規則集仍會封鎖刪除與非快轉更新。一般 PR 合併應繼續使用此閘門，而不是繞過失敗的 CI。另一個由嚴格 App 擁有的測試合併檢查，仍會將最新提交綁定至目前的 main。

當較新的最新提交合併後，GitHub 可能會將已被取代的 PR 工作標記為 cancelled。除非同一 PR 的最新執行也失敗，否則應將其視為 CI 雜訊。標準 main 執行在獲准進入後不會取消；合併流量抵達時，GitHub 只會以最新頂端提交取代較舊且待處理的執行。矩陣工作使用 fail-fast: false，而 build-artifacts 會直接回報內嵌頻道、核心支援邊界與閘道監看失敗，而不是將微型驗證工作排入佇列。自動 CI 並行處理鍵具有版本編號（CI-v7-*），因此 GitHub 端舊佇列群組中的殭屍工作無法無限期封鎖較新的主分支執行。手動完整套件執行使用 CI-manual-v1-*，且不會取消進行中的執行。外掛清單啟動記憶體防護在自架 Blacksmith Linux 上維持 350 MiB 上限，並在 GitHub 託管的 Linux 上允許 425 MiB；後者針對同一個已建置命令列介面的 RSS 基準值較高。

使用 pnpm ci:timings、pnpm ci:timings:recent 或 node scripts/ci-run-timings.mjs <run-id>，彙整 GitHub Actions 的實際經過時間、佇列時間、最慢工作、失敗，以及 pnpm-store-warmup 扇出屏障。工作流程內的 ci-timings-summary 工作存在於 ci.yml 中，但目前已停用（if: false）；請改為在本機執行計時輔助工具。若要查看建置計時，請檢查 build-artifacts 工作的 Build dist 步驟：pnpm build:ci-artifacts 會輸出 [build-all] phase timings:，並包含 ui:build；該工作也會上傳 startup-memory 成品。

PR 背景與證據

外部貢獻者的 PR 會從 .github/workflows/real-behavior-proof.yml 執行 PR 背景與證據閘門。此工作流程會簽出 受信任的工作流程修訂版本（github.workflow_sha），且僅評估 PR 本文； 不會執行貢獻者分支中的程式碼。

此閘門適用於不屬於儲存庫擁有者、成員、協作者或機器人的 PR 作者。當 PR 本文包含由作者撰寫的 What Problem This Solves 與 Evidence 區段時，檢查即會通過。證據可以是聚焦測試、 CI 結果、螢幕截圖、錄影、終端輸出、即時觀察、 經遮蔽處理的記錄，或成品連結。本文提供意圖與實用的驗證資訊； 審查者會檢查程式碼、測試與 CI，以評估正確性。

檢查失敗時，請更新 PR 本文，而不是再推送另一個程式碼提交。

範圍與路由

範圍邏輯位於 scripts/ci-changed-scope.mjs，並由 src/scripts/ci-changed-scope.test.ts 中的單元測試涵蓋。手動分派會略過變更範圍偵測，讓預檢資訊清單表現得如同每個受範圍控管的區域都已變更。

獨立的 iOS 與 macOS Periphery 工作流程會強制執行零發現項目的無用程式碼政策。各工作流程僅在非草稿 PR 觸及其原生掃描範圍，或手動分派時執行。

• CI 工作流程編輯會驗證 Node CI 圖、工作流程 lint，以及 Windows 執行通道（由 ci.yml 執行），但本身不會強制執行 iOS、Android 或 macOS 原生建置；這些平台執行通道仍僅限於平台原始碼變更。
• 工作流程健全性檢查會對所有工作流程 YAML 檔案執行 actionlint、zizmor，以及複合動作插值防護與衝突標記防護。PR 範圍內的 security-fast 工作也會對已變更的工作流程檔案執行 zizmor，讓工作流程安全性發現在主要 CI 圖中提早失敗。
• 推送至 main 時的文件會由獨立的 Docs 工作流程進行檢查，使用與 CI 相同的 ClawHub 文件鏡像，因此混合程式碼與文件的推送不會同時將 CI check-docs 分片排入佇列。當文件已變更時，PR 與手動 CI 仍會從 CI 執行 check-docs。
• 終端介面 PTY會在終端介面變更時，於 checks-node-core-runtime-tui-pty Linux Node 分片中執行。該分片會使用 OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 執行 test/vitest/vitest.tui-pty.config.ts，因此同時涵蓋確定性的 TuiBackend 固定資料執行通道，以及僅模擬外部模型端點、速度較慢的 tui --local 煙霧測試。
• 僅限 CI 路由的編輯、快速任務直接執行的一小組核心測試固定資料，以及範圍狹窄的外掛契約輔助工具編輯會使用僅限 Node 的快速資訊清單路徑：preflight、security-fast，以及變更所觸及的快速執行通道——單一 checks-fast-core CI 路由任務、兩個外掛契約分片，或兩者。此路徑會略過建置成品、Node 22 相容性、頻道契約、完整核心分片、隨附外掛分片，以及額外的防護矩陣。
• Windows Node 檢查的範圍僅限於 Windows 特定的程序／路徑包裝函式、npm／pnpm／UI 執行器輔助工具、套件管理員設定，以及執行該通道的 CI 工作流程介面；不相關的原始碼、外掛、安裝煙霧測試與僅測試變更，仍使用 Linux Node 執行通道。

最慢的 Node 測試系列會經過拆分或平衡，讓每個工作維持精簡，而不會過度預留執行器：

• 外掛合約與通道合約各自以兩個由 Blacksmith 支援的加權分片執行，並使用標準 GitHub 執行器作為後援。
• 核心單元快速／支援執行路徑分開執行；核心執行階段基礎設施拆分為程序、共用、掛鉤、密鑰，以及三個排程領域分片。
• 自動回覆以平衡的工作程序執行，回覆子樹則拆分為代理執行器、命令、分派、工作階段及狀態路由分片。
• 代理式閘道／伺服器（控制平面）設定拆分至聊天、驗證、模型、HTTP／外掛、執行階段及啟動執行路徑，而非等待建置成品。
• 一般 CI 僅將隔離的基礎設施 include-pattern 分片封裝成確定性套組，每組最多 64 個測試檔案，在不合併非隔離的命令／排程、具狀態的 agents-core 或閘道／伺服器測試套件的情況下縮減節點矩陣。繁重的固定測試套件維持使用 8 vCPU，而套組化及較低權重的執行路徑則使用 4 vCPU。
• 標準儲存庫上的 PR 會針對合成的合併樹差異重複使用變更測試解析器。精確變更會執行一個具針對性的節點工作；每個選取的測試檔案都有自己的程序，因此具狀態測試套件的隔離仍保持完整。規劃器會將同層測試與匯入圖相依項目合併，並在工作區套件、套件／鎖定檔、共用測試框架、拆分設定、重新命名或刪除的變更、公開擴充功能合約變更、具有特殊分片設定的測試、僅部分解析或空白的目標、過大的路徑或目標計畫，以及規劃器錯誤等情況下，回退至既有的 14 工作精簡完整測試套件計畫。具針對性的計畫一律保留完整的建置成品邊界閘門，因為其儲存庫掃描器無法從匯入關係推導。main 推送會執行相同的完整精簡測試套件：待處理的中間推送事件可能會合併，因此最新留存的執行必須驗證完整的整合樹，而非僅驗證最後一次單一推送的差異。手動分派與發布閘門會保留完整的具名逐分片矩陣。
• 完整節點矩陣會優先納入持續緩慢的序列工具、自動回覆命令分片及涵蓋範圍廣泛的 core-fast 快取寫入器。這可維持 28 個工作的上限，同時避免關鍵路徑工作及下一次執行的轉換種子延後至後續批次。
• 涵蓋範圍廣泛的瀏覽器、QA、媒體及其他外掛測試會使用各自專用的 Vitest 設定，而非共用的外掛全捕捉設定。include-pattern 分片會使用 CI 分片名稱記錄計時項目，使 .artifacts/vitest-shard-timings.json 能區分完整設定與經篩選的分片。
• Linux 節點分片工作會透過上游 Actions 快取 API 保存 Vitest 的實驗性檔案系統模組快取，Blacksmith 會在其執行器上透明地加速此快取。每個 CI 分片都僅進行還原，並將受保護的種子解壓縮至各自的執行器本機根目錄；接著，分片包裝函式會為並行的 Vitest 程序提供各自獨立的即時子目錄。只有不會取消的每日暖機程序或明確分派的暖機程序會儲存新的不可變封存檔，因此 PR 無法發布轉換結果或建立各 PR 專屬的快取系列。轉換輸入指紋會清除不相容的鎖定檔、套件、tsconfig 及 Vitest 設定世代。受保護的寫入器會掃描已還原的快取，並在快取超過 2 GiB 後將其修剪至 75%。Vitest 會雜湊模組 ID、原始碼內容、環境及解析後的轉換設定，因此一般的部分原始碼變更可讓未變更的項目保持暖機狀態，而變更的模組則會安全地發生快取未命中。粗粒度還原前綴可銜接不同工作流程執行；一般 Actions 快取的 LRU 與閒置淘汰機制會限制舊的不可變封存檔。
• 受信任的 Linux 節點工作也會將 pnpm 儲存區與 node_modules 繫結至每條受支援節點版本線的一個受保護相依套件磁碟。套件資訊清單、安裝設定、執行器平台及確切的節點修補版本不納入磁碟金鑰；確切的執行階段與安裝輸入指紋會決定工作要重複使用該樹，或重新安裝並重新整理同一磁碟。資訊清單會在雜湊前標準化。經稽核的直接根掛鉤僅保留 pnpm 的安裝生命週期指令碼，因此格式化及一般測試／建置指令碼的編輯可繼續使用暖機的相依套件樹；未經稽核的生命週期掛鉤偏移會採取失敗關閉，直到其來源輸入納入指紋合約。相依套件、套件管理器、掛鉤來源及鎖定檔變更一律使快照失效。指紋相符是必要條件，但並不足夠：設定程序還會檢查匯入器封存檔及資訊清單總和檢查碼，然後依據節點從其匯入器解析出的套件資訊清單，驗證由 postinstall 保留且以登錄檔為來源的鎖定檔相依套件。匯入器內容遺失或過時時，會回退至全新安裝，而非提供根層級提升內容。若 PR 的唯讀快照無法使用，系統會解除工作區繫結，並安裝至執行器本機儲存空間，避免對其無法發布的複本進行緩慢寫入。黏著式冷安裝會停用 pnpm 內部的擷取重試，並從逐步暖機的儲存區執行最多三次有界的完整安裝嘗試；逾時仍視為失敗。完成內容驗證的還原或 frozen-lockfile 安裝後，設定程序會停用 pnpm 重複的執行前相依套件檢查：儲存庫會刻意修剪外掛本機的 node_modules，否則 pnpm 會將其視為過時，並在分片扇出期間透過不安全的並行隱式安裝進行修復。標準 main 預檢是唯一的寫入器，且會在每次重新整理時測量儲存區，僅在已淘汰套件版本使其超過 8 GiB 後才執行 pnpm store prune。即使寫入器工作已完成，Blacksmith 快照發布仍採非同步進行，因此使用全新金鑰或指紋後的第一次執行可能仍是冷啟動；後續經內容驗證且具確切標記的還原才是推出證明。必要的 CI 工作與 PR 會取得可拋棄的複本，因此相依套件變更不會建立新磁碟、競爭快照，或產生可能取消建置的快取鎖。
• 節點分片與建置成品工作也會透過不可變 Actions 快取還原節點的可攜式磁碟編譯快取。獨立的 test 與 build 命名空間可防止其寫入器互相取代封存檔：排程測試暖機程序擁有受保護的測試種子，而 build-artifacts 每個 UTC 日最多可從受信任的 main 推送發布一個受保護的建置封存檔。PR 與一般測試工作僅讀取受保護的快照，因此功能分支的位元組碼永遠不會進入共用種子，而 PR 流量也不會建立任何快取封存檔。這會在不同簽出路徑間重複使用由節點載入的協調程式、建置工具及外部相依套件的 V8 位元組碼，包括僅部分原始碼圖發生變更時。Vitest 子程序會停用繼承的編譯快取，因為動態設定中可能啟用涵蓋率，而從位元組碼還原序列化指令碼時，V8 涵蓋率可能會失去原始碼位置精確度。
• 建置成品工作也會保存以內容指紋識別的 build-all 步驟輸出。CI 自行建置的外掛 SDK 宣告會雜湊完整的儲存庫自有 TypeScript／JSON 原始碼圖，排除已安裝及產生的目錄，並在 tsdown 清除 dist 後還原扁平宣告與套件橋接。該圖之外的文件、工作流程、外掛及其他變更可重複使用宣告快照；原始碼變更則會在執行匯出閘門前重新建置宣告。
• 完整宣告建置會將 tsdown 拆分為 AI、工作區套件及統一群組。每個群組僅快取宣告，接著仍會在還原這些宣告前重新建置執行階段 JavaScript。因此，核心或外掛變更只會使大型統一圖失效，而工作區套件變更則會保守地使所有相依宣告群組失效。公開完整建置通常使用不可變的 Actions 快取；粗粒度還原金鑰會為部分變更提供種子，各群組的內容指紋會拒絕過時資料，而 GitHub 的快取配額則會淘汰舊世代。每週的節點 22 執行路徑改為在成功執行 main 後發布保留 14 天的成品，並且僅還原不可變產生者身分在 main 上解析為該工作流程的成品，以避免配額頻繁變動，同時不允許 PR 程式碼寫入共用快取。私人 QA 宣告永遠不會保存於 Actions 快取，因為快取命名空間並非機密性邊界。
• check-additional-* 會將補充邊界防護清單（scripts/run-additional-boundary-checks.mjs）分條配置為一個提示詞密集型分片（check-additional-boundaries-a，其中包含 Codex 提示詞快照偏移檢查）以及一個合併其餘分條的分片（check-additional-boundaries-bcd），兩者各自並行執行獨立防護並輸出每項檢查的計時。套件邊界編譯／金絲雀工作維持在一起，而執行階段拓撲架構則與內嵌於 build-artifacts 的閘道監看涵蓋率分開執行。
• 在 32-vCPU 自行託管的建置執行器上，閘道監看、通道測試及核心支援邊界分片會在 dist/ 與 dist-runtime/ 已建置完成後，一同於 build-artifacts 內啟動。由 GitHub 託管的後援執行會讓閘道監看保持序列執行，以免低核心數競爭耗盡其就緒期限。

獲准執行後，標準 Linux CI 最多允許 28 個節點測試工作並行執行， 較小型的快速／檢查執行路徑則最多 12 個；Windows 與 Android 維持為兩個，因為 這些執行器集區較為有限。精簡的完整設定批次使用 120 分鐘的批次逾時，而 include-pattern 群組則共用相同的有界 工作預算。

Android CI 會同時執行 testPlayDebugUnitTest 與 testThirdPartyDebugUnitTest，然後建置 Play 偵錯 APK。第三方變體沒有獨立的原始碼集或資訊清單；其單元測試執行路徑仍會使用 SMS／通話記錄 BuildConfig 旗標編譯該變體，同時避免在每次 Android 相關推送時重複執行偵錯 APK 封裝工作。每個目前的 Gradle 工作都有一個受保護的黏著式磁碟；PR 工作使用可拋棄的複本，而受保護的執行則會就地重新整理以內容定址的 Gradle 項目。

Blacksmith 黏著式磁碟金鑰會刻意限制於受支援的執行階段或工作維度，絕不包含 PR 編號、提交、執行、分支或相依套件雜湊。執行階段轉換與編譯快取使用 Actions 快取而非黏著式磁碟，因為不可變封存檔可提供可驗證的還原／儲存結果，並避免可變快照升級失敗。完成黏著式金鑰版本遷移後，只將確切的過時金鑰、架構及區域身分加入 .github/retired-sticky-disks.json，以相同維度與確認資訊，從 main 分派 Sticky Disk Cleanup，驗證刪除結果，然後移除這些項目。該工作流程會將 ARM 身分路由至 ARM 執行器、拒絕執行器區域不相符的情況、使用 Blacksmith 的確切金鑰刪除動作，且絕不刪除 Docker 建置器快取或萬用字元前綴。Actions 快取封存檔使用一般的 LRU 與閒置淘汰機制。

check-dependencies 分片會執行正式環境的 Knip 相依套件、未使用檔案及未使用匯出檢查。當 PR 新增未經審查的未使用檔案，或留下過時的允許清單項目時，未使用檔案防護會失敗，同時保留 Knip 無法靜態解析的刻意動態外掛、產生項目、建置、即時測試及套件橋接介面。未使用匯出防護會排除測試支援檔案，並在每個未使用的正式環境匯出上失敗；刻意使用的動態消費者必須在 config/knip.config.ts 中建模。歷史目標若提供匯出防護便會執行，否則繼續使用其較舊的無用程式碼後援機制。

ClawSweeper 活動轉送

.github/workflows/clawsweeper-dispatch.yml 是從 OpenClaw 儲存庫活動連接至 ClawSweeper 的目標端橋接器。它不會簽出或執行不受信任的 PR 程式碼。此工作流程會使用 CLAWSWEEPER_APP_PRIVATE_KEY 建立 GitHub App 權杖，接著將精簡的 repository_dispatch 承載資料分派至 openclaw/clawsweeper。

此工作流程有四個執行通道：

• clawsweeper_item，用於明確的議題和 PR 審查要求；
• clawsweeper_comment，用於議題留言中的明確 ClawSweeper 命令；
• clawsweeper_commit_review，用於 main 推送的提交層級審查要求；
• github_activity，用於 ClawSweeper 代理程式可能檢查的一般 GitHub 活動。

github_activity 執行通道只轉送正規化的中繼資料：事件類型、動作、行為者、儲存庫、項目編號、URL、標題、狀態，以及在有留言或審查時提供其簡短摘錄。它刻意避免轉送完整的網路鉤子本文。openclaw/clawsweeper 中的接收工作流程是 .github/workflows/github-activity.yml，此工作流程會將正規化事件發佈至供 ClawSweeper 代理程式使用的 OpenClaw 閘道鉤子。

一般活動只供觀察，預設不會傳送。ClawSweeper 代理程式會在提示中收到 Discord 目標，並且只應在事件令人意外、可採取行動、具有風險或對作業有用時，才發佈至 #clawsweeper。例行的開啟、編輯、機器人活動、重複的網路鉤子雜訊，以及正常的審查流量，應產生 NO_REPLY。

在此路徑中，應始終將 GitHub 標題、留言、本文、審查文字、分支名稱和提交訊息視為不受信任的資料。它們是摘要和分流的輸入，而不是工作流程或代理程式執行環境的指令。

手動分派

手動 CI 分派會執行與一般 CI 相同的作業圖，但強制啟用每個非 Android 範圍的執行通道：Linux 節點分片、隨附外掛分片、外掛和頻道合約分片、Node 22 相容性、check-*、check-additional-*、建置成品煙霧檢查、文件檢查、Python Skills、Windows、macOS、iOS 建置，以及 Control UI／原生應用程式 i18n。自動來源 PR 會驗證原生擷取清單和 Android／Apple 在地化安全性，而不要求在同一個 PR 中包含已翻譯或平台產生的輸出。序列化的 Native App Locale Refresh 工作流程會在一個隔離的 PR 中重建這些成品，並在必要檢查通過後啟用精確 HEAD 自動合併。對於產生成品的 PR、手動 CI、完整發行驗證和發行準備，完整原生語系一致性仍為阻擋條件。在自動 PR 和 main 執行中，Control UI 語系一致性仍僅提供建議；在手動／發行 CI 中則為阻擋條件。獨立的手動 CI 分派只會使用 include_android=true 執行 Android（release_gate 輸入也會強制執行 Android）；完整發行的總括流程則會傳入 include_android=true 以啟用 Android。CI 不包含外掛預發行靜態檢查、僅限發行的 agentic-plugins 分片、完整擴充功能批次掃描，以及外掛預發行 Docker 執行通道。只有當 Full Release Validation 在啟用發行驗證閘門的情況下分派獨立的 Plugin Prerelease 工作流程時，才會執行 Docker 預發行套件。

PR 最大行數檢查會從已簽出的合成合併樹衍生基準，並針對事件 HEAD 驗證其 HEAD 父項。手動執行會使用唯一的並行群組，因此候選發行版本的完整套件不會被相同參照上的其他推送或 PR 執行取消。選用的 target_ref 輸入可讓受信任的呼叫者針對分支、標籤或完整提交 SHA 執行該作業圖，同時使用所選分派參照中的工作流程檔案；最大行數基準會與目標相對於該次執行所解析之預設分支 HEAD 的合併基底進行比較。release_gate 輸入是供維護者在 PR CI 因容量受阻時使用的精確 SHA 備援方案：它要求 target_ref 必須是與所分派分支 HEAD 相符的完整提交 SHA，且 pull_request_number 必須識別其合併樹接受驗證的開放 PR。

gh workflow run ci.yml --ref release/YYYY.M.PATCHgh workflow run ci.yml --ref main -f target_ref=<branch-or-sha> -f include_android=truegh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>

閘道延伸穩定版會從 extended-stable/YYYY.M.33 執行 npm 預檢、完整發行驗證和外掛 npm 發行；核心發佈會使用這三個 執行 ID 以及驗證嘗試次數。release-ci/* 證據無效，因為 發佈會將每次執行繫結至標準分支和發行 SHA。該標籤 會發佈閘道映像檔，且只發佈 extended-stable* 別名；此路徑會略過 一般協調器及其 ClawHub、原生應用程式、GitHub Release、網站 和私有 dist-tag 介面。命令和復原方式請參閱每月閘道延伸穩定版 發佈。

執行器

執行器註冊預算

OpenClaw 目前的 GitHub 執行器註冊配額顯示，在 ghx api rate_limit 中每 5 分鐘可進行 10,000 次自架 執行器註冊。每次調校前請重新檢查 actions_runner_registration，因為 GitHub 可能會變更 此配額。此限制由 openclaw 組織中的所有 Blacksmith 執行器註冊共用，因此新增另一個 Blacksmith 安裝不會增加 新的配額。

請將 Blacksmith 標籤視為控制突發量的稀缺資源。只負責 路由、通知、摘要、選取分片或執行短時間 CodeQL 掃描的作業，應 留在 GitHub 託管的執行器上，除非已實測確認其有 Blacksmith 特定 需求。任何新的 Blacksmith 矩陣、更大的 max-parallel 或高頻率 工作流程，都必須呈現其最壞情況的註冊數量，並將組織層級 目標維持在即時配額約 60% 以下。以目前 10,000 次註冊的 配額而言，這表示操作目標為 6,000 次註冊，並為 並行儲存庫、重試和突發重疊保留餘裕。

變更目標的 PR 計畫將常見的 Node 測試突發量從 14 次 Blacksmith 註冊減少為一次。廣泛風險 PR 會保留 14 次註冊的精簡備援，因此最壞情況不會增加。

標準儲存庫 CI 會繼續將 Blacksmith 作為一般推送和 PR 執行的預設執行器路徑。workflow_dispatch 和非標準儲存庫執行會使用 GitHub 託管的執行器，但一般標準執行目前不會探測 Blacksmith 佇列健康狀態，也不會在 Blacksmith 無法使用時自動改用 GitHub 託管的標籤。

介面棘輪

兩項只能縮減的預算會保護設定介面。若數量增加，兩者都會使 CI 失敗， 直到同一個 PR 中有意識地更新預算檔案；當清理作業降低實際數量時，兩者也都要求 向下調整棘輪。

• config/env-var-count-budget.txt 限制 src/、packages/ 和 extensions/ 下正式環境原始碼中不同 OPENCLAW_* 名稱的數量 （不包含測試和 QA Lab）。由 node scripts/check-env-var-count.mjs 檢查。 移除環境變數時：請在同一個 PR 中降低數字。新增環境變數屬於 設定介面決策——請在 PR 本文中說明理由。
• docs/.generated/config-baseline.counts.json 限制各種類型 （核心／頻道／外掛）的 openclaw.json 結構描述項目數量。由 pnpm config:docs:check 檢查；任何 結構描述變更後，請使用 pnpm config:docs:gen 重新產生。

本機對應方式

pnpm changed:lanes                            # 檢查本機針對 origin/main...HEAD 的變更分流分類器pnpm check:changed                            # 智慧型本機檢查閘門：依邊界分流檢查變更的格式、型別、lint 與防護pnpm check                                    # 快速本機閘門：正式環境 tsgo + 分片 lint + 平行快速防護pnpm check:test-typespnpm check:timed                              # 相同閘門，包含各階段計時pnpm build:strict-smokepnpm check:architecturepnpm test:gateway:watch-regressionOPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.tspnpm test                                     # vitest 測試pnpm test:changed                             # 低成本的智慧型變更 Vitest 目標pnpm test:ui                                  # Control UI 單元／瀏覽器測試套件pnpm ui:i18n:check                            # 產生的 Control UI 語系一致性（發行閘門）pnpm native:i18n:baseline                     # 更新由原始碼擁有的原生擷取清單pnpm native:i18n:verify                       # 原始碼清單 + Android／Apple 在地化安全性pnpm native:i18n:check                        # 嚴格的翻譯／平台產生內容一致性（發行閘門）pnpm test:channelspnpm test:contracts:channelspnpm check:docs                               # 文件格式 + lint + 失效連結pnpm build                                    # 當 CI 成品／冒煙檢查很重要時建置 distpnpm ios:build                                # 產生並建置 iOS 應用程式專案pnpm ci:timings                               # 摘要最新的 origin/main 推送 CI 執行pnpm ci:timings:recent                        # 比較近期成功的 main CI 執行node scripts/ci-run-timings.mjs <run-id>      # 摘要實際經過時間、佇列時間及最慢工作node scripts/ci-run-timings.mjs --latest-main # 忽略議題／留言雜訊並選擇 origin/main 推送 CInode scripts/ci-run-timings.mjs --recent 10   # 比較近期成功的 main CI 執行pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.jsonpnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.jsonpnpm test:startup:memorypnpm test:extensions:memory -- --json .artifacts/openclaw-performance/source/mock-provider/extension-memory.jsonpnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.json --output .artifacts/kova/summary.md

OpenClaw 效能

OpenClaw Performance 是產品／執行階段效能工作流程。它每天在 main 執行，也可手動分派：

gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1 -f deep_profile=true -f live_openai_candidate=truegh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3

手動分派通常會對工作流程 ref 進行基準測試。設定 target_ref，即可使用目前的工作流程實作，對發行標籤或其他分支進行基準測試。發布的報告路徑與最新指標會依受測 ref 區分，而每個 index.md 都會記錄受測 ref／SHA、工作流程 ref／SHA、Kova ref、設定檔、分流驗證模式、模型、重複次數及情境篩選條件。

此工作流程會從固定版本安裝 OCM，並從 openclaw/Kova 以固定的 kova_ref 輸入安裝 Kova，接著執行三個分流：

• mock-provider：使用確定性的假 OpenAI 相容驗證，針對本機建置執行階段執行 Kova 診斷情境。
• mock-deep-profile：針對啟動、閘道及代理程式回合熱點進行 CPU／heap／trace 分析。依排程執行，或在分派時搭配 deep_profile=true 執行。
• live-openai-candidate：一次真實的 OpenAI openai/gpt-5.6-luna 代理程式回合；當 OPENAI_API_KEY 無法使用時略過。依排程執行，或在分派時搭配 live_openai_candidate=true 執行。

模擬提供者分流也會在 Kova 通過後執行 OpenClaw 原生來源探測：涵蓋預設、略過頻道、內部掛鉤及五十個外掛啟動案例的閘道啟動時間與記憶體；內建外掛匯入 RSS、重複的模擬 OpenAI channel-chat-baseline hello 迴圈、針對已啟動閘道執行的命令列介面啟動命令，以及 SQLite 狀態冒煙效能探測。當受測 ref 有先前發布的模擬提供者來源報告可用時，來源摘要會將目前的 RSS 與 heap 值和該基準比較，並將大幅增加的 RSS 標記為 watch。來源探測的 Markdown 摘要位於報告套件中的 source/index.md，原始 JSON 則位於其旁。

每個分流都會上傳完整的 GitHub 成品，包括 CPU、heap、trace 及壓縮診斷套件。獨立的發布工作會下載並驗證這些成品，接著建立一個短效期的 ClawSweeper GitHub App 權杖，其範圍僅限 openclaw/clawgrit-reports 內容，且只會將它傳遞給 Git push 步驟。它會在 openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/ 下提交 report.json、report.md、index.md、來源探測成品，以及套件中繼資料／總和檢查碼；完整診斷封存檔則保留在連結的 Actions 成品中。發布器在嘗試推送前，會拒絕任何超過 50 MB 的報告檔案。目前的受測 ref 指標為 openclaw-performance/<tested-ref>/latest-<lane>.json。如果應用程式權杖建立或報告發布失敗，排程執行與 profile=release 分派就會失敗。手動的非發行分派會將發布維持為建議性質，並在驗證或發布失敗時保留 GitHub 成品。先前的來源基準是以匿名方式從公開報告儲存庫擷取，因此成功擷取基準並不代表發布器驗證成功。

完整發行驗證

Full Release Validation 是用於「發行前執行所有項目」的手動統括工作流程。它接受分支、標籤或完整 commit SHA，並以該目標分派手動 CI 工作流程（包括 Android）、分派 Plugin Prerelease 以執行僅限發行的外掛／套件／靜態／Docker 證明、針對目標 SHA 分派 OpenClaw Performance，以及分派 OpenClaw Release Checks 以執行安裝冒煙測試、套件驗收、跨作業系統套件檢查、QA Lab 一致性、Matrix、Telegram，以及設有閘門的 Discord、WhatsApp 和 Slack 分流（建議性的成熟度計分卡呈現可透過 run_maturity_scorecard 選擇啟用）。穩定版和完整設定檔一律包含完整的即時／E2E 與 Docker 發行路徑持續覆蓋；beta 設定檔可透過 run_release_soak=true 選擇啟用。標準套件 Telegram E2E 會在套件驗收內執行，因此完整候選版本不會啟動重複的即時輪詢器。發布後，傳入 release_package_spec，即可在發行檢查、套件驗收、Docker、跨作業系統及 Telegram 中重複使用已發布的 npm 套件，而不需重新建置。僅在針對已發布套件進行聚焦的 Telegram 重新執行時使用 npm_telegram_package_spec。Codex 外掛即時套件分流預設使用相同的選取狀態：已發布的 release_package_spec=openclaw@<tag> 會衍生 codex_plugin_spec=npm:@openclaw/codex@<tag>，而 SHA／成品執行則會從所選 ref 封裝 extensions/codex。對於 npm:、npm-pack: 或 git: 規格等自訂外掛來源，請明確設定 codex_plugin_spec。其即時代理程式證明會傳送可見的進度、繼續執行隨機化工作區讀取及精確的成品寫入，然後傳送完成訊息。

如需階段矩陣、確切的工作流程工作名稱、設定檔差異、成品及聚焦重新執行控制代碼，請參閱完整發行驗證。

OpenClaw Release Publish 是會進行變更的手動發行工作流程。在發行標籤存在且 OpenClaw npm 預檢成功後，從受信任的 main 分派一般 beta 和穩定版發布（預檢會執行 pnpm plugins:sync:check 等檢查）。標籤仍會選取確切的發行 commit，包括 release/YYYY.M.PATCH 上的 commit；Tideclaw alpha 發布則繼續使用相符的 alpha 分支。它需要已儲存的 preflight_run_id、成功的 full_release_validation_run_id 及其確切的 full_release_validation_run_attempt，並為所有可發布的外掛套件分派 Plugin NPM Release、為相同的發行 SHA 分派 Plugin ClawHub Release，之後才會分派 OpenClaw NPM Release。穩定版發布也需要確切的 windows_node_tag；此工作流程會先驗證 Windows 來源發行版本，並將其 x64／ARM64 安裝程式與候選版本核准的 windows_node_installer_digests 輸入比較，之後才執行任何發布子流程；接著會提升並驗證這些相同的固定安裝程式摘要，以及確切的配套成品與總和檢查碼合約，最後才發布 GitHub 發行草稿。聚焦的僅限外掛修復使用 plugin_publish_scope=selected，並提供非空白套件清單。僅限外掛的 all-publishable 執行需要與核心發布相同的不可變 npm 預檢及完整發行驗證證據。

gh workflow run openclaw-release-publish.yml \  --ref main \  -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 full_release_validation_run_attempt=<successful-full-release-validation-run-attempt> \  -f npm_dist_tag=beta

若要在快速變動的分支上進行固定 commit 證明，請使用輔助工具，而非 gh workflow run ... --ref main -f ref=<sha>：

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

GitHub 工作流程分派 ref 必須是分支或標籤，不能是原始 commit SHA。輔助工具會在受信任的 main 工作流程 SHA 建立暫時的 release-ci/<sha>-... 分支，透過工作流程的 ref 輸入傳遞要求的目標 SHA、在可用時重複使用嚴格的精確目標證據、驗證每個子工作流程的 headSha 都符合受信任的工作流程 SHA，並在執行完成時刪除暫時分支。傳入 -f reuse_evidence=false 可強制執行全新驗證。如果任何子工作流程使用不同的工作流程 SHA 執行，統括驗證器也會失敗。

release_profile 控制傳入發行檢查的即時／提供者廣度。手動發行工作流程預設為 stable；只有在刻意需要廣泛的建議性提供者／媒體矩陣時，才使用 full。穩定版和完整發行檢查一律執行完整的即時／E2E 與 Docker 發行路徑持續測試；beta 設定檔可透過 run_release_soak=true 選擇啟用。

• beta 保留最快的 OpenAI／核心發行關鍵分流。
• stable 加入穩定的提供者／後端集合。
• full 執行廣泛的建議性提供者／媒體矩陣。

統括工作流程會記錄已分派的子執行 ID，而最終的 Verify full validation 工作會重新檢查目前的子執行結論，並附加每個子執行的最慢工作表格。如果子工作流程重新執行後轉為通過，只需重新執行父驗證器工作，即可重新整理統括結果與計時摘要。

為了復原，Full Release Validation 與 OpenClaw Release Checks 都接受 rerun_group。在總控流程中，使用 all 處理候選版本，使用 ci 僅執行一般完整 CI 子流程，使用 plugin-prerelease 僅執行外掛預發佈子流程，使用 performance 僅執行 OpenClaw Performance 子流程，使用 release-checks 執行所有發佈子流程，或使用範圍較窄的群組：install-smoke、cross-os、live-e2e、package、qa、qa-parity、qa-live 或 npm-telegram。這能讓失敗的發佈機器在完成針對性修正後，只重新執行有限範圍。若只有一個跨作業系統執行路徑失敗，請將 rerun_group=cross-os 與 cross_os_suite_filter 結合，例如 windows/packaged-upgrade；長時間執行的跨作業系統命令會輸出心跳偵測行，而封裝升級摘要會包含各階段耗時。選定的 Matrix 與 Telegram QA 執行路徑會阻擋一般發佈驗證，核心執行階段配對工具涵蓋率閘門也是如此。QA 一致性、執行階段一致性，以及受閘門控管的 Discord、WhatsApp 與 Slack 即時執行路徑則僅供參考。

OpenClaw Release Checks 使用受信任的工作流程參照，將選定參照一次解析成 release-package-under-test tarball，接著把該成品傳給跨作業系統檢查與套件驗收；執行浸泡涵蓋率時，也會傳給即時／E2E 發佈路徑 Docker 工作流程。這可讓各發佈機器使用一致的套件位元組，並避免在多個子工作中重複封裝同一個候選版本。對於 Codex npm 外掛即時執行路徑，發佈檢查會傳入從 release_package_spec 衍生且相符的已發佈外掛規格、傳入操作員提供的 codex_plugin_spec，或將輸入留空，讓 Docker 指令碼封裝所選簽出內容中的 Codex 外掛。

針對 ref=main 與 rerun_group=all 的重複 Full Release Validation 執行 會取代較舊的總控流程。父監控器在父流程取消時，會取消所有已分派的 子工作流程，因此較新的 main 驗證不會排在過時且長達兩小時的發佈檢查 執行之後。發佈分支／標籤驗證與針對性重新執行群組會保留 cancel-in-progress: false。

即時與 E2E 分片

發佈即時／E2E 子流程會保留廣泛的原生 pnpm test:live 涵蓋範圍，但會透過 scripts/test-live-shard.mjs 以具名分片執行，而不是使用單一循序工作：

• native-live-src-agents 與 native-live-src-agents-zai-coding
• native-live-src-gateway-core
• 依提供者篩選的 native-live-src-gateway-profiles 工作
• native-live-src-gateway-backends
• native-live-src-infra
• native-live-test
• native-live-extensions-a-k
• native-live-extensions-l-n
• native-live-extensions-moonshot
• native-live-extensions-openai
• native-live-extensions-o-z-other
• native-live-extensions-xai
• 拆分媒體音訊／視訊分片，以及依提供者篩選的音樂分片

這會保留相同的檔案涵蓋範圍，同時讓速度緩慢的即時提供者故障更容易重新執行與診斷。彙總的 native-live-src-gateway、native-live-extensions-o-z、native-live-extensions-media 與 native-live-extensions-media-music 分片名稱，仍可用於手動的一次性重新執行。

原生即時媒體分片會在 ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04 中執行，該映像檔由 Live Media Runner Image 工作流程建置。此映像檔已預先安裝 ffmpeg 與 ffprobe；媒體工作只會在設定前驗證二進位檔。請讓由 Docker 支援的即時測試套件在一般 Blacksmith 執行器上執行——容器工作不適合啟動巢狀 Docker 測試。

由 Docker 支援的即時模型／後端分片，會針對每個選定的提交使用獨立的共用 ghcr.io/openclaw/openclaw-live-test:<sha>-<extensions> 映像檔。即時發佈工作流程只會建置並推送該映像檔一次，接著 Docker 即時模型、依提供者分片的閘道、命令列介面後端、ACP 繫結及 Codex 測試框架分片會使用 OPENCLAW_SKIP_DOCKER_BUILD=1 執行。閘道 Docker 分片會設定明確的指令碼層級 timeout 上限，且低於工作流程的工作逾時值，使卡住的容器或清理路徑能快速失敗，而不會耗盡整個發佈檢查時限。若這些分片各自重新建置完整的原始碼 Docker 目標，表示發佈執行設定錯誤，且會將實際經過時間浪費在重複的映像檔建置上。

套件驗收

當問題是「這個可安裝的 OpenClaw 套件能否作為產品正常運作？」時，請使用 Package Acceptance。它不同於一般 CI：一般 CI 驗證原始碼樹狀結構，而套件驗收則透過使用者安裝或更新後所使用的相同 Docker E2E 測試框架，驗證單一 tarball。

工作

1. resolve_package 簽出 workflow_ref、解析一個套件候選項目、寫入 .artifacts/docker-e2e-package/openclaw-current.tgz、寫入 .artifacts/docker-e2e-package/package-candidate.json、將兩者上傳為 package-under-test 成品，並在 GitHub 步驟摘要中輸出來源、工作流程參照、套件參照、版本、SHA-256 與設定檔。
2. package_integrity 下載 package-under-test 成品，並使用 scripts/check-openclaw-package-tarball.mjs 強制執行公開套件 tarball 合約。
3. docker_acceptance 使用已解析的套件來源 SHA（若無則退回 workflow_ref）與 package_artifact_name=package-under-test 呼叫 openclaw-live-and-e2e-checks-reusable.yml。可重複使用的工作流程會下載該成品、驗證 tarball 清單、在需要時準備套件摘要 Docker 映像檔，並針對該套件執行選定的 Docker 執行路徑，而非封裝工作流程簽出內容。當設定檔選取多個目標 docker_lanes 時，可重複使用的工作流程會準備套件與共用映像檔一次，接著將這些執行路徑展開為平行的目標 Docker 工作，且各自使用唯一成品。
4. package_telegram 可選擇性呼叫 NPM Telegram Beta E2E。當 telegram_mode 不為 none 時便會執行；若套件驗收已解析套件，則安裝相同的 package-under-test 成品；獨立的 Telegram 分派仍可安裝已發佈的 npm 規格。
5. summary 會在套件解析、完整性、Docker 驗收或選用的 Telegram 執行路徑失敗時，使工作流程失敗。advisory 輸入會將驗收失敗降級為警告，供參考性呼叫端使用。

候選來源

• source=npm 僅接受 openclaw@extended-stable、openclaw@beta、openclaw@latest，或確切的 OpenClaw 發佈版本，例如 openclaw@2026.4.27-beta.2。此選項適用於已發佈的延伸穩定版、預發佈版或穩定版驗收。
• source=ref 封裝受信任的 package_ref 分支、標籤或完整提交 SHA。解析器會擷取 OpenClaw 分支／標籤、驗證所選提交可從儲存庫分支歷程或發佈標籤抵達、在分離的工作樹中安裝相依套件，並使用 scripts/package-openclaw-for-docker.mjs 封裝。
• source=url 下載公開 HTTPS .tgz；必須提供 package_sha256。此路徑會拒絕 URL 認證資訊、非預設 HTTPS 連接埠、私有／內部／特殊用途的主機名稱或解析後的 IP，以及不符合相同公開安全政策的重新導向。
• source=trusted-url 從 .github/package-trusted-sources.json 中具名的受信任來源政策下載 HTTPS .tgz；必須提供 package_sha256 與 trusted_source_id。只有需要設定主機、連接埠、路徑前置字串、重新導向主機或私有網路解析的維護者自有企業鏡像或私有套件儲存庫，才應使用此選項。若政策宣告持有人驗證，工作流程會使用固定的 OPENCLAW_TRUSTED_PACKAGE_TOKEN 密鑰；仍會拒絕嵌入 URL 的認證資訊。
• source=artifact 從 artifact_run_id 與 artifact_name 下載一個 .tgz；package_sha256 為選用項目，但外部共用的成品應提供此值。

請將 workflow_ref 與 package_ref 分開。workflow_ref 是執行測試的受信任工作流程／測試框架程式碼。package_ref 是在 source=ref 時封裝的來源提交。這讓目前的測試框架無須執行舊工作流程邏輯，即可驗證較舊的受信任來源提交。

測試套件設定檔

• smoke — npm-onboard-channel-agent、gateway-network、config-reload
• package — npm-onboard-channel-agent、doctor-switch、update-channel-switch、skill-install、update-corrupt-plugin、upgrade-survivor、published-upgrade-survivor、root-managed-vps-upgrade、update-restart-auth、plugins-offline、plugin-update
• product — package 集合，但以即時 plugins 涵蓋範圍取代 plugins-offline，再加上 mcp-channels、cron-mcp-cleanup、openai-web-search-minimal、openwebui
• full — 包含 OpenWebUI 的完整 Docker 發佈路徑區塊
• custom — 確切的 docker_lanes；在 suite_profile=custom 時為必要項目

package 設定檔使用離線外掛涵蓋範圍，因此已發佈套件的驗證不會受限於即時 ClawHub 可用性。選用的 Telegram 執行路徑會在 NPM Telegram Beta E2E 中重複使用 package-under-test 成品，並保留已發佈 npm 規格路徑供獨立分派使用。

如需專用的更新與外掛測試政策，包括本機命令、 Docker 執行路徑、套件驗收輸入、發佈預設值與失敗分流， 請參閱測試更新與外掛。

發佈檢查會使用 source=artifact、已準備的發佈套件成品、suite_profile=custom、docker_lanes='doctor-switch update-channel-switch skill-install update-corrupt-plugin upgrade-survivor published-upgrade-survivor root-managed-vps-upgrade update-restart-auth plugins-offline plugin-update plugin-binding-command-escape' 與 telegram_mode=mock-openai 呼叫套件驗收。這會讓套件遷移、更新、即時 ClawHub skill 安裝、過時外掛相依套件清理、已設定外掛安裝修復、離線外掛、外掛更新與 Telegram 證明，都使用相同的已解析套件 tarball。在發佈 beta 版後，於完整發佈驗證或 OpenClaw 發佈檢查中設定 release_package_spec，即可針對已發佈的 npm 套件執行相同矩陣而不重新建置；只有當套件驗收需要使用不同於其餘發佈驗證的套件時，才設定 package_acceptance_package_spec。跨作業系統發佈檢查仍涵蓋各作業系統專屬的導入、安裝程式與平台行為；套件／更新產品驗證應從套件驗收開始。

published-upgrade-survivor Docker 執行路徑會在每次執行時，於阻擋式發佈路徑中驗證一個已發佈套件基準線。在套件驗收中，解析後的 package-under-test tarball 一律是候選項目，而 published_upgrade_survivor_baseline 會選取備用的已發佈基準線，預設為 openclaw@latest；失敗執行路徑的重新執行命令會保留該基準線。使用 run_release_soak=true 或 release_profile=full 的完整發佈驗證會設定 published_upgrade_survivor_baselines='last-stable-4 2026.4.23 2026.5.2 2026.4.15' 與 published_upgrade_survivor_scenarios=reported-issues，將範圍擴展至最新四個穩定 npm 發佈版本，加上固定的外掛相容性邊界版本，以及針對 Feishu 設定、保留的啟動／角色設定檔、已設定的 OpenClaw 外掛安裝、波浪號記錄路徑與過時的舊版外掛相依套件根目錄所設計的問題情境測試資料。多基準線的已發佈升級存續選項會依基準線分片為個別的目標 Docker 執行器工作。當問題是完整的已發佈更新清理，而非一般完整發佈 CI 廣度時，獨立的 Update Migration 工作流程會使用具有 all-since-2026.4.23 基準線與 plugin-deps-cleanup 情境的 update-migration Docker 執行路徑。本機彙總執行可以透過 OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS 傳入確切套件規格、透過 OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC（例如 openclaw@2026.4.15）只保留單一執行路徑，或設定 OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS 以使用情境矩陣。已發佈執行路徑會使用內建的 openclaw config set 命令配方設定基準線、將配方步驟記錄於 summary.json，並在閘道啟動後探查 /healthz、/readyz 及 RPC 狀態。Windows 封裝版與安裝程式全新安裝執行路徑，也會驗證已安裝的套件能否從原始的 Windows 絕對路徑匯入瀏覽器控制覆寫。OpenAI 跨作業系統代理程式回合冒煙測試會在已設定時預設使用 OPENCLAW_CROSS_OS_OPENAI_MODEL，否則使用 openai/gpt-5.6-luna，讓安裝與閘道證明採用成本較低的 GPT-5.6 測試層級。

舊版相容性期間

套件驗收對已發布的套件設有範圍明確的舊版相容性期間。至 2026.4.25（含 2026.4.25-beta.*）為止的套件可使用相容性路徑：

• dist/postinstall-inventory.json 中已知的私有 QA 項目可指向 tarball 中省略的檔案；
• 當套件未公開該旗標時，doctor-switch 可略過 gateway install --wrapper 持久化子案例；
• update-channel-switch 可從衍生自 tarball 的模擬 git 測試環境中移除缺少的 pnpm patchedDependencies，並可記錄缺少的持久化 update.channel；
• 外掛冒煙測試可讀取舊版安裝記錄位置，或接受市集安裝記錄未持久化；
• plugin-update 可允許設定中繼資料遷移，但仍要求安裝記錄與不重新安裝的行為保持不變。

已發布的 2026.4.26 套件也可針對已隨套件發布的本機建置中繼資料戳記檔案發出警告；至 2026.5.20 為止的套件在缺少 npm-shrinkwrap.json 時，也可發出警告而非失敗。後續套件必須符合現行合約；相同條件將導致失敗，而非警告或略過。

範例

# 使用產品層級涵蓋範圍驗證目前的 beta 套件。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 telegram_mode=mock-openai # 使用套件涵蓋範圍驗證已發布的 extended-stable 套件。gh workflow run package-acceptance.yml \  --ref main \  -f workflow_ref=main \  -f source=npm \  -f package_spec=openclaw@extended-stable \  -f suite_profile=package \  -f telegram_mode=mock-openai # 使用目前的測試框架封裝並驗證發布分支。gh workflow run package-acceptance.yml \  --ref main \  -f workflow_ref=main \  -f source=ref \  -f package_ref=release/YYYY.M.PATCH \  -f suite_profile=package \  -f telegram_mode=mock-openai # 驗證 tarball URL。source=url 必須提供 SHA-256。gh workflow run package-acceptance.yml \  --ref main \  -f workflow_ref=main \  -f source=url \  -f package_url=https://example.com/openclaw-current.tgz \  -f package_sha256=<64-char-sha256> \  -f suite_profile=smoke # 從具名且受信任的私有映像站原則驗證 tarball。gh workflow run package-acceptance.yml \  --ref main \  -f workflow_ref=main \  -f source=trusted-url \  -f trusted_source_id=enterprise-artifactory \  -f package_url=https://packages.example.internal:8443/artifactory/openclaw/openclaw-current.tgz \  -f package_sha256=<64-char-sha256> \  -f suite_profile=smoke # 重複使用另一個 Actions 執行所上傳的 tarball。gh workflow run package-acceptance.yml \  --ref main \  -f workflow_ref=main \  -f source=artifact \  -f artifact_run_id=<run-id> \  -f artifact_name=package-under-test \  -f suite_profile=custom \  -f docker_lanes='install-e2e plugin-update'

偵錯失敗的套件驗收執行時，先從 resolve_package 摘要確認套件來源、版本與 SHA-256。接著檢查 docker_acceptance 子執行及其 Docker 成品：.artifacts/docker-tests/**/summary.json、failures.json、測試通道記錄、階段計時，以及重新執行命令。應優先重新執行失敗的套件設定檔或確切的 Docker 測試通道，而非重新執行完整發布驗證。

安裝冒煙測試

Install Smoke 工作流程不再於 PR 或 main 推送時執行。其每夜／手動包裝流程與發布驗證都會呼叫唯讀的 install-smoke-reusable.yml 核心，而且每次執行都會在 GitHub 託管的執行器上走完完整的安裝冒煙測試路徑：

• 每個目標 SHA 僅建置一次根 Dockerfile 冒煙測試映像，並將其與工作流程修訂版本和產生者嘗試次數繫結於不可變成品中；接著由命令列介面冒煙測試、代理程式刪除共用工作區命令列介面冒煙測試、容器閘道網路 E2E，以及隨附的 matrix 外掛建置引數冒煙測試載入。外掛冒煙測試會驗證執行階段相依套件安裝鏡像，並確認外掛載入時不會產生進入點逸出診斷。
• QR 套件安裝與安裝程式／更新 Docker 冒煙測試（包括 Rocky Linux 安裝程式測試通道，以及針對可設定 update_baseline_version npm 基準線的更新測試通道）會以獨立工作執行，因此安裝程式工作不必排在根映像冒煙測試之後等待。

速度較慢的 Bun 全域安裝映像供應商冒煙測試由 run_bun_global_install_smoke 個別控管。它會按每夜排程執行，對發布檢查所呼叫的工作流程預設啟用，而手動 Install Smoke 分派則可選擇啟用。一般 PR CI 仍會針對與 Node 相關的變更執行快速 Bun 啟動器迴歸測試通道。QR 與安裝程式 Docker 測試會繼續使用各自聚焦於安裝的 Dockerfile。

本機 Docker E2E

pnpm test:docker:all 會預先建置一個共用的即時測試映像、將 OpenClaw 封裝一次為 npm tarball，並建置兩個共用 scripts/e2e/Dockerfile 映像：

• 供安裝程式／更新／外掛相依套件測試通道使用的純 Node/Git 執行器；
• 將相同 tarball 安裝至 /app、供一般功能測試通道使用的功能映像。

Docker 測試通道定義位於 scripts/lib/docker-e2e-scenarios.mjs，規劃器邏輯位於 scripts/lib/docker-e2e-plan.mjs，而執行器只會執行所選計畫。排程器透過 OPENCLAW_DOCKER_E2E_BARE_IMAGE 與 OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE 為各測試通道選取映像，然後使用 OPENCLAW_SKIP_DOCKER_BUILD=1 執行測試通道。

可調整項目

即使某個測試通道的權重高於其有效上限，仍可從空集區啟動，之後獨自執行，直到釋放容量為止。本機彙總流程會預先檢查 Docker、移除過期的 OpenClaw E2E 容器、輸出作用中測試通道狀態、保存測試通道計時以進行最長優先排序，並且預設在第一次失敗後停止排程新的集區測試通道。

可重複使用的即時／E2E 工作流程

可重複使用的即時／E2E 工作流程會詢問 scripts/test-docker-all.mjs --plan-json 所需的套件、映像種類、即時映像、測試通道，以及認證資訊涵蓋範圍。接著，scripts/docker-e2e.mjs 會將該計畫轉換為 GitHub 輸出與摘要。它會透過 scripts/package-openclaw-for-docker.mjs 封裝 OpenClaw、下載目前執行的套件成品，或從 package_artifact_run_id 下載套件成品，然後驗證 tarball 清單。預設 no-push-artifact 路徑會透過 Blacksmith 的 Docker 層快取建置以套件摘要標記的純／功能映像、將確切的映像位元組封裝為不可變工作流程成品，並讓每個取用者驗證及載入該成品。existing-only 則要求明確提供 docker_e2e_bare_image/docker_e2e_functional_image GHCR 參照，且絕不建置或推送。這些登錄檔提取作業每次嘗試均採用有限的 180 秒逾時，讓卡住的串流能快速重試，而不是耗盡大部分 CI 關鍵路徑。排程驗證成功後，openclaw-scheduled-live-checks.yml 會將不可變的已測試映像資訊清單傳給獨立的套件寫入發布器；唯讀的發布與預發布呼叫端絕不會經過該寫入器。

發布路徑分塊

發布 Docker 涵蓋範圍會使用 OPENCLAW_SKIP_DOCKER_BUILD=1 執行較小的分塊工作，因此每個分塊只會驗證並載入其所需、以成品為基礎的映像種類（或在明確使用 existing-only 重複使用時提取映像），並透過相同的加權排程器執行多個測試通道：

• OPENCLAW_DOCKER_ALL_PROFILE=release-path
• OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h | openwebui

目前的發布 Docker 分塊為 core、package-update-openai、package-update-anthropic、package-update-core、plugins-runtime-plugins、plugins-runtime-services、plugins-runtime-install-a 至 plugins-runtime-install-h，以及 openwebui。package-update-openai 包含即時 Codex 外掛套件測試通道；此通道會安裝候選 OpenClaw 套件、從 codex_plugin_spec 或同一參照的 tarball 安裝 Codex 外掛並明確核准安裝 Codex 命令列介面、執行 Codex 命令列介面預先檢查與同一工作階段的代理程式回合，然後執行一次零重試、中等思考強度的回合，在該回合中傳送進度、讀取隨機化的工作區輸入、寫入內容完全一致的成品，並傳送完成通知。plugins-runtime-core、plugins-runtime 與 plugins-integrations 仍是彙總外掛／執行階段別名。install-e2e 測試通道別名仍是兩個供應商安裝程式測試通道的彙總手動重新執行別名。

每當穩定版或完整發布路徑涵蓋範圍要求 OpenWebUI 時，它都會在專用的大磁碟 Blacksmith 執行器上，以獨立的 openwebui 分塊執行，即使可重複使用的工作流程將支援的工作導向 GitHub 託管執行器亦然。將外部映像提取作業分開，可避免大型映像與 plugins-runtime-services 中的共用套件和外掛映像爭用資源；舊版彙總外掛／執行階段分塊仍會包含 OpenWebUI，以供相容的手動重新執行。隨附頻道更新測試通道會針對暫時性 npm 網路失敗重試一次。

每個分塊都會上傳 .artifacts/docker-tests/，其中包含測試通道記錄、計時、summary.json、failures.json、階段計時、排程器計畫 JSON、慢速測試通道表格，以及各測試通道的重新執行命令。工作流程的 docker_lanes 輸入會針對為該次執行準備的映像執行所選測試通道，而非執行分塊工作，讓失敗測試通道的偵錯範圍限於單一目標 Docker 工作；若所選測試通道是即時 Docker 測試通道，目標工作會在本機建置該次重新執行所需的即時測試映像。重新執行輔助程式會驗證失敗成品中確切選定的目標 SHA，而手動分派會重新封裝該參照，因為內部可重複使用工作流程的套件元組不屬於 workflow_dispatch 結構描述。產生的命令只有在已準備的映像輸入由 GHCR 支援時，才會包含這些輸入與 shared_image_policy=existing-only；執行器本機成品標籤會被省略，讓全新的執行器重新建置。除非成品能證明已復原的 GHCR 映像參照與明確目標覆寫相符，否則該覆寫會移除這些參照。成品產生的工作流程定義參照也會被省略，因為完整發布的暫存分支會遭刪除；除非操作人員明確覆寫，否則分派會使用儲存庫預設分支。

pnpm test:docker:rerun <run-id>      # 下載 Docker 成品，並列印合併／各測試通道的目標重新執行命令pnpm test:docker:timings <summary>   # 慢速測試通道與階段關鍵路徑摘要

排程的即時／E2E 工作流程每天會執行完整的發布路徑 Docker 套件組，並在成功後針對確切的已測試映像成品叫用明確的發布器。

外掛預發布

Plugin Prerelease 涵蓋成本較高的產品／套件，因此是由 Full Release Validation 或明確操作人員分派的獨立工作流程。一般 PR、main 推送及獨立的手動 CI 分派均不會啟用該套件。它會將隨附外掛測試平均分配至八個擴充功能工作節點；這些擴充功能分片工作一次最多執行兩個外掛設定群組，每個群組使用一個 Vitest 工作節點並配置較大的 Node 堆積空間，避免匯入量大的外掛批次產生額外 CI 工作。僅限發行的 Docker 預發行路徑（由 full_release_validation 輸入啟用）會將目標 Docker 執行路徑以四個為一組進行批次處理，避免為只需一至三分鐘的工作保留數十個執行器。此工作流程也會從 @openclaw/plugin-inspector 上傳資訊用途的 plugin-inspector-advisory 成品；檢查器發現是分類處理的輸入，不會改變具阻斷作用的外掛預發行閘門。

QA Lab

QA Lab 在主要智慧範圍工作流程之外設有專用的 CI 執行路徑。代理式同等性檢查內嵌於廣泛的 QA 與發行測試框架中，而不是獨立的 PR 工作流程。當同等性檢查應隨廣泛驗證執行時，請搭配 rerun_group=qa-parity 使用 Full Release Validation。

• QA-Lab - All Lanes 工作流程每晚在 main 上執行，也可手動分派；它會展開模擬同等性檢查，以及即時 Matrix、Telegram、Discord、WhatsApp 和 Slack 工作。即時工作使用 qa-live-shared 環境；Telegram、Discord、WhatsApp 和 Slack 使用 Convex 租約，而 Matrix 會佈建可拋棄的本機認證資訊。

發行檢查會使用確定性模擬提供者及符合模擬條件的模型（mock-openai/gpt-5.6-luna 和 mock-openai/gpt-5.6-luna-alt），執行 Matrix 與 Telegram 即時傳輸執行路徑，讓頻道合約不受即時模型延遲及一般提供者外掛啟動影響。即時傳輸閘道會停用記憶搜尋，因為 QA 同等性檢查會另行涵蓋記憶行為；提供者連線能力則由獨立的即時模型、原生提供者及 Docker 提供者套件涵蓋。

排程與發行 Matrix 閘門使用共用 QA Lab 套件主機及搭配發行情境的即時轉接器。命令列介面預設值及手動工作流程輸入仍為 all；手動 all 分派會展開 transport、media、e2ee-smoke、e2ee-deep 和 e2ee-cli 設定檔，讓 93 個情境的證明維持在各工作的逾時限制內。聚焦的手動分派會在單一工作中選取 fast、release 或 transport。

OpenClaw Release Checks 也會在核准發行前執行發行關鍵的 QA Lab 執行路徑；其 QA 同等性閘門會將候選與基準套件當作平行執行路徑工作執行，接著將兩者的成品下載至小型報告工作，以進行最終同等性比較。

一般 PR 應依循範圍限定的 CI／檢查證據，而不要將同等性檢查視為必要狀態。

CodeQL

CodeQL 工作流程刻意設計為範圍有限的第一階段安全掃描器，而不是完整的儲存庫掃描。每日、手動、main 推送及非草稿 PR 防護執行，會掃描 Actions 工作流程程式碼及風險最高的 JavaScript／TypeScript 表面，並使用高可信度安全查詢，篩選為高／重大 security-severity。

PR 防護維持輕量：只有在 .github/actions、.github/codeql、.github/workflows、packages、scripts、src 或擁有處理程序的隨附外掛執行階段路徑下發生變更時才會啟動，並執行與排程工作流程相同的高可信度安全矩陣。Android 與 macOS CodeQL 不包含在 PR 預設值中。

安全性類別

平台特定安全性分片

• CodeQL Android Critical Security — 排程的 Android 安全性分片。在工作流程健全性檢查所接受的最小 Blacksmith Linux 執行器上，手動建置 Android 應用程式以供 CodeQL 使用。上傳至 /codeql-critical-security/android。
• CodeQL macOS Critical Security — 每週／手動 macOS 安全性分片。在 Blacksmith macOS 上手動建置 macOS 應用程式以供 CodeQL 使用，從上傳的 SARIF 中濾除相依套件建置結果，並上傳至 /codeql-critical-security/macos。此分片不包含在每日預設值中，因為即使結果無異常，macOS 建置仍占據大部分執行時間。

重大品質類別

CodeQL Critical Quality 是對應的非安全性分片。它只在 GitHub 託管的 Linux 執行器上，針對範圍有限且高價值的表面執行錯誤嚴重度、非安全性的 JavaScript／TypeScript 品質查詢，避免品質掃描消耗 Blacksmith 執行器註冊預算。其 PR 防護刻意小於排程設定檔：非草稿 PR 只會從十三個可由 PR 路由的分片中，執行與其所觸及表面相符的分片，包括 agent-runtime-boundary、channel-runtime-boundary、config-boundary、core-auth-secrets、gateway-runtime-boundary、mcp-process-runtime-boundary、memory-runtime-boundary、network-runtime-boundary、plugin-boundary、plugin-sdk-package-contract、plugin-sdk-reply-runtime、provider-runtime-boundary 和 session-diagnostics-boundary。ui-control-plane 與 web-media-runtime-boundary 不會在 PR 執行中啟用。CodeQL 設定與品質工作流程變更會執行完整的 PR 分片集合（網路執行階段分片會根據其自身 CodeQL 設定檔及擁有網路功能的來源路徑觸發）。

手動分派接受：

profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|network-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary

窄範圍設定檔是用來單獨執行一個品質分片的教學／迭代掛鉤。

品質與安全性保持分離，以便品質發現能在不模糊安全性訊號的情況下進行排程、衡量、停用或擴充。只有在窄範圍設定檔具備穩定的執行時間與訊號後，才能以範圍限定或分片的後續工作重新加入 Swift、Python 及隨附外掛的 CodeQL 擴充。

維護工作流程

文件代理程式

Docs Agent 工作流程是事件驅動的 Codex 維護執行路徑，用於讓現有文件與近期合併的變更保持一致。它沒有單純的排程：main 上成功的非機器人推送 CI 執行可觸發此流程，也可直接手動分派。若 main 已經前進，或過去一小時內已建立另一個未略過的文件代理程式執行，工作流程執行所觸發的叫用就會略過。執行時，它會審查從上一個未略過文件代理程式來源 SHA 到目前 main 的提交範圍，因此每小時一次的執行可涵蓋自上次文件檢查以來累積的所有主要分支變更。

測試效能代理程式

Test Performance Agent 工作流程是用於慢速測試、由事件驅動的 Codex 維護通道。它沒有單純的排程：在 main 上由非機器人推送所觸發且成功的 CI 執行可以啟動它，但如果同一個 UTC 日內已有另一個工作流程執行呼叫曾經執行或正在執行，就會略過。手動分派不受此每日活動閘門限制。此通道會建立完整測試套件的分組 Vitest 效能報告，僅允許 Codex 進行小型且維持覆蓋率的測試效能修正，而非大範圍重構，接著重新執行完整測試套件報告，並拒絕會降低基準通過測試數量的變更。分組報告會記錄 Linux 和 macOS 上各設定的實際經過時間與最大 RSS，因此前後比較會在持續時間差異旁顯示測試記憶體差異。如果基準中有失敗的測試，Codex 只能修正明顯的失敗，而且代理程式執行後的完整測試套件報告必須通過，才能提交任何內容。如果 main 在機器人推送完成前已有進展，此通道會將已驗證的修補程式重定基底、重新執行 pnpm check:changed，並重試推送；有衝突的過時修補程式會被略過。它使用 GitHub 託管的 Ubuntu，讓 Codex 動作可以維持與文件代理程式相同的停用 sudo 安全策略。

合併後的重複 PR

Duplicate PRs After Merge 工作流程是供維護者手動執行的工作流程，用於合併後清理重複項目。它預設為試執行，且僅在 apply=true 時關閉明確列出的 PR。在修改 GitHub 前，它會確認已落地的 PR 已合併，且每個重複 PR 具有共同引用的議題或重疊的變更區塊。

gh workflow run duplicate-after-merge.yml \  -f landed_pr=70532 \  -f duplicate_prs='70530,70592' \  -f apply=true

本機檢查閘門與變更路由

設定基準計數棘輪

pnpm config:docs:check 會拒絕未記錄於文件中的設定介面增長，以及損毀或過時的計數快照。當經過審查的產品變更有意新增結構描述路徑時，請執行 pnpm config:docs:gen、檢查核心／頻道／外掛的計數差異與產生的 SHA-256 檔案，並將經審慎確認的基準提升連同結構描述、說明、標籤、遷移和測試一併提交。請勿手動編輯計數檔案以規避棘輪。

設定作者也必須為新的葉節點設定「設定」層級。請在葉節點新增 advanced: false 或 advanced: true，或將索引鍵放在所有子節點都應繼承其層級的祖先節點下。未分類的根節點會使結構描述品質 測試失敗，並提供可複製貼上的存根；沒有祖先節點的路徑預設為進階層級。 經過策劃的常用葉節點快照可讓有意進行的層級變更在 審查中清楚可見。

本機變更通道路由邏輯位於 scripts/changed-lanes.mjs，並由 scripts/check-changed.mjs 執行。該本機檢查閘門對架構邊界的要求比廣泛的 CI 平台範圍更嚴格：

• 核心正式環境變更會執行核心正式環境和核心測試型別檢查，以及核心 lint／防護檢查；
• 僅核心測試的變更只執行核心測試型別檢查及核心 lint；
• 外掛正式環境變更會執行外掛正式環境和外掛測試型別檢查，以及外掛 lint；
• 僅外掛測試的變更會執行外掛測試型別檢查及外掛 lint；
• 公開的外掛 SDK 或外掛合約變更會擴展至外掛型別檢查，因為外掛依賴這些核心合約（Vitest 外掛全面檢查仍屬於明確的測試工作）；
• 僅發布中繼資料的版本提升會執行針對性的版本／設定／根依賴項檢查；
• 未知的根目錄／設定變更會採取安全失敗策略，執行所有檢查通道。

本機變更測試路由邏輯位於 scripts/test-projects.test-support.mjs，且刻意比 check:changed 更低成本：直接修改的測試會自行執行；來源變更會優先採用明確對應，接著才是同層測試與匯入圖相依項。共用群組房間傳遞設定是其中一項明確對應：對群組可見回覆設定、來源回覆傳遞模式或訊息工具系統提示詞的變更，會透過核心回覆測試加上 Discord 和 Slack 傳遞迴歸測試進行路由，使共用預設值的變更能在第一次推送 PR 前失敗。只有當變更廣泛到涵蓋整個測試框架，以致低成本的對應集合無法作為可信的替代指標時，才使用 OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed。

Testbox 驗證

Crabbox 是儲存庫自有的遠端主機包裝器，用於維護者的 Linux 驗證。只有在 來源可信且現有依賴項安裝已就緒時，代理程式工作階段才會在本機執行一個／少數幾個聚焦測試與低成本靜態檢查。 它們會使用 Crabbox 執行較大型的測試套件和 運算密集型工作，包括建置、型別檢查、lint 扇出、 Docker、套件通道、E2E、即時驗證和 CI 同等驗證。受信任維護者的重量級 驗證預設使用 blacksmith-testbox，而 .crabbox.yaml 現在也預設使用它。其設定的 工作流程會注入供應商和代理程式認證資訊，因此不受信任的貢獻者或 分支程式碼必須改用不含祕密的分支 CI，或經過清理的直接 AWS Crabbox。 經過清理的 AWS 執行會設定 CRABBOX_ENV_ALLOW=CI、傳入 --no-hydrate，並使用全新的暫時遠端 HOME；這可防止儲存庫的 OPENCLAW_* 允許清單及現有驗證設定檔接觸不受信任的程式碼。 它們會使用專供該不受信任來源、全新暖機的租用環境，而絕不使用 受信任或先前曾注入認證資訊的租用環境。請從乾淨且受信任的 main 簽出內容啟動已安裝的受信任 Crabbox 二進位檔，並僅透過 --fresh-pr 擷取遠端 PR；絕不在本機執行不受信任簽出內容的包裝器或設定。 取消設定 CRABBOX_AWS_INSTANCE_PROFILE，並採取安全失敗策略，除非解析後的 aws.instanceProfile 為空。在進行任何安裝／測試前，使用受信任的 絕對路徑工具要求 IMDSv2 權杖、證明 IAM 認證資訊 端點傳回 404，並將遠端 git rev-parse HEAD 與經完整 審查的 PR 頂端 SHA 進行比較。將租用環境繫結至該 SHA，並在頂端變更時停止並重新暖機。 將乾淨 main 中受信任的 scripts/crabbox-untrusted-bootstrap.sh 連同 --fresh-pr 上傳；它會安裝固定版本的 Node／pnpm、驗證 SHA 和 套件管理器版本固定設定、隔離 HOME、安裝依賴項，接著執行 要求的測試。 取消設定所有 CRABBOX_TAILSCALE* 覆寫、強制使用 --network public --tailscale=false、清除出口節點／LAN 旗標，並要求 crabbox inspect 在上傳任何指令碼前， 回報使用公開網路且沒有 Tailscale 狀態。 自有的 AWS／Hetzner 容量也仍可作為 Blacksmith 服務中斷、 配額問題或明確要求使用自有容量測試時的備援方案。

代理程式不會為預期的工作預先暖機。請在第一個 重量級命令就緒時才取得 Testbox，後續重量級命令重複使用傳回的 tbx_... ID， 每次執行時都同步目前的簽出內容，並在交接前停止它。

由 Crabbox 支援的 Blacksmith 執行會以單次方式將 Testbox 暖機、認領、同步、執行、回報並清理。 內建的同步健全性檢查會在同步主機上的 git status --short 顯示至少 200 個已追蹤刪除項目時快速失敗， 藉此偵測 pnpm-lock.yaml 等根目錄檔案消失的情況。對於有意進行 大量刪除的 PR，請為遠端命令設定 CRABBOX_ALLOW_MASS_DELETIONS=1。

如果本機 Blacksmith 命令列介面呼叫停留在 同步階段超過五分鐘，且沒有同步後輸出，Crabbox 也會終止該呼叫。設定 CRABBOX_BLACKSMITH_SYNC_TIMEOUT_MS=0 可停用此防護，或針對異常龐大的本機差異使用較大的 毫秒值。

首次執行前，請從儲存庫根目錄檢查包裝器：

pnpm crabbox:run -- --help | sed -n '1,120p'

如果過時的 Crabbox 二進位檔未宣告支援所選供應商，儲存庫包裝器會拒絕使用它；Blacksmith 支援的執行則要求 Crabbox 0.22.0 或更新版本，以便包裝器取得目前的 Testbox 同步、佇列和清理行為。在 Codex 工作樹或連結式／稀疏簽出內容中，請避免使用本機 pnpm crabbox:run 指令碼，因為 pnpm 可能在 Crabbox 啟動前協調依賴項；請改為直接呼叫 Node 包裝器：

node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox --timing-json --shell -- "pnpm test <path-or-filter>"

使用同層簽出內容時，請在計時或驗證工作前重新建置被忽略的本機二進位檔：

version="$(git -C ../crabbox describe --tags --always --dirty | sed 's/^v//')" \  && go build -C ../crabbox -trimpath -ldflags "-s -w -X github.com/openclaw/crabbox/internal/cli.version=${version}" -o bin/crabbox ./cmd/crabbox

.crabbox.yaml 中的 blacksmith: 區塊已固定組織、工作流程、工作和參照的預設值，因此下列明確旗標為選用。變更閘門：

pnpm crabbox:run -- --provider blacksmith-testbox \  --blacksmith-org openclaw \  --blacksmith-workflow .github/workflows/ci-check-testbox.yml \  --blacksmith-job check \  --blacksmith-ref main \  --idle-timeout 90m \  --ttl 240m \  --timing-json \  --shell -- \  "corepack pnpm check:changed"

當本機依賴項無法使用或目標會扇出時，在 Testbox 上重新執行聚焦測試：

pnpm crabbox:run -- --provider blacksmith-testbox \  --idle-timeout 90m \  --ttl 240m \  --timing-json \  --shell -- \  "corepack pnpm test <path-or-filter>"

完整測試套件：

pnpm crabbox:run -- --provider blacksmith-testbox \  --idle-timeout 90m \  --ttl 240m \  --timing-json \  --shell -- \  "corepack pnpm test"

請閱讀最終 JSON 摘要。實用欄位為 provider、leaseId、 syncDelegated、exitCode、commandMs 和 totalMs。對於委派的 Blacksmith Testbox 執行，Crabbox 包裝器結束代碼和 JSON 摘要即為 命令結果。連結的 GitHub Actions 執行負責注入認證資訊並維持連線；如果在 SSH 命令已傳回後由外部停止 Testbox，它可能會以 cancelled 結束。除非 包裝器的 exitCode 不為零，或命令輸出顯示測試失敗，否則應將其視為清理／狀態產物。 單次 Blacksmith 支援的 Crabbox 執行應會自動停止 Testbox； 如果執行遭到中斷或清理狀態不明，請檢查運作中的主機，且只停止 你建立的主機：

blacksmith testbox list --allblacksmith testbox status --id <tbx_id>blacksmith testbox stop --id <tbx_id>

只有在你有意於同一台已注入認證資訊的主機上執行多個命令時，才使用重複使用功能：

node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox --id <tbx_id> --timing-json --shell -- "corepack pnpm test <path-or-filter>"pnpm crabbox:stop -- <tbx_id>

重複使用租用環境，而非過時的來源。省略 --no-sync，讓每次執行都上傳 目前的簽出內容；只有在有意重新執行未變更且已同步的工作樹時才使用它。 不受信任的貢獻者／分支程式碼必須在每個命令中使用 CRABBOX_ENV_ALLOW=CI、--provider aws --no-hydrate 和全新的 暫時遠端 HOME；請在該清理命令內安裝依賴項後再進行測試。 只能重複使用專供同一不受信任來源、全新暖機的租用環境；絕不可使用受信任或先前曾注入認證資訊的租用環境。 絕不在本機執行不受信任簽出內容的包裝器或設定：請從乾淨且受信任的 main 啟動已安裝的 受信任 Crabbox 二進位檔，並在每次執行時傳入 --fresh-pr。 讓 CRABBOX_AWS_INSTANCE_PROFILE 保持未設定、拒絕非空的已解析 執行個體設定檔、要求受信任的遠端 IMDS 無角色證明，並在安裝／測試前驗證 經審查的頂端 SHA。將租用環境繫結至該 SHA；任何頂端變更後都要停止並 重新暖機。如果不存在遠端 PR，請使用不含祕密的分支 CI。 絕不可為不受信任的來源選擇 hydrate-github 或注入認證資訊的 Blacksmith 工作流程。

如果故障的是 Crabbox 層，而 Blacksmith 本身可正常運作，則只將直接 Blacksmith 用於 list、status 和清理等診斷。請先修正 Crabbox 路徑，再將直接 Blacksmith 執行視為維護者驗證。

如果 blacksmith testbox list --all 和 blacksmith testbox status 可正常運作，但新的 暖機在數分鐘後仍停留於 queued，且沒有 IP 或 Actions 執行 URL， 請將其視為 Blacksmith 提供者、佇列、計費或組織限制壓力。停止你建立的 排隊中 ID，避免啟動更多 Testbox，並將驗證移至下方自有 Crabbox 容量路徑， 同時由其他人檢查 Blacksmith 儀表板、計費與組織限制。

只有在 Blacksmith 停擺、配額受限、缺少所需環境，或明確以自有容量為目標時，才升級至自有 Crabbox 容量：

CRABBOX_CAPACITY_REGIONS=eu-west-1,eu-west-2,eu-central-1,us-east-1,us-west-2 \  pnpm crabbox:warmup -- --provider aws --class standard --market on-demand --idle-timeout 90mpnpm crabbox:hydrate -- --provider aws --id <cbx_id-or-slug>pnpm crabbox:run -- --provider aws --id <cbx_id-or-slug> --timing-json --shell -- "pnpm check:changed"pnpm crabbox:stop -- --provider aws <cbx_id-or-slug>

在 AWS 容量吃緊時，除非工作確實需要 48xlarge 等級的 CPU，否則請避免使用 class=beast。beast 請求從 192 個 vCPU 起跳，最容易觸發區域 EC2 Spot 或 On-Demand Standard 配額限制。儲存庫自有的 .crabbox.yaml 預設為 class: standard、on-demand 市場與 capacity.hints: true，因此經由代理配置的 AWS 租用會輸出所選區域／市場、配額壓力、Spot 備援，以及高壓力執行個體類別警告。較繁重的廣泛檢查請使用 fast；只有在 standard／fast 不足時才使用 large；而 beast 僅適用於特殊的 CPU 密集型執行工作，例如完整測試套件或所有外掛的 Docker 矩陣、明確的發行／阻擋問題驗證，或高核心數效能分析。請勿將 beast 用於 pnpm check:changed、聚焦測試、僅文件工作、一般 lint／型別檢查、小型端對端重現，或 Blacksmith 停擺分流處理。容量診斷請使用 --market on-demand，以免將 Spot 市場波動混入診斷訊號。

.crabbox.yaml 負責提供者、同步及 GitHub Actions 補水的預設值。Crabbox 同步絕不傳輸 .git，因此已補水的 Actions 簽出會保留自身的遠端 Git 中繼資料，而不會同步維護者本機的遠端與物件儲存區；此外，儲存庫設定也會排除絕不應傳輸的本機執行階段／建置成品（例如 .artifacts 與測試報告）。.github/workflows/crabbox-hydrate.yml 負責簽出、Node／pnpm 設定、origin/main 擷取，以及自有雲端 crabbox run --id <cbx_id> 命令的非機密環境交接。

相關內容

• 安裝概覽
• 開發通道