CI パイプライン

​

パイプライン概要

​

Fail-fast 順序

1. runner-admission は正規の main push のみ待機します。新しい push があると、Blacksmith 登録前に run がキャンセルされます。
2. preflight はどの lane がそもそも存在するかを決定します。docs-scope と changed-scope のロジックは、この job 内の step であり、独立した job ではありません。
3. security-fast、check-*、check-additional-*、check-docs、skills-python は、より重い artifact および platform matrix job を待たずにすばやく失敗します。
4. build-artifacts は高速な Linux lane と重なって実行されるため、共有 build の準備ができ次第、下流の consumer が開始できます。
5. その後、より重い platform および runtime lane がファンアウトします: checks-fast-core、checks-fast-contracts-plugins-*、checks-fast-contracts-channels-*、checks-node-*、checks-windows、macos-node、macos-swift、ios-build、android。

​

PR コンテキストと証拠

​

スコープとルーティング

• CI ワークフローの編集は、Node CI グラフ、ワークフローの lint、Windows レーン（ci.yml が実行）を検証しますが、それだけで iOS、Android、macOS のネイティブビルドを強制するものではありません。これらのプラットフォームレーンは、プラットフォームのソース変更にスコープされたままです。
• ワークフロー健全性は、すべてのワークフロー YAML ファイルに対する actionlint、zizmor、コンポジットアクション補間ガード、競合マーカーガードを実行します。PR スコープの security-fast ジョブも、変更されたワークフローファイルに対して zizmor を実行するため、ワークフローのセキュリティ所見はメインの CI グラフで早期に失敗します。
• main プッシュ時のドキュメントは、CI と同じ ClawHub ドキュメントミラーを使うスタンドアロンの Docs ワークフローでチェックされるため、コードとドキュメントが混在するプッシュでも CI の check-docs シャードは追加でキューに入りません。Pull request と手動 CI では、ドキュメントが変更された場合に引き続き CI から check-docs が実行されます。
• TUI PTYは、TUI の変更に対して 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 ルーティングのみの編集、高速タスクが直接実行する少数の core-test フィクスチャ、狭い Plugin 契約ヘルパーの編集は、高速な Node のみのマニフェストパスを使います。preflight、security-fast、および変更が触れた高速レーンのみ、つまり単一の checks-fast-core CI ルーティングタスク、2 つの Plugin 契約シャード、またはその両方です。このパスは、ビルド成果物、Node 22 互換性、チャネル契約、完全なコアシャード、バンドル済み Plugin シャード、追加のガードマトリクスをスキップします。
• Windows Node チェックは、Windows 固有のプロセス/パスラッパー、npm/pnpm/UI ランナーヘルパー、パッケージマネージャー設定、およびそのレーンを実行する CI ワークフローサーフェスにスコープされます。無関係なソース、Plugin、インストールスモーク、テストのみの変更は Linux Node レーンにとどまります。

• Plugin 契約とチャネル契約は、それぞれ標準の GitHub ランナーフォールバック付きで、重み付けされた Blacksmith バックの 2 つのシャードとして実行されます。
• コアユニットの高速/サポートレーンは個別に実行されます。コアランタイムインフラは、process、shared、hooks、secrets、3 つの cron ドメインシャードに分割されます。
• 自動返信はバランスされたワーカーとして実行され、reply サブツリーは agent-runner、commands、dispatch、session、state-routing シャードに分割されます。
• Agentic gateway/server（コントロールプレーン）設定は、ビルド済み成果物を待つのではなく、chat、auth、model、HTTP/plugin、runtime、startup レーンに分割されます。
• 通常の CI は、分離されたインフラ include-pattern シャードのみを最大 64 テストファイルの決定論的なバンドルに詰め込み、非分離の command/cron、ステートフルな agents-core、gateway/server スイートをマージせずに Node マトリクスを削減します。重い固定スイートは 8 vCPU のままにし、バンドル済みレーンと低重みレーンは 4 vCPU を使います。
• 正規リポジトリ上の Pull request は、コンパクトな受け入れプランを使います。同じ設定ごとのグループが分離サブプロセスで実行され、現在は 74 ジョブの完全マトリクスではなく 18 個の Node テストジョブです。main プッシュ、手動ディスパッチ、リリースゲートは完全マトリクスを維持します。
• 広範なブラウザー、QA、メディア、その他の Plugin テストは、共有 Plugin キャッチオールではなく専用の Vitest 設定を使います。Include-pattern シャードは CI シャード名を使ってタイミングエントリを記録するため、.artifacts/vitest-shard-timings.json は設定全体とフィルター済みシャードを区別できます。
• check-additional-* は、補助的な境界ガードリスト（scripts/run-additional-boundary-checks.mjs）を、プロンプト負荷の高い 1 つのシャード（check-additional-boundaries-a。Codex プロンプトスナップショットのドリフトチェックを含む）と、残りのストライプをまとめた 1 つのシャード（check-additional-boundaries-bcd）に分割します。各シャードは独立したガードを並行実行し、チェックごとのタイミングを出力します。パッケージ境界の compile/canary 作業はまとめたままにし、ランタイムトポロジーアーキテクチャは build-artifacts に埋め込まれた Gateway watch カバレッジとは別に実行されます。
• Gateway watch、チャネルテスト、コア support-boundary シャードは、dist/ と dist-runtime/ がすでにビルドされた後、build-artifacts 内で並行実行されます。

