OpenClaw CI Pipeline 指南：優化建置流程與效能

身為開發者，我們最怕的就是等待漫長的 CI 跑完後才發現一個微小的錯誤，或是因為改動了無關的程式碼卻觸發了整個專案的完整測試。這種無效的等待不僅浪費時間，更會打斷開發節奏。

OpenClaw 的 CI Pipeline 設計核心在於高效與精準，透過智慧化的範圍偵測，確保只有相關的變更才會觸發對應的測試，讓你把時間花在更有價值的地方。

工作概覽 (Job Overview)

下表整理了 CI 中各項任務的用途與觸發條件，幫助你快速了解系統如何運作。

任務 (Job)	用途	執行時機
preflight	偵測僅文件變更、變更範圍、擴充功能變更，並建立 CI 清單	非草稿推送與 PR 時執行
security-scm-fast	透過 zizmor 偵測私鑰與工作流程稽核	非草稿推送與 PR 時執行
security-dependency-audit	針對 npm advisories 進行無依賴的生產環境 lockfile 稽核	非草稿推送與 PR 時執行
security-fast	快速安全性任務的必要聚合檢查	非草稿推送與 PR 時執行
build-artifacts	建置 dist/ 與 Control UI，並為下游任務上傳可重複使用的 artifacts	Node 相關變更時
checks-fast-core	Linux 快速正確性檢查，如 bundled/plugin-contract/protocol 檢查	Node 相關變更時
checks-fast-contracts-channels	分片的 channel contract 檢查，並提供穩定的聚合檢查結果	Node 相關變更時
checks-node-extensions	針對擴充功能套件進行完整的 bundled-plugin 測試分片	Node 相關變更時
checks-node-core-test	核心 Node 測試分片，排除 channel、bundled、contract 與 extension 檢查	Node 相關變更時
extension-fast	僅針對變更的 bundled plugins 進行重點測試	偵測到擴充功能變更時
check	分片的主地端閘道等效檢查：生產環境型別、lint、guards、測試型別與嚴格冒煙測試	Node 相關變更時
check-additional	架構、邊界、擴充功能介面 guards、套件邊界與 Gateway 監控分片	Node 相關變更時
build-smoke	已建置 CLI 的冒煙測試與啟動記憶體冒煙測試	Node 相關變更時
checks	其餘 Linux Node 檢查：channel 測試與僅推送時的 Node 22 相容性	Node 相關變更時
check-docs	文件格式化、lint 與無效連結檢查	文件變更時
skills-python	針對 Python 技能使用 Ruff 與 pytest	Python 技能相關變更時
checks-windows	Windows 專屬測試檢查	Windows 相關變更時
macos-node	使用共享建置 artifacts 的 macOS TypeScript 測試檢查	macOS 相關變更時
macos-swift	macOS 應用程式的 Swift lint、建置與測試	macOS 相關變更時
android	Android 建置與測試矩陣	Android 相關變更時

快速失敗排序 (Fail-Fast Order)

為了節省資源，任務的執行順序經過精心安排，確保廉價的檢查能先過濾掉錯誤，避免浪費時間在昂貴的任務上。

1. preflight 決定哪些檢查路徑需要執行。其中的 docs-scope 與 changed-scope 邏輯是該任務內部的步驟，而非獨立任務。
2. security-scm-fast、security-dependency-audit、security-fast、check、check-additional、check-docs 與 skills-python 會快速失敗，無需等待較重的 artifact 與平台矩陣任務。
3. build-artifacts 與快速 Linux 檢查路徑重疊，讓下游消費者在共享建置準備好時即可立即開始。
4. 較重的平台與執行時期路徑隨後展開：checks-fast-core、checks-fast-contracts-channels、checks-node-extensions、checks-node-core-test、extension-fast、checks、checks-windows、macos-node、macos-swift 與 android。

範圍邏輯位於 scripts/ci-changed-scope.mjs，並由 src/scripts/ci-changed-scope.test.ts 中的單元測試覆蓋。獨立的 install-smoke 工作流程透過自身的 preflight 任務重複使用相同的範圍指令碼。它從較窄的 changed-smoke 訊號計算 run_install_smoke，因此 Docker/install 冒煙測試僅針對安裝、封裝與容器相關的變更執行。

地端變更路徑邏輯位於 scripts/changed-lanes.mjs，並由 scripts/check-changed.mjs 執行。該地端閘道對架構邊界的限制比廣泛的 CI 平台範圍更嚴格：核心生產變更會執行核心生產型別檢查與核心測試，僅核心測試變更則僅執行核心測試型別檢查與測試，擴充功能生產變更會執行擴充功能生產型別檢查與擴充功能測試，而僅擴充功能測試變更則僅執行擴充功能測試型別檢查與測試。公開的 Plugin SDK 或 plugin-contract 變更會擴展至擴充功能驗證，因為擴充功能依賴這些核心合約。未知的根目錄/配置變更會安全地預設為執行所有路徑。

在推送時，checks 矩陣會加入僅限推送的 compat-node22 路徑。在 GitHub 的 pull request 中，該路徑會被跳過，矩陣將保持專注於正常的測試/channel 路徑。

最慢的 Node 測試系列被拆分為 include-file 分片，以確保每個任務保持輕量：channel 合約將 registry 與核心覆蓋率各拆分為八個加權分片，自動回覆指令測試拆分為四個 include-pattern 分片，其他大型自動回覆前綴群組則各拆分為兩個分片。check-additional 也將套件邊界編譯/canary 工作與執行時期拓撲 Gateway/架構工作分開。

GitHub 可能會在較新的推送進入同一個 PR 或 main 參考時，將被取代的任務標記為 cancelled。除非同一個參考的最新的執行也失敗，否則請將其視為 CI 雜訊。聚合分片檢查會明確指出此取消情況，以便與測試失敗區分開來。

執行器 (Runners)

我們針對不同的任務需求配置了對應的執行器，以確保效能與相容性。

執行器	任務
blacksmith-16vcpu-ubuntu-2404	preflight, security-scm-fast, security-dependency-audit, security-fast, build-artifacts, Linux checks, docs checks, Python skills, android
blacksmith-32vcpu-windows-2025	checks-windows
macos-latest	macos-node, macos-swift

地端等效指令 (Local Equivalents)

你可以直接在本地端執行這些指令，以模擬 CI 的檢查流程，確保在推送程式碼前就解決問題。

pnpm changed:lanes   # inspect the local changed-lane classifier for origin/main...HEAD
pnpm check:changed   # smart local gate: changed typecheck/lint/tests by boundary lane
pnpm check          # fast local gate: production tsgo + sharded lint + parallel fast guards
pnpm check:test-types
pnpm check:timed    # same gate with per-stage timings
pnpm build:strict-smoke
pnpm check:architecture
pnpm test:gateway:watch-regression
pnpm test           # vitest tests
pnpm test:channels
pnpm test:contracts:channels
pnpm check:docs     # docs format + lint + broken links
pnpm build          # build dist when CI artifact/build-smoke lanes matter

下一步

• 了解如何設定你的 API
• 深入研究 Node.js 相關配置
• 參考 webhook 的進階用法

AI Setup Assistant