CI 管線

Documentation Index

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

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

​

Pipeline 概覽

​

Fail-fast 順序

1. preflight 決定哪些 lane 實際存在。docs-scope 和 changed-scope 邏輯是這個 job 內的 step，不是獨立 job。
2. security-scm-fast、security-dependency-audit、security-fast、check、check-additional、check-docs 和 skills-python 會快速失敗，不等待較重的 artifact 和平台 matrix job。
3. build-artifacts 會與快速 Linux lane 重疊，讓下游 consumer 可在共用 build 準備好後立即開始。
4. 較重的平台和 runtime lane 接著展開：checks-fast-core、checks-fast-contracts-channels、checks-node-core-test、checks、checks-windows、macos-node、macos-swift 和 android。

​

範圍和路由

• CI workflow 編輯會驗證 Node CI graph 加上 workflow linting，但不會單獨強制 Windows、Android 或 macOS native build；這些平台 lane 仍會限定在平台原始碼變更。
• 僅限 CI 路由的編輯、選定的便宜 core-test fixture 編輯，以及狹窄的 plugin contract helper/test-routing 編輯會使用快速 Node-only manifest 路徑：preflight、security，以及單一 checks-fast-core task。當變更僅限於該快速 task 直接執行的 routing 或 helper surface 時，該路徑會跳過 build artifacts、Node 22 compatibility、channel contracts、完整 core shards、bundled-plugin shards 和 additional guard matrices。
• Windows Node 檢查限定於 Windows 特定 process/path wrapper、npm/pnpm/UI runner helper、package manager config，以及執行該 lane 的 CI workflow surface；不相關的 source、plugin、install-smoke 和 test-only 變更會留在 Linux Node lane 上。

​

ClawSweeper 活動轉送

• clawsweeper_item 用於精確的 issue 和 pull request review request；
• clawsweeper_comment 用於 issue comment 中明確的 ClawSweeper command；
• clawsweeper_commit_review 用於 main push 上的 commit-level review request；
• github_activity 用於 ClawSweeper agent 可能檢查的一般 GitHub activity。

​

手動派送

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

​

Runner

​

本機等效命令

pnpm changed:lanes                            # inspect the local changed-lane classifier for origin/main...HEAD
pnpm check:changed                            # smart local check gate: changed typecheck/lint/guards by boundary lane
pnpm check                                    # fast local gate: prod 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:changed                             # cheap smart changed Vitest targets
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
pnpm ci:timings                               # summarize the latest origin/main push CI run
pnpm ci:timings:recent                        # compare recent successful main CI runs
node scripts/ci-run-timings.mjs <run-id>      # summarize wall time, queue time, and slowest jobs
node scripts/ci-run-timings.mjs --latest-main # ignore issue/comment noise and choose origin/main push CI
node scripts/ci-run-timings.mjs --recent 10   # compare recent successful main CI runs
pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json
pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json
pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.json --output .artifacts/kova/summary.md

​

OpenClaw 效能

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

• mock-provider：Kova diagnostic scenario，針對具備 deterministic fake OpenAI-compatible auth 的本機建置 runtime。
• mock-deep-profile：針對啟動、Gateway 與 agent-turn 熱點的 CPU/heap/trace profiling。
• live-gpt54：真實 OpenAI openai/gpt-5.4 agent turn，當 OPENAI_API_KEY 無法使用時會略過。

​

完整發行驗證

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

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

• minimum 保留最快的 OpenAI/核心發布關鍵線路。
• stable 加入穩定的 provider/backend 集合。
• full 執行廣泛的 advisory provider/media 矩陣。

​

Live 與 E2E 分片

• native-live-src-agents
• native-live-src-gateway-core
• provider-filtered native-live-src-gateway-profiles jobs
• native-live-src-gateway-backends
• native-live-test
• native-live-extensions-a-k
• native-live-extensions-l-n
• native-live-extensions-openai
• native-live-extensions-o-z-other
• native-live-extensions-xai
• 分割的 media audio/video 分片與 provider-filtered music 分片

