CI 流水线

​

流水线概览

​

快速失败顺序

1. runner-admission 只会等待规范 main 推送；较新的推送会在 Blacksmith 注册前取消该运行。
2. preflight 决定哪些通道实际存在。docs-scope 和 changed-scope 逻辑是此作业内的步骤，不是独立作业。
3. security-fast、check-*、check-additional-*、check-docs 和 skills-python 会快速失败，而不等待更重的产物和平台矩阵作业。
4. build-artifacts 会与快速 Linux 通道重叠运行，使下游消费者可在共享构建就绪后立即开始。
5. 更重的平台和运行时通道随后展开：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，并运行复合 action 插值保护和冲突标记保护。PR 范围的 security-fast 作业也会对变更的工作流文件运行 zizmor，以便工作流安全发现能在主 CI 图中尽早失败。
• main 推送上的文档由独立的 Docs 工作流检查，并使用与 CI 相同的 ClawHub 文档镜像，因此混合的代码+文档推送不会同时排队 CI check-docs 分片。拉取请求和手动 CI 在文档变更时仍会从 CI 运行 check-docs。
• TUI PTY会在 checks-node-core-runtime-tui-pty Linux Node 分片中针对 TUI 变更运行。该分片使用 OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 运行 test/vitest/vitest.tui-pty.config.ts，因此同时覆盖确定性的 TuiBackend fixture 通道，以及较慢的 tui --local 冒烟测试，后者只模拟外部模型端点。
• 仅 CI 路由编辑、快速任务直接运行的一小组核心测试 fixture，以及窄范围插件合约辅助工具编辑使用快速的仅 Node 清单路径：preflight、security-fast，以及变更触及的快速通道，即单个 checks-fast-core CI 路由任务、两个插件合约分片，或两者。该路径会跳过构建产物、Node 22 兼容性、渠道合约、完整核心分片、内置插件分片和额外保护矩阵。
• Windows Node 检查仅限于 Windows 特定的进程/路径包装器、npm/pnpm/UI runner 辅助工具、包管理器配置，以及执行该通道的 CI 工作流表面；无关的源代码、插件、安装冒烟和仅测试变更仍留在 Linux Node 通道上。

• 插件合约和渠道合约各自作为两个加权的 Blacksmith 支持分片运行，并带有标准 GitHub runner 回退。
• 核心单元 fast/support 通道会单独运行；核心运行时基础设施会拆分为 process、shared、hooks、secrets 和三个 cron 领域分片。
• 自动回复作为均衡的 worker 运行，reply 子树会拆分为 agent-runner、commands、dispatch、session 和 state-routing 分片。
• Agentic gateway/server（控制平面）配置会拆分到 chat、auth、model、HTTP/plugin、runtime 和 startup 通道，而不是等待已构建产物。
• 普通 CI 只将隔离的基础设施 include-pattern 分片打包进最多 64 个测试文件的确定性 bundle，从而减少 Node 矩阵，同时不合并非隔离的 command/cron、有状态 agents-core 或 gateway/server 套件。重型固定套件仍使用 8 vCPU，而打包后的通道和较低权重通道使用 4 vCPU。
• 规范仓库上的拉取请求使用紧凑准入计划：相同的按配置分组在隔离子进程中运行，目前是 18 个 Node 测试作业，而不是 74 个作业的完整矩阵。main 推送、手动分发和发布门禁保留完整矩阵。
• 广泛的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享插件 catch-all。Include-pattern 分片使用 CI 分片名称记录耗时条目，因此 .artifacts/vitest-shard-timings.json 可以区分完整配置和过滤后的分片。
• check-additional-* 会将补充边界保护列表（scripts/run-additional-boundary-checks.mjs）分条到一个提示词密集分片（check-additional-boundaries-a，其中包含 Codex 提示词快照漂移检查）和一个用于其余条带的组合分片（check-additional-boundaries-bcd），每个分片并发运行独立保护并打印每项检查的耗时。包边界编译/canary 工作保持在一起，而运行时拓扑架构会与嵌入在 build-artifacts 中的 Gateway 网关 watch 覆盖率分开运行。
• Gateway 网关 watch、渠道测试和核心 support-boundary 分片会在 dist/ 和 dist-runtime/ 已构建完成后，在 build-artifacts 内并发运行。

​

ClawSweeper 活动转发

• clawsweeper_item 用于精确的问题和拉取请求审查请求；
• clawsweeper_comment 用于 issue 评论中的显式 ClawSweeper 命令；
• clawsweeper_commit_review 用于 main 推送上的提交级审查请求；
• github_activity 用于 ClawSweeper 智能体可能检查的一般 GitHub 活动。

​

手动分发

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>

​

Runners

​

运行器注册预算

​

本地等效命令

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：针对本地构建运行时运行 Kova 诊断场景，并使用确定性的假 OpenAI 兼容鉴权。
• 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 发布关键 lane。
• stable 添加稳定的提供商/后端集合。
• full 运行广泛的 advisory 提供商/媒体矩阵。

​

Live 和 E2E 分片

• 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
• 拆分的媒体音频/视频分片，以及按提供商过滤的音乐分片

​

Package Acceptance

​

Jobs

