CI 流水线

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/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 图以及工作流 linting，但不会单独强制进行 Windows、Android 或 macOS 原生构建；这些平台流水线仍然仅对平台源代码变更进行范围控制。
• 仅 CI 路由编辑、部分廉价核心测试 fixture 编辑，以及狭窄的插件合约 helper/test-routing 编辑 会使用快速的仅 Node 清单路径：preflight、security，以及单个 checks-fast-core 任务。该路径会跳过构建产物、Node 22 兼容性、channel 合约、完整核心分片、bundled 插件分片，以及额外守卫矩阵，前提是变更仅限于快速任务直接执行的路由或 helper 表面。
• Windows Node 检查 仅针对 Windows 特有的进程/路径包装器、npm/pnpm/UI 运行器 helper、包管理器配置，以及执行该流水线的 CI 工作流表面；无关源码、插件、安装 smoke 和仅测试的变更仍停留在 Linux Node 流水线上。

​

ClawSweeper 活动转发

• clawsweeper_item：用于精确的 issue 和 pull request 审查请求；
• clawsweeper_comment：用于 issue 评论中的显式 ClawSweeper 命令；
• clawsweeper_commit_review：用于 main push 上的提交级审查请求；
• github_activity：用于 ClawSweeper 代理可能检查的一般 GitHub 活动。

​

手动派发

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                            # 检查 origin/main...HEAD 的本地 changed-lane 分类器
pnpm check:changed                            # 智能本地检查门禁：按边界 lane 进行已变更的类型检查/lint/guards
pnpm check                                    # 快速本地门禁：prod tsgo + 分片 lint + 并行快速 guards
pnpm check:test-types
pnpm check:timed                              # 与上面相同的门禁，但包含各阶段耗时
pnpm build:strict-smoke
pnpm check:architecture
pnpm test:gateway:watch-regression
pnpm test                                     # vitest 测试
pnpm test:changed                             # 便宜且智能的 changed Vitest 目标
pnpm test:channels
pnpm test:contracts:channels
pnpm check:docs                               # 文档格式 + lint + 断链检查
pnpm build                                    # 当 CI artifact/build-smoke 车道很重要时构建 dist
pnpm ci:timings                               # 汇总最近一次 origin/main push 的 CI 运行
pnpm ci:timings:recent                        # 比较最近成功的 main CI 运行
node scripts/ci-run-timings.mjs <run-id>      # 汇总总耗时、排队时间和最慢的任务
node scripts/ci-run-timings.mjs --latest-main # 忽略 issue/comment 噪音并选择 origin/main push 的 CI
node scripts/ci-run-timings.mjs --recent 10   # 比较最近成功的 main CI 运行
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 诊断场景，使用确定性的 fake OpenAI 兼容认证。
• mock-deep-profile：对启动、gateway 和 agent-turn 热点进行 CPU/heap/trace 分析。
• 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/核心发布关键 lane。
• stable 会增加稳定的 provider/backend 集合。
• full 运行更广泛的 advisory provider/media 矩阵。

​

Live 和 E2E 分片

• native-live-src-agents
• native-live-src-gateway-core
• 按 provider 过滤的 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
• 拆分的音频/视频媒体分片以及按 provider 过滤的音乐分片

​

包接受

​

作业

1. resolve_package 检出 workflow_ref，解析出一个包候选，写入 .artifacts/docker-e2e-package/openclaw-current.tgz，写入 .artifacts/docker-e2e-package/package-candidate.json，将两者作为 package-under-test 工件上传，并在 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。可复用工作流会下载该工件，在需要时校验 tarball 清单，为 package-digest Docker 镜像做准备，并针对该包而不是打包工作流检出内容运行所选的 Docker lanes。当某个 profile 选择了多个目标 docker_lanes 时，可复用工作流会先准备一次包和共享镜像，然后将这些 lanes 作为带有唯一工件的并行目标 Docker 作业分发出去。
3. package_telegram 可选地调用 NPM Telegram Beta E2E。当 telegram_mode 不是 none 且 Package Acceptance 已解析出一个包时，它会安装同一个 package-under-test 工件；独立的 Telegram 分发仍然可以安装已发布的 npm spec。
4. summary 会在包解析、Docker 接受，或可选的 Telegram lane 失败时使工作流失败。

​

候选来源