​

套件驗收

​

Jobs

1. resolve_package 會 checkout workflow_ref，解析一個套件候選版，寫入 .artifacts/docker-e2e-package/openclaw-current.tgz，寫入 .artifacts/docker-e2e-package/package-candidate.json，將兩者都上傳為 package-under-test artifact，並在 GitHub step summary 中列印來源、workflow ref、package ref、版本、SHA-256 與 profile。
2. docker_acceptance 會以 ref=workflow_ref 與 package_artifact_name=package-under-test 呼叫 openclaw-live-and-e2e-checks-reusable.yml。可重用 workflow 會下載該 artifact，驗證 tarball inventory，視需要準備 package-digest Docker images，並針對該套件執行選定的 Docker 線路，而不是打包 workflow checkout。當一個 profile 選取多個目標 docker_lanes 時，可重用 workflow 會準備套件與共用映像一次，然後將這些線路展開為並行的目標 Docker jobs，且各自使用唯一 artifact。
3. package_telegram 可選擇呼叫 NPM Telegram Beta E2E。當 telegram_mode 不是 none 時會執行；若套件驗收已解析出一個 artifact，則安裝相同的 package-under-test artifact；獨立 Telegram dispatch 仍可安裝已發布的 npm spec。
4. summary 會在套件解析、Docker 驗收或可選 Telegram 線路失敗時讓 workflow 失敗。

​

候選來源

• source=npm 只接受 openclaw@beta、openclaw@latest，或像 openclaw@2026.4.27-beta.2 這樣的精確 OpenClaw 發布版本。請用於已發布 prerelease/stable 驗收。
• source=ref 會打包受信任的 package_ref 分支、標籤或完整 commit SHA。resolver 會 fetch OpenClaw 分支/標籤，驗證選定 commit 可從 repository 分支歷史或發布標籤到達，在 detached worktree 中安裝 deps，並以 scripts/package-openclaw-for-docker.mjs 打包。
• source=url 會下載 HTTPS .tgz；必須提供 package_sha256。
• source=artifact 會從 artifact_run_id 與 artifact_name 下載一個 .tgz；package_sha256 為可選，但對外共享的 artifacts 應提供。

​

Suite profiles

• 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、update-restart-auth、plugins-offline、plugin-update
• product — package 加上 mcp-channels、cron-mcp-cleanup、openai-web-search-minimal、openwebui
• full — 包含 OpenWebUI 的完整 Docker 發布路徑 chunks
• custom — 精確的 docker_lanes；當 suite_profile=custom 時必填

​

舊版相容性視窗

• dist/postinstall-inventory.json 中已知的私有 QA 項目可以指向 tarball 省略的檔案；
• 當套件未公開該旗標時，doctor-switch 可以略過 gateway install --wrapper 持久化子案例；
• update-channel-switch 可以從 tarball 衍生的假 git fixture 中修剪缺漏的 pnpm.patchedDependencies，並可以記錄缺漏的已持久化 update.channel；
• Plugin 煙霧測試可以讀取舊版安裝記錄位置，或接受缺少 marketplace 安裝記錄持久化；
• plugin-update 可以允許設定 metadata 遷移，同時仍要求安裝記錄和不重新安裝行為保持不變。

​

範例

# Validate the current beta package with product-level coverage.
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

# Pack and validate a release branch with the current harness.
gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=ref \
  -f package_ref=release/YYYY.M.D \
  -f suite_profile=package \
  -f telegram_mode=mock-openai

# Validate a tarball URL. SHA-256 is mandatory for source=url.
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

# Reuse a tarball uploaded by another Actions run.
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'

​

安裝煙霧測試

