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.

​

파이프라인 개요

​

빠른 실패 순서

1. preflight는 어떤 레인이 존재할지 결정합니다. docs-scope와 changed-scope 로직은 독립 실행 작업이 아니라 이 작업 내부의 단계입니다.
2. security-scm-fast, security-dependency-audit, security-fast, check, check-additional, check-docs, skills-python은 더 무거운 아티팩트 및 플랫폼 매트릭스 작업을 기다리지 않고 빠르게 실패합니다.
3. build-artifacts는 빠른 Linux 레인과 겹쳐 실행되므로 공유 빌드가 준비되는 즉시 다운스트림 소비자가 시작할 수 있습니다.
4. 그다음 더 무거운 플랫폼 및 런타임 레인이 펼쳐집니다: checks-fast-core, checks-fast-contracts-channels, checks-node-core-test, checks, checks-windows, macos-node, macos-swift, android.

​

범위와 라우팅

• CI 워크플로 편집은 Node CI 그래프와 워크플로 린팅을 검증하지만, 그 자체만으로 Windows, Android, macOS 네이티브 빌드를 강제하지는 않습니다. 이러한 플랫폼 레인은 플랫폼 소스 변경으로 범위가 제한된 상태를 유지합니다.
• CI 라우팅 전용 편집, 선택된 저비용 코어 테스트 fixture 편집, 좁은 Plugin 계약 헬퍼/테스트 라우팅 편집은 빠른 Node 전용 매니페스트 경로를 사용합니다: preflight, 보안, 단일 checks-fast-core 작업. 해당 경로는 변경이 라우팅 또는 빠른 작업이 직접 실행하는 헬퍼 표면으로 제한될 때 빌드 아티팩트, Node 22 호환성, 채널 계약, 전체 코어 샤드, 번들 Plugin 샤드, 추가 가드 매트릭스를 건너뜁니다.
• Windows Node 검사는 Windows 전용 프로세스/경로 래퍼, npm/pnpm/UI runner 헬퍼, 패키지 관리자 설정, 해당 레인을 실행하는 CI 워크플로 표면으로 범위가 제한됩니다. 관련 없는 소스, Plugin, install-smoke, 테스트 전용 변경은 Linux Node 레인에 남습니다.

​

ClawSweeper 활동 전달

• 정확한 이슈 및 pull request 리뷰 요청을 위한 clawsweeper_item;
• 이슈 댓글의 명시적인 ClawSweeper 명령을 위한 clawsweeper_comment;
• main 푸시의 커밋 수준 리뷰 요청을 위한 clawsweeper_commit_review;
• ClawSweeper 에이전트가 검사할 수 있는 일반 GitHub 활동을 위한 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>

​

러너

​

로컬 대응 명령

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: 결정론적 가짜 OpenAI 호환 인증이 포함된 로컬 빌드 런타임에 대해 실행하는 Kova 진단 시나리오.
• mock-deep-profile: 시작, Gateway, 에이전트 턴 핫스팟에 대한 CPU/heap/trace 프로파일링.
• live-gpt54: 실제 OpenAI openai/gpt-5.4 에이전트 턴이며, 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은 안정 프로바이더/백엔드 세트를 추가합니다.
• full은 광범위한 권고용 프로바이더/미디어 매트릭스를 실행합니다.

​

라이브 및 E2E 샤드

• native-live-src-agents
• native-live-src-gateway-core
• 프로바이더로 필터링된 native-live-src-gateway-profiles 작업
• 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
• 분할된 미디어 오디오/비디오 샤드와 프로바이더로 필터링된 음악 샤드

​

패키지 승인

​

작업

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. docker_acceptance는 ref=workflow_ref 및 package_artifact_name=package-under-test로 openclaw-live-and-e2e-checks-reusable.yml을 호출합니다. 재사용 가능 워크플로는 해당 아티팩트를 다운로드하고, 타볼 인벤토리를 검증하며, 필요한 경우 패키지 다이제스트 Docker 이미지를 준비하고, 워크플로 체크아웃을 패킹하는 대신 해당 패키지를 대상으로 선택된 Docker 레인을 실행합니다. 프로필이 여러 대상 docker_lanes를 선택하면, 재사용 가능 워크플로는 패키지와 공유 이미지를 한 번 준비한 다음 고유한 아티팩트를 가진 병렬 대상 Docker 작업으로 해당 레인을 펼칩니다.
3. package_telegram은 선택적으로 NPM Telegram Beta E2E를 호출합니다. telegram_mode가 none이 아닐 때 실행되며, Package Acceptance가 하나를 확인한 경우 동일한 package-under-test 아티팩트를 설치합니다. 독립 실행형 Telegram 디스패치는 여전히 게시된 npm 사양을 설치할 수 있습니다.
4. summary는 패키지 확인, Docker 승인, 또는 선택적 Telegram 레인이 실패한 경우 워크플로를 실패시킵니다.

