CI 流水线

​

流水线概览

​

先失败顺序

1. preflight 决定哪些通道根本存在。docs-scope 和 changed-scope 逻辑是这个作业中的步骤，而不是独立作业。
2. security-fast、check-*、check-additional-*、check-docs 和 skills-python 会快速失败，而不会等待更重的产物和平台矩阵作业。
3. build-artifacts 会与快速 Linux 通道重叠运行，因此下游消费者可以在共享构建准备好后尽快开始。
4. 然后更重的平台和运行时通道会展开：checks-fast-core、checks-fast-contracts-plugins-*、checks-fast-contracts-channels-*、checks-node-core-*、checks-windows、macos-node、macos-swift 和 android。

​

Real behavior proof

• Behavior or issue addressed
• Real environment tested
• Exact steps or command run after this patch
• Evidence after fix
• Observed result after fix
• What was not tested

​

范围与路由

• CI workflow edits validate the Node CI graph plus workflow linting, but do not force Windows, Android, or macOS native builds by themselves; those platform lanes stay scoped to platform source changes.
• Workflow Sanity runs actionlint, zizmor over all workflow YAML files, the composite-action interpolation guard, and the conflict-marker guard. The PR-scoped security-fast job also runs zizmor over changed workflow files so workflow security findings fail early in the main CI graph.
• Docs on main pushes are checked by the standalone Docs workflow with the same ClawHub docs mirror used by CI, so mixed code+docs pushes do not also queue the CI check-docs shard. Pull requests and manual CI still run check-docs from CI when docs changed.
• TUI PTY is a focused workflow for TUI changes. It runs node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts on Linux Node 24 for src/tui/**, the watch harness, package script, lockfile, and workflow edits. The required lane uses a deterministic TuiBackend fixture; the slower tui --local smoke is opt-in with OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 and mocks only the external model endpoint.
• CI routing-only edits, selected cheap core-test fixture edits, and narrow plugin contract helper/test-routing edits use a fast Node-only manifest path: preflight, security, and a single checks-fast-core task. That path skips build artifacts, Node 22 compatibility, channel contracts, full core shards, bundled-plugin shards, and additional guard matrices when the change is limited to the routing or helper surfaces the fast task exercises directly.
• Windows Node checks are scoped to Windows-specific process/path wrappers, npm/pnpm/UI runner helpers, package manager config, and the CI workflow surfaces that execute that lane; unrelated source, plugin, install-smoke, and test-only changes stay on the Linux Node lanes.

​

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.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                            # 检查 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
node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts
pnpm test                                     # vitest 测试
pnpm test:changed                             # 低成本的智能变更 Vitest 目标
pnpm test:channels
pnpm test:contracts:channels
pnpm check:docs                               # 文档格式 + lint + 链接失效检查
pnpm build                                    # 当 CI 产物/冒烟检查重要时构建 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 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 性能

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：对启动、网关和代理轮次热点进行 CPU/heap/trace 分析。
• live-openai-candidate：一次真实的 OpenAI openai/gpt-5.5 代理轮次，在 OPENAI_API_KEY 不可用时跳过。

​

完整发布验证

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 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 发布版本，例如 [email protected]。用于已发布的预发布/稳定版接受。
• source=ref 打包一个受信任的 package_ref 分支、标签或完整 commit SHA。解析器会获取 OpenClaw 分支/标签，验证所选提交可从仓库分支历史或发布标签到达，在分离的 worktree 中安装依赖，并使用 scripts/package-openclaw-for-docker.mjs 打包。
• source=url 下载一个公共 HTTPS .tgz；package_sha256 为必需项。该路径会拒绝 URL 凭证、非默认 HTTPS 端口、私有/内部/特殊用途主机名或解析出的 IP，以及重定向到同一公共安全策略之外的地址。
• source=trusted-url 从 .github/package-trusted-sources.json 中命名的受信任来源策略下载一个 HTTPS .tgz；package_sha256 和 trusted_source_id 为必需项。仅当维护者拥有的企业镜像或私有包仓库需要配置主机、端口、路径前缀、重定向主机或私有网络解析时才使用此项。如果策略声明了 bearer auth，工作流会使用固定的 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, update-restart-auth, plugins-offline, plugin-update
• product — package plus mcp-channels, cron-mcp-cleanup, openai-web-search-minimal, openwebui
• full — 带有 OpenWebUI 的完整 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 fixture 中清理缺失的 pnpm patchedDependencies，并且可以记录缺失的持久化 update.channel；
• plugin smokes 可以读取旧版 install-record 位置，或接受缺失的 marketplace install-record 持久化；
• plugin-update 可以允许配置元数据迁移，同时仍要求 install record 和 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.PATCH \
  -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

# 从命名的受信任私有镜像策略验证一个 tarball。
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

# 重用由另一次 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'

​

安装 smoke

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

• QA-Lab - All Lanes 工作流在 main 上每晚运行一次，也支持手动派发；它会将 mock parity lane、live Matrix lane 以及 live Telegram 和 Discord lanes 作为并行作业展开。live 作业使用 qa-live-shared 环境，Telegram/Discord 使用 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: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 \
  --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 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 -- \
  "corepack 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 -- "pnpm check:changed"
pnpm crabbox:stop -- <cbx_id-or-slug>

​

相关内容

• 安装概览
• 开发通道