• 快速路徑會在 pull request 觸及 Docker/套件表面、內建 Plugin 套件/manifest 變更，或 Docker 煙霧測試 job 會演練的核心 Plugin/channel/Gateway/Plugin SDK 表面時執行。僅限來源的內建 Plugin 變更、僅測試編輯和僅文件編輯不會保留 Docker worker。快速路徑會建置一次根 Dockerfile 映像、檢查 CLI、執行 agents delete shared-workspace CLI 煙霧測試、執行容器 gateway-network e2e、驗證內建 extension build arg，並在 240 秒彙總命令 timeout 內執行有界的內建 Plugin Docker profile（每個情境的 Docker 執行會分別設上限）。
• 完整路徑保留 QR 套件安裝與 installer Docker/update 涵蓋範圍，用於 nightly 排程執行、手動 dispatch、workflow-call 發布檢查，以及真正觸及 installer/package/Docker 表面的 pull request。在完整模式中，install-smoke 會準備或重用一個目標 SHA 的 GHCR 根 Dockerfile 煙霧映像，然後將 QR 套件安裝、根 Dockerfile/Gateway 煙霧測試、installer/update 煙霧測試，以及快速內建 Plugin Docker E2E 作為獨立 job 執行，讓 installer 工作不必等在根映像煙霧測試後面。

​

本機 Docker E2E

• 用於 installer/update/plugin-dependency lane 的裸 Node/Git runner；
• 將相同 tarball 安裝到 /app、用於一般功能 lane 的功能映像。

​

可調參數

​

可重用 live/E2E workflow

​

發布路徑 chunk

• 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

pnpm test:docker:rerun <run-id>      # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary>   # slow-lane and phase critical-path summaries

​

Plugin 預發布

​

QA Lab

• QA-Lab - All Lanes workflow 每晚在 main 上執行，也可手動 dispatch；它會將 mock parity lane、live Matrix lane，以及 live Telegram 和 Discord lane 展開為並行 job。Live job 使用 qa-live-shared environment，而 Telegram/Discord 使用 Convex lease。

​

CodeQL

​

安全類別

​

平台特定安全分片

• CodeQL Android Critical Security — 排程的 Android 安全分片。為 CodeQL 手動建置 Android 應用程式，使用工作流程健全性接受的最小 Blacksmith Linux 執行器。上傳到 /codeql-critical-security/android 底下。
• CodeQL macOS Critical Security — 每週/手動 macOS 安全分片。在 Blacksmith macOS 上為 CodeQL 手動建置 macOS 應用程式，從上傳的 SARIF 中篩除相依性建置結果，並上傳到 /codeql-critical-security/macos 底下。由於即使乾淨時 macOS 建置也主導執行時間，因此保留在每日預設值之外。

​

關鍵品質類別

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

​

維護工作流程

​

文件代理

​

測試效能代理

​

合併後重複的 PR

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

​

本機檢查閘門與變更路由

• core production 變更會執行 core prod 與 core test typecheck，再加上 core lint/guards；
• core test-only 變更只會執行 core test typecheck，再加上 core lint；
• extension production 變更會執行 extension prod 與 extension test typecheck，再加上 extension lint；
• extension test-only 變更會執行 extension test typecheck，再加上 extension lint；
• public Plugin SDK 或 plugin-contract 變更會擴大到 extension typecheck，因為 extensions 依賴這些 core contracts（Vitest extension sweeps 仍維持明確的測試工作）；
• 僅 release metadata 的版本升級會執行目標式 version/config/root-dependency 檢查；
• 未知的 root/config 變更會以安全失敗方式進入所有 check lanes。

​

Testbox 驗證

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

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 -- \
  "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"

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 -- \
  "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test <path-or-filter>"

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 -- \
  "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test"

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

pnpm crabbox:run -- --provider blacksmith-testbox --id <tbx_id> --no-sync --timing-json --shell -- "pnpm test <path-or-filter>"
pnpm crabbox:stop -- <tbx_id>

blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
blacksmith testbox stop --id <tbx_id>

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 90m
pnpm crabbox:hydrate -- --id <cbx_id-or-slug>
pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
pnpm crabbox:stop -- <cbx_id-or-slug>

​

相關

• 安裝概覽
• 開發頻道