​

후보 소스

• source=npm은 openclaw@beta, openclaw@latest, 또는 openclaw@2026.4.27-beta.2 같은 정확한 OpenClaw 릴리스 버전만 허용합니다. 게시된 사전 릴리스/안정 승인에 사용하세요.
• source=ref는 신뢰된 package_ref 브랜치, 태그, 또는 전체 커밋 SHA를 패킹합니다. 리졸버는 OpenClaw 브랜치/태그를 가져오고, 선택된 커밋이 저장소 브랜치 기록 또는 릴리스 태그에서 도달 가능한지 검증하며, 분리된 워크트리에 의존성을 설치하고, scripts/package-openclaw-for-docker.mjs로 패킹합니다.
• source=url은 HTTPS .tgz를 다운로드합니다. package_sha256이 필요합니다.
• source=artifact는 artifact_run_id와 artifact_name에서 하나의 .tgz를 다운로드합니다. package_sha256은 선택 사항이지만 외부 공유 아티팩트에는 제공해야 합니다.

​

스위트 프로필

• 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 릴리스 경로 청크
• 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 smoke는 레거시 설치 레코드 위치를 읽거나 marketplace 설치 레코드 지속성 누락을 허용할 수 있습니다.
• 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

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

​

설치 smoke

• 빠른 경로는 Docker/패키지 표면, 번들 Plugin 패키지/manifest 변경, 또는 Docker smoke 작업이 실행하는 core Plugin/channel/gateway/Plugin SDK 표면을 건드리는 pull request에서 실행됩니다. 소스 전용 번들 Plugin 변경, 테스트 전용 편집, 문서 전용 편집은 Docker worker를 예약하지 않습니다. 빠른 경로는 루트 Dockerfile 이미지를 한 번 빌드하고, CLI를 확인하고, agents delete shared-workspace CLI smoke를 실행하고, container gateway-network e2e를 실행하고, 번들 extension build arg를 검증하고, 각 시나리오의 Docker 실행을 별도로 제한하면서 240초 집계 명령 제한 시간 내에 제한된 번들 Plugin Docker profile을 실행합니다.
• 전체 경로는 야간 예약 실행, 수동 dispatch, workflow-call 릴리스 검사, 그리고 실제로 설치 관리자/패키지/Docker 표면을 건드리는 pull request를 위해 QR 패키지 설치와 설치 관리자 Docker/업데이트 범위를 유지합니다. 전체 모드에서 install-smoke는 하나의 target-SHA GHCR 루트 Dockerfile smoke 이미지를 준비하거나 재사용한 다음 QR 패키지 설치, 루트 Dockerfile/gateway smoke, 설치 관리자/업데이트 smoke, 빠른 번들 Plugin Docker E2E를 별도의 작업으로 실행하여 설치 관리자 작업이 루트 이미지 smoke 뒤에서 기다리지 않도록 합니다.

​

로컬 Docker E2E

• 설치 관리자/업데이트/Plugin 의존성 레인을 위한 기본 Node/Git runner
• 일반 기능 레인을 위해 동일한 tarball을 /app에 설치하는 기능 이미지

​

조정 가능한 항목

​

재사용 가능한 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 랩

• QA-Lab - All Lanes 워크플로는 main에서 매일 밤과 수동 디스패치 시 실행되며, 모의 패리티 레인, 라이브 Matrix 레인, 라이브 Telegram 및 Discord 레인을 병렬 작업으로 펼칩니다. 라이브 작업은 qa-live-shared 환경을 사용하고, Telegram/Discord는 Convex 리스를 사용합니다.

​

CodeQL

​

보안 범주

​

플랫폼별 보안 샤드

• CodeQL Android Critical Security — 예약된 Android 보안 샤드입니다. 워크플로 정상성 검사에서 허용하는 가장 작은 Blacksmith Linux 러너에서 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|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/가드를 실행합니다.
• 코어 테스트 전용 변경은 코어 테스트 타입체크와 코어 lint만 실행합니다.
• 확장 프로덕션 변경은 확장 프로덕션 및 확장 테스트 타입체크와 확장 lint를 실행합니다.
• 확장 테스트 전용 변경은 확장 테스트 타입체크와 확장 lint를 실행합니다.
• 공개 Plugin SDK 또는 Plugin 계약 변경은 확장이 해당 코어 계약에 의존하므로 확장 타입체크로 확장됩니다. Vitest 확장 스윕은 명시적 테스트 작업으로 유지됩니다.
• 릴리스 메타데이터 전용 버전 범프는 대상 지정 버전/구성/루트 의존성 검사를 실행합니다.
• 알 수 없는 루트/구성 변경은 안전하게 모든 검사 레인으로 실패 처리됩니다.

​

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>

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>

​

관련 항목

• 설치 개요
• 개발 채널