​

ClawSweeper アクティビティ転送

• 正確な issue と pull request レビューリクエスト用の clawsweeper_item;
• issue コメント内の明示的な ClawSweeper コマンド用の clawsweeper_comment;
• main プッシュ上のコミットレベルレビューリクエスト用の clawsweeper_commit_review;
• ClawSweeper エージェントが検査する可能性のある一般的な GitHub アクティビティ用の github_activity。

​

手動ディスパッチ

gh workflow run ci.yml --ref release/YYYY.M.PATCH
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>

​

ランナー

​

ランナー登録予算

​

ローカル同等コマンド

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
OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts
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/smoke checks matter
pnpm ios:build                                # generate and build the iOS app project
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 test:startup:memory
pnpm test:extensions:memory -- --json .artifacts/openclaw-performance/source/mock-provider/extension-memory.json
pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.json --output .artifacts/kova/summary.md

​

OpenClaw Performance

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_openai_candidate=true
gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3

• mock-provider: 決定的な偽の OpenAI 互換認証を使い、ローカルビルドランタイムに対して Kova 診断シナリオを実行する。
• mock-deep-profile: 起動、Gateway、エージェントターンのホットスポットに対する CPU/ヒープ/トレースプロファイリング。スケジュール時、または deep_profile=true 付きのディスパッチ時に実行される。
• live-openai-candidate: 実際の OpenAI openai/gpt-5.5 エージェントターン。OPENAI_API_KEY が利用できない場合はスキップされる。スケジュール時、または live_openai_candidate=true 付きのディスパッチ時に実行される。

​

フルリリース検証

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

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

• minimum は最速の OpenAI/core release-critical lanes を維持します。
• stable は stable provider/backend セットを追加します。
• full は広範な advisory provider/media matrix を実行します。

​

Live と E2E shards

• native-live-src-agents と native-live-src-agents-zai-coding
• native-live-src-gateway-core
• provider-filtered native-live-src-gateway-profiles jobs
• 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
• 分割された media audio/video shards と provider-filtered music shards

​

Package Acceptance

​

Jobs

1. resolve_package は workflow_ref を checkout し、1 つの package candidate を解決し、.artifacts/docker-e2e-package/openclaw-current.tgz を書き込み、.artifacts/docker-e2e-package/package-candidate.json を書き込み、その両方を package-under-test artifact として upload し、source、workflow ref、package ref、version、SHA-256、profile を GitHub step summary に出力します。
2. package_integrity は package-under-test artifact を download し、scripts/check-openclaw-package-tarball.mjs で public package tarball contract を強制します。
3. docker_acceptance は、解決済み package source SHA（workflow_ref に fallback）と package_artifact_name=package-under-test で openclaw-live-and-e2e-checks-reusable.yml を呼び出します。reusable workflow はその artifact を download し、tarball inventory を検証し、必要に応じて package-digest Docker images を準備し、workflow checkout を pack する代わりにその package に対して選択された Docker lanes を実行します。profile が複数の targeted docker_lanes を選択した場合、reusable workflow は package と shared images を一度だけ準備し、その後それらの lane を unique artifact を持つ並列 targeted Docker jobs として fan out します。
4. package_telegram は必要に応じて NPM Telegram Beta E2E を呼び出します。telegram_mode が none でない場合に実行され、Package Acceptance が package を解決した場合は同じ package-under-test artifact を install します。standalone Telegram dispatch では、引き続き公開済み npm spec を install できます。
5. summary は package resolution、integrity、Docker acceptance、または任意の Telegram lane が失敗した場合に workflow を失敗させます。advisory input は、advisory caller 向けに acceptance failure を warning に downgrade します。

​

Candidate sources

• source=npm は openclaw@extended-stable、openclaw@beta、openclaw@latest、または openclaw@2026.4.27-beta.2 のような正確な OpenClaw release version のみを受け付けます。公開済み extended-stable、prerelease、または stable acceptance に使います。
• source=ref は信頼済み package_ref branch、tag、または full commit SHA を pack します。resolver は OpenClaw branch/tag を fetch し、選択された commit が repository branch history または release tag から到達可能であることを検証し、detached worktree に deps を install し、scripts/package-openclaw-for-docker.mjs で pack します。
• source=url は public HTTPS .tgz を download します。package_sha256 は必須です。この path は URL credentials、default 以外の HTTPS port、private/internal/special-use hostname または解決済み IP、同じ public safety policy の外への redirect を拒否します。
• source=trusted-url は .github/package-trusted-sources.json の名前付き trusted-source policy から HTTPS .tgz を download します。package_sha256 と trusted_source_id は必須です。configured hosts、ports、path prefixes、redirect hosts、または private-network resolution が必要な maintainer-owned enterprise mirror または private package repository にのみ使います。policy が bearer auth を宣言している場合、workflow は固定の OPENCLAW_TRUSTED_PACKAGE_TOKEN secret を使います。URL-embedded credentials は引き続き拒否されます。
• source=artifact は artifact_run_id と artifact_name から 1 つの .tgz を download します。package_sha256 は任意ですが、外部共有 artifact には指定するべきです。