1. resolve_package checkout workflow_ref，解析一个包候选，写入 .artifacts/docker-e2e-package/openclaw-current.tgz，写入 .artifacts/docker-e2e-package/package-candidate.json，将两者作为 package-under-test 构件上传，并在 GitHub 步骤摘要中打印来源、workflow ref、package ref、版本、SHA-256 和 profile。
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。可复用 workflow 下载该构件，验证 tarball 清单，在需要时准备 package-digest Docker 镜像，并针对该包运行所选 Docker lane，而不是打包 workflow checkout。当某个 profile 选择多个目标 docker_lanes 时，可复用 workflow 会先准备包和共享镜像一次，然后将这些 lane 扇出为并行的目标 Docker job，并使用唯一构件。
4. package_telegram 可选调用 NPM Telegram Beta E2E。当 telegram_mode 不是 none 时它会运行，并在 Package Acceptance 已解析包时安装同一个 package-under-test 构件；独立 Telegram dispatch 仍可安装已发布的 npm spec。
5. 如果包解析、完整性、Docker acceptance 或可选 Telegram lane 失败，summary 会使 workflow 失败。advisory 输入会把 advisory 调用方的 acceptance 失败降级为警告。

​

候选来源

• source=npm 只接受 openclaw@extended-stable、openclaw@beta、openclaw@latest，或精确的 OpenClaw 发布版本，例如 openclaw@2026.4.27-beta.2。将其用于已发布的 extended-stable、预发布或 stable acceptance。
• source=ref 打包受信任的 package_ref 分支、标签或完整提交 SHA。解析器会获取 OpenClaw 分支/标签，验证所选提交可从仓库分支历史或发布标签到达，在 detached worktree 中安装依赖，并使用 scripts/package-openclaw-for-docker.mjs 打包。
• source=url 下载公共 HTTPS .tgz；package_sha256 是必需的。此路径会拒绝 URL 凭证、非默认 HTTPS 端口、私有/内部/特殊用途主机名或解析后的 IP，以及跳转到同一公共安全策略之外的重定向。
• source=trusted-url 从 .github/package-trusted-sources.json 中命名的 trusted-source policy 下载 HTTPS .tgz；package_sha256 和 trusted_source_id 是必需的。仅将其用于维护者拥有的企业镜像或私有包仓库，这些仓库需要配置主机、端口、路径前缀、重定向主机或私有网络解析。如果该 policy 声明 bearer auth，workflow 会使用固定的 OPENCLAW_TRUSTED_PACKAGE_TOKEN secret；URL 嵌入式凭证仍会被拒绝。
• source=artifact 从 artifact_run_id 和 artifact_name 下载一个 .tgz；package_sha256 是可选的，但应为外部共享构件提供。

​

套件 profile

• 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 集合，但使用 live plugins 覆盖率代替 plugins-offline，并添加 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 省略的文件；
• 当包未暴露 gateway install --wrapper 标志时，doctor-switch 可以跳过其持久化子用例；
• update-channel-switch 可以从 tarball 派生的假 git 夹具中修剪缺失的 pnpm patchedDependencies，并可以记录缺失的已持久化 update.channel；
• 插件 smoke 可以读取旧版安装记录位置，或接受缺少 marketplace 安装记录持久化；
• plugin-update 可以允许配置元数据迁移，同时仍要求安装记录和 no-reinstall 行为保持不变。

​

示例

# 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 构建一次（或从 GHCR 作为 ghcr.io/openclaw/openclaw-dockerfile-smoke:<sha> 复用），然后 CLI smoke、agents delete shared-workspace CLI smoke、容器 gateway-network E2E，以及内置 matrix 插件 build-arg smoke 都会基于它运行。插件 smoke 会验证运行时依赖安装镜像一致，并验证插件加载时没有 entry-escape 诊断。
• QR 包安装以及安装器/更新 Docker smoke（包括 Rocky Linux 安装器 lane 和针对可配置 update_baseline_version npm 基线的更新 lane）作为单独作业运行，这样安装器工作不会等待根镜像 smoke。

​

本地 Docker E2E

• 用于安装器/更新/插件依赖 lane 的裸 Node/Git runner；
• 将同一个 tarball 安装到 /app 的功能镜像，用于普通功能 lane。

​

可调项

​

可复用 live/E2E workflow

​

发布路径分块

• 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

​

插件预发布

​

QA Lab

• QA-Lab - All Lanes 工作流每晚在 main 上运行，也可手动分发；它会将 mock parity 通道、live Matrix 通道，以及 live Telegram 和 Discord 通道作为并行作业扇出。Live 作业使用 qa-live-shared 环境，Telegram/Discord 使用 Convex leases。

​

CodeQL

​

安全类别

​

平台特定安全分片

• CodeQL Android Critical Security — 定时 Android 安全分片。在工作流完整性检查接受的最小 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；
• 公共插件 SDK 或插件契约更改会扩展到插件类型检查，因为插件依赖这些核心契约（Vitest 插件扫描仍然是显式测试工作）；
• 仅发布元数据的版本升级会运行定向版本/配置/根依赖检查；
• 未知的根目录/配置更改会 fail safe 到所有检查通道。

​

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>

​

相关

• 安装概览
• 开发频道