openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-02 06:55:47 +00:00
parent 9a3544b25f
commit 79f3841a26
4 changed files with 444 additions and 426 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

364
docs/zh-CN/ci.md
View File

@ -1,93 +1,93 @@
---
read_when:
- 你需要了解为什么某个 CI 作业运行了或没有运行
- 你需要了解一个 CI 作业为什么运行了或没有运行
- 你正在调试一个失败的 GitHub Actions 检查
- 你正在协调发布验证的运行或重新运行
- 你正在协调一次发布验证运行或重新运行
- 你正在更改 ClawSweeper 调度或 GitHub 活动转发
summary: CI 作业图、范围门禁、发布总括流程和本地命令等价项
summary: CI 作业图、范围门禁、发布总括流程和本地命令等效项
title: CI 流水线
x-i18n:
generated_at: "2026-05-02T06:28:19Z"
generated_at: "2026-05-02T06:53:34Z"
model: gpt-5.5
provider: openai
source_hash: 03258176c6672355abf335bfcb2a962c0ddc62605aaeaba1f60f513d03bce2d4
source_hash: 39af4afcb3e7c847c44a9d47513ac4b99c62d13fb139ece0bee979f24687ea38
source_path: ci.md
workflow: 16
---
OpenClaw CI 会在每次推送到 `main` 以及每个拉取请求时运行。`preflight` 作业会对差异进行分类，并在只有无关区域发生变更时关闭昂贵的执行线。手动 `workflow_dispatch` 运行会有意绕过智能作用域限定，并为候选发布和广泛验证展开完整图。Android 执行线通过 `include_android` 保持选择加入。仅发布使用的插件覆盖率位于单独的 [`Plugin Prerelease`](#plugin-prerelease) 工作流中，并且只会从 [`Full Release Validation`](#full-release-validation) 或显式手动调度运行。
OpenClaw CI 会在每次推送到 `main` 以及每个拉取请求上运行。`preflight` 作业会对差异进行分类，并在只有无关区域发生变化时关闭昂贵的通道。手动 `workflow_dispatch` 运行会有意绕过智能作用域限定，并展开完整图谱，用于发布候选版本和广泛验证。Android 通道仍通过 `include_android` 选择启用。仅发布使用的插件覆盖位于单独的 [`插件预发布`](#plugin-prerelease) 工作流中，并且只会从 [`完整发布验证`](#full-release-validation) 或显式手动分发运行。
## 流水线概览
| 作业 | 目的 | 运行时机 |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | 检测仅文档变更、已变更作用域、已变更插件，并构建 CI 清单 | 始终在非草稿推送和 PR 上运行 |
| `preflight` | 检测仅文档变更、变更作用域、变更插件，并构建 CI 清单 | 始终在非草稿推送和 PR 上运行 |
| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 始终在非草稿推送和 PR 上运行 |
| `security-dependency-audit` | 针对 npm 公告对生产锁文件进行无依赖审计 | 始终在非草稿推送和 PR 上运行 |
| `security-fast` | 快速安全作业所需的聚合检查 | 始终在非草稿推送和 PR 上运行 |
| `check-dependencies` | 生产 Knip 依赖专用检查，以及未使用文件允许列表防护 | Node 相关变更 |
| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查和可复用的下游产物 | Node 相关变更 |
| `checks-fast-core` | 快速 Linux 正确性执行线，例如内置/插件契约/协议检查 | Node 相关变更 |
| `checks-fast-contracts-channels` | 分片渠道契约检查，并提供稳定的聚合检查结果 | Node 相关变更 |
| `checks-node-core-test` | Core Node 测试分片，不包括渠道、内置、契约和插件执行线 | Node 相关变更 |
| `check` | 分片的主要本地门禁等价项：生产类型、lint、防护、测试类型和严格冒烟 | Node 相关变更 |
| `check-additional` | 架构、边界、插件表面防护、包边界和 gateway-watch 分片 | Node 相关变更 |
| `build-smoke` | 已构建 CLI 冒烟测试和启动内存冒烟 | Node 相关变更 |
| `checks` | 构建产物渠道测试的验证器 | Node 相关变更 |
| `checks-node-compat-node22` | Node 22 兼容性构建和冒烟执行线 | 用于发布的手动 CI 调度 |
| `check-docs` | 文档格式、lint 和坏链接检查 | 文档已变更 |
| `security-dependency-audit` | 针对 npm 公告进行不依赖额外依赖项的生产 lockfile 审计 | 始终在非草稿推送和 PR 上运行 |
| `security-fast` | 快速安全作业的必需聚合项 | 始终在非草稿推送和 PR 上运行 |
| `check-dependencies` | 生产 Knip 仅依赖项检查，以及未使用文件允许列表保护 | Node 相关变更 |
| `build-artifacts` | 构建 `dist/`、Control UI、已构建产物检查和可复用下游产物 | Node 相关变更 |
| `checks-fast-core` | 快速 Linux 正确性通道，例如内置/插件契约/协议检查 | Node 相关变更 |
| `checks-fast-contracts-channels` | 分片的渠道契约检查，并提供稳定的聚合检查结果 | Node 相关变更 |
| `checks-node-core-test` | 核心 Node 测试分片，不包括渠道、内置、契约和插件通道 | Node 相关变更 |
| `check` | 分片的主本地门禁等价项：生产类型、lint、保护项、测试类型和严格冒烟测试 | Node 相关变更 |
| `check-additional` | 架构、边界、插件表面保护项、包边界和 gateway-watch 分片 | Node 相关变更 |
| `build-smoke` | 已构建 CLI 冒烟测试和启动内存冒烟测试 | Node 相关变更 |
| `checks` | 已构建产物渠道测试的验证器 | Node 相关变更 |
| `checks-node-compat-node22` | Node 22 兼容性构建和冒烟通道 | 面向发布的手动 CI 分发 |
| `check-docs` | 文档格式化、lint 和断链检查 | 文档已变更 |
| `skills-python` | 针对 Python 支持的 Skills 运行 Ruff + pytest | Python Skill 相关变更 |
| `checks-windows` | Windows 特定的进程/路径测试，以及共享运行时导入说明符回归测试 | Windows 相关变更 |
| `macos-node` | 使用共享构建产物的 macOS TypeScript 测试执行线 | macOS 相关变更 |
| `checks-windows` | Windows 特定进程/路径测试，以及共享运行时导入说明符回归检查 | Windows 相关变更 |
| `macos-node` | 使用共享已构建产物的 macOS TypeScript 测试通道 | macOS 相关变更 |
| `macos-swift` | macOS 应用的 Swift lint、构建和测试 | macOS 相关变更 |
| `android` | 两种 flavor 的 Android 单元测试，以及一个 debug APK 构建 | Android 相关变更 |
| `test-performance-agent` | 可信活动后的每日 Codex 慢测试优化 | 主 CI 成功或手动调度 |
| `android` | 两种 flavor 的 Android 单元测试，以及一次 debug APK 构建 | Android 相关变更 |
| `test-performance-agent` | 受信任活动后的每日 Codex 慢测试优化 | 主 CI 成功或手动分发 |
## 快速失败顺序
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`。
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`。
当同一个 PR 或 `main` ref 上有较新的推送落地时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一 ref 的最新运行也失败，否则将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已被取代后继续排队。自动 CI 并发键带有版本号（`CI-v7-*`），因此 GitHub 侧旧队列组中的僵尸任务无法无限期阻塞较新的 main 运行。手动全套件运行使用 `CI-manual-v1-*`，且不会取消正在进行的运行。
当同一 PR 或 `main` 引用上有更新的推送落地时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一引用的最新运行也在失败，否则将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已被取代后继续排队。自动 CI 并发键带有版本号（`CI-v7-*`），因此 GitHub 端旧队列组中的僵尸任务无法无限期阻塞更新的 main 运行。手动完整套件运行使用 `CI-manual-v1-*`，并且不会取消进行中的运行。
## 作用域和路由
作用域逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。手动调度会跳过变更作用域检测，并让 preflight 清单表现得像每个有作用域的区域都已变更。
作用域逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。手动分发会跳过变更作用域检测，并让 preflight 清单表现得像每个受作用域限定的区域都发生了变更。
- **CI 工作流编辑**会验证 Node CI 图和工作流 lint，但本身不会强制 Windows、Android 或 macOS 原生构建；这些平台执行线仍限定在平台源代码变更范围内。
- **仅 CI 路由编辑、选定的廉价核心测试 fixture 编辑，以及窄范围插件契约辅助/测试路由编辑**使用快速 Node 专用清单路径：`preflight`、安全检查和单个 `checks-fast-core` 任务。当变更仅限于该快速任务直接覆盖的路由或辅助表面时，该路径会跳过构建产物、Node 22 兼容性、渠道契约、完整核心分片、内置插件分片和额外防护矩阵。
- **Windows Node 检查**限定在 Windows 特定的进程/路径包装器、npm/pnpm/UI runner 辅助、包管理器配置，以及执行该执行线的 CI 工作流表面；无关源代码、插件、安装冒烟和仅测试变更会继续留在 Linux Node 执行线上。
- **CI 工作流编辑**会验证 Node CI 图谱以及工作流 lint，但本身不会强制执行 Windows、Android 或 macOS 原生构建；这些平台通道仍限定于平台源代码变更。
- **仅 CI 路由编辑、选定的低成本核心测试 fixture 编辑，以及窄范围插件契约辅助/测试路由编辑**会使用快速的仅 Node 清单路径：`preflight`、安全检查和单个 `checks-fast-core` 任务。当变更仅限于该快速任务直接执行的路由或辅助表面时，该路径会跳过构建产物、Node 22 兼容性、渠道契约、完整核心分片、内置插件分片和额外保护矩阵。
- **Windows Node 检查**限定于 Windows 特定进程/路径包装器、npm/pnpm/UI runner 辅助项、包管理器配置，以及执行该通道的 CI 工作流表面；无关源代码、插件、安装冒烟测试和仅测试变更仍停留在 Linux Node 通道上。
最慢的 Node 测试族会被拆分或均衡，以便每个作业保持较小规模且不会过度预留 runner：渠道契约作为三个加权分片运行，小型核心单元执行线会成对运行，自动回复作为四个均衡 worker 运行（其中 reply 子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片），而 agentic Gateway 网关/插件配置会分散到现有的仅源代码 agentic Node 作业中，而不是等待构建产物。广泛的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件兜底配置。包含模式分片使用 CI 分片名称记录计时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分整个配置和过滤后的分片。`check-additional` 将包边界编译/canary 工作保持在一起，并将运行时拓扑架构与 gateway watch 覆盖分开；边界防护分片会在一个作业内并发运行其小型独立防护。Gateway watch、渠道测试和核心支持边界分片会在 `dist/` 和 `dist-runtime/` 已经构建完成后，在 `build-artifacts` 内并发运行。
最慢的 Node 测试族会被拆分或平衡，使每个作业保持较小规模而不过度预留 runner：渠道契约作为三个加权分片运行，小型核心单元通道成对组合，自动回复作为四个平衡 worker 运行（reply 子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片），agentic gateway/plugin 配置则分布在现有的仅源代码 agentic Node 作业中，而不是等待已构建产物。广泛的浏览器、QA、媒体和杂项插件测试使用其专用 Vitest 配置，而不是共享插件统配项。包含模式分片使用 CI 分片名称记录计时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分完整配置和过滤后的分片。`check-additional` 将包边界编译/canary 工作放在一起，并将运行时拓扑架构与 gateway watch 覆盖分开；边界保护分片会在一个作业内并发运行其小型独立保护项。Gateway 网关 watch、渠道测试和核心支持边界分片会在 `dist/` 和 `dist-runtime/` 已构建后，在 `build-artifacts` 内并发运行。
Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的源集或清单；其单元测试执行线仍会使用 SMS/call-log BuildConfig 标志编译该 flavor，同时避免在每次 Android 相关推送上重复执行 debug APK 打包作业。
Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的源集或 manifest；它的单元测试通道仍会使用 SMS/call-log BuildConfig 标志编译该 flavor，同时避免在每个 Android 相关推送上重复执行 debug APK 打包作业。
`check-dependencies` 分片会运行 `pnpm deadcode:dependencies`（生产 Knip 依赖专用检查，固定到最新 Knip 版本，并在 `dlx` 安装时禁用 pnpm 的最小发布年龄）和 `pnpm deadcode:unused-files`，后者会将 Knip 的生产未使用文件发现结果与 `scripts/deadcode-unused-files.allowlist.mjs` 进行比较。当 PR 新增未审查的未使用文件或留下过期允许列表条目时，未使用文件防护会失败，同时保留 Knip 无法静态解析的有意动态插件、生成文件、构建、实时测试和包桥接表面。
`check-dependencies` 分片会运行 `pnpm deadcode:dependencies`（生产 Knip 仅依赖项检查，固定到最新 Knip 版本，并为 `dlx` 安装禁用 pnpm 的最小发布年龄限制）和 `pnpm deadcode:unused-files`，后者会将 Knip 的生产未使用文件发现结果与 `scripts/deadcode-unused-files.allowlist.mjs` 进行比较。当 PR 添加新的未审查未使用文件，或留下过期允许列表条目时，未使用文件保护项会失败，同时保留 Knip 无法静态解析的有意动态插件、生成内容、构建、实时测试和包桥接表面。
## ClawSweeper 活动转发
`.github/workflows/clawsweeper-dispatch.yml` 是从 OpenClaw 仓库活动到 ClawSweeper 的目标侧桥接。它不会检出或执行不可信的拉取请求代码。该工作流会从 `CLAWSWEEPER_APP_PRIVATE_KEY` 创建 GitHub App 令牌，然后向 `openclaw/clawsweeper` 调度紧凑的 `repository_dispatch` 载荷。
`.github/workflows/clawsweeper-dispatch.yml` 是从 OpenClaw 仓库活动到 ClawSweeper 的目标端桥接。它不会签出或执行不受信任的拉取请求代码。该工作流会从 `CLAWSWEEPER_APP_PRIVATE_KEY` 创建 GitHub App 令牌，然后向 `openclaw/clawsweeper` 分发紧凑的 `repository_dispatch` 载荷。
该工作流有四条执行线：
该工作流有四个通道：
- `clawsweeper_item` 用于精确的问题和拉取请求审查请求；
- `clawsweeper_comment` 用于问题评论中的显式 ClawSweeper 命令；
- `clawsweeper_commit_review` 用于 `main` 推送上的提交级审查请求；
- `github_activity` 用于 ClawSweeper 智能体可能检查的一般 GitHub 活动。
`github_activity` 执行线仅转发规范化元数据：事件类型、动作、参与者、仓库、条目编号、URL、标题、状态，以及存在评论或审查时的短摘录。它有意避免转发完整 webhook 正文。`openclaw/clawsweeper` 中的接收工作流是 `.github/workflows/github-activity.yml`，它会将规范化事件发布到 ClawSweeper 智能体的 OpenClaw Gateway 网关钩子。
`github_activity` 通道只转发规范化元数据：事件类型、操作、actor、仓库、条目编号、URL、标题、状态，以及存在评论或审查时的简短摘录。它有意避免转发完整 webhook 正文。`openclaw/clawsweeper` 中的接收工作流是 `.github/workflows/github-activity.yml`，它会将规范化事件发布到 ClawSweeper 智能体的 OpenClaw Gateway 网关钩子。
一般活动是观察，而不是默认投递。ClawSweeper 智能体会在提示中收到 Discord 目标，并且只有当事件令人意外、可操作、有风险或对运维有用时，才应发布到 `#clawsweeper`。常规打开、编辑、bot churn、重复 webhook 噪声和正常审查流量应产生 `NO_REPLY`。
一般活动是观察，而不是默认投递。ClawSweeper 智能体会在其提示中收到 Discord 目标，并且只有当事件令人意外、可操作、有风险或对运维有用时，才应发布到 `#clawsweeper`。常规打开、编辑、机器人噪声、重复 webhook 噪声和正常审查流量应产生 `NO_REPLY`。
在整个路径中，将 GitHub 标题、评论、正文、审查文本、分支名称和提交消息视为不可信数据。它们是用于摘要和分诊的输入，而不是工作流或智能体运行时的指令。
在整个路径中，将 GitHub 标题、评论、正文、审查文本、分支名称和提交消息视为不受信任的数据。它们是用于总结和分诊的输入，不是工作流或智能体运行时的指令。
## 手动调度
## 手动分发
手动 CI 调度运行与普通 CI 相同的作业图，但会强制开启所有非 Android 作用域执行线：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS 和 Control UI i18n。独立的手动 CI 调度仅在 `include_android=true` 时运行 Android；完整发布总入口通过传递 `include_android=true` 启用 Android。插件预发布静态检查、仅发布使用的 `agentic-plugins` 分片、完整插件批量扫描和插件预发布 Docker 执行线都被排除在 CI 之外。Docker 预发布套件只会在 `Full Release Validation` 使用启用 release-validation 门禁的方式调度单独的 `Plugin Prerelease` 工作流时运行。
手动 CI 分发运行与正常 CI 相同的作业图谱，但会强制开启每个非 Android 作用域通道：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟测试、文档检查、Python Skills、Windows、macOS 和 Control UI i18n。独立手动 CI 分发只有在 `include_android=true` 时才会运行 Android；完整发布总控通过传递 `include_android=true` 启用 Android。插件预发布静态检查、仅发布使用的 `agentic-plugins` 分片、完整插件批量扫描和插件预发布 Docker 通道都排除在 CI 之外。Docker 预发布套件只会在 `完整发布验证` 分发单独的 `插件预发布` 工作流并启用发布验证门禁时运行。
手动运行使用唯一的并发组，因此候选发布全套件不会被同一 ref 上的另一个推送或 PR 运行取消。可选的 `target_ref` 输入允许可信调用者使用所选调度 ref 中的工作流文件，针对分支、标签或完整提交 SHA 运行该图。
手动运行使用唯一并发组，因此发布候选完整套件不会被同一引用上的另一个推送或 PR 运行取消。可选的 `target_ref` 输入允许受信任调用方在使用所选分发引用中的工作流文件时，针对分支、标签或完整提交 SHA 运行该图谱。
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -99,15 +99,15 @@ gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
| 运行器 | 作业 |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`、快速安全作业和聚合项（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速协议/契约/内置检查、分片渠道契约检查、除 lint 以外的 `check` 分片、`check-additional` 分片和聚合项、Node 测试聚合验证器、文档检查、Python Skills、workflow-sanity、labeler、auto-response；install-smoke 预检也使用 GitHub 托管的 Ubuntu，以便 Blacksmith 矩阵可以更早排队 |
| `ubuntu-24.04` | `preflight`、快速安全作业和聚合项（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速协议/合约/内置检查、分片的渠道合约检查、除 lint 外的 `check` 分片、`check-additional` 分片和聚合项、Node 测试聚合验证器、文档检查、Python Skills、workflow-sanity、labeler、auto-response；install-smoke 预检也使用 GitHub 托管的 Ubuntu，因此 Blacksmith 矩阵可以更早排队 |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`、较轻量的插件分片、`checks-fast-core`、`checks-node-compat-node22`、`check-prod-types` 和 `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node 测试分片、内置插件测试分片、`android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`（对 CPU 足够敏感，8 vCPU 的成本高于节省的时间）；install-smoke Docker 构建（32-vCPU 的排队时间成本高于节省的时间） |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`（对 CPU 足够敏感，8 vCPU 节省的成本不及带来的开销）；install-smoke Docker 构建（32-vCPU 排队时间的成本不及节省的时间） |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-node`；fork 回退到 `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-swift`；fork 回退到 `macos-latest` |
## 本地等效命令
## 本地等价命令
```bash
pnpm changed:lanes # inspect the local changed-lane classifier for origin/main...HEAD
@ -135,41 +135,49 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac
## 完整发布验证
`Full Release Validation` 是用于“在发布前运行所有内容”的手动总控工作流。它接受分支、标签或完整提交 SHA，使用该目标分发手动 `CI` 工作流，为仅发布使用的插件/包/静态/Docker 验证分发 `Plugin Prerelease`，并为安装冒烟、包验收、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram 车道分发 `OpenClaw Release Checks`。使用 `rerun_group=all` 和 `release_profile=full` 时，它还会针对来自 release checks 的 `release-package-under-test` 构件运行 `NPM Telegram Beta E2E`。发布后，传入 `npm_telegram_package_spec` 可针对已发布的 npm 包重新运行同一个 Telegram 包车道。
`Full Release Validation` 是用于“在发布前运行所有内容”的手动总括工作流。它接受分支、标签或完整提交 SHA，使用该目标分发手动 `CI` 工作流，分发 `Plugin Prerelease` 以提供仅发布相关的插件/包/静态/Docker 证明，并分发 `OpenClaw Release Checks` 以运行安装冒烟测试、包验收、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab 对等性、Matrix 和 Telegram 通道。在 `rerun_group=all` 且 `release_profile=full` 时，它还会针对 release checks 生成的 `release-package-under-test` 工件运行 `NPM Telegram Beta E2E`。发布后，传入 `npm_telegram_package_spec` 可针对已发布的 npm 包重新运行相同的 Telegram 包通道。
有关阶段矩阵、精确的工作流作业名称、配置档差异、构件以及聚焦重跑句柄，请参阅[完整发布验证](/zh-CN/reference/full-release-validation)。
有关阶段矩阵、精确的工作流作业名称、配置差异、工件和定向重新运行句柄，请参阅[完整发布验证](/zh-CN/reference/full-release-validation)。
`OpenClaw Release Publish` 是会修改状态的手动发布工作流。在发布标签存在且 OpenClaw npm 预检成功后，从 `release/YYYY.M.D` 或 `main` 分发它。它会验证 `pnpm plugins:sync:check`，为所有可发布插件包分发 `Plugin NPM Release`，为同一个发布 SHA 分发 `Plugin ClawHub Release`，然后才使用保存的 `preflight_run_id` 分发 `OpenClaw NPM Release`。
`OpenClaw Release Publish` 是会产生变更的手动发布工作流。在发布标签存在且 OpenClaw npm 预检成功后，从 `release/YYYY.M.D` 或 `main` 分发它。它会验证 `pnpm plugins:sync:check`，为所有可发布的插件包分发 `Plugin NPM Release`，为同一个发布 SHA 分发 `Plugin ClawHub Release`，然后才会使用保存的 `preflight_run_id` 分发 `OpenClaw NPM Release`。
若要在快速移动的分支上证明固定提交，请使用辅助命令，而不是 `gh workflow run ... --ref main -f ref=<sha>`：
```bash
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
```
对于快速变化分支上的固定提交证明，请使用辅助命令，而不是 `gh workflow run ... --ref main -f ref=<sha>`：
```bash
pnpm ci:full-release --sha <full-sha>
```
GitHub 工作流分发 ref 必须是分支或标签，不能是原始提交 SHA。该辅助命令会在目标 SHA 处推送一个临时 `release-ci/<sha>-...` 分支，从该固定 ref 分发 `Full Release Validation`，验证每个子工作流的 `headSha` 都与目标匹配，并在运行完成后删除临时分支。如果任何子工作流在不同 SHA 上运行，总控验证器也会失败。
GitHub 工作流分发引用必须是分支或标签，不能是原始提交 SHA。辅助命令会在目标 SHA 上推送一个临时 `release-ci/<sha>-...` 分支，从该固定引用分发 `Full Release Validation`，验证每个子工作流的 `headSha` 都与目标匹配，并在运行完成后删除临时分支。如果任何子工作流在不同 SHA 上运行，总括验证器也会失败。
`release_profile` 控制传入 release checks 的 live/provider 覆盖范围。手动发布工作流默认使用 `stable`；仅在你明确需要广泛的 advisory provider/media 矩阵时才使用 `full`。
`release_profile` 控制传递给 release checks 的 live/提供商覆盖范围。手动发布工作流默认使用 `stable`；只有在你有意运行广泛的咨询性提供商/媒体矩阵时才使用 `full`。
- `minimum` 保留最快的 OpenAI/core 发布关键车道。
- `stable` 添加稳定的 provider/backend 集合。
- `full` 运行广泛的 advisory provider/media 矩阵。
- `minimum` 保留最快的 OpenAI/核心发布关键通道。
- `stable` 添加稳定提供商/后端集合。
- `full` 运行广泛的咨询性提供商/媒体矩阵。
总控会记录已分发的子运行 ID，最终的 `Verify full validation` 作业会重新检查当前子运行结论，并为每个子运行追加最慢作业表。如果某个子工作流被重跑并变绿，只需重跑父级验证器作业即可刷新总控结果和计时摘要。
总括工作流会记录已分发的子运行 ID，最终的 `Verify full validation` 作业会重新检查当前子运行结论，并为每个子运行追加最慢作业表。如果某个子工作流重新运行后变绿，只需重新运行父验证器作业即可刷新总括结果和耗时摘要。
对于恢复，`Full Release Validation` 和 `OpenClaw Release Checks` 都接受 `rerun_group`。发布候选版本使用 `all`，仅普通完整 CI 子项使用 `ci`，仅插件预发布子项使用 `plugin-prerelease`，每个发布子项使用 `release-checks`，或在总控上使用更窄的分组：`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。这样，在聚焦修复后，失败的发布环境重跑会保持有界。
对于恢复，`Full Release Validation` 和 `OpenClaw Release Checks` 都接受 `rerun_group`。发布候选使用 `all`，仅普通完整 CI 子项使用 `ci`，仅插件预发布子项使用 `plugin-prerelease`，每个发布子项使用 `release-checks`，或在总括工作流上使用更窄的组：`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。这可以让失败的发布箱在定向修复后重新运行的范围保持有界。
`OpenClaw Release Checks` 使用受信任的工作流 ref 将所选 ref 一次性解析为 `release-package-under-test` tarball，然后将该构件传递给 live/E2E 发布路径 Docker 工作流和包验收分片。这会让发布环境之间的包字节保持一致，并避免在多个子作业中重新打包同一个候选版本。
`OpenClaw Release Checks` 使用受信任的工作流引用将所选引用解析一次为 `release-package-under-test` tarball，然后将该工件同时传递给 live/E2E 发布路径 Docker 工作流和包验收分片。这可以让发布箱之间的包字节保持一致，并避免在多个子作业中重新打包同一个候选版本。
`ref=main` 和 `rerun_group=all` 的重复 `Full Release Validation` 运行会取代较旧的总控运行。父级监视器会在父级被取消时取消它已经分发的任何子工作流，因此较新的 main 验证不会被滞后的两小时 release-check 运行阻塞。发布分支/标签验证和聚焦重跑分组会保持 `cancel-in-progress: false`。
对于 `ref=main` 且 `rerun_group=all` 的重复 `Full Release Validation` 运行，较新的运行会取代旧的总括运行。当父运行被取消时，父监控器会取消它已分发的任何子工作流，因此较新的 main 验证不会被陈旧的两小时 release-check 运行阻塞。发布分支/标签验证和定向重新运行组保持 `cancel-in-progress: false`。
## Live 和 E2E 分片
发布 live/E2E 子项保留广泛的原生 `pnpm test:live` 覆盖，但它通过 `scripts/test-live-shard.mjs` 以具名分片运行，而不是作为一个串行作业运行：
发布 live/E2E 子项保留广泛的原生 `pnpm test:live` 覆盖，但它通过 `scripts/test-live-shard.mjs` 作为命名分片运行，而不是作为一个串行作业运行：
- `native-live-src-agents`
- `native-live-src-gateway-core`
- provider-filtered `native-live-src-gateway-profiles` 作业
- 提供商过滤的 `native-live-src-gateway-profiles` 作业
- `native-live-src-gateway-backends`
- `native-live-test`
- `native-live-extensions-a-k`
@ -177,35 +185,35 @@ GitHub 工作流分发 ref 必须是分支或标签，不能是原始提交 SHA
- `native-live-extensions-openai`
- `native-live-extensions-o-z-other`
- `native-live-extensions-xai`
- 拆分后的媒体音频/视频分片，以及按 provider 过滤的音乐分片
- 拆分的媒体音频/视频分片和提供商过滤的音乐分片
这会保持相同的文件覆盖，同时让较慢的 live provider 失败更容易重跑和诊断。聚合 `native-live-extensions-o-z`、`native-live-extensions-media` 和 `native-live-extensions-media-music` 分片名称仍可用于手动一次性重跑。
这会保持相同的文件覆盖范围，同时让缓慢的 live 提供商故障更容易重新运行和诊断。聚合的 `native-live-extensions-o-z`、`native-live-extensions-media` 和 `native-live-extensions-media-music` 分片名称对于手动一次性重新运行仍然有效。
原生 live 媒体分片在 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中运行，该镜像由 `Live Media Runner Image` 工作流构建。该镜像预安装了 `ffmpeg` 和 `ffprobe`；媒体作业只会在设置前验证这些二进制文件。将 Docker 支持的 live 套件保持在普通 Blacksmith 运行器上，容器作业不是启动嵌套 Docker 测试的合适位置。
原生 live 媒体分片在 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中运行，该镜像由 `Live Media Runner Image` 工作流构建。该镜像预安装了 `ffmpeg` 和 `ffprobe`；媒体作业只会在设置前验证这些二进制文件。请将基于 Docker 的 live 套件保留在普通 Blacksmith 运行器上，容器作业并不适合启动嵌套 Docker 测试。
Docker 支持的实时模型/后端分片会为每个选定提交使用单独的共享 `ghcr.io/openclaw/openclaw-live-test:<sha>` 镜像。实时发布 workflow 只构建并推送该镜像一次，随后 Docker 实时模型、按提供商分片的 Gateway 网关、CLI 后端、ACP 绑定和 Codex harness 分片都会以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。Gateway 网关 Docker 分片在 workflow 作业超时之前带有明确的脚本级 `timeout` 上限，这样卡住的容器或清理路径会快速失败，而不是耗尽整个发布检查预算。如果这些分片各自独立重建完整源码 Docker 目标，则表示发布运行配置错误，并且会在重复镜像构建上浪费实际时间。
Docker 支持的实时模型/后端分片会为每个选定提交使用一个单独的共享 `ghcr.io/openclaw/openclaw-live-test:<sha>` 镜像。实时发布工作流会构建并推送该镜像一次，然后 Docker 实时模型、按提供商分片的 Gateway 网关、CLI 后端、ACP 绑定以及 Codex harness 分片会带着 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。Gateway 网关 Docker 分片在脚本级别带有显式 `timeout` 上限，低于工作流作业超时时间，因此卡住的容器或清理路径会快速失败，而不是耗尽整个发布检查预算。如果这些分片独立重建完整源码 Docker 目标，则说明发布运行配置错误，并会在重复镜像构建上浪费实际耗时。
## 包验收
当问题是“这个可安装的 OpenClaw 包是否能作为产品正常工作？”时，使用 `Package Acceptance`。它不同于普通 CI：普通 CI 验证源码树，而包验收会通过用户在安装或更新后实际使用的同一个 Docker E2E harness 验证单个 tarball。
当问题是“这个可安装的 OpenClaw 包是否能作为产品正常工作？”时，使用 `Package Acceptance`。它不同于普通 CI：普通 CI 验证源码树，而包验收会通过用户在安装或更新后实际使用的同一个 Docker E2E harness 来验证单个 tarball。
### 作业
1. `resolve_package` 会检出 `workflow_ref`，解析一个候选包，写入 `.artifacts/docker-e2e-package/openclaw-current.tgz`，写入 `.artifacts/docker-e2e-package/package-candidate.json`，将两者作为 `package-under-test` artifact 上传，并在 GitHub 步骤摘要中打印来源、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`。可复用 workflow 会下载该 artifact，验证 tarball 清单，在需要时准备 package-digest Docker 镜像，并针对该包运行选定的 Docker lane，而不是打包 workflow checkout。当某个 profile 选择多个目标 `docker_lanes` 时，可复用 workflow 会准备一次包和共享镜像，然后将这些 lane 扇出为并行的目标 Docker 作业，并使用唯一 artifact。
3. `package_telegram` 可选调用 `NPM Telegram Beta E2E`。当 `telegram_mode` 不是 `none` 时它会运行，并在包验收解析出包时安装同一个 `package-under-test` artifact；独立 Telegram dispatch 仍然可以安装已发布的 npm spec。
4. `summary` 会在包解析、Docker 验收或可选 Telegram lane 失败时使 workflow 失败。
1. `resolve_package` 会检出 `workflow_ref`，解析一个候选包，写入 `.artifacts/docker-e2e-package/openclaw-current.tgz`，写入 `.artifacts/docker-e2e-package/package-candidate.json`，将两者作为 `package-under-test` artifact 上传，并在 GitHub 步骤摘要中打印来源、工作流 ref、包 ref、版本、SHA-256 和配置文件。
2. `docker_acceptance` 会用 `ref=workflow_ref` 和 `package_artifact_name=package-under-test` 调用 `openclaw-live-and-e2e-checks-reusable.yml`。可复用工作流会下载该 artifact，验证 tarball 清单，在需要时准备 package-digest Docker 镜像，并针对该包运行选定的 Docker lane，而不是打包工作流检出内容。当某个配置文件选择多个定向 `docker_lanes` 时，可复用工作流会准备包和共享镜像一次，然后将这些 lane 扇出为并行的定向 Docker 作业，并使用唯一 artifact。
3. `package_telegram` 可选调用 `NPM Telegram Beta E2E`。它会在 `telegram_mode` 不是 `none` 时运行，并在包验收解析出包时安装同一个 `package-under-test` artifact；独立的 Telegram dispatch 仍可安装已发布的 npm spec。
4. `summary` 会在包解析、Docker 验收或可选 Telegram lane 失败时使工作流失败。
### 候选来源
- `source=npm` 只接受 `openclaw@beta`、`openclaw@latest`，或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。将它用于已发布 beta/stable 的验收。
- `source=ref` 会打包受信任的 `package_ref` 分支、标签或完整提交 SHA。解析器会获取 OpenClaw 分支/标签，验证所选提交可从仓库分支历史或发布标签到达，在 detached worktree 中安装依赖，并使用 `scripts/package-openclaw-for-docker.mjs` 打包。
- `source=url` 会下载 HTTPS `.tgz`；必须提供 `package_sha256`。
- `source=artifact` 会从 `artifact_run_id` 和 `artifact_name` 下载一个 `.tgz`；`package_sha256` 可选，但应为外部共享的 artifact 提供。
- `source=npm` 只接受 `openclaw@beta`、`openclaw@latest`，或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。将它用于已发布 beta/稳定版验收。
- `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` 是可选的，但对于外部共享的 artifact 应提供。
保持 `workflow_ref` 和 `package_ref` 分离。`workflow_ref` 是运行测试的受信任 workflow/harness 代码。`package_ref` 是在 `source=ref` 时被打包的源提交。这样当前测试 harness 可以验证较旧的受信任源提交，而不运行旧的 workflow 逻辑。
保持 `workflow_ref` 和 `package_ref` 分离。`workflow_ref` 是运行测试的受信任工作流/harness 代码。`package_ref` 是 `source=ref` 时会被打包的源提交。这样当前测试 harness 就能验证较旧的受信任源码提交，而无需运行旧的工作流逻辑。
### 套件 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`
@ -213,28 +221,28 @@ Docker 支持的实时模型/后端分片会为每个选定提交使用单独的
- `full` — 带 OpenWebUI 的完整 Docker 发布路径分块
- `custom` — 精确的 `docker_lanes`；当 `suite_profile=custom` 时必需
`package` profile 使用离线插件覆盖，因此已发布包验证不会被实时 ClawHub 可用性阻塞。可选 Telegram lane 会在 `NPM Telegram Beta E2E` 中复用 `package-under-test` artifact，同时为独立 dispatch 保留已发布 npm spec 路径。
`package` 配置文件使用离线插件覆盖范围，因此已发布包验证不会被实时 ClawHub 可用性阻塞。可选 Telegram lane 会在 `NPM Telegram Beta E2E` 中复用 `package-under-test` artifact，并为独立 dispatch 保留已发布 npm spec 路径。
有关专用更新和插件测试策略，包括本地命令、Docker lane、包验收输入、发布默认值和失败分诊，请参阅[更新和插件测试](/zh-CN/help/testing-updates-plugins)。
有关专门的更新和插件测试策略，包括本地命令、Docker lane、包验收输入、发布默认值和失败分诊，请参阅[更新和插件测试](/zh-CN/help/testing-updates-plugins)。
发布检查会使用 `source=artifact`、准备好的发布包 artifact、`suite_profile=custom`、`docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`、`published_upgrade_survivor_baselines=release-history`、`published_upgrade_survivor_scenarios=reported-issues` 和 `telegram_mode=mock-openai` 调用包验收。这样可以让包迁移、更新、陈旧插件依赖清理、离线插件、插件更新和 Telegram 证明使用同一个已解析的包 tarball。跨 OS 发布检查仍然覆盖特定于 OS 的新手引导、安装器和平台行为；包/更新产品验证应从包验收开始。`published-upgrade-survivor` Docker lane 每次运行验证一个已发布包基线。在包验收中，解析出的 `package-under-test` tarball 始终是候选包，`published_upgrade_survivor_baseline` 选择回退的已发布基线，默认是 `openclaw@latest`；失败 lane 的重新运行命令会保留该基线。设置 `published_upgrade_survivor_baselines=release-history` 可将该 lane 扩展为去重历史矩阵：最新六个 stable 版本、`2026.4.23`，以及 `2026-03-15` 之前的最新 stable 版本。设置 `published_upgrade_survivor_scenarios=reported-issues` 可将同一批基线扩展到按 issue 形态构建的夹具，覆盖 Feishu 配置、保留的 bootstrap/persona 文件、波浪号日志路径，以及陈旧旧版插件依赖根。单独的 `Update Migration` workflow 在问题是穷尽式已发布更新清理，而不是普通完整发布 CI 广度时，会使用 `update-migration` Docker lane，并带上 `all-since-2026.4.23` 和 `plugin-deps-cleanup`。本地聚合运行可以通过 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` 传入精确包 spec，使用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` 保持单个 lane，例如 `openclaw@2026.4.15`，或者设置 `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` 以启用场景矩阵。已发布 lane 会使用内置的 `openclaw config set` 命令配方配置基线，在 `summary.json` 中记录配方步骤，并在 Gateway 网关启动后探测 `/healthz`、`/readyz` 以及 RPC Status。Windows 打包和安装器全新安装 lane 还会验证已安装的包可以从原始绝对 Windows 路径导入 browser-control 覆盖项。OpenAI 跨 OS Agent-turn smoke 在设置时默认使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.5`，因此安装和 Gateway 网关证明会保持在首选 GPT-5 测试模型上。
发布检查会调用包验收，并使用 `source=artifact`、准备好的发布包 artifact、`suite_profile=custom`、`docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`、`published_upgrade_survivor_baselines=release-history`、`published_upgrade_survivor_scenarios=reported-issues` 和 `telegram_mode=mock-openai`。这会让包迁移、更新、过期插件依赖清理、离线插件、插件更新和 Telegram 证明都基于同一个已解析包 tarball。跨 OS 发布检查仍覆盖 OS 特定的新手引导、安装器和平台行为；包/更新产品验证应从包验收开始。`published-upgrade-survivor` Docker lane 每次运行会验证一个已发布包基线。在包验收中，已解析的 `package-under-test` tarball 始终是候选包，而 `published_upgrade_survivor_baseline` 会选择回退的已发布基线，默认为 `openclaw@latest`；失败 lane 的重跑命令会保留该基线。设置 `published_upgrade_survivor_baselines=release-history` 可将该 lane 扩展为去重后的历史矩阵：最新六个稳定版本、`2026.4.23`，以及 `2026-03-15` 之前的最新稳定版本。设置 `published_upgrade_survivor_scenarios=reported-issues` 可将同一组基线扩展到按 issue 形状构造的 fixture，覆盖 Feishu 配置、保留的 bootstrap/persona 文件、波浪号日志路径，以及过期旧版插件依赖根目录。单独的 `Update Migration` 工作流会在问题是完整的已发布更新清理，而不是普通完整发布 CI 覆盖范围时，使用带 `all-since-2026.4.23` 和 `plugin-deps-cleanup` 的 `update-migration` Docker lane。本地聚合运行可以通过 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` 传入精确包 spec，也可以用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` 保持单个 lane，例如 `openclaw@2026.4.15`，或设置 `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` 来启用场景矩阵。已发布 lane 会用烘焙好的 `openclaw config set` 命令配方配置基线，在 `summary.json` 中记录配方步骤，并在 Gateway 网关启动后探测 `/healthz`、`/readyz` 以及 RPC 状态。Windows 打包和安装器全新 lane 还会验证已安装包可以从原始绝对 Windows 路径导入 browser-control override。OpenAI 跨 OS 智能体回合冒烟测试在设置时默认使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.5`，因此安装和 Gateway 网关证明会留在首选的 GPT-5 测试模型上。
### 旧版兼容窗口
包验收对已发布包有有界的旧版兼容窗口。到 `2026.4.25` 为止的包（包括 `2026.4.25-beta.*`）可以使用兼容路径：
包验收为已经发布的包提供有界旧版兼容窗口。直到 `2026.4.25` 的包，包括 `2026.4.25-beta.*`，可以使用兼容路径：
- `dist/postinstall-inventory.json` 中已知的私有 QA 条目可以指向 tarball 省略的文件；
- 当包未暴露 `gateway install --wrapper` 标志时，`doctor-switch` 可以跳过该持久化子用例；
- `update-channel-switch` 可以从 tarball 派生的假 git 夹具中裁剪缺失的 `pnpm.patchedDependencies`，并可以记录缺失的持久化 `update.channel`；
- 插件 smoke 可以读取旧版安装记录位置，或接受缺失的 marketplace 安装记录持久化；
- `plugin-update` 可以允许配置元数据迁移，同时仍要求安装记录和不重新安装行为保持不变。
- 当包未暴露 `gateway install --wrapper` 标志时，`doctor-switch` 可以跳过 `gateway install --wrapper` 持久化子用例；
- `update-channel-switch` 可以从 tarball 派生的假 git fixture 中修剪缺失的 `pnpm.patchedDependencies`，并可以记录缺失的持久化 `update.channel`；
- 插件冒烟测试可以读取旧版安装记录位置，或接受缺失的 marketplace 安装记录持久化；
- `plugin-update` 可以允许配置元数据迁移，同时仍要求安装记录和不重装行为保持不变。
已发布的 `2026.4.26` 包也可能对已经发布的本地构建元数据戳文件发出警告。后续包必须满足现代契约；相同条件会失败，而不是警告或跳过。
已发布的 `2026.4.26` 包也可能因已经发布的本地构建元数据戳文件而警告。之后的包必须满足现代契约；相同条件会失败，而不是警告或跳过。
### 示例
```bash
# 使用产品级覆盖验证当前 beta 包。
# Validate the current beta package with product-level coverage.
gh workflow run package-acceptance.yml \
--ref main \
-f workflow_ref=main \
@ -243,7 +251,7 @@ gh workflow run package-acceptance.yml \
-f suite_profile=product \
-f telegram_mode=mock-openai
# 使用当前 harness 打包并验证发布分支。
# Pack and validate a release branch with the current harness.
gh workflow run package-acceptance.yml \
--ref main \
-f workflow_ref=main \
@ -252,7 +260,7 @@ gh workflow run package-acceptance.yml \
-f suite_profile=package \
-f telegram_mode=mock-openai
# 验证 tarball URL。source=url 必须提供 SHA-256。
# Validate a tarball URL. SHA-256 is mandatory for source=url.
gh workflow run package-acceptance.yml \
--ref main \
-f workflow_ref=main \
@ -261,7 +269,7 @@ gh workflow run package-acceptance.yml \
-f package_sha256=<64-char-sha256> \
-f suite_profile=smoke
# 复用另一个 Actions 运行上传的 tarball。
# Reuse a tarball uploaded by another Actions run.
gh workflow run package-acceptance.yml \
--ref main \
-f workflow_ref=main \
@ -272,111 +280,111 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
调试失败的包验收运行时，先查看 `resolve_package` 摘要，确认包来源、版本和 SHA-256。然后检查 `docker_acceptance` 子运行及其 Docker artifact：`.artifacts/docker-tests/**/summary.json`、`failures.json`、lane 日志、阶段耗时和重新运行命令。优先重新运行失败的包 profile 或精确 Docker lane，而不是重新运行完整发布验证。
调试失败的包验收运行时，先查看 `resolve_package` 摘要，以确认包来源、版本和 SHA-256。然后检查 `docker_acceptance` 子运行及其 Docker artifact：`.artifacts/docker-tests/**/summary.json`、`failures.json`、lane 日志、阶段耗时和重跑命令。优先重跑失败的包配置文件或精确 Docker lane，而不是重跑完整发布验证。
## 安装 smoke
## 安装冒烟测试
单独的 `Install Smoke` workflow 会通过自己的 `preflight` 作业复用同一个 scope 脚本。它将 smoke 覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。
单独的 `Install Smoke` 工作流通过自己的 `preflight` 作业复用同一个作用域脚本。它将冒烟覆盖范围拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。
- **快速路径**会在 pull request 触及 Docker/包表面、内置插件包/manifest 变更，或 Docker smoke 作业会执行的核心插件/渠道/Gateway 网关/插件 SDK 表面时运行。仅源码的内置插件变更、仅测试编辑和仅文档编辑不会预留 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete shared-workspace CLI smoke，运行容器 gateway-network e2e，验证内置扩展构建参数，并在 240 秒聚合命令超时内运行有界的内置插件 Docker profile（每个场景的 Docker 运行单独设置上限）。
- **完整路径**会为夜间计划运行、手动 dispatch、workflow-call 发布检查，以及真正触及安装器/包/Docker 表面的 pull request 保留 QR 包安装和安装器 Docker/更新覆盖。在完整模式下，install-smoke 会准备或复用一个目标 SHA GHCR 根 Dockerfile smoke 镜像，然后将 QR 包安装、根 Dockerfile/Gateway 网关 smoke、安装器/更新 smoke，以及快速内置插件 Docker E2E 作为单独作业运行，使安装器工作不会被根镜像 smoke 阻塞。
- **快速路径** 会在 pull request 触及 Docker/包表面、内置插件包/manifest 变更，或 Docker 冒烟作业会执行的核心插件/渠道/Gateway 网关/插件 SDK 表面时运行。仅源码的内置插件变更、仅测试编辑和仅文档编辑不会预留 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete 共享工作区 CLI 冒烟测试，运行容器 gateway-network e2e，验证内置 extension 构建参数，并在 240 秒聚合命令超时下运行有界内置插件 Docker 配置文件（每个场景的 Docker 运行会分别设置上限）。
- **完整路径** 会为每晚定时运行、手动 dispatch、workflow-call 发布检查，以及真正触及安装器/包/Docker 表面的 pull request 保留 QR 包安装和安装器 Docker/更新覆盖。在完整模式下，install-smoke 会准备或复用一个目标 SHA GHCR 根 Dockerfile 冒烟镜像，然后将 QR 包安装、根 Dockerfile/Gateway 网关冒烟测试、安装器/更新冒烟测试，以及快速内置插件 Docker E2E 作为单独作业运行，使安装器工作不必等待根镜像冒烟测试。
`main` push（包括 merge commit）不会强制完整路径；当变更范围逻辑会在 push 上请求完整覆盖时，workflow 会保留快速 Docker smoke，并将完整安装 smoke 留给夜间或发布验证。
`main` 推送（包括合并提交）不会强制完整路径；当变更作用域逻辑会在推送时请求完整覆盖时，工作流会保留快速 Docker 冒烟测试，并将完整安装冒烟测试留给每晚或发布验证。
较慢的 Bun 全局安装 image-provider smoke 由 `run_bun_global_install_smoke` 单独控制。它会在夜间计划和发布检查 workflow 中运行，手动 `Install Smoke` dispatch 可以选择启用它，但 pull request 和 `main` push 不会运行。QR 和安装器 Docker 测试会保留各自面向安装的 Dockerfile。
较慢的 Bun 全局安装 image-provider 冒烟测试由 `run_bun_global_install_smoke` 单独控制。它会在每晚计划任务和发布检查工作流中运行，手动 `Install Smoke` dispatch 可以选择加入它，但 pull request 和 `main` 推送不会。QR 和安装器 Docker 测试保留各自面向安装的 Dockerfile。
## 本地 Docker E2E
`pnpm test:docker:all` 会预构建一个共享 live-test 镜像，将 OpenClaw 打包一次为 npm tarball，并构建两个共享的 `scripts/e2e/Dockerfile` 镜像：
`pnpm test:docker:all` 会预构建一个共享 live-test 镜像，将 OpenClaw 打包一次为 npm tarball，并构建两个共享 `scripts/e2e/Dockerfile` 镜像：
- 用于安装器/更新/插件依赖 lane 的裸 Node/Git runner；
- 一个将同一 tarball 安装到 `/app` 的功能镜像，用于普通功能 lane。
- 将同一个 tarball 安装到 `/app` 中、用于正常功能 lane 的功能镜像。
Docker 通道定义位于 `scripts/lib/docker-e2e-scenarios.mjs`，规划器逻辑位于 `scripts/lib/docker-e2e-plan.mjs`，运行器只执行选定的计划。调度器会按通道通过 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 选择镜像，然后用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行通道。
Docker 执行线定义位于 `scripts/lib/docker-e2e-scenarios.mjs`，规划器逻辑位于 `scripts/lib/docker-e2e-plan.mjs`，运行器只执行选定的计划。调度器会使用 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 按执行线选择镜像，然后使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行执行线。
### 可调参数
| 变量 | 默认值 | 用途 |
| -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | 普通通道的主池槽位数量。 |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | 对提供商敏感的尾部池槽位数量。 |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | 并发实时通道上限，避免提供商限流。 |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | 并发 npm 安装通道上限。 |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | 并发多服务通道上限。 |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | 通道启动之间的错峰时间，用于避免 Docker 守护进程创建风暴；设为 `0` 表示不做错峰。 |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | 每个通道的兜底超时（120 分钟）；选定的实时/尾部通道使用更严格的上限。 |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` 会打印调度器计划而不运行通道。 |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | 逗号分隔的精确通道列表；会跳过清理冒烟测试，以便智能体复现某个失败通道。 |
| 变量 | 默认值 | 用途 |
| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | 普通执行线的主池槽位数量。 |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | 对提供商敏感的尾部池槽位数量。 |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | 并发实时执行线数量上限，避免提供商限流。 |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | 并发 npm 安装执行线数量上限。 |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | 并发多服务执行线数量上限。 |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | 执行线启动之间的错峰时间，用于避免 Docker daemon 创建风暴；设为 `0` 表示不做错峰。 |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | 每条执行线的回退超时时间（120 分钟）；选定的实时/尾部执行线使用更严格的上限。 |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` 会打印调度器计划而不运行执行线。 |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | 逗号分隔的精确执行线列表；会跳过清理冒烟测试，让智能体可以复现某一条失败执行线。 |
重于其有效上限的通道仍可从空池启动，然后独占运行，直到释放容量。此本地聚合流程会预检 Docker，移除陈旧的 OpenClaw E2E 容器，输出活动通道状态，持久化通道耗时以便按最长优先排序，并且默认在首次失败后停止调度新的池化通道。
比其有效上限更重的执行线仍可从空池启动，然后会独占运行，直到释放容量。该本地聚合流程会预检 Docker、移除陈旧的 OpenClaw E2E 容器、输出活跃执行线状态、持久化执行线耗时用于最长优先排序，并且默认在第一次失败后停止调度新的池化执行线。
### 可复用的实时/E2E 工作流
### 可复用实时/E2E 工作流
可复用的实时/E2E 工作流会询问 `scripts/test-docker-all.mjs --plan-json` 需要哪个包、镜像类型、实时镜像、通道和凭证覆盖范围。随后 `scripts/docker-e2e.mjs` 会将该计划转换为 GitHub 输出和摘要。它会通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw，或下载当前运行的包构件，或从 `package_artifact_run_id` 下载包构件；校验 tarball 清单；当计划需要已安装包的通道时，通过 Blacksmith 的 Docker 层缓存构建并推送以包摘要标记的 bare/functional GHCR Docker E2E 镜像；并在提供了 `docker_e2e_bare_image`/`docker_e2e_functional_image` 输入或已有包摘要镜像时复用它们，而不是重新构建。Docker 镜像拉取会在每次尝试设置有界的 180 秒超时后重试，因此卡住的 registry/cache 流会快速重试，而不是消耗 CI 关键路径的大部分时间。
可复用实时/E2E 工作流会询问 `scripts/test-docker-all.mjs --plan-json` 需要哪个包、镜像种类、实时镜像、执行线和凭证覆盖范围。随后 `scripts/docker-e2e.mjs` 会将该计划转换为 GitHub 输出和摘要。它会通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw、下载当前运行的包构件，或从 `package_artifact_run_id` 下载包构件；校验 tarball 清单；当计划需要已安装包的执行线时，通过 Blacksmith 的 Docker 层缓存构建并推送带包摘要标签的裸/功能型 GHCR Docker E2E 镜像；并且会复用提供的 `docker_e2e_bare_image`/`docker_e2e_functional_image` 输入或现有包摘要镜像，而不是重新构建。Docker 镜像拉取会使用有界的每次尝试 180 秒超时进行重试，这样卡住的注册表/缓存流会快速重试，而不是消耗 CI 关键路径的大部分时间。
### 发布路径分片
### 发布路径分块
发布 Docker 覆盖会用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行较小的分片作业，因此每个分片只拉取所需的镜像类型，并通过同一个加权调度器执行多个通道：
发布 Docker 覆盖范围会使用较小的分块作业，并设置 `OPENCLAW_SKIP_DOCKER_BUILD=1`，这样每个分块只拉取自己需要的镜像种类，并通过同一个加权调度器执行多条执行线：
- `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`
当前发布 Docker 分片包括 `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`，以及从 `plugins-runtime-install-a` 到 `plugins-runtime-install-h`。`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍是聚合插件/运行时别名。`install-e2e` 通道别名仍是两个提供商安装器通道的聚合手动重跑别名。
当前发布 Docker 分块包括 `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`，以及从 `plugins-runtime-install-a` 到 `plugins-runtime-install-h`。`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍然是聚合插件/运行时别名。`install-e2e` 执行线别名仍然是两个提供商安装器执行线的聚合手动重跑别名。
当完整发布路径覆盖请求它时，OpenWebUI 会并入 `plugins-runtime-services`，并且仅在只调度 OpenWebUI 时保留独立的 `openwebui` 分片。内置渠道更新通道会针对临时 npm 网络故障重试一次。
当完整发布路径覆盖范围请求 OpenWebUI 时，OpenWebUI 会并入 `plugins-runtime-services`，并且仅为仅 OpenWebUI 的调度保留独立的 `openwebui` 分块。内置渠道更新执行线会针对瞬时 npm 网络故障重试一次。
每个分片都会上传 `.artifacts/docker-tests/`，其中包含通道日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON、慢通道表，以及每个通道的重跑命令。工作流的 `docker_lanes` 输入会针对准备好的镜像运行选定通道，而不是运行分片作业，这会将失败通道调试限制在一个定向 Docker 作业内，并为该运行准备、下载或复用包构件；如果选定通道是实时 Docker 通道，定向作业会为该重跑在本地构建实时测试镜像。生成的每通道 GitHub 重跑命令会在这些值存在时包含 `package_artifact_run_id`、`package_artifact_name` 和已准备镜像输入，因此失败通道可以复用失败运行中的精确包和镜像。
每个分块都会上传 `.artifacts/docker-tests/`，其中包含执行线日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON、慢执行线表，以及每条执行线的重跑命令。工作流 `docker_lanes` 输入会针对准备好的镜像运行选定执行线，而不是运行分块作业，这会把失败执行线调试限制在一个目标 Docker 作业内，并为该次运行准备、下载或复用包构件；如果选定执行线是实时 Docker 执行线，目标作业会在本地为该次重跑构建实时测试镜像。生成的每条执行线 GitHub 重跑命令会在这些值存在时包含 `package_artifact_run_id`、`package_artifact_name` 和准备好的镜像输入，因此失败执行线可以复用失败运行中的精确包和镜像。
```bash
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
```
计划的实时/E2E 工作流每天运行完整的发布路径 Docker 套件。
定时实时/E2E 工作流每天运行完整发布路径 Docker 套件。
## 插件预发布
`Plugin Prerelease` 是成本更高的产品/包覆盖，因此它是一个由 `Full Release Validation` 或明确的操作员单独调度的工作流。普通拉取请求、`main` 推送和独立的手动 CI 调度都会关闭该套件。它会在八个扩展 worker 之间平衡内置插件测试；这些扩展分片作业一次最多运行两个插件配置组，每个组使用一个 Vitest worker 和更大的 Node 堆，因此导入负载较高的插件批次不会创建额外的 CI 作业。仅发布的 Docker 预发布路径会以小组批处理定向 Docker 通道，避免为一到三分钟的作业预留数十个 runner。
`Plugin Prerelease` 是更昂贵的产品/包覆盖范围，因此它是由 `Full Release Validation` 或显式操作员调度的独立工作流。普通拉取请求、`main` 推送和独立手动 CI 调度会保持该套件关闭。它会在八个扩展工作器之间均衡内置插件测试；这些扩展分片作业一次最多运行两个插件配置组，每组使用一个 Vitest 工作器和更大的 Node 堆，这样导入繁重的插件批次不会创建额外的 CI 作业。仅发布的 Docker 预发布路径会将目标 Docker 执行线按小组批处理，避免为一到三分钟的作业预留几十个运行器。
## QA 实验室
## QA Lab
QA 实验室在主智能作用域工作流之外有专用 CI 通道。
QA Lab 在主智能范围工作流之外拥有专用 CI 执行线。
- `Parity gate` 工作流会在匹配的 PR 变更和手动调度时运行；它会构建私有 QA 运行时，并比较模拟 GPT-5.5 和 Opus 4.6 的智能体包。
- `QA-Lab - All Lanes` 工作流每晚在 `main` 上运行，也可手动调度；它会将模拟一致性门禁、实时 Matrix 通道，以及实时 Telegram 和 Discord 通道扇出为并行作业。实时作业使用 `qa-live-shared` 环境，Telegram/Discord 使用 Convex 租约。
- `Parity gate` 工作流会在匹配的 PR 变更和手动调度时运行；它会构建私有 QA 运行时，并比较模拟 GPT-5.5 和 Opus 4.6 智能体包。
- `QA-Lab - All Lanes` 工作流每晚在 `main` 上运行，也可手动调度；它会将模拟一致性门禁、实时 Matrix 执行线，以及实时 Telegram 和 Discord 执行线作为并行作业扇出。实时作业使用 `qa-live-shared` 环境，Telegram/Discord 使用 Convex 租约。
发布检查会使用确定性的模拟提供商和模拟限定模型（`mock-openai/gpt-5.5` 和 `mock-openai/gpt-5.5-alt`）运行 Matrix 和 Telegram 实时传输通道，因此渠道契约会与实时模型延迟和常规提供商插件启动隔离。实时传输 Gateway 网关会禁用记忆搜索，因为 QA 一致性会单独覆盖记忆行为；提供商连接性由单独的实时模型、原生提供商和 Docker 提供商套件覆盖。
发布检查会使用确定性模拟提供商和模拟限定模型（`mock-openai/gpt-5.5` 与 `mock-openai/gpt-5.5-alt`）运行 Matrix 和 Telegram 实时传输执行线，因此渠道契约会与实时模型延迟和普通提供商插件启动隔离。实时传输 Gateway 网关会禁用记忆搜索，因为 QA 一致性单独覆盖记忆行为；提供商连接性由独立的实时模型、原生提供商和 Docker 提供商套件覆盖。
Matrix 会在计划和发布门禁中使用 `--profile fast`，并且仅当检出的 CLI 支持时才添加 `--fail-fast`。CLI 默认值和手动工作流输入仍为 `all`；手动 `matrix_profile=all` 调度始终会将完整 Matrix 覆盖分片为 `transport`、`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 作业。
Matrix 会对定时和发布门禁使用 `--profile fast`，仅在检出的 CLI 支持时添加 `--fail-fast`。CLI 默认值和手动工作流输入仍为 `all`；手动 `matrix_profile=all` 调度始终会将完整 Matrix 覆盖范围分片为 `transport`、`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 作业。
`OpenClaw Release Checks` 还会在发布审批前运行发布关键的 QA 实验室通道；其 QA 一致性门禁会将候选包和基线包作为并行通道作业运行，然后把两个构件下载到一个小型报告作业中，用于最终一致性比较。
`OpenClaw Release Checks` 还会在发布批准前运行发布关键的 QA Lab 执行线；其 QA 一致性门禁会将候选包和基线包作为并行执行线作业运行，然后把两个构件下载到一个小型报告作业中，用于最终一致性比较。
不要把 PR 合入路径置于 `Parity gate` 之后，除非变更确实触及 QA 运行时、模型包一致性，或一致性工作流拥有的表面。对于常规渠道、配置、文档或单元测试修复，请将其视为可选信号，并遵循有作用域的 CI/检查证据。
除非变更实际触及 QA 运行时、模型包一致性，或一致性工作流拥有的表面，否则不要把 PR 落地路径放在 `Parity gate` 之后。对于普通渠道、配置、文档或单元测试修复，将它视为可选信号，并遵循范围化 CI/检查证据。
## CodeQL
`CodeQL` 工作流有意作为窄范围的第一轮安全扫描器，而不是完整仓库扫描。每日、手动和非草稿拉取请求保护运行会扫描 Actions 工作流代码，以及风险最高的 JavaScript/TypeScript 表面，并使用过滤到高/严重 `security-severity` 的高置信度安全查询。
`CodeQL` 工作流有意作为狭窄的第一轮安全扫描器，而不是完整仓库扫描。每日、手动和非草稿拉取请求守护运行会扫描 Actions 工作流代码，以及最高风险的 JavaScript/TypeScript 表面，并使用筛选到高/严重 `security-severity` 的高置信度安全查询。
拉取请求保护保持轻量：它只会针对 `.github/actions`、`.github/codeql`、`.github/workflows`、`packages` 或 `src` 下的变更启动，并运行与计划工作流相同的高置信度安全矩阵。Android 和 macOS CodeQL 不包含在 PR 默认项中。
拉取请求守护保持轻量：它只会针对 `.github/actions`、`.github/codeql`、`.github/workflows`、`packages` 或 `src` 下的变更启动，并运行与定时工作流相同的高置信度安全矩阵。Android 和 macOS CodeQL 不进入 PR 默认项。
### 安全类别
| 类别 | 表面 |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | 认证、密钥、沙箱、cron 和 gateway 基线 |
| `/codeql-security-high/channel-runtime-boundary` | 核心渠道实现契约，以及渠道插件运行时、Gateway 网关、插件 SDK、密钥、审计触点 |
| `/codeql-security-high/network-ssrf-boundary` | 核心 SSRF、IP 解析、网络保护、web-fetch，以及插件 SDK SSRF 策略表面 |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP 服务器、进程执行辅助工具、出站投递，以及智能体工具执行门禁 |
| `/codeql-security-high/plugin-trust-boundary` | 插件安装、加载器、manifest、registry、包管理器安装、源码加载，以及插件 SDK 包契约信任表面 |
| 类别 | 表面 |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | 身份验证、密钥、沙箱、cron 和 gateway 基线 |
| `/codeql-security-high/channel-runtime-boundary` | 核心渠道实现契约，以及渠道插件运行时、Gateway 网关、插件 SDK、密钥、审计触点 |
| `/codeql-security-high/network-ssrf-boundary` | 核心 SSRF、IP 解析、网络防护、web-fetch 和插件 SDK SSRF 策略表面 |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP 服务器、进程执行帮助器、出站投递，以及智能体工具执行门禁 |
| `/codeql-security-high/plugin-trust-boundary` | 插件安装、加载器、manifest、注册表、包管理器安装、源码加载，以及插件 SDK 包契约信任表面 |
### 平台特定安全分片
- `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 构建也占主导耗时，因此保持在每日默认项之外。
- `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 构建即使在干净状态下也主导运行时间，因此它保持在每日默认项之外。
### 关键质量类别
`CodeQL Critical Quality` 是匹配的非安全分片。它只在较小的 Blacksmith Linux runner 上，对窄范围高价值表面运行错误严重级别、非安全 JavaScript/TypeScript 质量查询。它的拉取请求保护有意小于计划配置：非草稿 PR 只会针对智能体命令/模型/工具执行和回复分发代码、配置 schema/迁移/IO 代码、认证/密钥/沙箱/安全代码、核心渠道和内置渠道插件运行时、Gateway 网关协议/服务器方法、记忆运行时/SDK 胶水、MCP/进程/出站投递、提供商运行时/模型目录、会话诊断/投递队列、插件加载器、插件 SDK/包契约，或插件 SDK 回复运行时变更，运行匹配的 `agent-runtime-boundary`、`config-boundary`、`core-auth-secrets`、`channel-runtime-boundary`、`gateway-runtime-boundary`、`memory-runtime-boundary`、`mcp-process-runtime-boundary`、`provider-runtime-boundary`、`session-diagnostics-boundary`、`plugin-boundary`、`plugin-sdk-package-contract` 和 `plugin-sdk-reply-runtime` 分片。CodeQL 配置和质量工作流变更会运行全部十二个 PR 质量分片。
`CodeQL Critical Quality` 是对应的非安全分片。它只会在较小的 Blacksmith Linux 运行器上，对狭窄的高价值表面运行错误严重级别、非安全 JavaScript/TypeScript 质量查询。它的拉取请求守护有意小于定时配置：非草稿 PR 只会针对智能体命令/模型/工具执行与回复分发代码、配置 schema/迁移/IO 代码、身份验证/密钥/沙箱/安全代码、核心渠道和内置渠道插件运行时、Gateway 网关协议/server-method、记忆运行时/SDK 粘合层、MCP/进程/出站投递、提供商运行时/模型目录、会话诊断/投递队列、插件加载器、插件 SDK/包契约，或插件 SDK 回复运行时变更，运行对应的 `agent-runtime-boundary`、`config-boundary`、`core-auth-secrets`、`channel-runtime-boundary`、`gateway-runtime-boundary`、`memory-runtime-boundary`、`mcp-process-runtime-boundary`、`provider-runtime-boundary`、`session-diagnostics-boundary`、`plugin-boundary`、`plugin-sdk-package-contract` 和 `plugin-sdk-reply-runtime` 分片。CodeQL 配置和质量工作流变更会运行全部十二个 PR 质量分片。
手动调度接受：
@ -384,40 +392,40 @@ Matrix 会在计划和发布门禁中使用 `--profile fast`，并且仅当检
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
```
这些窄范围 profile 是教学/迭代钩子，用于隔离运行一个质量分片。
窄配置档是用于单独运行一个质量分片的教学/迭代钩子。
| 类别 | 范围 |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | 凭证、密钥、沙箱、cron 和 Gateway 网关安全边界代码 |
| `/codeql-critical-quality/config-boundary` | 配置架构、迁移、规范化和 IO 契约 |
| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway 网关协议架构和服务器方法契约 |
| `/codeql-critical-quality/channel-runtime-boundary` | 核心渠道和内置渠道插件实现契约 |
| `/codeql-critical-quality/agent-runtime-boundary` | 命令执行、模型/提供商分发、自动回复分发与队列，以及 ACP 控制平面运行时契约 |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP 服务器和工具桥接、进程监管辅助函数，以及出站交付契约 |
| `/codeql-critical-quality/memory-runtime-boundary` | 记忆主机 SDK、记忆运行时门面、记忆插件 SDK 别名、记忆运行时激活胶水代码，以及记忆 Doctor 命令 |
| `/codeql-critical-quality/session-diagnostics-boundary` | 回复队列内部机制、会话交付队列、出站会话绑定/交付辅助函数、诊断事件/日志包表面，以及会话 Doctor CLI 契约 |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | 插件 SDK 入站回复分发、回复载荷/分块/运行时辅助函数、渠道回复选项、交付队列，以及会话/thread 绑定辅助函数 |
| `/codeql-critical-quality/provider-runtime-boundary` | 模型目录规范化、提供商凭证和设备发现、提供商运行时注册、提供商默认值/目录，以及 web/search/fetch/embedding 注册表 |
| `/codeql-critical-quality/ui-control-plane` | 控制 UI 启动、本地持久化、Gateway 网关控制流，以及任务控制平面运行时契约 |
| `/codeql-critical-quality/web-media-runtime-boundary` | 核心 web fetch/search、媒体 IO、媒体理解、图像生成和媒体生成运行时契约 |
| `/codeql-critical-quality/plugin-boundary` | 加载器、注册表、公开表面和插件 SDK 入口点契约 |
| `/codeql-critical-quality/plugin-sdk-package-contract` | 已发布包侧插件 SDK 源代码和插件包契约辅助函数 |
| 类别 | 表面 |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | 凭证、密钥、沙箱、cron 和 Gateway 网关安全边界代码 |
| `/codeql-critical-quality/config-boundary` | 配置 schema、迁移、规范化和 IO 契约 |
| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway 网关协议 schema 和服务器方法契约 |
| `/codeql-critical-quality/channel-runtime-boundary` | 核心渠道和内置渠道插件实现契约 |
| `/codeql-critical-quality/agent-runtime-boundary` | 命令执行、模型/提供商分派、自动回复分派和队列，以及 ACP 控制平面运行时契约 |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP 服务器和工具桥接、进程监督助手，以及出站投递契约 |
| `/codeql-critical-quality/memory-runtime-boundary` | 记忆宿主 SDK、记忆运行时外观、记忆插件 SDK 别名、记忆运行时激活粘合代码，以及记忆 Doctor 命令 |
| `/codeql-critical-quality/session-diagnostics-boundary` | 回复队列内部机制、会话投递队列、出站会话绑定/投递助手、诊断事件/日志包表面，以及会话 Doctor CLI 契约 |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | 插件 SDK 入站回复分派、回复 payload/分块/运行时助手、渠道回复选项、投递队列，以及会话/线程绑定助手 |
| `/codeql-critical-quality/provider-runtime-boundary` | 模型目录规范化、提供商凭证和设备发现、提供商运行时注册、提供商默认值/目录，以及 Web/搜索/抓取/嵌入注册表 |
| `/codeql-critical-quality/ui-control-plane` | 控制 UI 引导、本地持久化、Gateway 网关控制流，以及任务控制平面运行时契约 |
| `/codeql-critical-quality/web-media-runtime-boundary` | 核心 Web 抓取/搜索、媒体 IO、媒体理解、图像生成，以及媒体生成运行时契约 |
| `/codeql-critical-quality/plugin-boundary` | 加载器、注册表、公共表面，以及插件 SDK 入口点契约 |
| `/codeql-critical-quality/plugin-sdk-package-contract` | 已发布包侧插件 SDK 源码和插件包契约助手 |
质量与安全保持分离，这样质量发现就可以被排期、度量、禁用或扩展，而不会遮蔽安全信号。只有在窄范围 profile 拥有稳定的运行时和信号之后，才应将 Swift、Python 和内置插件 CodeQL 扩展作为有范围或分片的后续工作加回。
质量与安全保持分离，这样质量发现就可以在不遮蔽安全信号的情况下被排期、度量、禁用或扩展。只有在窄配置档拥有稳定的运行时和信号之后，才应将 Swift、Python 和内置插件 CodeQL 扩展作为有作用域或分片的后续工作加回。
## 维护工作流
### Docs Agent
### 文档 Agent
`Docs Agent` 工作流是一个事件驱动的 Codex 维护通道，用于让现有文档与最近落地的变更保持一致。它没有纯定时计划：`main` 上一次成功的非 bot push CI 运行可以触发它，手动派发也可以直接运行它。当 `main` 已经前进，或最近一小时内已创建另一次未跳过的 Docs Agent 运行时，workflow-run 调用会跳过。运行时，它会审查从上一次未跳过的 Docs Agent 源 SHA 到当前 `main` 的提交范围，因此一次每小时运行可以覆盖自上次文档处理以来积累的所有 main 变更。
`Docs Agent` 工作流是一个事件驱动的 Codex 维护通道，用于让现有文档与最近落地的变更保持一致。它没有纯定时计划：`main` 上一次成功的非机器人 push CI 运行可以触发它，也可以通过手动分派直接运行它。当 `main` 已经继续推进，或过去一小时内已经创建过另一个未跳过的 Docs Agent 运行时，workflow-run 调用会跳过。运行时，它会审查从上一个未跳过的 Docs Agent 源 SHA 到当前 `main` 的提交范围，因此一次每小时运行可以覆盖自上次文档处理以来累积的所有 main 变更。
### Test Performance Agent
### 测试性能 Agent
`Test Performance Agent` 工作流是一个事件驱动的 Codex 维护通道，用于处理慢测试。它没有纯定时计划：`main` 上一次成功的非 bot push CI 运行可以触发它，但如果同一个 UTC 日已有另一次 workflow-run 调用已运行或正在运行，它会跳过。手动派发会绕过这个每日活动门控。该通道会构建一次全套件分组 Vitest 性能报告，让 Codex 只做小型、保覆盖率的测试性能修复，而不是大范围重构；然后重新运行全套件报告，并拒绝会降低通过基线测试数量的变更。如果基线存在失败测试，Codex 只能修复明显的失败，并且 agent 后的全套件报告必须通过，才会提交任何内容。当 bot push 落地前 `main` 前进时，该通道会 rebase 已验证的补丁，重新运行 `pnpm check:changed`，并重试 push；存在冲突的陈旧补丁会被跳过。它使用 GitHub 托管的 Ubuntu，因此 Codex action 可以保持与 docs agent 相同的 drop-sudo 安全姿态。
`Test Performance Agent` 工作流是一个事件驱动的 Codex 维护通道，用于处理慢测试。它没有纯定时计划：`main` 上一次成功的非机器人 push CI 运行可以触发它，但如果当天 UTC 已经有另一个 workflow-run 调用运行过或正在运行，它会跳过。手动分派会绕过这个每日活动门禁。该通道会构建完整套件分组的 Vitest 性能报告，让 Codex 只做小型、保留覆盖率的测试性能修复，而不是大范围重构，然后重新运行完整套件报告，并拒绝会降低通过基线测试数量的变更。如果基线存在失败测试，Codex 只能修复明显的失败，并且 agent 后的完整套件报告必须通过后才能提交任何内容。当 `main` 在机器人 push 落地前推进时，该通道会 rebase 已验证的补丁，重新运行 `pnpm check:changed`，并重试 push；有冲突的陈旧补丁会被跳过。它使用 GitHub 托管的 Ubuntu，因此 Codex action 可以保持与文档 agent 相同的 drop-sudo 安全姿态。
### 合并后的重复 PR
`Duplicate PRs After Merge` 工作流是一个面向维护者的手动工作流，用于落地后的重复项清理。它默认 dry-run，并且只有在 `apply=true` 时才会关闭显式列出的 PR。在变更 GitHub 之前，它会验证已落地的 PR 已合并，并且每个重复项要么共享引用的 issue，要么存在重叠的变更 hunk。
`Duplicate PRs After Merge` 工作流是一个手动维护者工作流，用于落地后的重复项清理。它默认 dry-run，并且只有在 `apply=true` 时才会关闭显式列出的 PR。在修改 GitHub 之前，它会验证已落地 PR 已合并，并且每个重复 PR 都有共享的引用 issue 或重叠的变更 hunk。
```bash
gh workflow run duplicate-after-merge.yml \
@ -428,27 +436,27 @@ gh workflow run duplicate-after-merge.yml \
## 本地检查门禁和变更路由
本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。这个本地检查门禁在架构边界方面比宽泛的 CI 平台范围更严格：
本地变更通道路由逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。相较于宽泛的 CI 平台作用域，这个本地检查门禁对架构边界更严格：
- 核心生产代码变更会运行核心生产和核心测试 typecheck，加上核心 lint/guard；
- 仅核心测试的变更只运行核心测试 typecheck，加上核心 lint；
- 插件生产代码变更会运行插件生产和插件测试 typecheck，加上插件 lint；
- 仅插件测试的变更会运行插件测试 typecheck，加上插件 lint；
- 公开插件 SDK 或插件契约变更会扩展到插件 typecheck，因为插件依赖这些核心契约（Vitest 插件扫测仍是显式测试工作）；
- 仅发布元数据的版本提升会运行定向版本/配置/root-dependency 检查；
- 未知的 root/config 变更会安全失败到所有检查通道。
- 核心生产变更会运行核心 prod 和核心测试类型检查，以及核心 lint/guard；
- 仅核心测试变更只运行核心测试类型检查和核心 lint；
- 插件生产变更会运行插件 prod 和插件测试类型检查，以及插件 lint；
- 仅插件测试变更会运行插件测试类型检查和插件 lint；
- 公共插件 SDK 或插件契约变更会扩展到插件类型检查，因为插件依赖这些核心契约（Vitest 插件 sweep 仍然是显式测试工作）；
- 仅发布元数据的版本 bump 会运行有针对性的版本/配置/根依赖检查；
- 未知的根目录/配置变更会保守失败到所有检查通道。
本地 changed-test 路由位于 `scripts/test-projects.test-support.mjs`，并且有意比 `check:changed` 更便宜：直接测试编辑会运行自身，源码编辑优先使用显式映射，然后是兄弟测试和导入图依赖项。共享 group-room 交付配置是显式映射之一：对群组可见回复配置、源回复交付模式或 message-tool 系统 prompt 的变更，会路由到核心回复测试以及 Discord 和 Slack 交付回归测试，因此共享默认值变更会在第一次 PR push 前失败。仅当变更足够 harness-wide，以至于便宜的映射集合不是可信代理时，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。
本地变更测试路由位于 `scripts/test-projects.test-support.mjs`，并且刻意比 `check:changed` 更轻量：直接测试编辑会运行自身，源码编辑优先使用显式映射，然后是同级测试和 import-graph 依赖项。共享群组聊天室投递配置是显式映射之一：对群组可见回复配置、源回复投递模式或 message-tool 系统提示词的变更，会路由到核心回复测试以及 Discord 和 Slack 投递回归测试，因此共享默认值变更会在第一次 PR push 前失败。只有当变更范围足够覆盖整个 harness，以至于廉价映射集不能作为可信代理时，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。
## Testbox 验证
从仓库根目录运行 Testbox，并优先使用一个新预热的 box 来做宽范围证明。在把慢门禁时间花在一个被复用、已过期或刚报告异常大同步量的 box 上之前，先在 box 内运行 `pnpm testbox:sanity`。
从仓库根目录运行 Testbox，并优先使用新预热的 box 做宽泛证明。在把慢门禁花到一个被复用、已过期或刚刚报告异常大同步量的 box 上之前，先在 box 内运行 `pnpm testbox:sanity`。
当所需 root 文件（例如 `pnpm-lock.yaml`）消失，或 `git status --short` 显示至少 200 个 tracked deletion 时，完整性检查会快速失败。这通常意味着远端同步状态不是 PR 的可信副本；应停止该 box 并预热一个新的，而不是调试产品测试失败。对于有意的大量删除 PR，请为那次完整性检查设置 `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。
当必需的根文件（例如 `pnpm-lock.yaml`）消失，或者 `git status --short` 显示至少 200 个已跟踪删除时，完整性检查会快速失败。这通常意味着远程同步状态不是 PR 的可信副本；停止该 box 并预热一个新的，而不是调试产品测试失败。对于有意的大删除 PR，请为该完整性检查运行设置 `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。
如果本地 Blacksmith CLI 调用停留在同步阶段超过五分钟且没有同步后输出，`pnpm testbox:run` 也会终止它。设置 `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` 可禁用该 guard，或为异常大的本地 diff 使用更大的毫秒值。
如果本地 Blacksmith CLI 调用在同步阶段停留超过五分钟且没有同步后输出，`pnpm testbox:run` 也会终止该调用。设置 `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` 可禁用该 guard，或为异常大的本地 diff 使用更大的毫秒值。
当 Blacksmith 不可用，或更适合使用自有云容量时，Crabbox 是仓库自有的第二条远端 box Linux 证明路径。预热一个 box，通过项目工作流 hydrate 它，然后通过 Crabbox CLI 运行命令：
Crabbox 是仓库拥有的第二条远程 box 路径，用于在 Blacksmith 不可用或更适合使用自有云容量时提供 Linux 证明。预热一个 box，通过项目工作流 hydrate 它，然后通过 Crabbox CLI 运行命令：
```bash
pnpm crabbox:warmup -- --idle-timeout 90m
@ -457,7 +465,7 @@ pnpm crabbox:run -- --id <cbx_id> --shell "OPENCLAW_TESTBOX=1 pnpm check:changed
pnpm crabbox:stop -- <cbx_id>
```
`.crabbox.yaml` 负责提供商、同步和 GitHub Actions hydrate 默认值。它会排除本地 `.git`，因此 hydrated Actions checkout 会保留自己的远端 Git 元数据，而不是同步维护者本地的 remote 和 object store；它还会排除绝不应传输的本地运行时/构建产物。`.github/workflows/crabbox-hydrate.yml` 负责 checkout、Node/pnpm 设置、`origin/main` fetch，以及后续 `crabbox run --id <cbx_id>` 命令会 source 的非 secret 环境移交。
`.crabbox.yaml` 拥有提供商、同步和 GitHub Actions hydrate 默认值。它会排除本地 `.git`，因此 hydrate 后的 Actions checkout 会保留自己的远程 Git 元数据，而不是同步维护者本地的 remote 和 object store；它也会排除绝不应被传输的本地运行时/构建产物。`.github/workflows/crabbox-hydrate.yml` 拥有 checkout、Node/pnpm 设置、`origin/main` 抓取，以及后续 `crabbox run --id <cbx_id>` 命令会 source 的非密钥环境交接。
## 相关

37
docs/zh-CN/diagnostics/flags.md
View File

@ -1,19 +1,19 @@
---
read_when:
- 你需要在不提高全局日志级别的情况下获取定向调试日志
- 你需要捕获特定子系统的日志以便支持排查
- 你需要有针对性的调试日志，而不提高全局日志级别
- 你需要为技术支持捕获特定于子系统的日志
summary: 用于定向调试日志的诊断标志
title: 诊断标志
x-i18n:
generated_at: "2026-04-29T18:57:41Z"
generated_at: "2026-05-02T06:53:20Z"
model: gpt-5.5
provider: openai
source_hash: 486051e54c456dedcae5dce59e253add3554d8417660bfc97a75d21fa5fdd6f5
source_hash: 1d0ff92d45cf1c5a12a7103ba5b97d656a55a13a7a4f2e86e26ba3a9cfae7687
source_path: diagnostics/flags.md
workflow: 16
---
诊断标志可让你启用有针对性的调试日志，而不必到处开启详细日志记录。标志需要显式启用；除非某个子系统检查它们，否则不会产生任何效果。
诊断标志允许你启用有针对性的调试日志，而不必在所有地方开启详细日志。标志是选择性启用的，除非某个子系统检查它们，否则不会产生任何影响。
## 工作原理
@ -38,7 +38,7 @@ x-i18n:
```json
{
"diagnostics": {
"flags": ["telegram.http", "gateway.*"]
"flags": ["telegram.http", "brave.http", "gateway.*"]
}
}
```
@ -57,7 +57,7 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload
OPENCLAW_DIAGNOSTICS=0
```
## 时间线产物
## 时间线构件
`timeline` 标志会为外部 QA harness 写入结构化的启动和运行时计时事件：
@ -77,13 +77,13 @@ openclaw gateway run
}
```
时间线文件路径仍来自 `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH`。当仅从配置启用 `timeline` 时，最早的配置加载 span 不会发出，因为 OpenClaw 还没有读取配置；后续启动 span 会使用配置标志。
时间线文件路径仍然来自 `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH`。当 `timeline` 仅从配置中启用时，最早的配置加载 span 不会被发出，因为 OpenClaw 尚未读取配置；后续启动 span 会使用配置标志。
`OPENCLAW_DIAGNOSTICS=1`、`OPENCLAW_DIAGNOSTICS=all` 和 `OPENCLAW_DIAGNOSTICS=*` 也会启用时间线，因为它们会启用每一个诊断标志。当你只需要 JSONL 计时产物时，优先使用 `timeline`。
`OPENCLAW_DIAGNOSTICS=1`、`OPENCLAW_DIAGNOSTICS=all` 和 `OPENCLAW_DIAGNOSTICS=*` 也会启用时间线，因为它们会启用所有诊断标志。当你只需要 JSONL 计时构件时，优先使用 `timeline`。
时间线记录使用 `openclaw.diagnostics.v1` 信封。事件可以包含进程 ID、阶段名称、span 名称、持续时间、插件 ID、依赖数量、事件循环延迟样本、提供商操作名称、子进程退出状态，以及启动错误名称/消息。请将时间线文件视为本地诊断产物；在机器外共享之前先审阅它们。
时间线记录使用 `openclaw.diagnostics.v1` 信封。事件可以包含进程 ID、阶段名称、span 名称、持续时间、插件 ID、依赖项数量、事件循环延迟样本、提供商操作名称、子进程退出状态，以及启动错误名称/消息。将时间线文件视为本地诊断构件；在分享给你的机器外部之前，请先审阅它们。
## 日志写入位置
## 日志位置
标志会将日志发出到标准诊断日志文件。默认情况下：
@ -91,7 +91,7 @@ openclaw gateway run
/tmp/openclaw/openclaw-YYYY-MM-DD.log
```
如果你设置了 `logging.file`，则改用该路径。日志是 JSONL（一行一个 JSON 对象）。脱敏仍会基于 `logging.redactSensitive` 应用。
如果你设置了 `logging.file`，请改用该路径。日志是 JSONL（每行一个 JSON 对象）。脱敏仍会基于 `logging.redactSensitive` 应用。
## 提取日志
@ -107,7 +107,13 @@ ls -t /tmp/openclaw/openclaw-*.log | head -n 1
rg "telegram http error" /tmp/openclaw/openclaw-*.log
```
或者在复现时跟踪：
筛选 Brave Search HTTP 诊断：
```bash
rg "brave http" /tmp/openclaw/openclaw-*.log
```
或在复现时跟踪：
```bash
tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"
@ -115,11 +121,12 @@ tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"
对于远程 Gateway 网关，你也可以使用 `openclaw logs --follow`（参见 [/cli/logs](/zh-CN/cli/logs)）。
## 备注
## 注意事项
- 如果 `logging.level` 设置得高于 `warn`，这些日志可能会被抑制。默认的 `info` 没问题。
- `brave.http` 会记录 Brave Search 请求 URL/查询参数、响应状态/计时，以及缓存命中/未命中/写入事件。它不会记录 API 密钥或响应正文，但搜索查询可能包含敏感信息。
- 标志可以安全地保持启用；它们只会影响特定子系统的日志量。
- 使用 [/logging](/zh-CN/logging) 更改日志目标位置、级别和脱敏。
- 使用 [/logging](/zh-CN/logging) 更改日志目标位置、级别和脱敏设置。
## 相关

420
docs/zh-CN/reference/RELEASING.md
View File

@ -1,24 +1,24 @@
---
read_when:
- 正在查找公开发布渠道定义
- 运行发布验证或包验收
- 运行发布验证或软件包验收
- 查找版本命名和发布节奏
summary: 发布通道、操作员检查清单、验证环境、版本命名和发布节奏
title: 发布策略
x-i18n:
generated_at: "2026-05-02T06:28:11Z"
generated_at: "2026-05-02T06:53:31Z"
model: gpt-5.5
provider: openai
source_hash: 97554cdf9ac79080a7b371afe0a0c8288a6ca53729abb42401399dca24a12067
source_hash: ce52c9144de3c8b914954db64f6ca5b2196edbbdcc7385984235a39c208bb59e
source_path: reference/RELEASING.md
workflow: 16
---
OpenClaw 有三个公开发布通道：
- stable：带标签的发布版本，默认发布到 npm `beta`，或在明确请求时发布到 npm `latest`
- beta：预发布标签，发布到 npm `beta`
- dev：`main` 的移动头部
- 稳定版：带标签的发布，默认发布到 npm `beta`，或在明确请求时发布到 npm `latest`
- 测试版：预发布标签，发布到 npm `beta`
- 开发版：`main` 的移动头部
## 版本命名
@ -26,118 +26,128 @@ OpenClaw 有三个公开发布通道：
- Git 标签：`vYYYY.M.D`
- 稳定版修正发布版本：`YYYY.M.D-N`
- Git 标签：`vYYYY.M.D-N`
- Beta 预发布版本：`YYYY.M.D-beta.N`
- 测试版预发布版本：`YYYY.M.D-beta.N`
- Git 标签：`vYYYY.M.D-beta.N`
- 月份或日期不要补零
- `latest` 表示当前已提升的稳定版 npm 发布版本
- `beta` 表示当前 beta 安装目标
- 稳定版和稳定版修正发布默认发布到 npm `beta`；发布操作员可以明确指定 `latest`，或稍后提升一个已验证的 beta 构建
- 不要给月份或日期补零
- `latest` 表示当前已提升的稳定版 npm 发布
- `beta` 表示当前测试版安装目标
- 稳定版和稳定版修正发布默认发布到 npm `beta`；发布操作人员可以明确指定 `latest`，或稍后提升一个已验证的测试版构建
- 每个稳定版 OpenClaw 发布都会同时交付 npm 包和 macOS 应用；
beta 发布通常先验证并发布 npm/包路径，mac 应用的构建/签名/公证保留给稳定版，除非明确请求
测试版发布通常会先验证并发布 npm/包路径，除非明确请求，否则
mac 应用构建/签名/公证只为稳定版保留
## 发布节奏
- 发布按 beta 优先推进
- 只有在最新 beta 通过验证后才发布稳定版
- 维护者通常从当前 `main` 创建的 `release/YYYY.M.D` 分支切出发布版本，
- 发布按测试版优先推进
- 只有在最新测试版验证通过后，稳定版才会跟进
- 维护者通常从基于当前 `main` 创建的 `release/YYYY.M.D` 分支切出发布，
这样发布验证和修复不会阻塞 `main` 上的新开发
- 如果 beta 标签已经推送或发布并且需要修复，维护者会切出下一个 `-beta.N` 标签，而不是删除或重新创建旧 beta 标签
- 详细的发布流程、审批、凭据和恢复说明仅限维护者
- 如果测试版标签已经推送或发布且需要修复，维护者会切出下一个
`-beta.N` 标签，而不是删除或重新创建旧的测试版标签
- 详细的发布流程、审批、凭证和恢复说明仅限维护者查看
## 发布操作员检查清单
## 发布操作人员清单
此检查清单展示发布流程的公开形态。私有凭据、签名、公证、dist-tag 恢复和紧急回滚细节保留在仅限维护者的发布运行手册中。
此清单是发布流程的公开形态。私有凭证、签名、公证、dist-tag 恢复和紧急回滚细节保留在仅限维护者使用的发布运行手册中。
1. 从当前 `main` 开始：拉取最新内容，确认目标提交已推送，
并确认当前 `main` CI 足够绿色，可以从它创建分支。
2. 使用 `/changelog` 根据真实提交历史重写顶部 `CHANGELOG.md` 章节，
保持条目面向用户，提交并推送，然后在创建分支前再次 rebase/pull。
并确认当前 `main` CI 足够正常，可以从它创建分支。
2. 使用 `/changelog` 根据真实提交历史重写顶部的 `CHANGELOG.md` 章节，
保持条目面向用户，提交、推送，并在创建分支前再次 rebase/pull。
3. 审查
`src/plugins/compat/registry.ts` 和
`src/commands/doctor/shared/deprecation-compat.ts` 中的发布兼容性记录。只有在升级路径仍被覆盖时才移除过期兼容性，或记录为什么有意继续保留。
4. 从当前 `main` 创建 `release/YYYY.M.D`；不要直接在 `main` 上执行常规发布工作。
5. 为目标标签更新所有必需的版本位置，运行
`src/commands/doctor/shared/deprecation-compat.ts` 中的发布兼容性记录。只有在升级路径仍被覆盖时才移除过期兼容性，或者记录为什么有意继续保留。
4. 从当前 `main` 创建 `release/YYYY.M.D`；不要直接在 `main` 上做常规发布工作。
5. 为目标标签更新每个必需的版本位置，运行
`pnpm plugins:sync`，让可发布的插件包共享发布版本和兼容性元数据，然后运行本地确定性预检：
`pnpm check:test-types`、`pnpm check:architecture`、
`pnpm build && pnpm ui:build`、`pnpm plugins:sync:check` 和
`pnpm release:check`。
6. 使用 `preflight_only=true` 运行 `OpenClaw NPM Release`。在标签存在之前，
允许使用完整 40 字符的发布分支 SHA 进行仅验证预检。保存成功的 `preflight_run_id`。
7. 使用 `Full Release Validation` 为发布分支、标签或完整提交 SHA 启动所有预发布测试。这是四个大型发布测试箱的唯一手动入口点：Vitest、Docker、QA Lab 和 Package。
8. 如果验证失败，在发布分支上修复，并重新运行能证明修复的最小失败文件、通道、工作流作业、包配置、提供商或模型允许列表。只有当变更面使先前证据失效时，才重新运行完整总入口。
9. 对于 beta，打标签 `vYYYY.M.D-beta.N`，然后从匹配的 `release/YYYY.M.D` 分支运行 `OpenClaw Release Publish`。它会验证 `pnpm plugins:sync:check`，先将所有可发布的插件包发布到 npm，再将同一组发布到 ClawHub，然后用 dist-tag `beta` 提升准备好的 OpenClaw npm 预检产物。发布后，针对已发布的 `openclaw@YYYY.M.D-beta.N` 或 `openclaw@beta` 包运行发布后包验收。如果已推送或已发布的 beta 需要修复，切出下一个 `-beta.N`；不要删除或重写旧 beta。
10. 对于稳定版，只有在已验证的 beta 或候选版本具备所需验证证据后才继续。稳定版 npm 发布也通过
`OpenClaw Release Publish` 进行，并通过
`preflight_run_id` 复用成功的预检产物；稳定版 macOS 发布就绪还要求 `main` 上已有打包的 `.zip`、`.dmg`、`.dSYM.zip` 和更新后的 `appcast.xml`。
11. 发布后，运行 npm 发布后验证器；在需要发布后渠道证明时，可选运行独立的已发布 npm Telegram E2E；按需进行 dist-tag 提升；从完整匹配的 `CHANGELOG.md` 章节生成 GitHub 发布/预发布说明；并完成发布公告步骤。
6. 以 `preflight_only=true` 运行 `OpenClaw NPM Release`。在标签存在之前，
允许使用完整的 40 字符发布分支 SHA 进行仅验证预检。保存成功的 `preflight_run_id`。
7. 针对发布分支、标签或完整提交 SHA，使用 `Full Release Validation` 启动所有预发布测试。这是四个大型发布测试盒的唯一手动入口点：Vitest、Docker、QA Lab 和 Package。
8. 如果验证失败，在发布分支上修复，并重新运行能证明修复的最小失败
文件、通道、工作流作业、包配置、提供商或模型 allowlist。只有当变更表面使先前证据失效时，才重新运行完整总控流程。
9. 对于测试版，标记 `vYYYY.M.D-beta.N`，然后从匹配的 `release/YYYY.M.D` 分支运行 `OpenClaw Release Publish`。它会验证 `pnpm plugins:sync:check`，
先将所有可发布的插件包发布到 npm，再将同一组发布到 ClawHub，然后用 dist-tag `beta` 提升已准备好的 OpenClaw npm 预检制品。发布后，针对已发布的 `openclaw@YYYY.M.D-beta.N` 或 `openclaw@beta`
包运行发布后包验收。如果已推送或已发布的测试版需要修复，切出下一个 `-beta.N`；
不要删除或重写旧测试版。
10. 对于稳定版，只有在已验证的测试版或候选发布版具备所需验证证据后才继续。
稳定版 npm 发布也通过 `OpenClaw Release Publish`，并通过
`preflight_run_id` 复用成功的预检制品；稳定版 macOS 发布就绪还要求
`main` 上具备打包的 `.zip`、`.dmg`、`.dSYM.zip` 和更新后的 `appcast.xml`。
11. 发布后，运行 npm 发布后验证器，在需要发布后渠道证明时可选运行独立的
已发布 npm Telegram E2E，按需进行 dist-tag 提升，根据完整匹配的
`CHANGELOG.md` 章节生成 GitHub 发布/预发布说明，并执行发布公告步骤。
## 发布预检
- 在发布预检前运行 `pnpm check:test-types`，确保测试 TypeScript 在更快的本地 `pnpm check` 门禁之外也保持覆盖
- 在发布预检前运行 `pnpm check:architecture`，确保更广泛的导入循环和架构边界检查在更快的本地门禁之外也为绿色
- 在 `pnpm release:check` 前运行 `pnpm build && pnpm ui:build`，确保用于打包验证步骤的预期 `dist/*` 发布产物和 Control UI 包已存在
- 在发布批准前运行手动 `Full Release Validation` 工作流，从单一入口启动所有预发布测试箱。它接受分支、标签或完整提交 SHA，调度手动 `CI`，并调度 `OpenClaw Release Checks`，覆盖安装冒烟、包验收、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab 对等性、Matrix 和 Telegram 通道。使用 `release_profile=full` 和 `rerun_group=all` 时，它还会针对发布检查中的 `release-package-under-test` 产物运行包 Telegram E2E。发布后，如果同一个 Telegram E2E 也应验证已发布的 npm 包，请提供 `npm_telegram_package_spec`。如果私有证据报告应验证该验证与已发布的 npm 包匹配，但不强制运行 Telegram E2E，请提供 `evidence_package_spec`。示例：
- 在发布预检前运行 `pnpm check:test-types`，确保测试 TypeScript 在更快的本地 `pnpm check` 门禁之外仍有覆盖
- 在发布预检前运行 `pnpm check:architecture`，确保更广的导入循环和架构边界检查在更快的本地门禁之外为绿色
- 在 `pnpm release:check` 前运行 `pnpm build && pnpm ui:build`，确保预期的 `dist/*` 发布产物和 Control UI 包已存在，供打包验证步骤使用
- 在根版本号提升后、打标签前运行 `pnpm plugins:sync`。它会更新可发布插件包版本、OpenClaw peer/API 兼容性元数据、构建元数据和插件 changelog 存根，使其匹配核心发布版本。`pnpm plugins:sync:check` 是非变更型发布保护；如果忘记此步骤，发布工作流会在任何 registry 变更前失败。
- 在发布批准前运行手动 `Full Release Validation` 工作流，从一个入口点启动所有预发布测试盒。它接受分支、标签或完整 commit SHA，派发手动 `CI`，并派发 `OpenClaw Release Checks`，覆盖安装冒烟、包验收、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram 通道。使用 `release_profile=full` 和 `rerun_group=all` 时，它还会针对发布检查中的 `release-package-under-test` 产物运行包 Telegram E2E。发布后，如果同一个 Telegram E2E 也应验证已发布的 npm 包，请提供 `npm_telegram_package_spec`。如果私有证据报告应证明验证匹配已发布的 npm 包，而不强制运行 Telegram E2E，请提供 `evidence_package_spec`。示例：
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
- 当你想在发布工作继续进行时为包候选项获取旁路证明，请运行手动 `Package Acceptance` 工作流。对 `openclaw@beta`、`openclaw@latest` 或精确发布版本使用 `source=npm`；使用 `source=ref` 通过当前 `workflow_ref` harness 打包可信的 `package_ref` 分支/标签/SHA；对带必需 SHA-256 的 HTTPS tarball 使用 `source=url`；或对另一个 GitHub Actions 运行上传的 tarball 使用 `source=artifact`。该工作流会将候选项解析为 `package-under-test`，针对该 tarball 复用 Docker E2E 发布调度器，并可使用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 针对同一个 tarball 运行 Telegram QA。当选中的 Docker 通道包含 `published-upgrade-survivor` 时，包产物就是候选项，`published_upgrade_survivor_baseline` 选择已发布的基线。
- 当你想在发布工作继续进行时为包候选版本提供旁路证明，请运行手动 `Package Acceptance` 工作流。对 `openclaw@beta`、`openclaw@latest` 或精确发布版本使用 `source=npm`；使用 `source=ref` 通过当前 `workflow_ref` harness 打包受信任的 `package_ref` 分支/标签/SHA；对带必需 SHA-256 的 HTTPS tarball 使用 `source=url`；或对另一个 GitHub Actions run 上传的 tarball 使用 `source=artifact`。该工作流会将候选解析为 `package-under-test`，复用 Docker E2E 发布调度器对该 tarball 运行，并可用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 对同一个 tarball 运行 Telegram QA。当所选 Docker 通道包含 `published-upgrade-survivor` 时，包产物就是候选版本，`published_upgrade_survivor_baseline` 用于选择已发布基线。
示例：`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 published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
常用配置：
常用 profile：
- `smoke`：安装/渠道/智能体、Gateway 网关网络和配置重载通道
- `package`：不含 OpenWebUI 或 live ClawHub 的产物原生包/更新/插件通道
- `product`：包配置，加上 MCP 渠道、cron/subagent 清理、OpenAI web 搜索和 OpenWebUI
- `full`：带 OpenWebUI 的 Docker 发布路径分块
- `package`：产物原生包/更新/插件通道，不包含 OpenWebUI 或 live ClawHub
- `product`：包 profile，加上 MCP 渠道、cron/subagent 清理、OpenAI web 搜索和 OpenWebUI
- `full`：包含 OpenWebUI 的 Docker 发布路径分块
- `custom`：用于聚焦重跑的精确 `docker_lanes` 选择
- 当你只需要发布候选项的完整常规 CI 覆盖时，直接运行手动 `CI` 工作流。手动 CI 调度会绕过变更范围限定，并强制运行 Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n 通道。
- 当你只需要发布候选版本的完整常规 CI 覆盖时，直接运行手动 `CI` 工作流。手动 CI 派发会绕过变更范围限定，并强制运行 Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n 通道。
示例：`gh workflow run ci.yml --ref release/YYYY.M.D`
- 验证发布遥测时运行 `pnpm qa:otel:smoke`。它会通过本地 OTLP/HTTP 接收器执行 QA-lab，并验证导出的 trace span 名称、有界属性，以及内容/标识符脱敏，不需要 Opik、Langfuse 或其他外部收集器。
- 每次带标签发布前运行 `pnpm release:check`
- 标签存在后运行 `OpenClaw Release Publish`，执行会产生变更的发布序列。从 `release/YYYY.M.D` 调度它（或在发布 main 可达标签时从 `main` 调度），传入发布标签和成功的 OpenClaw npm `preflight_run_id`，并保留默认插件发布范围 `all-publishable`，除非你有意运行聚焦修复。该工作流会串行化插件 npm 发布、插件 ClawHub 发布和 OpenClaw npm 发布，确保核心包不会早于其外部化插件发布。
- 验证发布遥测时运行 `pnpm qa:otel:smoke`。它通过本地 OTLP/HTTP 接收器演练 QA-lab，并验证导出的 trace span 名称、有界属性以及内容/标识符脱敏，无需 Opik、Langfuse 或其他外部收集器。
- 每次打标签发布前运行 `pnpm release:check`
- 标签存在后，为会变更状态的发布序列运行 `OpenClaw Release Publish`。从 `release/YYYY.M.D`（或发布 main 可达标签时从 `main`）派发它，传入发布标签和成功的 OpenClaw npm `preflight_run_id`，并保持默认插件发布范围 `all-publishable`，除非你是在有意执行聚焦修复。该工作流会串行执行插件 npm 发布、插件 ClawHub 发布和 OpenClaw npm 发布，确保核心包不会早于其外置插件发布。
- 发布检查现在在单独的手动工作流中运行：
`OpenClaw Release Checks`
- `OpenClaw Release Checks` 还会在发布批准前运行 QA Lab mock 对等性门禁，以及快速 live Matrix 配置和 Telegram QA 通道。live 通道使用 `qa-live-shared` 环境；Telegram 还使用 Convex CI 凭据租约。当你想并行获取完整 Matrix 传输、媒体和 E2EE 清单时，请使用 `matrix_profile=all` 和 `matrix_shards=true` 运行手动 `QA-Lab - All Lanes` 工作流。
- 跨操作系统安装和升级运行时验证是公开 `OpenClaw Release Checks` 和 `Full Release Validation` 的一部分，它们会直接调用可复用工作流 `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- 这种拆分是有意的：保持真正的 npm 发布路径短小、确定且聚焦产物，同时较慢的 live 检查留在自己的通道中，避免拖慢或阻塞发布
- 携带密钥的发布检查应通过 `Full Release Validation` 调度，或从 `main`/发布工作流 ref 调度，确保工作流逻辑和密钥保持受控
- `OpenClaw Release Checks` 接受分支、标签或完整提交 SHA，只要解析出的提交可从 OpenClaw 分支或发布标签到达
- `OpenClaw NPM Release` 仅验证预检也接受当前完整 40 字符工作流分支提交 SHA，不要求已推送标签
- `OpenClaw Release Checks` 还会在发布批准前运行 QA Lab mock parity 门禁，以及快速 live Matrix profile 和 Telegram QA 通道。live 通道使用 `qa-live-shared` 环境；Telegram 还使用 Convex CI 凭据租约。当你想并行获取完整 Matrix 传输、媒体和 E2EE inventory 时，请运行手动 `QA-Lab - All Lanes` 工作流，并设置 `matrix_profile=all` 和 `matrix_shards=true`。
- 跨 OS 安装和升级运行时验证是公开 `OpenClaw Release Checks` 和 `Full Release Validation` 的一部分，它们会直接调用可复用工作流 `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- 这种拆分是有意的：保持真正 npm 发布路径短、确定且聚焦产物，同时让较慢的 live 检查留在自己的通道中，避免拖慢或阻塞发布
- 带有机密的发布检查应通过 `Full Release Validation` 派发，或从 `main`/发布工作流 ref 派发，以确保工作流逻辑和密钥保持受控
- `OpenClaw Release Checks` 接受分支、标签或完整 commit SHA，只要解析出的 commit 可从 OpenClaw 分支或发布标签到达
- `OpenClaw NPM Release` 仅验证预检也接受当前完整 40 字符工作流分支 commit SHA，无需已推送标签
- 该 SHA 路径仅用于验证，不能提升为真正发布
- 在 SHA 模式下，工作流仅为包元数据检查合成 `v<package.json version>`；真正发布仍需要真实发布标签
- 两个工作流都将真正发布和提升路径保留在 GitHub-hosted runner 上，而非变更型验证路径可以使用更大的 Blacksmith Linux runner
- 该工作流使用 `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` 运行，并同时使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 工作流密钥
- 两个工作流都将真正发布和提升路径保留在 GitHub 托管 runner 上，而非变更型验证路径可以使用更大的 Blacksmith Linux runner
- 该工作流使用 `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` 运行，并使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 两个工作流 secret
- npm 发布预检不再等待单独的发布检查通道
- 批准前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`（或匹配的 beta/修正标签）
- npm 发布后，运行 `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（或匹配的 beta/修正版本），在新的临时前缀中验证已发布注册表安装路径
- beta 发布后，运行 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`，使用共享的租赁 Telegram 凭据池，针对已发布 npm 包验证已安装包新手引导、Telegram 设置和真实 Telegram E2E。本地维护者一次性运行可以省略 Convex 变量，并直接传入三个 `OPENCLAW_QA_TELEGRAM_*` 环境变量凭据。
- 维护者可以通过手动 `NPM Telegram Beta E2E` 工作流，从 GitHub Actions 运行相同的发布后检查。它有意设计为仅手动运行，不会在每次合并时运行。
- 维护者发布自动化现在使用先预检后提升：
- 真实 npm 发布必须通过一次成功的 npm `preflight_run_id`
- 真实 npm 发布必须从与成功预检运行相同的 `main` 或 `release/YYYY.M.D` 分支调度
- 稳定版 npm 发布默认使用 `beta`
- 稳定版 npm 发布可以通过工作流输入显式目标为 `latest`
- 基于 token 的 npm dist-tag 变更现在位于 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`，用于安全隔离，因为 `npm dist-tag add` 仍需要 `NPM_TOKEN`，而公共仓库保持仅 OIDC 发布
- 公开 `macOS Release` 仅用于验证；当标签只存在于发布分支但工作流从 `main` 调度时，设置 `public_release_branch=release/YYYY.M.D`
- 真实私有 mac 发布必须通过成功的私有 mac `preflight_run_id` 和 `validate_run_id`
- 真实发布路径会提升已准备的产物，而不是再次重建它们
- 对于 `YYYY.M.D-N` 这样的稳定版修正发布，发布后验证器还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的同一临时前缀升级路径，确保发布修正不会悄悄让较旧的全局安装停留在基础稳定版 payload 上
- npm 发布预检默认失败关闭，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空 `dist/control-ui/assets/` payload，避免再次发布空的浏览器仪表盘
- 发布后验证还会检查已发布插件入口点和包元数据是否存在于已安装的注册表布局中。如果某个发布缺少插件运行时 payload，会导致发布后验证器失败，并且不能提升为 `latest`。
- `pnpm test:install:smoke` 还会对候选更新 tarball 强制执行 npm pack `unpackedSize` 预算，因此安装器 e2e 会在发布路径前捕获意外的打包膨胀
- 如果发布工作触及 CI 规划、插件计时 manifest 或插件测试矩阵，请在批准前重新生成并审查 `.github/workflows/plugin-prerelease.yml` 中由规划器拥有的 `plugin-prerelease-extension-shard` 矩阵输出，确保发布说明不会描述过时的 CI 布局
- 稳定版 macOS 发布就绪性还包括更新器表面：
- GitHub 发布最终必须包含打包的 `.zip`、`.dmg` 和 `.dSYM.zip`
- 发布后，`main` 上的 `appcast.xml` 必须指向新的稳定版 zip
- 打包后的应用必须保持非调试 bundle id、非空 Sparkle feed URL，以及不低于该发布版本规范 Sparkle 构建下限的 `CFBundleVersion`
- npm 发布后运行 `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（或匹配的 beta/修正版本），以在全新的临时 prefix 中验证已发布 registry 安装路径
- beta 发布后运行 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`，使用共享租约 Telegram 凭据池，针对已发布 npm 包验证已安装包的新手引导、Telegram 设置和真实 Telegram E2E。本地维护者一次性运行可以省略 Convex 变量，并直接传入三个 `OPENCLAW_QA_TELEGRAM_*` 环境变量凭据。
- 维护者可以通过手动 `NPM Telegram Beta E2E` 工作流，从 GitHub Actions 运行同样的发布后检查。它有意仅手动运行，不会在每次合并时运行。
- 维护者发布自动化现在使用先预检、后提升：
- 真正的 npm 发布必须通过成功的 npm `preflight_run_id`
- 真正的 npm 发布必须从与成功预检运行相同的 `main` 或 `release/YYYY.M.D` 分支派发
- stable npm 发布默认使用 `beta`
- stable npm 发布可以通过工作流输入显式指向 `latest`
- 基于 token 的 npm dist-tag 变更现在位于 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`，出于安全原因，因为 `npm dist-tag add` 仍需要 `NPM_TOKEN`，而公开仓库保持仅 OIDC 发布
- 公开 `macOS Release` 仅用于验证；当标签只存在于发布分支上，但工作流从 `main` 派发时，请设置 `public_release_branch=release/YYYY.M.D`
- 真正的私有 mac 发布必须通过成功的私有 mac `preflight_run_id` 和 `validate_run_id`
- 真正发布路径会提升已准备好的产物，而不是再次重建
- 对于 `YYYY.M.D-N` 这类 stable 修正发布，发布后验证器还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的同一临时 prefix 升级路径，确保发布修正不会静默地让较旧的全局安装停留在基础 stable payload 上
- npm 发布预检会失败关闭，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空 `dist/control-ui/assets/` payload，避免再次发布空的浏览器仪表盘
- 发布后验证还会检查已发布插件入口点和包元数据是否存在于已安装的 registry 布局中。如果某个发布缺少插件运行时 payload，发布后验证器会失败，且不能提升到 `latest`。
- `pnpm test:install:smoke` 还会对候选更新 tarball 强制执行 npm pack `unpackedSize` 预算，因此安装器 e2e 会在发布发布路径前捕获意外的打包膨胀
- 如果发布工作触及 CI 规划、扩展计时 manifest 或扩展测试矩阵，请在批准前重新生成并审查规划器拥有的 `plugin-prerelease-extension-shard` 矩阵输出，来源为 `.github/workflows/plugin-prerelease.yml`，确保发布说明不会描述过期的 CI 布局
- stable macOS 发布就绪还包括更新器界面：
- GitHub release 最终必须包含打包的 `.zip`、`.dmg` 和 `.dSYM.zip`
- 发布后，`main` 上的 `appcast.xml` 必须指向新的 stable zip
- 打包后的应用必须保持非 debug bundle id、非空 Sparkle feed URL，以及达到或高于该发布版本规范 Sparkle 构建下限的 `CFBundleVersion`
## 发布测试箱
## 发布测试盒
`Full Release Validation` 是操作员从单一入口启动所有预发布测试的方式。对于快速移动分支上的固定提交证明，请使用辅助工具，确保每个子工作流都从固定到目标 SHA 的临时分支运行：
`Full Release Validation` 是操作员从一个入口点启动所有预发布测试的方式。对于快速移动分支上的固定 commit 证明，请使用该助手，让每个子工作流都从固定到目标 SHA 的临时分支运行：
```bash
pnpm ci:full-release --sha <full-sha>
```
该辅助工具会推送 `release-ci/<sha>-...`，从该分支调度 `Full Release Validation` 并传入 `ref=<sha>`，验证每个子工作流 `headSha` 都与目标匹配，然后删除临时分支。这可以避免意外证明较新的 `main` 子运行。
该助手会推送 `release-ci/<sha>-...`，从该分支派发 `Full Release Validation` 并设置 `ref=<sha>`，验证每个子工作流的 `headSha` 都匹配目标，然后删除临时分支。这避免了意外证明较新的 `main` 子运行。
对于发布分支或标签验证，请从可信的 `main` 工作流 ref 运行，并将发布分支或标签作为 `ref` 传入：
对于发布分支或标签验证，请从受信任的 `main` 工作流 ref 运行，并将发布分支或标签作为 `ref` 传入：
```bash
gh workflow run full-release-validation.yml \
@ -149,32 +159,19 @@ gh workflow run full-release-validation.yml \
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
```
该工作流会解析目标 ref，使用
`target_ref=<release-ref>` 分发手动 `CI`，分发 `OpenClaw Release Checks`，并在 `release_profile=full` 且
`rerun_group=all` 时，或设置了 `npm_telegram_package_spec` 时，分发独立的软件包 Telegram E2E。随后，`OpenClaw Release
Checks` 会扇出安装冒烟测试、跨 OS 发布检查、实时/E2E Docker
发布路径覆盖、带 Telegram 软件包 QA 的 Package Acceptance、QA Lab
一致性、实时 Matrix 和实时 Telegram。只有当
`Full Release Validation`
摘要显示 `normal_ci` 和 `release_checks` 成功时，完整运行才可接受。在 full/all 模式下，
`npm_telegram` 子项也必须成功；在 full/all 之外，除非提供了已发布的 `npm_telegram_package_spec`，否则会跳过它。最终验证器摘要包含每个子运行的最慢作业表，因此发布负责人无需下载日志即可看到当前关键路径。
参见[完整发布验证](/zh-CN/reference/full-release-validation)，了解完整阶段矩阵、精确的工作流作业名称、stable 与 full 配置差异、产物以及聚焦重跑句柄。
子工作流会从运行 `Full Release
Validation` 的可信 ref 分发，通常是 `--ref main`，即使目标 `ref` 指向较旧的发布分支或标签也是如此。没有单独的 Full Release Validation
workflow-ref 输入；通过选择工作流运行 ref 来选择可信 harness。
不要在移动的 `main` 上使用 `--ref main -f ref=<sha>` 来证明精确提交；
原始提交 SHA 不能作为工作流分发 ref，因此请使用
`pnpm ci:full-release --sha <sha>` 创建固定的临时分支。
工作流会解析目标 ref，使用 `target_ref=<release-ref>` 调度手动 `CI`，调度 `OpenClaw Release Checks`，并在 `release_profile=full` 且 `rerun_group=all` 时，或设置了 `npm_telegram_package_spec` 时，调度独立的 package Telegram E2E。随后 `OpenClaw Release Checks` 会展开安装冒烟、跨 OS 发布检查、live/E2E Docker 发布路径覆盖、带 Telegram package QA 的 Package Acceptance、QA Lab parity、live Matrix 和 live Telegram。只有当 `Full Release Validation` 摘要显示 `normal_ci` 和 `release_checks` 均成功时，完整运行才可接受。在 full/all 模式下，`npm_telegram` 子项也必须成功；在 full/all 之外，除非提供了已发布的 `npm_telegram_package_spec`，否则会跳过它。最终验证器摘要会包含每个子运行的最慢 job 表，因此发布负责人无需下载日志即可看到当前关键路径。
请参阅[完整发布验证](/zh-CN/reference/full-release-validation)，了解完整阶段矩阵、确切工作流 job 名称、stable 与 full profile 的差异、构件以及聚焦 rerun 句柄。
子工作流会从运行 `Full Release Validation` 的可信 ref 调度，通常是 `--ref main`，即使目标 `ref` 指向较旧的发布分支或标签也是如此。没有单独的 Full Release Validation workflow-ref 输入；通过选择工作流运行 ref 来选择可信 harness。
不要在移动的 `main` 上使用 `--ref main -f ref=<sha>` 作为精确提交证明；原始提交 SHA 不能作为工作流调度 ref，因此请使用 `pnpm ci:full-release --sha <sha>` 创建固定的临时分支。
使用 `release_profile` 选择实时/提供商覆盖宽度：
使用 `release_profile` 选择 live/提供商覆盖广度：
- `minimum`：最快的发布关键 OpenAI/core 实时和 Docker 路径
- `minimum`：最快的发布关键 OpenAI/core live 和 Docker 路径
- `stable`：minimum 加上用于发布批准的稳定提供商/后端覆盖
- `full`：stable 加上广泛的咨询性提供商/媒体覆盖
- `full`：stable 加上广泛的 advisory 提供商/媒体覆盖
`OpenClaw Release Checks` 使用可信工作流 ref 将目标
ref 解析一次为 `release-package-under-test`，并在发布路径 Docker 检查和 Package Acceptance 中复用该产物。这会让所有面向软件包的机器使用相同字节，并避免重复构建软件包。
当设置了 repo/org 变量时，跨 OS OpenAI 安装冒烟测试使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.5`，因为该 lane 证明的是软件包安装、新手引导、Gateway 网关启动和一次实时智能体轮次，而不是对最慢的默认模型做基准测试。更广泛的实时提供商矩阵仍然是模型特定覆盖的位置。
`OpenClaw Release Checks` 使用可信工作流 ref 将目标 ref 一次性解析为 `release-package-under-test`，并在发布路径 Docker 检查和 Package Acceptance 中复用该构件。这会让所有面向 package 的 box 使用相同字节，并避免重复构建 package。
跨 OS OpenAI 安装冒烟会在设置了 repo/org 变量时使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.5`，因为这条 lane 证明的是 package 安装、新手引导、Gateway 网关启动和一次 live 智能体轮次，而不是基准测试最慢的默认模型。更广泛的 live 提供商矩阵仍然是进行模型特定覆盖的地方。
根据发布阶段使用这些变体：
@ -206,30 +203,23 @@ gh workflow run full-release-validation.yml \
-f npm_telegram_provider_mode=mock-openai
```
在聚焦修复后的第一次重跑中，不要使用完整总控工作流。如果某台机器失败，请使用失败的子工作流、作业、Docker lane、软件包配置、模型提供商或 QA lane 作为下一次证明。只有当修复更改了共享发布编排，或让早先的全机器证据失效时，才再次运行完整总控工作流。总控工作流的最终验证器会重新检查已记录的子工作流运行 id，因此在某个子工作流成功重跑后，只需重跑失败的
`Verify full validation` 父作业。
不要把完整 umbrella 作为聚焦修复后的第一次 rerun。如果一个 box 失败，请使用失败的子工作流、job、Docker lane、package profile、模型提供商或 QA lane 作为下一次证明。只有当修复更改了共享发布编排，或使早先的全 box 证据过期时，才再次运行完整 umbrella。umbrella 的最终验证器会重新检查记录的子工作流运行 ID，因此在子工作流成功 rerun 后，只需 rerun 失败的 `Verify full validation` 父 job。
对于有界恢复，将 `rerun_group` 传给总控工作流。`all` 是真正的
release-candidate 运行，`ci` 只运行普通 CI 子项，`plugin-prerelease`
只运行仅发布用的插件子项，`release-checks` 运行每个发布机器，更窄的发布分组为 `install-smoke`、`cross-os`、
`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 和 `npm-telegram`。
聚焦的 `npm-telegram` 重跑需要 `npm_telegram_package_spec`；带有 `release_profile=full` 的 full/all 运行使用 release-checks 软件包产物。
对于有界恢复，请向 umbrella 传递 `rerun_group`。`all` 是真正的发布候选运行，`ci` 只运行普通 CI 子项，`plugin-prerelease` 只运行仅发布插件子项，`release-checks` 运行每个发布 box，更窄的发布组包括 `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 和 `npm-telegram`。
聚焦的 `npm-telegram` rerun 需要 `npm_telegram_package_spec`；带 `release_profile=full` 的 full/all 运行会使用 release-checks package 构件。
### Vitest
Vitest 机器是手动 `CI` 子工作流。手动 CI 会有意绕过变更范围限定，并强制对发布候选执行普通测试图：Linux Node 分片、内置插件分片、渠道契约、Node 22
兼容性、`check`、`check-additional`、构建冒烟测试、文档检查、Python
Skills、Windows、macOS、Android 和 Control UI i18n。
Vitest box 是手动 `CI` 子工作流。手动 CI 会有意绕过 changed 范围限定，并强制对发布候选运行普通测试图：Linux Node 分片、内置插件分片、渠道合约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n。
用这台机器回答“源代码树是否通过了完整的普通测试套件？”
它不同于发布路径产品验证。需要保留的证据：
使用此 box 回答“源代码树是否通过了完整的普通测试套件？”它不同于发布路径产品验证。需要保留的证据：
- `Full Release Validation` 摘要，显示已分发的 `CI` 运行 URL
- `CI` 在精确目标 SHA 上运行通过
- 调查回归时来自 CI 作业的失败或缓慢分片名称
- 当一次运行需要性能分析时，保留 `.artifacts/vitest-shard-timings.json` 等 Vitest 计时产物
- `Full Release Validation` 摘要，显示已调度的 `CI` 运行 URL
- `CI` 在确切目标 SHA 上运行通过
- 调查回归时的失败或较慢分片名称，来自 CI jobs
- 运行需要性能分析时的 Vitest 计时构件，例如 `.artifacts/vitest-shard-timings.json`
仅当发布需要确定性的普通 CI，但不需要 Docker、QA Lab、实时、跨 OS 或软件包机器时，才直接运行手动 CI：
只有当发布需要确定性的普通 CI，而不需要 Docker、QA Lab、live、跨 OS 或 package box 时，才直接运行手动 CI：
```bash
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
@ -237,81 +227,52 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
### Docker
Docker 机器位于 `OpenClaw Release Checks` 中，通过
`openclaw-live-and-e2e-checks-reusable.yml` 以及发布模式
`install-smoke` 工作流执行。它通过打包的 Docker 环境验证发布候选，而不只是源代码级测试。
Docker box 位于 `OpenClaw Release Checks` 中，通过 `openclaw-live-and-e2e-checks-reusable.yml` 以及发布模式 `install-smoke` 工作流提供。它通过打包的 Docker 环境验证发布候选，而不仅仅是源代码级测试。
发布 Docker 覆盖包括：
- 启用慢速 Bun 全局安装冒烟测试的完整安装冒烟测试
- 按目标 SHA 准备/复用 root Dockerfile 冒烟镜像，QR、
root/gateway 和 installer/Bun 冒烟作业作为独立 install-smoke
分片运行
- 启用慢速 Bun 全局安装冒烟的完整安装冒烟
- 按目标 SHA 准备/复用根 Dockerfile 冒烟镜像，其中 QR、root/gateway 和 installer/Bun 冒烟 job 作为独立 install-smoke 分片运行
- 仓库 E2E lane
- 发布路径 Docker 分块：`core`、`package-update-openai`、
`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、
`plugins-runtime-services`、
`plugins-runtime-install-a`、`plugins-runtime-install-b`、
`plugins-runtime-install-c`、`plugins-runtime-install-d`、
`plugins-runtime-install-e`、`plugins-runtime-install-f`、
`plugins-runtime-install-g` 和 `plugins-runtime-install-h`
- 请求时，`plugins-runtime-services` 分块内的 OpenWebUI 覆盖
- 拆分的内置插件安装/卸载 lane：
`bundled-plugin-install-uninstall-0` 到
`bundled-plugin-install-uninstall-23`
- 当发布检查包含实时套件时，实时/E2E 提供商套件和 Docker 实时模型覆盖
- 发布路径 Docker chunk：`core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g` 和 `plugins-runtime-install-h`
- 请求时在 `plugins-runtime-services` chunk 内的 OpenWebUI 覆盖
- 拆分的内置插件安装/卸载 lane：从 `bundled-plugin-install-uninstall-0` 到 `bundled-plugin-install-uninstall-23`
- 当发布检查包含 live 套件时的 live/E2E 提供商套件和 Docker live 模型覆盖
重跑前先使用 Docker 产物。发布路径调度器会上传
`.artifacts/docker-tests/`，其中包含 lane 日志、`summary.json`、`failures.json`、
阶段计时、调度器计划 JSON 和重跑命令。对于聚焦恢复，请在可复用实时/E2E 工作流上使用
`docker_lanes=<lane[,lane]>`，而不是重跑所有发布分块。生成的重跑命令会在可用时包含先前的
`package_artifact_run_id` 和已准备 Docker 镜像输入，因此失败的 lane 可以复用同一个 tarball 和 GHCR 镜像。
rerun 前先使用 Docker 构件。发布路径调度器会上传 `.artifacts/docker-tests/`，其中包含 lane 日志、`summary.json`、`failures.json`、阶段计时、调度器计划 JSON 和 rerun 命令。对于聚焦恢复，请在可复用 live/E2E 工作流上使用 `docker_lanes=<lane[,lane]>`，而不是 rerun 所有发布 chunk。生成的 rerun 命令会在可用时包含先前的 `package_artifact_run_id` 和已准备 Docker 镜像输入，因此失败的 lane 可以复用相同的 tarball 和 GHCR 镜像。
### QA Lab
QA Lab 机器也是 `OpenClaw Release Checks` 的一部分。它是智能体行为和渠道级发布关卡，独立于 Vitest 和 Docker
软件包机制。
QA Lab box 也是 `OpenClaw Release Checks` 的一部分。它是智能体行为和渠道级发布门禁，与 Vitest 和 Docker package 机制分开。
发布 QA Lab 覆盖包括：
- 使用智能体一致性包，将 OpenAI 候选 lane 与 Opus 4.6
基线进行比较的 mock 一致性关卡
- 使用 `qa-live-shared` 环境的快速实时 Matrix QA 配置
- 使用 Convex CI 凭证租约的实时 Telegram QA lane
- 当发布遥测需要明确本地证明时运行 `pnpm qa:otel:smoke`
- mock parity gate，使用 agentic parity pack 比较 OpenAI 候选 lane 与 Opus 4.6 基线
- 使用 `qa-live-shared` 环境的快速 live Matrix QA profile
- 使用 Convex CI 凭证租约的 live Telegram QA lane
- 当发布遥测需要明确本地证明时的 `pnpm qa:otel:smoke`
用这台机器回答“发布版本在 QA 场景和实时渠道流程中是否行为正确？”
批准发布时，请保留 parity、Matrix 和 Telegram lane 的产物 URL。完整 Matrix 覆盖仍然可作为手动分片 QA-Lab 运行使用，而不是默认的发布关键 lane。
使用此 box 回答“发布在 QA 场景和 live 渠道流程中的行为是否正确？”批准发布时保留 parity、Matrix 和 Telegram lane 的构件 URL。完整 Matrix 覆盖仍可作为手动分片 QA-Lab 运行使用，而不是默认的发布关键 lane。
### 软件包
### Package
软件包机器是可安装产品关卡。它由
`Package Acceptance` 和解析器
`scripts/resolve-openclaw-package-candidate.mjs` 支持。解析器会将候选规范化为供 Docker E2E 使用的 `package-under-test` tarball，验证软件包清单，记录软件包版本和 SHA-256，并将工作流 harness ref 与软件包源 ref 分离。
Package box 是可安装产品门禁。它由 `Package Acceptance` 和解析器 `scripts/resolve-openclaw-package-candidate.mjs` 支撑。解析器会把候选规范化为供 Docker E2E 使用的 `package-under-test` tarball，验证 package 清单，记录 package 版本和 SHA-256，并让工作流 harness ref 与 package 源 ref 分离。
支持的候选来源：
- `source=npm`：`openclaw@beta`、`openclaw@latest` 或精确的 OpenClaw 发布版本
- `source=ref`：使用选定的 `workflow_ref` harness 打包可信 `package_ref` 分支、标签或完整提交 SHA
- `source=url`：下载 HTTPS `.tgz`，并要求提供 `package_sha256`
- `source=npm`：`openclaw@beta`、`openclaw@latest` 或确切的 OpenClaw 发布版本
- `source=ref`：使用所选 `workflow_ref` harness 打包可信的 `package_ref` 分支、标签或完整提交 SHA
- `source=url`：下载需要 `package_sha256` 的 HTTPS `.tgz`
- `source=artifact`：复用另一个 GitHub Actions 运行上传的 `.tgz`
`OpenClaw Release Checks` 使用 `source=artifact`、已准备的发布软件包产物、`suite_profile=custom`、
`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`、
`published_upgrade_survivor_baselines=release-history`、
`published_upgrade_survivor_scenarios=reported-issues` 和
`telegram_mode=mock-openai` 运行 Package Acceptance。Package Acceptance 会针对同一个已解析 tarball 保持迁移、更新、陈旧插件依赖清理、离线插件 fixture、插件更新和 Telegram
软件包 QA。它是 GitHub 原生替代方案，用于取代此前需要 Parallels 的大部分软件包/更新覆盖。跨 OS 发布检查对于 OS 特定的新手引导、安装器和平台行为仍然重要，但软件包/更新产品验证应优先使用 Package Acceptance。
`OpenClaw Release Checks` 会用 `source=artifact`、准备好的发布 package 构件、`suite_profile=custom`、`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`、`published_upgrade_survivor_baselines=release-history`、`published_upgrade_survivor_scenarios=reported-issues` 和 `telegram_mode=mock-openai` 运行 Package Acceptance。Package Acceptance 会让迁移、更新、陈旧插件依赖清理、离线插件 fixtures、插件更新和 Telegram package QA 都针对同一个已解析的 tarball。它是大多数过去需要 Parallels 的 package/update 覆盖的 GitHub 原生替代方案。跨 OS 发布检查对于特定 OS 的新手引导、安装器和平台行为仍然重要，但 package/update 产品验证应优先使用 Package Acceptance。
更新和插件验证的规范清单是
[更新和插件测试](/zh-CN/help/testing-updates-plugins)。在决定哪个本地、Docker、Package Acceptance 或 release-check lane 能证明插件安装/更新、Doctor 清理或已发布软件包迁移更改时，请使用它。
从每个稳定版 `2026.4.23+` 软件包进行的穷尽式已发布更新迁移是单独的手动 `Update Migration` 工作流，不属于 Full Release CI。
更新和插件验证的规范清单是[更新和插件测试](/zh-CN/help/testing-updates-plugins)。在判断哪个本地、Docker、Package Acceptance 或 release-check lane 能证明插件安装/更新、Doctor 清理或已发布 package 迁移变更时，请使用它。
从每个稳定 `2026.4.23+` package 进行的穷尽式已发布更新迁移，是单独的手动 `Update Migration` 工作流，不属于 Full Release CI。
旧版 package-acceptance 宽容策略有意设置了时间盒。到
`2026.4.25` 为止的软件包可以对已发布到 npm 的元数据缺口使用兼容路径：tarball 中缺少的私有 QA 清单条目、缺少
`gateway install --wrapper`、tarball 派生的 git fixture 中缺少补丁文件、缺少持久化的 `update.channel`、旧版插件安装记录位置、缺少 marketplace 安装记录持久化，以及 `plugins update` 期间的配置元数据迁移。已发布的 `2026.4.26` 软件包可以对已经随包发布的本地构建元数据戳文件发出警告。后续软件包必须满足现代软件包契约；同样的缺口会导致发布验证失败。
旧版 package-acceptance 宽容性是有意设置时间边界的。到 `2026.4.25` 为止的 package 可以对已经发布到 npm 的元数据缺口使用兼容路径：tarball 中缺失的私有 QA 清单条目、缺失的 `gateway install --wrapper`、tarball 派生 git fixture 中缺失的 patch 文件、缺失的持久化 `update.channel`、旧版插件 install-record 位置、缺失的 marketplace install-record 持久化，以及 `plugins update` 期间的配置元数据迁移。已发布的 `2026.4.26` package 可以对已经发布的本地构建元数据 stamp 文件发出警告。之后的 package 必须满足现代 package 合约；这些相同缺口会导致发布验证失败。
当发布问题涉及实际可安装软件包时，使用更广泛的 Package Acceptance 配置：
当发布问题涉及实际可安装 package 时，请使用更广的 Package Acceptance profile：
```bash
gh workflow run package-acceptance.yml \
@ -323,35 +284,82 @@ gh workflow run package-acceptance.yml \
-f published_upgrade_survivor_baseline=openclaw@2026.4.26
```
常用软件包配置：
常见 package profile：
- `smoke`：快速软件包安装/渠道/智能体、Gateway 网关网络和配置重载 lane
- `package`：不含实时 ClawHub 的安装/更新/插件软件包契约；这是 release-check
默认值
- `product`：`package` 加上 MCP 渠道、cron/subagent 清理、OpenAI Web
搜索和 OpenWebUI
- `full`：带 OpenWebUI 的 Docker 发布路径分块
- `custom`：用于聚焦重跑的精确 `docker_lanes` 列表
- `smoke`：快速 package 安装/渠道/智能体、Gateway 网关网络和配置重载 lane
- `package`：不含 live ClawHub 的安装/更新/插件 package 合约；这是 release-check 默认值
- `product`：`package` 加上 MCP 渠道、cron/subagent 清理、OpenAI web 搜索和 OpenWebUI
- `full`：带 OpenWebUI 的 Docker 发布路径 chunk
- `custom`：用于聚焦 rerun 的确切 `docker_lanes` 列表
对于包候选版的 Telegram 验证，在 Package Acceptance 上启用 `telegram_mode=mock-openai` 或
`telegram_mode=live-frontier`。该工作流会把解析出的
`package-under-test` tarball 传入 Telegram 通道；独立的
Telegram 工作流仍接受已发布的 npm 规格，用于发布后检查。
对于包候选版本的 Telegram 验证，在 Package Acceptance 上启用 `telegram_mode=mock-openai` 或
`telegram_mode=live-frontier`。该工作流会将解析出的 `package-under-test` tarball
传入 Telegram 通道；独立的 Telegram 工作流仍接受已发布的 npm 规范，用于发布后检查。
## 发布自动化
`OpenClaw Release Publish` 是常规的变更性发布入口点。它会按发布所需顺序编排受信发布者工作流：
1. 检出发布标签并解析其提交 SHA。
2. 验证该标签可从 `main` 或 `release/*` 访问。
3. 运行 `pnpm plugins:sync:check`。
4. 使用 `publish_scope=all-publishable` 和 `ref=<release-sha>` 分发 `Plugin NPM Release`。
5. 使用相同的范围和 SHA 分发 `Plugin ClawHub Release`。
6. 使用发布标签、npm dist-tag 和保存的 `preflight_run_id` 分发 `OpenClaw NPM Release`。
Beta 发布示例：
```bash
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
```
将稳定版发布到默认 beta dist-tag：
```bash
gh workflow run openclaw-release-publish.yml \
--ref release/YYYY.M.D \
-f tag=vYYYY.M.D \
-f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
-f npm_dist_tag=beta
```
直接提升稳定版到 `latest` 是显式操作：
```bash
gh workflow run openclaw-release-publish.yml \
--ref release/YYYY.M.D \
-f tag=vYYYY.M.D \
-f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
-f npm_dist_tag=latest
```
仅在聚焦修复或重新发布工作时使用较底层的 `Plugin NPM Release` 和 `Plugin ClawHub Release` 工作流。对于选定插件修复，请向 `OpenClaw Release Publish` 传入 `plugin_publish_scope=selected` 和 `plugins=@openclaw/name`，或者在不得发布 OpenClaw 包时直接分发子工作流。
## NPM 工作流输入
`OpenClaw NPM Release` 接受这些由操作员控制的输入：
- `tag`：必需的发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或
`v2026.4.2-beta.1`；当 `preflight_only=true` 时，它也可以是当前
workflow 分支的完整 40 字符提交 SHA，用于仅验证的预检
- `tag`：必需的发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或 `v2026.4.2-beta.1`；当 `preflight_only=true` 时，也可以是当前完整的 40 字符工作流分支提交 SHA，用于仅验证预检
- `preflight_only`：`true` 表示仅验证/构建/打包，`false` 表示真实发布路径
- `preflight_run_id`：真实发布路径必需，供工作流复用成功预检运行中准备好的 tarball
- `preflight_run_id`：真实发布路径必需，以便工作流复用成功预检运行中准备好的 tarball
- `npm_dist_tag`：发布路径的 npm 目标标签；默认为 `beta`
`OpenClaw Release Publish` 接受这些由操作员控制的输入：
- `tag`：必需的发布标签；必须已存在
- `preflight_run_id`：成功的 `OpenClaw NPM Release` 预检运行 ID；当 `publish_openclaw_npm=true` 时必需
- `npm_dist_tag`：OpenClaw 包的 npm 目标标签
- `plugin_publish_scope`：默认为 `all-publishable`；仅在聚焦修复工作中使用 `selected`
- `plugins`：当 `plugin_publish_scope=selected` 时使用逗号分隔的 `@openclaw/*` 包名
- `publish_openclaw_npm`：默认为 `true`；仅在将该工作流用作仅插件修复编排器时设置为 `false`
`OpenClaw Release Checks` 接受这些由操作员控制的输入：
- `ref`：要验证的分支、标签或完整提交 SHA。携带密钥的检查要求解析出的提交可从 OpenClaw 分支或发布标签访问。
- `ref`：要验证的分支、标签或完整提交 SHA。带有密钥的检查要求解析出的提交可从 OpenClaw 分支或发布标签访问。
规则：
@ -359,33 +367,27 @@ Telegram 工作流仍接受已发布的 npm 规格，用于发布后检查。
- Beta 预发布标签只能发布到 `beta`
- 对于 `OpenClaw NPM Release`，仅当 `preflight_only=true` 时才允许输入完整提交 SHA
- `OpenClaw Release Checks` 和 `Full Release Validation` 始终仅用于验证
- 真实发布路径必须使用预检期间使用的同一个 `npm_dist_tag`；工作流会在继续发布前验证该元数据
- 真实发布路径必须使用预检期间使用的相同 `npm_dist_tag`；工作流会在发布继续前验证该元数据
## 稳定版 npm 发布序列
## 稳定版 npm 发布顺序
发布稳定版 npm 版本时：
切出稳定版 npm 发布时：
1. 运行 `OpenClaw NPM Release`，并设置 `preflight_only=true`
- 在标签存在之前，你可以使用当前 workflow 分支的完整提交 SHA，对预检工作流进行仅验证的试运行
2. 对于正常的先 beta 后正式流程，选择 `npm_dist_tag=beta`；仅当你有意直接发布稳定版时才选择 `latest`
3. 当你希望通过一个手动工作流获得常规 CI 加实时 prompt cache、Docker、QA Lab、Matrix 和 Telegram 覆盖时，在发布分支、发布标签或完整提交 SHA 上运行 `Full Release Validation`
4. 如果你有意只需要确定性的常规测试图，请改为在发布引用上运行手动 `CI` 工作流
1. 使用 `preflight_only=true` 运行 `OpenClaw NPM Release`
- 在标签存在之前，你可以使用当前完整的工作流分支提交 SHA，对预检工作流进行仅验证空运行
2. 为常规 beta 优先流程选择 `npm_dist_tag=beta`，或仅在你有意直接发布稳定版时选择 `latest`
3. 当你希望从一个手动工作流获得常规 CI 加上实时提示缓存、Docker、QA Lab、Matrix 和 Telegram 覆盖时，在发布分支、发布标签或完整提交 SHA 上运行 `Full Release Validation`
4. 如果你明确只需要确定性的常规测试图，请改为在发布引用上运行手动 `CI` 工作流
5. 保存成功的 `preflight_run_id`
6. 再次运行 `OpenClaw NPM Release`，并设置 `preflight_only=false`、相同的
`tag`、相同的 `npm_dist_tag`，以及已保存的 `preflight_run_id`
7. 如果发布落在 `beta`，使用私有
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
工作流，将该稳定版本从 `beta` 推广到 `latest`
8. 如果发布有意直接发布到 `latest`，并且 `beta`
应立即跟随同一个稳定版构建，请使用同一个私有工作流将两个 dist-tag 都指向该稳定版本，或让其定时自愈同步稍后移动 `beta`
6. 使用相同的 `tag`、相同的 `npm_dist_tag` 和保存的 `preflight_run_id` 运行 `OpenClaw Release Publish`；它会先将外部化插件发布到 npm 和 ClawHub，再提升 OpenClaw npm 包
7. 如果发布落在 `beta` 上，请使用私有 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` 工作流，将该稳定版本从 `beta` 提升到 `latest`
8. 如果发布有意直接发布到 `latest`，且 `beta` 应立即跟随同一个稳定版构建，请使用同一个私有工作流将两个 dist-tag 都指向该稳定版本，或者让其计划的自修复同步稍后移动 `beta`
dist-tag 变更位于私有仓库中是出于安全考虑，因为它仍然需要
`NPM_TOKEN`，而公共仓库保持仅使用 OIDC 发布。
dist-tag 变更位于私有仓库中是出于安全考虑，因为它仍需要 `NPM_TOKEN`，而公共仓库保持仅使用 OIDC 发布。
这样会让直接发布路径和先 beta 后推广路径都被记录下来，并且对操作员可见。
这让直接发布路径和 beta 优先提升路径都保持文档化，并且对操作员可见。
如果维护者必须回退到本地 npm 身份验证，只能在专用 tmux 会话中运行任何 1Password
CLI（`op`）命令。不要直接从主 agent shell 调用 `op`；将其放在 tmux 中可以让提示、警报和 OTP 处理可观察，并防止重复的主机警报。
如果维护者必须回退到本地 npm 身份验证，请只在专用 tmux 会话中运行任何 1Password CLI（`op`）命令。不要从主智能体 shell 直接调用 `op`；将其保持在 tmux 内可让提示、警报和 OTP 处理可观察，并防止重复的主机警报。
## 公共参考

49
docs/zh-CN/tools/brave-search.md
View File

@ -1,27 +1,27 @@
---
read_when:
- 你想使用 Brave Search 进行 web_search
- 你需要 BRAVE_API_KEY 或套餐详细信息
- 你需要 BRAVE_API_KEY 或套餐详情
summary: 用于 web_search 的 Brave Search API 设置
title: Brave 搜索
x-i18n:
generated_at: "2026-05-02T03:43:37Z"
generated_at: "2026-05-02T06:53:20Z"
model: gpt-5.5
provider: openai
source_hash: d5b6624d078ba55e30fbac4dd863a0d016e2e8d160e32bcc406e5070998241ba
source_hash: 06cfef368f01d0af91ddb4e8adc13b7699019cbf662783b88c573049bfb77e18
source_path: tools/brave-search.md
workflow: 16
---
# Brave Search API
OpenClaw 支持将 Brave Search API 作为 `web_search` 提供商。
OpenClaw 支持将 Brave Search API 用作 `web_search` 提供商。
## 获取 API 密钥
## 获取 API key
1. 在 [https://brave.com/search/api/](https://brave.com/search/api/) 创建 Brave Search API 账户
2. 在仪表板中，选择 **Search** 套餐并生成 API 密钥。
3. 将密钥存储在配置中，或在 Gateway 网关环境中设置 `BRAVE_API_KEY`。
1. 在 [https://brave.com/search/api/](https://brave.com/search/api/) 创建 Brave Search API 账号
2. 在仪表板中，选择 **Search** 方案并生成 API key。
3. 将该键存储在配置中，或在 Gateway 网关环境中设置 `BRAVE_API_KEY`。
## 配置示例
@ -51,13 +51,13 @@ OpenClaw 支持将 Brave Search API 作为 `web_search` 提供商。
}
```
Brave 专用的搜索设置现在位于 `plugins.entries.brave.config.webSearch.*` 下。
Brave 提供商专用搜索设置现在位于 `plugins.entries.brave.config.webSearch.*` 下。
旧版 `tools.web.search.apiKey` 仍会通过兼容性 shim 加载，但它不再是规范配置路径。
`webSearch.mode` 控制 Brave 传输方式：
- `web`（默认）：普通 Brave 网页搜索，包含标题、URL 和摘要片段
- `llm-context`：Brave LLM Context API，包含预提取的文本块和用于依据溯源的来源
- `llm-context`：Brave LLM Context API，包含预提取的文本块和用于依据来源的来源信息
## 工具参数
@ -66,7 +66,7 @@ Brave 专用的搜索设置现在位于 `plugins.entries.brave.config.webSearch.
</ParamField>
<ParamField path="count" type="number" default="5">
返回的结果数量（1–10）。
要返回的结果数量（1–10）。
</ParamField>
<ParamField path="country" type="string">
@ -86,15 +86,15 @@ UI 元素的 ISO 语言代码。
</ParamField>
<ParamField path="freshness" type="'day' | 'week' | 'month' | 'year'">
时间筛选器 — `day` 表示 24 小时。
时间过滤器 — `day` 表示 24 小时。
</ParamField>
<ParamField path="date_after" type="string">
仅返回此日期之后发布的结果（`YYYY-MM-DD`）。
仅返回在此日期之后发布的结果（`YYYY-MM-DD`）。
</ParamField>
<ParamField path="date_before" type="string">
仅返回此日期之前发布的结果（`YYYY-MM-DD`）。
仅返回在此日期之前发布的结果（`YYYY-MM-DD`）。
</ParamField>
**示例：**
@ -121,18 +121,19 @@ await web_search({
});
```
## 备注
## 说明
- OpenClaw 使用 Brave **Search** 套餐。如果你有旧版订阅（例如原始 Free 套餐，每月 2,000 次查询），它仍然有效，但不包含 LLM Context 或更高速率限制等较新功能。
- 每个 Brave 套餐都包含**每月 \$5 免费额度**（会续期）。Search 套餐每 1,000 次请求收费 \$5，因此该额度可覆盖每月 1,000 次查询。请在 Brave 仪表板中设置你的用量限制，以避免意外收费。有关当前套餐，请参阅 [Brave API 门户](https://brave.com/search/api/)。
- Search 套餐包含 LLM Context 端点和 AI 推理权利。若要存储结果以训练或调优模型，需要具有明确存储权利的套餐。请参阅 Brave [服务条款](https://api-dashboard.search.brave.com/terms-of-service)。
- `llm-context` 模式返回基于依据溯源的来源条目，而不是普通网页搜索摘要片段格式。
- `llm-context` 模式支持 `freshness` 和有边界的 `date_after` + `date_before` 范围。它不支持 `ui_lang`；不带 `date_after` 的 `date_before` 会被拒绝，因为 Brave 要求自定义新鲜度范围同时包含开始日期和结束日期。
- OpenClaw 使用 Brave **Search** 方案。如果你有旧版订阅（例如原始的每月 2,000 次查询 Free 方案），它仍然有效，但不包含 LLM Context 或更高频率限制等较新功能。
- 每个 Brave 方案都包含 **每月 \$5 免费额度**（会续期）。Search 方案价格为每 1,000 次请求 \$5，因此该额度可覆盖每月 1,000 次查询。请在 Brave 仪表板中设置你的用量限制，以避免意外收费。有关当前方案，请参阅 [Brave API 门户](https://brave.com/search/api/)。
- Search 方案包含 LLM Context 端点和 AI 推理权限。存储结果以训练或调优模型需要具有明确存储权限的方案。请参阅 Brave [服务条款](https://api-dashboard.search.brave.com/terms-of-service)。
- `llm-context` 模式返回有依据来源的来源条目，而不是普通网页搜索摘要形态。
- `llm-context` 模式支持 `freshness` 以及有界的 `date_after` + `date_before` 范围。它不支持 `ui_lang`；没有 `date_after` 的 `date_before` 会被拒绝，因为 Brave 要求自定义 freshness 范围同时包含开始日期和结束日期。
- `ui_lang` 必须包含区域子标签，例如 `en-US`。
- 默认情况下，结果会缓存 15 分钟（可通过 `cacheTtlMinutes` 配置）。
- 结果默认缓存 15 分钟（可通过 `cacheTtlMinutes` 配置）。
- 启用 `brave.http` 诊断标志，可在故障排除时记录 Brave 请求 URL/查询参数、响应状态/耗时，以及搜索缓存命中/未命中/写入事件。该标志绝不会记录 API key 或响应正文，但搜索查询可能包含敏感信息。
## 相关内容
- [网页搜索概览](/zh-CN/tools/web) -- 所有提供商和自动检测
- [Perplexity Search](/zh-CN/tools/perplexity-search) -- 带域名过滤的结构化结果
- [Exa Search](/zh-CN/tools/exa-search) -- 带内容提取的神经搜索
- [Web 搜索概览](/zh-CN/tools/web) -- 所有提供商和自动检测
- [Perplexity Search](/zh-CN/tools/perplexity-search) -- 支持域名过滤的结构化结果
- [Exa Search](/zh-CN/tools/exa-search) -- 支持内容提取的神经搜索