​

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, root-managed-vps-upgrade, update-restart-auth, plugins-offline, plugin-update
• product — live plugins coverage を plugins-offline の代わりに使う package セットに加えて、mcp-channels、cron-mcp-cleanup、openai-web-search-minimal、openwebui
• full — OpenWebUI を含む full Docker release-path chunks
• custom — 正確な docker_lanes。suite_profile=custom の場合は必須です

​

レガシー互換性ウィンドウ

• dist/postinstall-inventory.json 内の既知の非公開 QA エントリは、tarball から省略されたファイルを指していてもかまいません。
• パッケージがそのフラグを公開していない場合、doctor-switch は gateway install --wrapper 永続化サブケースをスキップできます。
• update-channel-switch は、tarball 由来の fake git フィクスチャから欠落している pnpm patchedDependencies を除去でき、永続化された update.channel の欠落をログに出力できます。
• Plugin smoke は、レガシーのインストールレコード場所を読み取るか、マーケットプレイスのインストールレコード永続化の欠落を許容できます。
• plugin-update は、インストールレコードと再インストールなしの挙動が変わらないことを引き続き要求しながら、設定メタデータ移行を許可できます。

​

例

# 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

# Validate the published extended-stable package with package coverage.
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

# 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.PATCH \
  -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

# Validate a tarball from a named trusted private mirror policy.
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

# 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'

​

インストール smoke

• ルート Dockerfile smoke イメージはターゲット SHA ごとに 1 回ビルドされるか、ghcr.io/openclaw/openclaw-dockerfile-smoke:<sha> として GHCR から再利用されます。その後、CLI smoke、agents delete shared-workspace CLI smoke、コンテナ gateway-network E2E、組み込み matrix Plugin build-arg smoke がそのイメージに対して実行されます。Plugin smoke は、ランタイム依存関係インストールのミラーリングと、Plugin が entry-escape 診断なしで読み込まれることを検証します。
• QR パッケージインストールとインストーラー/update Docker smoke（Rocky Linux インストーラーレーン、および設定可能な update_baseline_version npm ベースラインに対する update レーンを含む）は個別のジョブとして実行されるため、インストーラー作業がルートイメージ smoke の後ろで待たされることはありません。

​

ローカル Docker E2E

• インストーラー/update/Plugin 依存関係レーン用の素の Node/Git ランナー。
• 通常の機能レーン用に同じ tarball を /app にインストールする機能イメージ。

​

調整可能項目

​

再利用可能な live/E2E ワークフロー

​

リリースパスのチャンク

• 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 ワークフローは、main で毎晩および手動ディスパッチで実行されます。これは、モックパリティレーン、ライブ Matrix レーン、ライブ Telegram レーンおよび Discord レーンを並列ジョブとして展開します。ライブジョブは qa-live-shared 環境を使用し、Telegram/Discord は Convex リースを使用します。

​

CodeQL

​

セキュリティカテゴリ

​

プラットフォーム固有のセキュリティシャード

• CodeQL Android Critical Security — スケジュールされた Android セキュリティシャード。ワークフロー sanity が許容する最小の Blacksmith Linux runner 上で、CodeQL 用に Android アプリを手動でビルドします。/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|network-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary

​

メンテナンスワークフロー

​

Docs Agent

​

Test Performance Agent

​

マージ後の重複 PR

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

​

ローカルチェックゲートと変更ルーティング

• コア本番変更は、コア本番およびコアテストの型チェックに加えて、コア lint/guard を実行します。
• コアのテストのみの変更は、コアテストの型チェックに加えてコア lint のみを実行します。
• 拡張機能の本番変更は、拡張機能の本番および拡張機能テストの型チェックに加えて、拡張機能 lint を実行します。
• 拡張機能のテストのみの変更は、拡張機能テストの型チェックに加えて拡張機能 lint を実行します。
• 公開 Plugin SDK または plugin-contract の変更は、拡張機能がそれらのコアコントラクトに依存するため、拡張機能の型チェックへ拡張されます（Vitest 拡張機能スイープは明示的なテスト作業のままです）。
• リリースメタデータのみのバージョン更新は、対象を絞ったバージョン/設定/ルート依存関係チェックを実行します。
• 不明な root/config 変更は、安全側に倒してすべてのチェックレーンを実行します。

​

Testbox 検証

node scripts/crabbox-wrapper.mjs warmup --provider blacksmith-testbox --keep --timing-json

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

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

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"

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"

blacksmith testbox list --all
blacksmith 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>

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 -- --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>

​

関連

• インストール概要
• 開発チャンネル