• source=npm 只接受 openclaw@beta、openclaw@latest，或像 openclaw@2026.4.27-beta.2 这样的精确 OpenClaw 发布版本。用于已发布的预发布/稳定版接受。
• source=ref 打包受信任的 package_ref 分支、标签或完整提交 SHA。解析器会获取 OpenClaw 的分支/标签，验证所选提交可从仓库分支历史或发布标签访问，在分离的 worktree 中安装依赖，并使用 scripts/package-openclaw-for-docker.mjs 进行打包。
• source=url 下载一个 HTTPS .tgz；此时 package_sha256 是必需的。
• 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、upgrade-survivor、published-upgrade-survivor、plugins-offline、plugin-update
• product — package 外加 mcp-channels、cron-mcp-cleanup、openai-web-search-minimal、openwebui
• full — 含 OpenWebUI 的完整 Docker release-path 分块
• 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 可以允许配置元数据迁移，同时仍然要求安装记录和 no-reinstall 行为保持不变。

​

示例

# 使用产品级覆盖验证当前 beta package。
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

# 使用当前 harness 打包并验证一个 release 分支。
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

# 验证一个 tarball URL。对于 source=url，SHA-256 是必需的。
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

# 复用另一个 Actions 运行上传的 tarball。
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'

​

Install smoke

• Fast path 适用于触及 Docker/package 表面、捆绑插件 package/manifest 变更，或 Docker smoke 作业会执行到的核心插件/channel/gateway/Plugin SDK 表面的拉取请求。仅源代码层面的捆绑插件改动、仅测试改动和仅文档改动不会占用 Docker worker。fast path 会先构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete shared-workspace CLI smoke，运行容器 gateway-network e2e，验证捆绑扩展 build arg，并在 240 秒的聚合命令超时下运行受限的捆绑插件 Docker profile（每个场景的 Docker run 会单独设上限）。
• Full path 为夜间定时运行、手动分发、workflow-call 发布检查，以及真正触及 installer/package/Docker 表面的拉取请求保留 QR package install 和 installer Docker/update 覆盖。在 full 模式下，install-smoke 会准备或复用一个目标 SHA 的 GHCR 根 Dockerfile smoke 镜像，然后将 QR package install、根 Dockerfile/gateway smoke、installer/update smoke 以及 fast bundled-plugin Docker E2E 作为独立作业运行，这样 installer 工作就不必排在根镜像 smoke 后面等待。

​

本地 Docker E2E

• 一个裸的 Node/Git 运行器，用于 installer/update/plugin-dependency 这些 lane；
• 一个功能性镜像，将同一个 tarball 安装到 /app 中，用于普通功能 lane。

​

可调参数

​

可复用的 live/E2E 工作流

​

Release-path 分块

• 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>      # 下载 Docker 工件并打印合并的/按 lane 定向的重跑命令
pnpm test:docker:timings <summary>   # 慢 lane 和阶段关键路径摘要

​

插件预发布

​

QA 实验室

• The QA-Lab - All Lanes workflow runs nightly on main and on manual dispatch; it fans out the mock parity lane, live Matrix lane, and live Telegram and Discord lanes as parallel jobs. Live jobs use the qa-live-shared environment, and Telegram/Discord use Convex leases.

​

CodeQL

​

安全类别

​

平台特定的安全分片

• CodeQL Android Critical Security — 定时 Android 安全分片。它在工作流可接受的最小 Blacksmith Linux runner 上手动构建 Android 应用以供 CodeQL 使用。产物上传到 /codeql-critical-security/android。
• CodeQL macOS Critical Security — 每周/手动 macOS 安全分片。它在 Blacksmith macOS 上手动构建 macOS 应用供 CodeQL 使用，从上传的 SARIF 中过滤掉依赖构建结果，并上传到 /codeql-critical-security/macos。之所以不放在每日默认项中，是因为即使在干净状态下，macOS 构建也会主导运行时间。

​

Critical Quality 类别

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 生产变更运行 core prod 和 core test typecheck，以及 core lint/guards；
• core 仅测试变更只运行 core test typecheck 和 core lint；
• extension 生产变更运行 extension prod 和 extension test typecheck，以及 extension lint；
• extension 仅测试变更只运行 extension test typecheck 和 extension lint；
• public Plugin SDK 或 plugin-contract 变更会扩展到 extension typecheck，因为 extensions 依赖这些 core 合约（Vitest extension 全量扫描仍然属于明确的测试工作）；
• 仅发布元数据版本提升会运行定向的 version/config/root-dependency 检查；
• 未知的 root/config 变更会安全失败为所有检查通道。

​

Testbox 验证

pnpm crabbox:warmup -- --idle-timeout 90m
pnpm crabbox:hydrate -- --id <cbx_id>
pnpm crabbox:run -- --id <cbx_id> --shell "OPENCLAW_TESTBOX=1 pnpm check:changed"
pnpm crabbox:stop -- <cbx_id>

​

相关内容

• 安装概览
• 开发通道