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 21:51:39 +00:00
parent acb369fdd9
commit 85fdc5fc09
4 changed files with 411 additions and 470 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,94 +1,94 @@
---
read_when:
- 你需要了解 CI 作业为何运行或未运行
- 你正在调试一个未通过的 GitHub Actions 检查
- 你正在协调一次发布验证运行或重新运行
- 你正在更改 ClawSweeper 派发或 GitHub 活动转发
summary: CI 作业图、范围门禁、发布总括项和本地命令等效项
- 你需要了解为什么某个 CI 作业运行了或没有运行
- 你正在调试一个失败的 GitHub Actions 检查
- 你正在协调一次发布验证的运行或重新运行
- 你正在更改 ClawSweeper 调度或 GitHub 活动转发
summary: CI 作业图、范围门控、发布总括以及本地命令等效项
title: CI 流水线
x-i18n:
generated_at: "2026-05-02T20:01:43Z"
generated_at: "2026-05-02T21:49:12Z"
model: gpt-5.5
provider: openai
source_hash: 39410c5ceb3598e9e1771f98fba79485b13967df372c7a3f55ef5a5350416435
source_hash: a8033b928b26adfa340200ea69fd63d339a6e65c21659b8119a68b23b8b16016
source_path: ci.md
workflow: 16
---
OpenClaw CI 会在每次推送到 `main` 以及每个拉取请求时运行。`preflight` 作业会对差异进行分类，并在只有无关区域发生更改时关闭昂贵的通道。手动 `workflow_dispatch` 运行会有意绕过智能范围限定，并为候选发布和广泛验证展开完整图。Android 通道继续通过 `include_android` 保持选择加入。仅发布使用的插件覆盖范围位于单独的 [`插件预发布`](#plugin-prerelease) 工作流中，并且只会从 [`全量发布验证`](#full-release-validation) 或显式手动调度运行。
OpenClaw CI 会在每次推送到 `main` 和每个拉取请求时运行。`preflight` 作业会对 diff 进行分类，并在只有无关区域发生变化时关闭昂贵的 lanes。手动 `workflow_dispatch` 运行会有意绕过智能作用域划分，并为发布候选版本和广泛验证展开完整图。Android lanes 通过 `include_android` 保持选择启用。仅发布时的插件覆盖率位于单独的 [`插件预发布`](#plugin-prerelease) 工作流中，并且只会从 [`完整发布验证`](#full-release-validation) 或显式手动分发运行。
## 管道概览
## 流水线概览
| 作业 | 用途 | 运行时机 |
| -------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | 检测仅文档变更、变更范围、变更插件，并构建 CI 清单 | 始终在非草稿推送和 PR 上运行 |
| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 始终在非草稿推送和 PR 上运行 |
| `security-dependency-audit` | 针对 npm 公告执行无依赖的生产 lockfile 审计 | 始终在非草稿推送和 PR 上运行 |
| `security-fast` | 快速安全作业的必需聚合项 | 始终在非草稿推送和 PR 上运行 |
| `check-dependencies` | 仅生产 Knip 依赖检查，以及未使用文件 allowlist 防护 | 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、防护、测试类型和严格 smoke | Node 相关变更 |
| `check-additional` | 架构、边界、插件表面防护、包边界和 gateway-watch 分片 | Node 相关变更 |
| `build-smoke` | 已构建 CLI 的 smoke 测试和启动内存 smoke | Node 相关变更 |
| `checks` | 已构建产物渠道测试的验证器 | Node 相关变更 |
| `checks-node-compat-node22` | Node 22 兼容性构建和 smoke 通道 | 发布使用的手动 CI 调度 |
| `check-docs` | 文档格式、lint 和断链检查 | 文档已变更 |
| `skills-python` | 针对 Python 支持的 Skills 运行 Ruff + pytest | Python skill 相关变更 |
| `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 成功或手动调度 |
| `openclaw-performance` | 每日/按需生成 Kova 运行时性能报告，包含 mock-provider、deep-profile 和 GPT 5.4 实时通道 | 定时和手动调度 |
| 作业 | 目的 | 运行时机 |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | 检测仅文档变更、变更作用域、变更 extensions，并构建 CI 清单 | 始终在非草稿推送和 PR 上运行 |
| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 始终在非草稿推送和 PR 上运行 |
| `security-dependency-audit` | 针对 npm advisories 的无依赖生产 lockfile 审计 | 始终在非草稿推送和 PR 上运行 |
| `security-fast` | 快速安全作业的必需聚合 | 始终在非草稿推送和 PR 上运行 |
| `check-dependencies` | 生产 Knip 仅依赖检查，以及未使用文件 allowlist 保护 | Node 相关变更 |
| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查，以及可复用下游产物 | Node 相关变更 |
| `checks-fast-core` | 快速 Linux 正确性 lanes，例如内置/插件契约/协议检查 | Node 相关变更 |
| `checks-fast-contracts-channels` | 分片的渠道契约检查，并提供稳定的聚合检查结果 | Node 相关变更 |
| `checks-node-core-test` | 核心 Node 测试分片，不包括渠道、内置、契约和 extension lanes | Node 相关变更 |
| `check` | 分片的主本地 gate 等价项：生产类型、lint、guards、测试类型和严格 smoke | Node 相关变更 |
| `check-additional` | 架构、边界、提示词快照漂移、extension 表面 guards、包边界和 gateway-watch 分片 | Node 相关变更 |
| `build-smoke` | 已构建 CLI 的 smoke 测试和启动内存 smoke | Node 相关变更 |
| `checks` | 已构建产物渠道测试的验证器 | Node 相关变更 |
| `checks-node-compat-node22` | Node 22 兼容性构建和 smoke lane | 用于发布的手动 CI 分发 |
| `check-docs` | 文档格式、lint 和断链检查 | 文档变更 |
| `skills-python` | 针对 Python 支持的 Skills 的 Ruff + pytest | Python Skill 相关变更 |
| `checks-windows` | Windows 特定进程/路径测试，以及共享运行时导入说明符回归 | Windows 相关变更 |
| `macos-node` | 使用共享构建产物的 macOS TypeScript 测试 lane | macOS 相关变更 |
| `macos-swift` | macOS 应用的 Swift lint、构建和测试 | macOS 相关变更 |
| `android` | 两种 flavor 的 Android 单元测试，以及一次 debug APK 构建 | Android 相关变更 |
| `test-performance-agent` | 受信任活动之后的每日 Codex 慢测试优化 | 主 CI 成功或手动分发 |
| `openclaw-performance` | 每日/按需的 Kova 运行时性能报告，包含 mock-provider、deep-profile 和 GPT 5.4 live lanes | 定时和手动分发 |
## 快速失败顺序
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` 决定哪些 lanes 根本存在。`docs-scope` 和 `changed-scope` 逻辑是此作业内的步骤，而不是独立作业。
2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，而不等待更重的产物和平台矩阵作业。
3. `build-artifacts` 会与快速 Linux lanes 重叠，因此下游消费者可以在共享构建就绪后立即开始。
4. 更重的平台和运行时 lanes 随后展开：`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` ref 上有更新的推送落地时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一 ref 的最新运行也失败，否则将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已经被取代后继续排队。自动 CI 并发 key 带有版本号（`CI-v7-*`），因此 GitHub 侧旧队列组中的僵尸任务无法无限期阻塞更新的 main 运行。手动全套件运行使用 `CI-manual-v1-*`，且不会取消进行中的运行。
## 范围和路由
## 作用域和路由
范围逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。手动调度会跳过 changed-scope 检测，并让 preflight 清单表现得像每个限定范围区域都发生了变更。
作用域逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。手动分发会跳过变更作用域检测，并让 preflight 清单表现得像每个有作用域的区域都发生了变化。
- **CI 工作流编辑**会验证 Node CI 图和工作流 lint，但不会单独强制运行 Windows、Android 或 macOS 原生构建；这些平台通道仍限定到平台源代码变更。
- **仅 CI 路由编辑、选定的廉价核心测试 fixture 编辑，以及窄范围的插件契约 helper/测试路由编辑**会使用快速的仅 Node 清单路径：`preflight`、安全检查和一个 `checks-fast-core` 任务。当变更仅限于该快速任务直接覆盖的路由或 helper 表面时，此路径会跳过构建产物、Node 22 兼容性、渠道契约、完整核心分片、内置插件分片，以及额外防护矩阵。
- **Windows Node 检查**限定到 Windows 特定的进程/路径 wrapper、npm/pnpm/UI runner helper、包管理器配置，以及执行该通道的 CI 工作流表面；无关的源代码、插件、install-smoke 和仅测试变更会留在 Linux Node 通道上。
- **CI 工作流编辑** 会验证 Node CI 图和工作流 lint，但本身不会强制触发 Windows、Android 或 macOS 原生构建；这些平台 lanes 仍限定于平台源代码变更。
- **仅 CI 路由编辑、选定的廉价核心测试 fixture 编辑，以及窄范围插件契约 helper/test-routing 编辑** 使用快速的仅 Node 清单路径：`preflight`、security，以及单个 `checks-fast-core` 任务。当变更仅限于该快速任务直接覆盖的路由或 helper 表面时，此路径会跳过构建产物、Node 22 兼容性、渠道契约、完整核心分片、内置插件分片和额外 guard 矩阵。
- **Windows Node 检查** 限定于 Windows 特定进程/路径 wrapper、npm/pnpm/UI runner helper、包管理器配置，以及执行该 lane 的 CI 工作流表面；无关的源代码、插件、install-smoke 和仅测试变更仍停留在 Linux Node lanes 上。
最慢的 Node 测试系列会被拆分或平衡，让每个作业保持较小规模，同时不过度预留 runner：渠道契约作为三个加权分片运行，小型核心单元通道会成对运行，auto-reply 作为四个平衡 worker 运行（reply 子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片），agentic gateway/插件配置会分布在现有的仅源码 agentic Node 作业中，而不是等待构建产物。广泛的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件兜底配置。include-pattern 分片使用 CI 分片名称记录计时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分整个配置与经过过滤的分片。`check-additional` 将包边界编译/canary 工作放在一起，并将运行时拓扑架构与 Gateway 网关 watch 覆盖范围分开；边界防护分片会在一个作业内并发运行它的小型独立防护。Gateway 网关 watch、渠道测试和核心支持边界分片会在 `dist/` 和 `dist-runtime/` 已经构建完成后，在 `build-artifacts` 内并发运行。
最慢的 Node 测试族会被拆分或均衡，让每个作业保持较小规模且不过度预留 runner：渠道契约作为三个加权分片运行，小型核心单元 lanes 会配对，auto-reply 作为四个均衡 worker 运行（reply 子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片），agentic gateway/插件配置会分散到现有的仅源代码 agentic Node 作业中，而不是等待构建产物。广泛的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件总括配置。include-pattern 分片使用 CI 分片名称记录 timing 条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分整个配置和过滤后的分片。`check-additional` 会将包边界编译/canary 工作放在一起，并将运行时拓扑架构与 gateway watch 覆盖率分开；boundary guard 分片会在一个作业内并发运行其小型独立 guards，包括 `pnpm prompt:snapshots:check`，因此 Codex happy-path 提示词漂移会固定到造成它的 PR 上。Gateway watch、渠道测试和核心支持边界分片会在 `dist/` 和 `dist-runtime/` 已经构建完成后，在 `build-artifacts` 内并发运行。
Android CI 会运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。third-party flavor 没有单独的 source set 或 manifest；它的单元测试通道仍会使用 SMS/通话记录 BuildConfig 标志编译该 flavor，同时避免在每个 Android 相关推送上重复执行 debug APK 打包作业。
Android CI 会运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的 source set 或 manifest；它的单元测试 lane 仍会使用 SMS/call-log BuildConfig flags 编译该 flavor，同时避免在每个 Android 相关推送上重复执行 debug APK 打包作业。
`check-dependencies` 分片会运行 `pnpm deadcode:dependencies`（一个仅生产 Knip 依赖检查，固定到最新 Knip 版本，并在 `dlx` 安装时禁用 pnpm 的 minimum release age）和 `pnpm deadcode:unused-files`，后者会将 Knip 的生产未使用文件发现结果与 `scripts/deadcode-unused-files.allowlist.mjs` 进行比较。当 PR 添加了新的未经审查的未使用文件，或留下过期 allowlist 条目时，未使用文件防护会失败，同时保留 Knip 无法静态解析的有意动态插件、生成文件、构建、实时测试和包桥接表面。
`check-dependencies` 分片运行 `pnpm deadcode:dependencies`（生产 Knip 仅依赖检查，固定到最新 Knip 版本，并为 `dlx` 安装禁用 pnpm 的最低发布年龄）和 `pnpm deadcode:unused-files`，后者会将 Knip 的生产未使用文件发现结果与 `scripts/deadcode-unused-files.allowlist.mjs` 进行比较。当 PR 添加新的未经审查未使用文件，或留下陈旧 allowlist 条目时，未使用文件 guard 会失败，同时保留 Knip 无法静态解析的有意动态插件、生成产物、构建、live-test 和包桥接表面。
## ClawSweeper 活动转发
`.github/workflows/clawsweeper-dispatch.yml` 是从 OpenClaw 仓库活动到 ClawSweeper 的目标侧桥接。它不会检出或执行不可信的拉取请求代码。该工作流会从 `CLAWSWEEPER_APP_PRIVATE_KEY` 创建 GitHub App token，然后向 `openclaw/clawsweeper` 调度紧凑的 `repository_dispatch` payload。
`.github/workflows/clawsweeper-dispatch.yml` 是从 OpenClaw 仓库活动到 ClawSweeper 的目标侧桥接。它不会 checkout 或执行不受信任的拉取请求代码。该工作流会从 `CLAWSWEEPER_APP_PRIVATE_KEY` 创建 GitHub App token，然后向 `openclaw/clawsweeper` 分发紧凑的 `repository_dispatch` payload。
该工作流有四条通道：
该工作流有四个 lanes：
- `clawsweeper_item` 用于精确的 issue 和拉取请求审查请求；
- `clawsweeper_item` 用于精确 issue 和拉取请求审查请求；
- `clawsweeper_comment` 用于 issue 评论中的显式 ClawSweeper 命令；
- `clawsweeper_commit_review` 用于 `main` 推送上的提交级审查请求；
- `clawsweeper_commit_review` 用于 `main` 推送上的 commit 级审查请求；
- `github_activity` 用于 ClawSweeper 智能体可能检查的一般 GitHub 活动。
`github_activity` 通道只转发规范化的元数据：事件类型、动作、参与者、仓库、条目编号、URL、标题、状态，以及存在评论或审查时的短摘录。它有意避免转发完整 webhook body。`openclaw/clawsweeper` 中的接收工作流是 `.github/workflows/github-activity.yml`，该工作流会将规范化事件发布到面向 ClawSweeper 智能体的 OpenClaw Gateway 网关 hook。
`github_activity` lane 只转发规范化元数据：事件类型、action、actor、repository、item number、URL、title、state，以及存在评论或 review 时的短摘录。它有意避免转发完整 webhook body。`openclaw/clawsweeper` 中的接收工作流是 `.github/workflows/github-activity.yml`，它会将规范化事件发布到 ClawSweeper 智能体的 OpenClaw Gateway 网关 hook。
一般活动是观察，而不是默认投递。ClawSweeper 智能体会在其 prompt 中收到 Discord 目标，并且只有当事件令人意外、可执行、有风险或对运营有用时，才应发布到 `#clawsweeper`。例行打开、编辑、机器人噪音、重复 webhook 噪音以及正常审查流量应返回 `NO_REPLY`。
一般活动是观察，而不是默认交付。ClawSweeper 智能体会在提示词中收到 Discord 目标，并且只应在事件出人意料、可操作、有风险或具有运维价值时发布到 `#clawsweeper`。常规打开、编辑、bot churn、重复 webhook 噪声和正常 review 流量应产生 `NO_REPLY`。
在整个路径中，都应将 GitHub 标题、评论、正文、审查文本、分支名称和提交消息视为不可信数据。它们是摘要和分流的输入，而不是工作流或智能体运行时的指令。
在整个路径中，将 GitHub 标题、评论、正文、review 文本、分支名称和 commit 消息视为不受信任的数据。它们是用于摘要和 triage 的输入，而不是工作流或智能体运行时的指令。
## 手动调度
## 手动分发
手动 CI 调度运行与常规 CI 相同的任务图，但会强制开启每个非 Android 范围的 lane：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 lane 都不包含在 CI 中。Docker 预发布套件仅在 `Full 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 预发布套件仅在 `Full Release Validation` 分发启用发布验证门禁的独立 `Plugin Prerelease` 工作流时运行。
手动运行使用唯一的并发组，因此候选发布的完整套件不会被同一 ref 上的另一个 push 或 PR 运行取消。可选的 `target_ref` 输入允许受信任的调用方在使用所选调度 ref 中的工作流文件时，针对分支、标签或完整提交 SHA 运行该任务图。
手动运行使用唯一的并发组，因此发布候选完整套件不会被同一 ref 上的另一个 push 或 PR 运行取消。可选的 `target_ref` 输入允许可信调用方使用所选分发 ref 中的工作流文件，针对分支、标签或完整提交 SHA 运行该作业图。
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -98,12 +98,12 @@ 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 preflight 也使用 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` |
@ -135,32 +135,32 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac
pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.json --output .artifacts/kova/summary.md
```
## OpenClaw Performance
## OpenClaw 性能
`OpenClaw Performance` 是产品/运行时性能工作流。它每天在 `main` 上运行，也可以手动调度：
`OpenClaw Performance` 是产品/运行时性能工作流。它每天在 `main` 上运行，也可以手动分发：
```bash
gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3
gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1 -f deep_profile=true -f live_gpt54=true
```
该工作流从固定发布版本安装 OCM，并从固定的 `kova_ref` 输入安装 Kova，然后运行三个 lane：
该工作流从固定发布版本安装 OCM，并从固定的 `kova_ref` 输入安装 Kova，然后运行三个通道：
- `mock-provider`：使用确定性的假 OpenAI 兼容凭证，针对本地构建运行时运行 Kova 诊断场景。
- `mock-deep-profile`：针对启动、gateway 和 agent-turn 热点进行 CPU/堆/trace 分析。
- `live-gpt54`：一次真实的 OpenAI `openai/gpt-5.4` agent turn，在 `OPENAI_API_KEY` 不可用时跳过。
- `mock-provider`：针对本地构建运行时运行 Kova 诊断场景，并使用确定性的假 OpenAI 兼容认证。
- `mock-deep-profile`：针对启动、Gateway 网关和智能体轮次热点进行 CPU/heap/trace 性能剖析。
- `live-gpt54`：真实的 OpenAI `openai/gpt-5.4` 智能体轮次，在 `OPENAI_API_KEY` 不可用时跳过。
mock-provider lane 还会在 Kova 通过后运行 OpenClaw 原生源码探针：覆盖默认、hook 和 50 插件启动场景的 gateway 启动耗时和内存；重复的 mock-OpenAI `channel-chat-baseline` hello 循环；以及针对已启动 gateway 的 CLI 启动命令。源码探针的 Markdown 摘要位于报告包中的 `source/index.md`，原始 JSON 位于其旁边。
mock-provider 通道还会在 Kova 通过后运行 OpenClaw 原生源码探针：默认、钩子和 50 插件启动场景下的 Gateway 网关启动耗时与内存；重复的 mock-OpenAI `channel-chat-baseline` hello 循环；以及针对已启动 Gateway 网关的 CLI 启动命令。源码探针 Markdown 摘要位于报告包中的 `source/index.md`，原始 JSON 位于其旁边。
每个 lane 都会上传 GitHub artifact。当配置了 `CLAWGRIT_REPORTS_TOKEN` 时，该工作流还会将 `report.json`、`report.md`、bundle、`index.md` 和源码探针 artifact 提交到 `openclaw/clawgrit-reports` 中的 `openclaw-performance/<ref>/<run-id>-<attempt>/<lane>/` 下。当前分支指针会写入 `openclaw-performance/<ref>/latest-<lane>.json`。
每个通道都会上传 GitHub 构件。配置 `CLAWGRIT_REPORTS_TOKEN` 后，工作流还会将 `report.json`、`report.md`、包、`index.md` 和源码探针构件提交到 `openclaw/clawgrit-reports` 的 `openclaw-performance/<ref>/<run-id>-<attempt>/<lane>/` 下。当前分支指针会写入 `openclaw-performance/<ref>/latest-<lane>.json`。
## 完整发布验证
`Full Release Validation` 是用于“发布前运行所有内容”的手动总控工作流。它接受分支、标签或完整提交 SHA，使用该目标调度手动 `CI` 工作流，为仅发布使用的插件/包/静态/Docker 证明调度 `Plugin Prerelease`，并为安装冒烟、包验收、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram lane 调度 `OpenClaw Release Checks`。在 `rerun_group=all` 且 `release_profile=full` 时，它还会针对发布检查中的 `release-package-under-test` artifact 运行 `NPM Telegram Beta E2E`。发布后，传入 `npm_telegram_package_spec` 以针对已发布的 npm 包重新运行同一个 Telegram 包 lane。
`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-package-under-test` 构件运行 `NPM Telegram Beta E2E`。发布后，传入 `npm_telegram_package_spec` 可针对已发布的 npm 包重新运行同一个 Telegram 包通道。
请参阅[完整发布验证](/zh-CN/reference/full-release-validation)，了解阶段矩阵、确切的工作流任务名称、profile 差异、artifact 以及聚焦重跑句柄。
请参阅[完整发布验证](/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 preflight 成功后，从 `release/YYYY.M.D` 或 `main` 分发它。它会验证 `pnpm plugins:sync:check`，为所有可发布插件包分发 `Plugin NPM Release`，为同一发布 SHA 分发 `Plugin ClawHub Release`，然后才使用保存的 `preflight_run_id` 分发 `OpenClaw NPM Release`。
```bash
gh workflow run openclaw-release-publish.yml \
@ -170,35 +170,35 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
对于快速移动分支上的固定提交证明，请使用辅助命令，而不是 `gh workflow run ... --ref main -f ref=<sha>`：
要在快速移动的分支上提供固定提交证明，请使用辅助命令，而不是 `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 工作流分发 ref 必须是分支或标签，不能是原始提交 SHA。该辅助命令会在目标 SHA 处推送一个临时 `release-ci/<sha>-...` 分支，从该固定 ref 分发 `Full Release Validation`，验证每个子工作流的 `headSha` 与目标匹配，并在运行完成后删除临时分支。如果任何子工作流在不同的 SHA 上运行，总控验证器也会失败。
`release_profile` 控制传入发布检查的 live/provider 覆盖范围。手动发布工作流默认使用 `stable`；仅在你有意需要广泛的 advisory provider/media 矩阵时使用 `full`。
`release_profile` 控制传入发布检查的 live/提供商覆盖范围。手动发布工作流默认使用 `stable`；仅当你有意需要广泛的 advisory 提供商/媒体矩阵时，才使用 `full`。
- `minimum` 保留最快的 OpenAI/核心发布关键 lane。
- `stable` 添加稳定的 provider/backend 集合。
- `full` 运行广泛的 advisory provider/media 矩阵。
- `minimum` 保留最快的 OpenAI/核心发布关键通道。
- `stable` 添加稳定的提供商/后端集合。
- `full` 运行广泛的 advisory 提供商/媒体矩阵。
总控会记录已调度的子运行 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` 使用可信工作流引用，将选定引用解析一次为 `release-package-under-test` tarball，然后把该构件传给实时/E2E 发布路径 Docker 工作流和软件包验收分片。这能让发布环境之间的软件包字节保持一致，并避免在多个子任务中重复打包同一个候选版本。
`OpenClaw Release Checks` 使用受信任的工作流引用将所选引用解析一次，生成 `release-package-under-test` tarball，然后将该构件传递给 live/E2E 发布路径 Docker 工作流和软件包验收分片。这样可以让各个发布环境中的软件包字节保持一致，并避免在多个子任务中重新打包同一个候选包。
对于 `ref=main` 和 `rerun_group=all` 的重复 `Full Release Validation` 运行，会取代较旧的总控工作流。当父监控器被取消时，它会取消已经分发的所有子工作流，因此较新的 main 验证不会排在过期的两小时发布检查运行后面。发布分支/标签验证和聚焦重跑分组会保持 `cancel-in-progress: false`。
`ref=main` 且 `rerun_group=all` 的重复 `Full Release Validation` 运行会取代较旧的总控流程。父级监控器在父流程被取消时，会取消它已经派发的任何子工作流，因此较新的 main 验证不会排在过期的两小时发布检查运行之后。发布分支/标签验证和针对性重跑分组会保持 `cancel-in-progress: false`。
## 实时和 E2E 分片
## Live 和 E2E 分片
发布实时/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`
- 按提供商过滤的 `native-live-src-gateway-profiles` 任务
- 提供商过滤后的 `native-live-src-gateway-profiles` 任务
- `native-live-src-gateway-backends`
- `native-live-test`
- `native-live-extensions-a-k`
@ -206,64 +206,64 @@ GitHub 工作流调度 ref 必须是分支或标签，不能是原始提交 SHA
- `native-live-extensions-openai`
- `native-live-extensions-o-z-other`
- `native-live-extensions-xai`
- 拆分后的媒体音频/视频分片，以及按提供商过滤的音乐分片
- 拆分后的媒体音频/视频分片和提供商过滤后的音乐分片
这会保持相同的文件覆盖，同时让较慢的实时提供商失败更容易重跑和诊断。聚合的 `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` 分片名称仍可用于手动一次性重跑。
原生实时媒体分片在 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中运行，该镜像由 `Live Media Runner Image` 工作流构建。该镜像预安装了 `ffmpeg` 和 `ffprobe`；媒体任务只会在设置前验证这些二进制文件。将 Docker 支持的实时套件保留在普通 Blacksmith 运行器上，容器任务不适合启动嵌套 Docker 测试。
原生 live 媒体分片在 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中运行，该镜像由 `Live Media Runner Image` 工作流构建。该镜像预装了 `ffmpeg` 和 `ffprobe`；媒体任务只会在设置前验证这些二进制文件。让 Docker 支持的 live 套件继续在普通 Blacksmith runner 上运行，容器任务并不适合启动嵌套 Docker 测试。
Docker 支持的实时模型/后端分片会为每个选定提交使用单独的共享 `ghcr.io/openclaw/openclaw-live-test:<sha>` 镜像。实时发布工作流会构建并推送该镜像一次，然后 Docker 实时模型、按提供商分片的 Gateway 网关、CLI 后端、ACP 绑定和 Codex harness 分片会带着 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。Gateway 网关 Docker 分片带有显式脚本级 `timeout` 上限，低于工作流任务超时，因此卡住的容器或清理路径会快速失败，而不是消耗整个发布检查预算。如果这些分片独立重建完整源 Docker 目标，则说明发布运行配置错误，并会把墙钟时间浪费在重复镜像构建上。
Docker 支持的 live 模型/后端分片会针对每个所选提交使用单独共享的 `ghcr.io/openclaw/openclaw-live-test:<sha>` 镜像。live 发布工作流会构建并推送该镜像一次，然后 Docker live 模型、按提供商分片的 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` 构件上传，并在 GitHub 步骤摘要中打印来源、工作流引用、软件包引用、版本、SHA-256 和配置档。
2. `docker_acceptance` 使用 `ref=workflow_ref` 和 `package_artifact_name=package-under-test` 调用 `openclaw-live-and-e2e-checks-reusable.yml`。可复用工作流会下载该构件，验证 tarball 清单，在需要时准备软件包摘要 Docker 镜像，并针对该软件包运行选定的 Docker lanes，而不是打包工作流检出内容。当某个配置档选择多个目标 `docker_lanes` 时，可复用工作流会准备一次软件包和共享镜像，然后将这些 lanes 扇出为并行的目标 Docker 任务，并使用唯一构件。
3. `package_telegram` 可选调用 `NPM Telegram Beta E2E`。当 `telegram_mode` 不是 `none` 时运行；如果软件包验收解析了一个 `package-under-test` 构件，它会安装同一个构件；独立 Telegram 分发仍可安装已发布的 npm 规范。
4. 如果软件包解析、Docker 验收或可选 Telegram lane 失败，`summary` 会使工作流失败。
1. `resolve_package` 会检出 `workflow_ref`，解析一个软件包候选，写入 `.artifacts/docker-e2e-package/openclaw-current.tgz`，写入 `.artifacts/docker-e2e-package/package-candidate.json`，将二者作为 `package-under-test` 构件上传，并在 GitHub 步骤摘要中打印来源、工作流引用、软件包引用、版本、SHA-256 和配置档。
2. `docker_acceptance` 会调用 `openclaw-live-and-e2e-checks-reusable.yml`，并传入 `ref=workflow_ref` 和 `package_artifact_name=package-under-test`。该可复用工作流会下载该构件，验证 tarball 清单，在需要时准备软件包摘要 Docker 镜像，并针对该软件包运行所选 Docker 通道，而不是打包工作流检出内容。当某个配置档选择多个定向 `docker_lanes` 时，可复用工作流会先准备一次软件包和共享镜像，然后将这些通道作为并行定向 Docker 任务展开，并生成唯一构件。
3. `package_telegram` 可选调用 `NPM Telegram Beta E2E`。当 `telegram_mode` 不是 `none` 时它会运行，并且在软件包验收已解析出软件包时安装同一个 `package-under-test` 构件；独立的 Telegram 派发仍可安装已发布的 npm 规格。
4. `summary` 会在软件包解析、Docker 验收或可选 Telegram 通道失败时让工作流失败。
### 候选来源
- `source=npm` 只接受 `openclaw@alpha`、`openclaw@beta`、`openclaw@latest` 或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。用于已发布的预发布/稳定版验收。
- `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` 可选，但对于外部共享构件应提供。
- `source=npm` 只接受 `openclaw@alpha`、`openclaw@beta`、`openclaw@latest`，或类似 `openclaw@2026.4.27-beta.2` 的精确 OpenClaw 发布版本。使用它来验收已发布的预发布版/稳定版。
- `source=ref` 会打包受信任的 `package_ref` 分支、标签或完整提交 SHA。解析器会获取 OpenClaw 分支/标签，验证所选提交可从仓库分支历史或发布标签访问，在分离工作树中安装依赖，并使用 `scripts/package-openclaw-for-docker.mjs` 打包。
- `source=url` 会下载 HTTPS `.tgz`；必须提供 `package_sha256`。
- `source=artifact` 会从 `artifact_run_id` 和 `artifact_name` 下载一个 `.tgz`；`package_sha256` 可选，但对于外部共享的构件应提供它。
保持 `workflow_ref` 和 `package_ref` 分离。`workflow_ref` 是运行测试的可信工作流/harness 代码。`package_ref` 是当 `source=ref` 时要打包的源提交。这让当前测试 harness 能够验证较旧的可信源提交，而不运行旧的工作流逻辑。
保持 `workflow_ref` 和 `package_ref` 分离。`workflow_ref` 是运行测试的受信任工作流/harness 代码。`package_ref` 是在 `source=ref` 时会被打包的源提交。这样，当前测试 harness 可以验证较旧的受信任源提交，而无需运行旧的工作流逻辑。
### 套件配置档
- `smoke` — `npm-onboard-channel-agent`、`gateway-network`、`config-reload`
- `package` — `npm-onboard-channel-agent`、`doctor-switch`、`update-channel-switch`、`upgrade-survivor`、`published-upgrade-survivor`、`plugins-offline`、`plugin-update`
- `product` — `package` 加上 `mcp-channels`、`cron-mcp-cleanup`、`openai-web-search-minimal`、`openwebui`
- `full` — 带 OpenWebUI 的完整 Docker 发布路径分块
- `full` — 带 OpenWebUI 的完整 Docker 发布路径块
- `custom` — 精确的 `docker_lanes`；当 `suite_profile=custom` 时必需
`package` 配置档使用离线插件覆盖，因此已发布软件包验证不会受实时 ClawHub 可用性限制。可选 Telegram lane 会在 `NPM Telegram Beta E2E` 中复用 `package-under-test` 构件，同时为独立分发保留已发布 npm 规范路径。
`package` 配置档使用离线插件覆盖范围，因此已发布软件包验证不会受制于 live ClawHub 可用性。可选 Telegram 通道会在 `NPM Telegram Beta E2E` 中复用 `package-under-test` 构件，同时保留已发布 npm 规格路径用于独立派发。
有关专门的更新和插件测试策略，包括本地命令、Docker lanes、软件包验收输入、发布默认值和失败分诊，请参见[更新和插件测试](/zh-CN/help/testing-updates-plugins)。
有关专用更新和插件测试策略，包括本地命令、Docker 通道、软件包验收输入、发布默认值和失败分诊，请参阅[更新和插件测试](/zh-CN/help/testing-updates-plugins)。
发布检查会调用软件包验收，并使用 `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=all-since-2026.4.23`、`published_upgrade_survivor_scenarios=reported-issues` 和 `telegram_mode=mock-openai`。这能让软件包迁移、更新、过期插件依赖清理、已配置插件安装修复、离线插件、插件更新和 Telegram 证明都基于同一个已解析的软件包 tarball。在 Full Release Validation 或 OpenClaw Release Checks 上设置 `package_acceptance_package_spec`，可对已发布的 npm 软件包运行同一矩阵，而不是针对 SHA 构建的构件运行。跨操作系统发布检查仍覆盖特定操作系统的新手引导、安装程序和平台行为；软件包/更新产品验证应从软件包验收开始。`published-upgrade-survivor` Docker lane 在每次运行中验证一个已发布软件包基线。在软件包验收中，已解析的 `package-under-test` tarball 始终是候选包，而 `published_upgrade_survivor_baseline` 选择回退的已发布基线，默认是 `openclaw@latest`；失败 lane 重跑命令会保留该基线。设置 `published_upgrade_survivor_baselines=all-since-2026.4.23`，可将完整发布 CI 扩展到从 `2026.4.23` 到 `latest` 的每个稳定 npm 发布；`release-history` 仍可用于使用较旧日期前锚点的手动更广采样。设置 `published_upgrade_survivor_scenarios=reported-issues`，可将同一组基线扩展到类似问题的夹具，覆盖 Feishu 配置、保留的 bootstrap/persona 文件、已配置的 OpenClaw 插件安装、波浪号日志路径和过期旧版插件依赖根。单独的 `Update Migration` 工作流在问题是穷尽式已发布更新清理而非普通完整发布 CI 广度时，会使用带 `all-since-2026.4.23` 和 `plugin-deps-cleanup` 的 `update-migration` Docker lane。本地聚合运行可以通过 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` 传入精确软件包规范，通过 `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 打包和安装程序全新安装 lanes 还会验证已安装软件包可以从原始绝对 Windows 路径导入 browser-control 覆盖。OpenAI 跨操作系统 agent 回合冒烟在设置时默认使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.4`，因此安装和 Gateway 网关证明会保留在 GPT-5 测试模型上，同时避免 GPT-4.x 默认值。
发布检查会调用软件包验收，并使用 `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=all-since-2026.4.23`、`published_upgrade_survivor_scenarios=reported-issues` 和 `telegram_mode=mock-openai`。这会让软件包迁移、更新、过期插件依赖清理、已配置插件安装修复、离线插件、插件更新和 Telegram 证明使用同一个已解析的软件包 tarball。在 Full Release Validation 或 OpenClaw Release Checks 上设置 `package_acceptance_package_spec`，即可针对已发布的 npm 软件包运行同一矩阵，而不是针对基于 SHA 构建的构件运行。跨 OS 发布检查仍覆盖 OS 特定的新手引导、安装器和平台行为；软件包/更新产品验证应从软件包验收开始。`published-upgrade-survivor` Docker 通道每次运行会验证一个已发布软件包基线。在软件包验收中，已解析的 `package-under-test` tarball 始终是候选包，而 `published_upgrade_survivor_baseline` 会选择回退的已发布基线，默认是 `openclaw@latest`；失败通道的重跑命令会保留该基线。设置 `published_upgrade_survivor_baselines=all-since-2026.4.23`，可将 Full Release CI 扩展到从 `2026.4.23` 到 `latest` 的每个稳定 npm 发布版本；`release-history` 仍可用于手动进行更宽采样，并使用较旧的日期前锚点。设置 `published_upgrade_survivor_scenarios=reported-issues`，可将相同基线扩展到按问题形态构造的 fixture，覆盖 Feishu 配置、保留的引导/persona 文件、已配置的 OpenClaw 插件安装、波浪号日志路径和过期旧版插件依赖根。单独的 `Update Migration` 工作流会在问题是彻底的已发布更新清理，而不是普通 Full Release CI 广度时，使用带有 `all-since-2026.4.23` 和 `plugin-deps-cleanup` 的 `update-migration` Docker 通道。本地聚合运行可以通过 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` 传入精确软件包规格，通过 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` 保持单个通道并使用类似 `openclaw@2026.4.15` 的值，或设置 `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` 来运行场景矩阵。已发布通道会用内置的 `openclaw config set` 命令配方配置基线，在 `summary.json` 中记录配方步骤，并在 Gateway 网关启动后探测 `/healthz`、`/readyz` 以及 RPC 状态。Windows 打包和安装器全新安装通道还会验证已安装的软件包可以从原始绝对 Windows 路径导入浏览器控制覆盖。OpenAI 跨 OS agent 回合 smoke 在设置时默认使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.4`，因此安装和 Gateway 网关证明会停留在 GPT-5 测试模型上，同时避免使用 GPT-4.x 默认值。
### 旧版兼容窗口
软件包验收为已经发布的软件包提供有界旧版兼容窗口。到 `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`；
- 插件冒烟可以读取旧版安装记录位置，或接受缺失的 marketplace 安装记录持久化；
- `plugin-update` 可以允许配置元数据迁移，同时仍要求安装记录和不重装行为保持不变。
- `dist/postinstall-inventory.json` 中已知的私有 QA 条目可以指向 tarball 省略的文件；
- 当软件包未公开 `gateway install --wrapper` 标志时，`doctor-switch` 可以跳过 `gateway install --wrapper` 持久化子用例；
- `update-channel-switch` 可以从 tarball 派生的假 git fixture 中修剪缺失的 `pnpm.patchedDependencies`，并可以记录缺失的持久化 `update.channel`；
- 插件 smoke 可以读取旧版安装记录位置，或接受缺失的 marketplace 安装记录持久化；
- `plugin-update` 可以允许配置元数据迁移，同时仍要求安装记录和不重新安装行为保持不变。
已发布的 `2026.4.26` 软件包也可以对已发布的本地构建元数据戳文件发出警告。后续软件包必须满足现代契约；相同条件会失败，而不是警告或跳过。
已发布的 `2026.4.26` 软件包也可以对已经发布的本地构建元数据戳文件发出警告。之后的软件包必须满足现代契约；相同条件会失败，而不是警告或跳过。
### 示例
```bash
# Validate the current beta package with product-level coverage.
# 使用产品级覆盖范围验证当前 beta 软件包。
gh workflow run package-acceptance.yml \
--ref main \
-f workflow_ref=main \
@ -272,7 +272,7 @@ gh workflow run package-acceptance.yml \
-f suite_profile=product \
-f telegram_mode=mock-openai
# Pack and validate a release branch with the current harness.
# 使用当前 harness 打包并验证一个发布分支。
gh workflow run package-acceptance.yml \
--ref main \
-f workflow_ref=main \
@ -281,7 +281,7 @@ gh workflow run package-acceptance.yml \
-f suite_profile=package \
-f telegram_mode=mock-openai
# Validate a tarball URL. SHA-256 is mandatory for source=url.
# 验证一个 tarball URL。source=url 时必须提供 SHA-256。
gh workflow run package-acceptance.yml \
--ref main \
-f workflow_ref=main \
@ -290,7 +290,7 @@ gh workflow run package-acceptance.yml \
-f package_sha256=<64-char-sha256> \
-f suite_profile=smoke
# Reuse a tarball uploaded by another Actions run.
# 复用另一个 Actions 运行上传的 tarball。
gh workflow run package-acceptance.yml \
--ref main \
-f workflow_ref=main \
@ -301,151 +301,151 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
调试失败的包验收运行时，先查看 `resolve_package` 摘要，以确认包来源、版本和 SHA-256。然后检查 `docker_acceptance` 子运行及其 Docker 工件：`.artifacts/docker-tests/**/summary.json`、`failures.json`、测试线日志、阶段耗时和重新运行命令。优先重新运行失败的包配置文件或精确 Docker 测试线，而不是重新运行完整发布验证。
调试失败的软件包验收运行时，先查看 `resolve_package` 摘要，确认软件包来源、版本和 SHA-256。然后检查 `docker_acceptance` 子运行及其 Docker 工件：`.artifacts/docker-tests/**/summary.json`、`failures.json`、通道日志、阶段耗时和重新运行命令。优先重新运行失败的软件包 profile 或精确的 Docker 通道，而不是重新运行完整发布验证。
## 安装冒烟测试
独立的 `Install Smoke` 工作流通过自己的 `preflight` 作业复用同一个作用域脚本。它将冒烟覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。
单独的 `Install Smoke` 工作流通过自己的 `preflight` 作业复用相同的范围脚本。它将冒烟覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。
- **快速路径** 会在拉取请求触及 Docker/包表面、内置插件包/清单变更，或 Docker 冒烟作业会覆盖的核心插件/渠道/Gateway 网关/插件 SDK 表面时运行。仅源码的内置插件变更、仅测试编辑和仅文档编辑不会占用 Docker 工作器。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete 共享工作区 CLI 冒烟测试，运行容器 gateway-network e2e，验证内置扩展构建参数，并在 240 秒聚合命令超时内运行有界的内置插件 Docker 配置文件（每个场景的 Docker 运行单独设有上限）。
- **完整路径** 为夜间定时运行、手动分派、workflow-call 发布检查，以及真正触及安装器/包/Docker 表面的拉取请求保留 QR 包安装和安装器 Docker/更新覆盖。在完整模式下，install-smoke 会准备或复用一个目标 SHA 的 GHCR 根 Dockerfile 冒烟镜像，然后将 QR 包安装、根 Dockerfile/Gateway 网关冒烟测试、安装器/更新冒烟测试，以及快速内置插件 Docker E2E 作为独立作业运行，因此安装器工作不必等待根镜像冒烟测试。
- **快速路径** 会在拉取请求触及 Docker/软件包表面、内置插件软件包/清单变更，或 Docker 冒烟作业会覆盖的核心插件/渠道/Gateway 网关/插件 SDK 表面时运行。仅源码的内置插件变更、仅测试编辑和仅文档编辑不会预留 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行智能体删除共享工作区 CLI 冒烟测试，运行容器 gateway-network e2e，验证内置扩展构建参数，并在 240 秒聚合命令超时内运行有界内置插件 Docker profile（每个场景的 Docker run 单独设置上限）。
- **完整路径** 为夜间定时运行、手动触发、workflow-call 发布检查，以及真正触及安装器/软件包/Docker 表面的拉取请求保留 QR 软件包安装和安装器 Docker/更新覆盖。在完整模式下，install-smoke 会准备或复用一个目标 SHA 的 GHCR 根 Dockerfile 冒烟镜像，然后将 QR 软件包安装、根 Dockerfile/Gateway 网关冒烟测试、安装器/更新冒烟测试，以及快速内置插件 Docker E2E 作为单独作业运行，这样安装器工作不会排在根镜像冒烟测试之后等待。
`main` 推送（包括合并提交）不会强制完整路径；当变更作用域逻辑会在推送上请求完整覆盖时，工作流会保留快速 Docker 冒烟测试，并把完整安装冒烟测试留给夜间或发布验证。
`main` 推送（包括合并提交）不会强制走完整路径；当变更范围逻辑会在推送上请求完整覆盖时，工作流会保留快速 Docker 冒烟测试，并将完整安装冒烟测试留给夜间运行或发布验证。
较慢的 Bun 全局安装 image-provider 冒烟测试由 `run_bun_global_install_smoke` 单独控制。它会在夜间计划和发布检查工作流中运行，手动 `Install Smoke` 分派也可以选择加入它，但拉取请求和 `main` 推送不会运行。QR 和安装器 Docker 测试保留各自以安装为重点的 Dockerfile。
较慢的 Bun 全局安装 image-provider 冒烟测试由 `run_bun_global_install_smoke` 单独控制。它会在夜间计划和发布检查工作流中运行，手动 `Install Smoke` 触发也可以选择启用它，但拉取请求和 `main` 推送不会运行。QR 和安装器 Docker 测试保留各自以安装为重点的 Dockerfile。
## 本地 Docker E2E
`pnpm test:docker:all` 会预构建一个共享实时测试镜像，将 OpenClaw 打包一次为 npm tarball，并构建两个共享的 `scripts/e2e/Dockerfile` 镜像：
`pnpm test:docker:all` 会预构建一个共享 live-test 镜像，将 OpenClaw 打包一次为 npm tarball，并构建两个共享的 `scripts/e2e/Dockerfile` 镜像：
- 一个用于安装器/更新/plugin-dependency 测试线的裸 Node/Git 运行器；
- 一个会把同一个 tarball 安装到 `/app`、用于常规功能测试线的功能镜像。
- 用于安装器/更新/插件依赖通道的裸 Node/Git runner；
- 将同一个 tarball 安装到 `/app` 的功能镜像，用于常规功能通道。
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`，runner 只执行选中的计划。调度器使用 `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 daemon 创建风暴；设置为 `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 | 并发 live 通道上限，避免提供商限流。 |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | 并发 npm install 通道上限。 |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | 并发多服务通道上限。 |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | 通道启动之间的错峰时间，用于避免 Docker daemon 创建风暴；设为 `0` 表示不进行错峰。 |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | 每通道兜底超时（120 分钟）；选定的 live/尾部通道使用更严格的上限。 |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` 会打印调度器计划而不运行通道。 |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | 逗号分隔的精确通道列表；跳过清理冒烟测试，以便智能体复现一个失败通道。 |
比其有效上限更重的测试线仍可从空池启动，然后会独占运行，直到释放容量。本地聚合会预检 Docker，移除过期的 OpenClaw E2E 容器，输出活动测试线状态，持久化测试线耗时以便按最长优先排序，并且默认在第一次失败后停止调度新的池化测试线。
比其有效上限更重的通道仍可从空池启动，然后独占运行，直到释放容量。本地聚合会预检 Docker、移除过期的 OpenClaw E2E 容器、输出活动通道状态、持久化通道耗时以便按最长优先排序，并默认在首次失败后停止调度新的池化通道。
### 可复用实时/E2E 工作流
### 可复用 live/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 layer cache 构建并推送带包摘要标签的裸/功能 GHCR Docker E2E 镜像；并复用提供的 `docker_e2e_bare_image`/`docker_e2e_functional_image` 输入或现有包摘要镜像，而不是重新构建。Docker 镜像拉取会使用有界的每次尝试 180 秒超时重试，因此卡住的 registry/cache 流会快速重试，而不会消耗 CI 关键路径的大部分时间。
可复用的 live/E2E 工作流会询问 `scripts/test-docker-all.mjs --plan-json` 需要哪些软件包、镜像类型、live 镜像、通道和凭据覆盖。随后 `scripts/docker-e2e.mjs` 会将该计划转换为 GitHub 输出和摘要。它要么通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw，要么下载当前运行的软件包工件，要么从 `package_artifact_run_id` 下载软件包工件；验证 tarball 清单；当计划需要已安装软件包的通道时，通过 Blacksmith 的 Docker layer cache 构建并推送带有软件包摘要标签的裸/功能 GHCR Docker E2E 镜像；并复用提供的 `docker_e2e_bare_image`/`docker_e2e_functional_image` 输入或现有的软件包摘要镜像，而不是重新构建。Docker 镜像拉取会使用有界的每次尝试 180 秒超时进行重试，这样卡住的 registry/cache 流会快速重试，而不是消耗 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` 通道别名仍是两个提供商安装器通道的聚合手动重新运行别名。
当完整 release-path 覆盖请求 OpenWebUI 时，它会被并入 `plugins-runtime-services`，并且仅为 OpenWebUI 专用分派保留独立的 `openwebui` 分块。内置渠道更新测试线会针对短暂 npm 网络故障重试一次。
当完整 release-path 覆盖请求 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 作业中，并为该运行准备、下载或复用软件包工件；如果选中的通道是 live Docker 通道，目标作业会为该次重新运行在本地构建 live-test 镜像。生成的每通道 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
pnpm test:docker:rerun <run-id> # 下载 Docker 工件并打印组合/每通道的定向重新运行命令
pnpm test:docker:timings <summary> # 慢通道和阶段关键路径摘要
```
计划的实时/E2E 工作流每天运行完整 release-path Docker 套件。
定时 live/E2E 工作流每天运行完整的 release-path Docker 套件。
## 插件预发布
`Plugin Prerelease` 是成本更高的产品/包覆盖，因此它是一个由 `Full Release Validation` 或显式操作员分派的独立工作流。普通拉取请求、`main` 推送和独立手动 CI 分派都会关闭该套件。它会在八个扩展工作器之间平衡内置插件测试；这些扩展分片作业一次最多运行两个插件配置组，每个组使用一个 Vitest 工作器和更大的 Node 堆，因此导入密集的插件批次不会创建额外 CI 作业。仅发布的 Docker 预发布路径会将目标 Docker 测试线按小组批处理，以避免为一到三分钟的作业占用大量运行器。
`Plugin Prerelease` 是成本更高的产品/软件包覆盖，因此它是一个由 `Full Release Validation` 或显式操作员触发的单独工作流。常规拉取请求、`main` 推送和独立手动 CI 触发都会关闭该套件。它会在八个扩展 worker 之间均衡内置插件测试；这些扩展分片作业一次最多运行两个插件配置组，每组使用一个 Vitest worker 和更大的 Node 堆，这样导入密集的插件批次不会创建额外的 CI 作业。仅发布的 Docker 预发布路径会将目标 Docker 通道按小组批处理，以避免为一到三分钟的作业预留数十个 runner。
## QA Lab
QA Lab 在主智能作用域工作流之外有专用 CI 测试线。智能体一致性嵌套在广泛的 QA 和发布 harness 下，而不是独立的 PR 工作流。当一致性应随广泛验证运行一起执行时，使用带有 `rerun_group=qa-parity` 的 `Full Release Validation`。
QA Lab 在主智能范围工作流之外有专用 CI 通道。Agentic parity 嵌套在宽范围 QA 和发布 harness 下，而不是独立的 PR 工作流。当 parity 应随宽范围验证运行一起执行时，使用 `Full Release Validation` 并设置 `rerun_group=qa-parity`。
- `QA-Lab - All Lanes` 工作流每晚在 `main` 上运行，并支持手动分派；它会将模拟一致性测试线、实时 Matrix 测试线，以及实时 Telegram 和 Discord 测试线展开为并行作业。实时作业使用 `qa-live-shared` 环境，Telegram/Discord 使用 Convex 租约。
- `QA-Lab - All Lanes` 工作流会每晚在 `main` 上运行，也可手动触发；它会将 mock parity 通道、live Matrix 通道，以及 live Telegram 和 Discord 通道展开为并行作业。Live 作业使用 `qa-live-shared` 环境，Telegram/Discord 使用 Convex leases。
发布检查使用确定性模拟提供商和模拟限定模型（`mock-openai/gpt-5.5` 与 `mock-openai/gpt-5.5-alt`）运行 Matrix 和 Telegram 实时传输测试线，因此渠道契约会与实时模型延迟和常规提供商插件启动隔离。实时传输 Gateway 网关会禁用记忆搜索，因为 QA 一致性会单独覆盖记忆行为；提供商连通性由单独的实时模型、原生提供商和 Docker 提供商套件覆盖。
发布检查使用确定性 mock 提供商和 mock-qualified 模型（`mock-openai/gpt-5.5` 和 `mock-openai/gpt-5.5-alt`）运行 Matrix 和 Telegram live 传输通道，使渠道契约与 live 模型延迟和常规提供商插件启动隔离。Live 传输 Gateway 网关会禁用记忆搜索，因为 QA parity 会单独覆盖记忆行为；提供商连接性由单独的 live 模型、原生提供商和 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 Lab 测试线；它的 QA 一致性门禁会将候选包和基线包作为并行测试线作业运行，然后将两个工件下载到一个小型报告作业中，用于最终一致性比较。
`OpenClaw Release Checks` 也会在发布批准前运行发布关键的 QA Lab 通道；其 QA parity 门禁会将候选包和基线包作为并行通道作业运行，然后把两个工件下载到一个小型报告作业中，用于最终 parity 比较。
对于普通 PR，请遵循作用域内 CI/检查证据，而不是将一致性视为必需状态。
对于常规 PR，遵循范围化 CI/检查证据，而不是将 parity 视为必需状态。
## CodeQL
`CodeQL` 工作流有意作为范围较窄的第一轮安全扫描器，而不是完整的仓库扫描。每日、手动和非草稿拉取请求守护运行会扫描 Actions 工作流代码，以及最高风险的 JavaScript/TypeScript 表面，并使用高置信度安全查询筛选出 high/critical `security-severity`。
`CodeQL` 工作流有意作为范围较窄的第一轮安全扫描器，而不是完整仓库扫描。每日、手动和非草稿拉取请求保护运行会扫描 Actions 工作流代码，以及风险最高的 JavaScript/TypeScript 表面，并使用高置信度安全查询，过滤到 high/critical `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` | 插件安装、加载器、清单、注册表、包管理器安装、源加载，以及插件 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 获取和插件 SDK SSRF 策略表面 |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP 服务器、进程执行辅助程序、出站投递和智能体工具执行门禁 |
| `/codeql-security-high/plugin-trust-boundary` | 插件安装、加载器、清单、注册表、包管理器安装、源码加载和插件 SDK 包契约信任表面 |
### 平台特定安全分片
- `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 Android Critical Security` — 定时 Android 安全分片。为 CodeQL 手动构建 Android 应用，使用工作流完整性检查接受的最小 Blacksmith Linux runner。在 `/codeql-critical-security/android` 下上传。
- `CodeQL macOS Critical Security` — 每周/手动 macOS 安全分片。在 Blacksmith macOS 上为 CodeQL 手动构建 macOS 应用，从上传的 SARIF 中过滤掉依赖构建结果，并在 `/codeql-critical-security/macos` 下上传。它保留在每日默认项之外，因为即使结果干净，macOS 构建也会主导运行时间。
### 关键质量类别
`CodeQL Critical Quality` 是对应的非安全分片。它只在较小的 Blacksmith Linux 运行器上，针对范围较窄的高价值表面运行 error-severity、非安全的 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 质量分片。
`CodeQL Critical Quality` 是匹配的非安全分片。它只在较小的 Blacksmith Linux runner 上，对较窄的高价值表面运行 error 严重级别、非安全 JavaScript/TypeScript 质量查询。它的拉取请求保护有意小于定时配置：非草稿 PR 只有在智能体命令/模型/工具执行和回复派发代码、配置架构/迁移/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 质量分片。
手动调度接受：
手动分发接受：
```
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
```
这些窄配置是用于单独运行一个质量分片的教学/迭代钩子。
窄配置是用于单独运行一个质量分片的教学/迭代钩子。
| 类别 | 表面 |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/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、记忆运行时 facade、记忆插件 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/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` | 配置架构、迁移、规范化和 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 入站回复派发、回复载荷/分块/运行时辅助程序、渠道回复选项、投递队列，以及会话/线程绑定辅助程序 |
| `/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 源码和插件包契约辅助程序 |
质量与安全保持分离，因此质量发现可以被定时运行、度量、禁用或扩展，而不会遮蔽安全信号。Swift、Python 和内置插件的 CodeQL 扩展只应在窄配置具备稳定运行时间和信号之后，作为有范围或分片的后续工作重新加入。
质量与安全保持分离，这样质量发现就可以被定时运行、度量、禁用或扩展，而不会遮蔽安全信号。Swift、Python 和内置插件 CodeQL 扩展应只在窄配置具有稳定运行时间和信号之后，作为有范围或分片的后续工作重新加入。
## 维护工作流
### Docs 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
`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 运行可以触发它，但如果另一个 workflow-run 调用在该 UTC 日已经运行过或正在运行，它会跳过。手动分发会绕过该每日活动门禁。该通道会构建一份全套件分组 Vitest 性能报告，让 Codex 只做小型、保留覆盖率的测试性能修复，而不是大范围重构，然后重新运行全套件报告，并拒绝会减少通过基线测试数量的变更。如果基线存在失败测试，Codex 只能修复明显失败，并且在提交任何内容之前，agent 之后的全套件报告必须通过。当 `main` 在机器人 push 落地前前进时，该通道会 rebase 已验证的补丁，重新运行 `pnpm check:changed`，并重试 push；存在冲突的陈旧补丁会被跳过。它使用 GitHub 托管的 Ubuntu，因此 Codex action 可以保持与 docs 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 已合并，并验证每个重复项要么有共享的引用 issue，要么有重叠的变更 hunk。
```bash
gh workflow run duplicate-after-merge.yml \
@ -454,29 +454,29 @@ gh workflow run duplicate-after-merge.yml \
-f apply=true
```
## 本地检查闸门和变更路由
## 本地检查门禁和变更路由
本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。该本地检查闸门在架构边界上比宽泛的 CI 平台范围更严格：
本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。该本地检查门禁在架构边界方面比宽泛的 CI 平台范围更严格：
- 核心生产变更会运行核心 prod 和核心 test 类型检查，以及核心 lint/guards；
- 仅核心测试的变更只会运行核心 test 类型检查，以及核心 lint；
- 插件生产变更会运行插件 prod 和插件 test 类型检查，以及插件 lint；
- 仅插件测试的变更会运行插件 test 类型检查，以及插件 lint；
- 公共插件 SDK 或插件契约变更会扩展到插件类型检查，因为插件依赖这些核心契约（Vitest 插件扫描仍然是显式测试工作）；
- 仅发布元数据的版本 bump 会运行定向版本/配置/根依赖检查；
- 未知根目录/配置变更会安全失败到所有检查通道。
- 核心生产代码变更会运行核心生产代码和核心测试类型检查，加上核心 lint/保护；
- 仅核心测试变更只运行核心测试类型检查，加上核心 lint；
- 插件生产代码变更会运行插件生产代码和插件测试类型检查，加上插件 lint；
- 仅插件测试变更会运行插件测试类型检查，加上插件 lint；
- 公开插件 SDK 或插件契约变更会扩展到插件类型检查，因为插件依赖这些核心契约（Vitest 插件扫描仍然是显式测试工作）；
- 仅发布元数据的版本 bump 会运行有针对性的版本/配置/根依赖检查；
- 未知 root/config 变更会失败保护到所有检查通道。
本地 changed-test 路由位于 `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`。
本地 changed-test 路由位于 `scripts/test-projects.test-support.mjs`，并且有意比 `check:changed` 更便宜：直接测试编辑会运行自身，源码编辑优先使用显式映射，然后运行同级测试和导入图依赖项。共享 group-room 投递配置是显式映射之一：对群组可见回复配置、源回复投递模式或 message-tool 系统提示词的变更，会通过核心回复测试以及 Discord 和 Slack 投递回归测试进行路由，因此共享默认值变更会在第一次 PR push 前失败。只有当变更足够 harness-wide，以至于便宜的映射集合不是可信代理时，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。
## Testbox 验证
从仓库根目录运行 Testbox，并优先使用新的已预热 box 做广泛验证。在复用过、已过期，或刚报告了异常大规模同步的 box 上投入慢速门禁前，先在该 box 内运行 `pnpm testbox:sanity`。
从仓库根目录运行 Testbox，并优先使用新预热的实例来做大范围验证。在把耗时的检查任务投入到一个复用过、已过期，或刚刚报告了异常大量同步内容的实例之前，先在该实例内运行 `pnpm testbox:sanity`。
当 `pnpm-lock.yaml` 等必需根目录文件消失，或 `git status --short` 显示至少 200 个已跟踪文件被删除时，完整性检查会快速失败。这通常意味着远程同步状态不是 PR 的可信副本；停止该 box 并预热一个新的，而不是调试产品测试失败。对于有意进行大规模删除的 PR，为该完整性检查运行设置 `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。
当所需的根文件（例如 `pnpm-lock.yaml`）消失，或 `git status --short` 显示至少 200 个已跟踪文件被删除时，完整性检查会快速失败。这通常表示远程同步状态不是该 PR 的可信副本；停止该实例并预热一个新实例，而不是调试产品测试失败。对于有意进行大量删除的 PR，请为该次完整性检查设置 `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。
如果本地 Blacksmith CLI 调用停留在同步阶段超过五分钟且没有同步后的输出，`pnpm testbox:run` 也会终止该调用。设置 `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` 可禁用该保护，或为异常大的本地 diff 使用更大的毫秒值。
如果本地 Blacksmith CLI 调用在同步阶段停留超过五分钟且没有同步后输出，`pnpm testbox:run` 也会终止该调用。设置 `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` 可禁用此保护；对于异常大的本地 diff，也可以设置更大的毫秒值。
当 Blacksmith 不可用，或更适合使用自有云容量时，Crabbox 是仓库自有的第二条 Linux 远程 box 验证路径。预热一个 box，通过项目工作流注水，然后通过 Crabbox CLI 运行命令：
当 Blacksmith 不可用，或更适合使用自有云容量时，Crabbox 是仓库拥有的第二条 Linux 远程实例验证路径。预热一个实例，通过项目工作流初始化它，然后通过 Crabbox CLI 运行命令：
```bash
pnpm crabbox:warmup -- --idle-timeout 90m
@ -485,7 +485,7 @@ pnpm crabbox:run -- --id <cbx_id> --shell "OPENCLAW_TESTBOX=1 pnpm check:changed
pnpm crabbox:stop -- <cbx_id>
```
`.crabbox.yaml` 负责提供商、同步和 GitHub Actions 注水默认值。它会排除本地 `.git`，这样注水后的 Actions checkout 会保留自己的远程 Git 元数据，而不是同步维护者本地的 remote 和 object store；它还会排除不应被传输的本地运行时/构建产物。`.github/workflows/crabbox-hydrate.yml` 负责 checkout、Node/pnpm 设置、`origin/main` 获取，以及非 secret 环境交接，后续的 `crabbox run --id <cbx_id>` 命令会加载这些环境。
`.crabbox.yaml` 负责提供商、同步和 GitHub Actions 初始化默认设置。它会排除本地 `.git`，这样初始化后的 Actions checkout 会保留自身的远程 Git 元数据，而不是同步维护者本地的远程和对象存储；它也会排除永远不应传输的本地运行时/构建产物。`.github/workflows/crabbox-hydrate.yml` 负责 checkout、Node/pnpm 设置、`origin/main` 获取，以及非机密环境交接，后续 `crabbox run --id <cbx_id>` 命令会读取这些环境。
## 相关

104
docs/zh-CN/concepts/experimental-features.md
View File

@ -1,47 +1,97 @@
---
read_when:
- 你看到了一个 `.experimental` 配置键，想知道它是否稳定
- 你想尝试预览版运行时功能，同时不将它们与正常默认设置混淆
- 你想在一个地方找到当前已记录的实验性标志
summary: OpenClaw 中实验性标志的含义，以及当前已记录了哪些实验性标志
- 你看到一个 `.experimental` 配置键，并想知道它是否稳定
- 你想尝试预览版运行时功能，而不把它们和常规默认设置混淆
- 你想要一个地方来查找当前文档中记录的实验性标志
summary: OpenClaw 中实验性标志的含义以及当前已记录的标志
title: 实验性功能
x-i18n:
generated_at: "2026-04-24T04:02:01Z"
model: gpt-5.4
generated_at: "2026-05-02T21:49:05Z"
model: gpt-5.5
provider: openai
source_hash: 1a97e8efa180844e1ca94495d626956847a15a15bba0846aaf54ff9c918cda02
source_hash: 066efa297bac995597f1092ed6473d9cff28c01d7e28fa1382d7997f8f83a346
source_path: concepts/experimental-features.md
workflow: 15
workflow: 16
---
OpenClaw 中的实验性功能是**选择加入的预览能力**。它们被放在显式标志之后，是因为在成为稳定默认值或长期公开契约之前，仍然需要真实环境中的验证。
Experimental features in OpenClaw are **opt-in preview surfaces**. They are
behind explicit flags because they still need real-world mileage before they
deserve a stable default or a long-lived public contract.
请将它们与普通配置区别对待：
Treat them differently from normal config:
- 默认情况下保持**关闭**，除非相关文档明确建议你尝试某个标志。
- 预期其**结构和行为会比稳定配置变化得更快**。
- 如果已有稳定路径，优先使用稳定路径。
- 如果你要大范围部署 OpenClaw，请先在较小环境中测试实验性标志，再将其纳入共享基线。
- Keep them **off by default** unless the related doc tells you to try one.
- Expect **shape and behavior to change** faster than stable config.
- Prefer the stable path first when one already exists.
- If you are rolling OpenClaw out broadly, test experimental flags in a smaller
environment before baking them into a shared baseline.
## 当前已记录的标志
## Currently documented flags
| Surface | Key | Use it when | More |
| Surface | Key | Use it when | More |
| ------------------------ | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| 本地模型运行时 | `agents.defaults.experimental.localModelLean` | 较小或更严格的本地后端无法处理 OpenClaw 完整的默认工具能力 | [本地模型](/zh-CN/gateway/local-models) |
| 记忆搜索 | `agents.defaults.memorySearch.experimental.sessionMemory` | 你希望 `memory_search` 为先前的会话转录建立索引，并接受额外的存储/索引成本 | [记忆配置参考](/zh-CN/reference/memory-config#session-memory-search-experimental) |
| 结构化规划工具 | `tools.experimental.planTool` | 你希望在兼容的运行时和 UI 中公开结构化的 `update_plan` 工具，用于多步骤工作跟踪 | [Gateway 网关配置参考](/zh-CN/gateway/config-tools#toolsexperimental) |
| Local model runtime | `agents.defaults.experimental.localModelLean` | A smaller or stricter local backend chokes on OpenClaw's full default tool surface | [Local Models](/zh-CN/gateway/local-models) |
| Memory search | `agents.defaults.memorySearch.experimental.sessionMemory` | You want `memory_search` to index prior session transcripts and accept the extra storage/indexing cost | [Memory configuration reference](/zh-CN/reference/memory-config#session-memory-search-experimental) |
| Structured planning tool | `tools.experimental.planTool` | You want the structured `update_plan` tool exposed for multi-step work tracking in compatible runtimes and UIs | [Gateway configuration reference](/zh-CN/gateway/config-tools#toolsexperimental) |
## 本地模型精简模式
## Local model lean mode
`agents.defaults.experimental.localModelLean: true` 是为较弱的本地模型环境提供的缓冲阀。它会裁剪像 `browser`、`cron` 和 `message` 这样的重量级默认工具，使提示结构更小，在小上下文或更严格的 OpenAI 兼容后端中更不易出问题。
`agents.defaults.experimental.localModelLean: true` is a pressure-release valve for weaker local-model setups. When it is on, OpenClaw drops three default tools — `browser`, `cron`, and `message` — from the agent's tool surface for every turn. Nothing else changes.
这**不是**正常路径。如果你的后端能够稳定处理完整运行时，请保持关闭。
### Why these three tools
## 实验性不等于隐藏
These three tools have the largest descriptions and the most parameter shapes in the default OpenClaw runtime. On a small-context or stricter OpenAI-compatible backend that is the difference between:
如果某个功能是实验性的，OpenClaw 应该在文档和配置路径本身中明确说明。它**不应该**做的是，把预览行为偷偷塞进一个看起来稳定的默认开关里，然后假装那是正常用法。那样只会让配置能力变得混乱。
- Tool schemas fitting cleanly in the prompt vs. crowding out conversation history.
- The model picking the right tool vs. emitting malformed tool calls because there are too many similar-looking schemas.
- The Chat Completions adapter staying inside the server's structured-output limits vs. tripping a 400 on tool-call payload size.
## 相关内容
Removing them does not silently rewire OpenClaw — it just makes the tool list shorter. The model still has `read`, `write`, `edit`, `exec`, `apply_patch`, web search/fetch (when configured), memory, and session/agent tools available.
- [功能](/zh-CN/concepts/features)
- [发布渠道](/zh-CN/install/development-channels)
### When to turn it on
Enable lean mode when you have already proved the model can talk to the Gateway but full agent turns misbehave. The typical signal chain is:
1. `openclaw infer model run --gateway --model <ref> --prompt "Reply with exactly: pong"` succeeds.
2. A normal agent turn fails with malformed tool calls, oversized prompts, or the model ignoring its tools.
3. Toggling `localModelLean: true` clears the failure.
### When to leave it off
If your backend handles the full default runtime cleanly, leave this off. Lean mode is a workaround, not a default. It exists because some local stacks need a smaller tool surface to behave; hosted models and well-resourced local rigs do not.
Lean mode also does not replace `tools.profile`, `tools.allow`/`tools.deny`, or the model `compat.supportsTools: false` escape hatch. If you need a permanent narrower tool surface for a specific agent, prefer those stable knobs over the experimental flag.
### Enable
```json5
{
agents: {
defaults: {
experimental: {
localModelLean: true,
},
},
},
}
```
Restart the Gateway after changing the flag, then confirm the trimmed tool list with:
```bash
openclaw status --deep
```
The deep status output lists the active agent tools; `browser`, `cron`, and `message` should be absent when lean mode is on.
## Experimental does not mean hidden
If a feature is experimental, OpenClaw should say so plainly in docs and in the
config path itself. What it should **not** do is smuggle preview behavior into a
stable-looking default knob and pretend that is normal. That's how config
surfaces get messy.
## Related
- [Features](/zh-CN/concepts/features)
- [Release channels](/zh-CN/install/development-channels)

207
docs/zh-CN/concepts/system-prompt.md
View File

@ -1,134 +1,93 @@
---
read_when:
- 编辑系统提示文本、工具列表或时间/Heartbeat 部分
- 编辑系统提示词文本、工具列表或时间/Heartbeat 部分
- 更改工作区引导或 Skills 注入行为
summary: OpenClaw 系统提示词包含什么以及它是如何组装的
summary: OpenClaw 系统提示词包含哪些内容以及如何组装
title: 系统提示词
x-i18n:
generated_at: "2026-05-02T16:04:30Z"
generated_at: "2026-05-02T21:49:00Z"
model: gpt-5.5
provider: openai
source_hash: 56b29c354ea4b3f48fd7279614677905b3065bc0afa6741fb4273ef229e8cebb
source_hash: 3b8761a8722bb328b937e0832774be7b4e99602ae032c9a255f26843237c110c
source_path: concepts/system-prompt.md
workflow: 16
---
OpenClaw 会为每次智能体运行构建自定义系统提示词。该提示词由 **OpenClaw 所有**，不会使用 pi-coding-agent 默认提示词。
OpenClaw 会为每次智能体运行构建一个自定义系统提示词。该提示词**归 OpenClaw 所有**，不使用 pi-coding-agent 的默认提示词。
提示词由 OpenClaw 组装，并注入到每次智能体运行中。
提供商插件可以贡献缓存感知的提示词指导，而无需替换
完整的 OpenClaw 所有提示词。提供商运行时可以：
提供商插件可以贡献支持缓存感知的提示词指导，而无需替换完整的 OpenClaw 所有提示词。提供商运行时可以：
- 替换一小组命名的核心区段（`interaction_style`、
`tool_call_style`、`execution_bias`）
- 在提示词缓存边界上方注入一个**稳定前缀**
- 在提示词缓存边界下方注入一个**动态后缀**
- 替换一小组命名核心章节（`interaction_style`、`tool_call_style`、`execution_bias`）
- 在提示词缓存边界之上注入一个**稳定前缀**
- 在提示词缓存边界之下注入一个**动态后缀**
将提供商所有的贡献用于特定模型家族的调优。保留旧版
`before_prompt_build` 提示词变更，用于兼容性或真正全局的提示词
更改，而不是常规提供商行为。
使用提供商自有贡献来做模型家族特定调优。保留旧版 `before_prompt_build` 提示词变更机制，用于兼容性或真正全局的提示词更改，而不是普通提供商行为。
OpenAI GPT-5 家族覆盖层会让核心执行规则保持小巧，并添加
针对模型的指导，涵盖人设锁定、简洁输出、工具纪律、
并行查找、交付物覆盖、验证、缺失上下文和
终端工具卫生。
OpenAI GPT-5 家族叠加层会保持核心执行规则较小，并添加针对模型的指导，覆盖角色锁定、简洁输出、工具纪律、并行查找、交付物覆盖、验证、缺失上下文和终端工具卫生。
## 结构
提示词有意保持紧凑，并使用固定区段：
提示词有意保持紧凑，并使用固定章节：
- **工具使用**：结构化工具真实来源提醒，以及运行时工具使用指导。
- **执行倾向**：紧凑的跟进指导：对可执行请求在本轮中行动，
持续进行直到完成或受阻，从薄弱的工具结果中恢复，
实时检查可变状态，并在最终回复前验证。
- **安全**：简短的护栏提醒，避免追求权力的行为或绕过监督。
- **Skills**（可用时）：告诉模型如何按需加载 Skills 指令。
- **OpenClaw 自更新**：如何使用
`config.schema.lookup` 安全检查配置，使用 `config.patch` 修补配置，
使用 `config.apply` 替换完整配置，并且只在用户明确请求时运行
`update.run`。仅所有者可用的 `gateway` 工具也会拒绝重写
`tools.exec.ask` / `tools.exec.security`，包括会规范化到这些受保护 exec 路径的旧版
`tools.bash.*` 别名。
- **工具调用**：结构化工具事实来源提醒，以及运行时工具使用指导。
- **执行倾向**：紧凑的跟进指导：对可执行请求在当前轮次中行动，持续推进直到完成或受阻，从较弱的工具结果中恢复，实时检查可变状态，并在最终回复前验证。
- **安全**：简短护栏提醒，避免寻求权力的行为或绕过监督。
- **Skills**（可用时）：告诉模型如何按需加载 skill 指令。
- **OpenClaw 自更新**：如何使用 `config.schema.lookup` 安全检查配置，使用 `config.patch` 修补配置，使用 `config.apply` 替换完整配置，并且仅在用户明确请求时运行 `update.run`。仅限所有者使用的 `gateway` 工具也会拒绝重写 `tools.exec.ask` / `tools.exec.security`，包括会规范化为这些受保护 exec 路径的旧版 `tools.bash.*` 别名。
- **工作区**：工作目录（`agents.defaults.workspace`）。
- **文档**：OpenClaw 文档的本地路径（仓库或 npm package），以及何时阅读它们。
- **工作区文件（已注入）**：表示 bootstrap 文件包含在下方。
- **文档**：OpenClaw 文档的本地路径（仓库或 npm 包），以及何时读取它们。
- **工作区文件（已注入）**：表示引导文件包含在下方。
- **沙箱**（启用时）：表示沙箱隔离运行时、沙箱路径，以及是否可用提权 exec。
- **当前日期和时间**：用户本地时间、时区和时间格式。
- **回复标签**：受支持提供商的可选回复标签语法。
- **Heartbeats**：默认智能体启用 Heartbeats 时的 Heartbeat 提示词和确认行为。
- **运行时**：主机、OS、node、模型、仓库根目录（检测到时）、思考级别（一行）。
- **Heartbeat**：默认智能体启用 Heartbeat 时的 Heartbeat 提示词和确认行为。
- **运行时**：主机、操作系统、node、模型、仓库根目录（检测到时）、思考级别（一行）。
- **推理**：当前可见性级别 + /reasoning 切换提示。
OpenClaw 会将大型稳定内容（包括**项目上下文**）保留在
内部提示词缓存边界之上。易变的渠道/会话区段，例如
Control UI 嵌入指导、**消息传递**、**语音**、**群聊上下文**、
**回应**、**Heartbeats** 和**运行时**，会追加到该边界下方，
这样带前缀缓存的本地后端就能在不同渠道轮次之间复用稳定的工作区前缀。
同样，工具描述也应避免嵌入当前渠道名称，前提是已接受的 schema
已经携带该运行时细节。
OpenClaw 会把大型稳定内容（包括**项目上下文**）放在内部提示词缓存边界之上。易变的渠道/会话章节，例如 Control UI 嵌入指导、**消息传递**、**语音**、**群聊上下文**、**回应**、**Heartbeat** 和**运行时**，会追加到该边界之下，因此带前缀缓存的本地后端可以在不同渠道轮次之间复用稳定的工作区前缀。工具描述同样应避免嵌入当前渠道名称，因为已接受的 schema 已经携带该运行时细节。
工具使用区段还包含面向长时间运行工作的运行时指导：
工具调用章节还包含针对长时间运行工作的运行时指导：
- 对未来跟进使用 cron（`check back later`、提醒、周期性工作），
而不是 `exec` sleep 循环、`yieldMs` 延迟技巧，或重复的 `process`
轮询
- 仅将 `exec` / `process` 用于现在开始并在后台继续运行的命令
- 启用自动完成唤醒时，只启动命令一次，并在其输出或失败时依赖
基于推送的唤醒路径
- 当你需要检查正在运行的命令时，使用 `process` 查看日志、状态、输入或进行干预
- 如果任务更大，优先使用 `sessions_spawn`；子智能体完成是
基于推送的，并会自动向请求者通告
- 不要在循环中轮询 `subagents list` / `sessions_list`，只是为了等待
完成
- 对未来跟进使用 cron（`check back later`、提醒、重复工作），而不是 `exec` 睡眠循环、`yieldMs` 延迟技巧或重复的 `process` 轮询
- 仅将 `exec` / `process` 用于立即启动并在后台持续运行的命令
- 启用自动完成唤醒时，只启动一次命令，并在其输出或失败时依赖基于推送的唤醒路径
- 需要检查运行中命令的日志、状态、输入或干预时，使用 `process`
- 如果任务更大，优先使用 `sessions_spawn`；子智能体完成是基于推送的，并会自动向请求者通告
- 不要为了等待完成而在循环中轮询 `subagents list` / `sessions_list`
启用实验性 `update_plan` 工具时，工具使用区段还会告诉
模型只在非简单的多步骤工作中使用它，始终只保留一个
`in_progress` 步骤，并避免每次更新后重复整个计划。
启用实验性 `update_plan` 工具时，工具调用章节还会告诉模型仅将其用于非平凡的多步骤工作，始终只保留一个 `in_progress` 步骤，并避免每次更新后重复整个计划。
系统提示词中的安全护栏是建议性的。它们指导模型行为，但不强制执行策略。使用工具策略、exec 审批、沙箱隔离和渠道 allowlist 进行硬性执行；操作员可以按设计禁用这些机制。
系统提示词中的安全护栏是建议性的。它们指导模型行为，但不强制执行策略。使用工具策略、exec 审批、沙箱隔离和渠道 allowlist 进行硬性执行；运营者按设计可以禁用这些机制。
在带有原生审批卡片/按钮的渠道上，运行时提示词现在会告诉
智能体优先依赖该原生审批 UI。只有当工具结果表示聊天审批不可用，
或手动审批是唯一路径时，才应包含手动
`/approve` 命令。
在支持原生审批卡片/按钮的渠道上，运行时提示词现在会告诉智能体优先依赖该原生审批 UI。只有当工具结果说明聊天审批不可用，或手动审批是唯一路径时，才应包含手动 `/approve` 命令。
## 提示词模式
OpenClaw 可以为子智能体渲染更小的系统提示词。运行时会为每次运行设置
`promptMode`（不是面向用户的配置）：
OpenClaw 可以为子智能体渲染更小的系统提示词。运行时会为每次运行设置一个 `promptMode`（不是面向用户的配置）：
- `full`（默认）：包含上面的所有区段。
- `minimal`：用于子智能体；省略 **Skills**、**记忆召回**、**OpenClaw
自更新**、**模型别名**、**用户身份**、**回复标签**、
**消息传递**、**静默回复** 和 **Heartbeats**。工具使用、**安全**、
工作区、沙箱、当前日期和时间（已知时）、运行时以及注入的
上下文仍然可用。
- `full`（默认）：包含上方所有章节。
- `minimal`：用于子智能体；省略 **Skills**、**记忆召回**、**OpenClaw 自更新**、**模型别名**、**用户身份**、**回复标签**、**消息传递**、**静默回复** 和 **Heartbeat**。工具调用、**安全**、工作区、沙箱、当前日期和时间（已知时）、运行时，以及注入的上下文仍然可用。
- `none`：仅返回基础身份行。
当 `promptMode=minimal` 时，额外注入的提示词会标记为**子智能体
上下文**，而不是**群聊上下文**。
当 `promptMode=minimal` 时，额外注入的提示词会标记为**子智能体上下文**，而不是**群聊上下文**。
对于渠道自动回复运行，当直接/群聊上下文已经包含解析后的
特定会话 `NO_REPLY` 行为时，OpenClaw 可以省略通用的**静默回复**
区段。这样可避免在全局系统提示词和渠道上下文中同时重复令牌机制。
对于渠道自动回复运行，当直接/群聊上下文已经包含已解析的会话特定 `NO_REPLY` 行为时，OpenClaw 可以省略通用的**静默回复**章节。这可避免在全局系统提示词和渠道上下文中重复令牌机制。
## 提示词快照
OpenClaw 在 `test/fixtures/agents/prompt-snapshots/happy-path/` 下保留
已提交的 Codex/message-tool 运行时 happy-path 提示词快照。它们会渲染
OpenClaw 所有的 Codex app-server 开发者指令、选定的线程
开始/恢复参数、轮次用户输入，以及 Telegram 直聊、
Discord 群组和 Heartbeat 轮次的动态工具规格。隐藏的基础 Codex 系统提示词和
轮次范围的 Codex 协作模式指令由 Codex 运行时所有，
不会由 OpenClaw 渲染。
OpenClaw 在 `test/fixtures/agents/prompt-snapshots/happy-path/` 下保留了针对 Codex/message-tool 运行时提交的成功路径提示词快照。它们会渲染选定的 app-server 线程/轮次参数，以及为 Telegram 直聊、Discord 群组和 Heartbeat 轮次重建的模型绑定提示词层堆栈。该堆栈包含一个固定的 Codex `gpt-5.5` 模型提示词 fixture，它从 Codex 的模型目录/缓存形态生成，还包含 Codex 成功路径权限 developer 文本、OpenClaw developer 指令、用户轮次输入，以及对动态工具规范的引用。
使用 `pnpm prompt:snapshots:gen` 重新生成它们，并使用
`pnpm prompt:snapshots:check` 验证漂移。
使用 `pnpm prompt:snapshots:sync-codex-model` 刷新固定的 Codex 模型提示词 fixture。默认情况下，该脚本会查找 Codex 在 `$CODEX_HOME/models_cache.json` 的运行时缓存，然后查找 `~/.codex/models_cache.json`，最后才回退到维护者 Codex checkout 约定路径 `~/code/codex/codex-rs/models-manager/models.json`。如果这些来源都不存在，命令会退出且不更改已提交的 fixture。传入 `--catalog <path>` 可从指定的 `models_cache.json` 或 `models.json` 文件刷新。
## 工作区 bootstrap 注入
这些快照仍然不是逐字节的原始 OpenAI 请求捕获。OpenClaw 发送线程和轮次参数后，Codex 可以在 Codex 运行时内添加运行时自有的工作区上下文，例如 `AGENTS.md`、环境上下文、记忆、应用/插件指令，以及未来的协作模式指令。
Bootstrap 文件会被裁剪并追加到**项目上下文**下，使模型无需显式读取即可看到身份和档案上下文：
使用 `pnpm prompt:snapshots:gen` 重新生成它们，并使用 `pnpm prompt:snapshots:check` 验证漂移。CI 会在额外的边界分片中运行漂移检查，以便提示词更改和快照更新保持附着在同一个 PR 上。
## 工作区引导注入
引导文件会被裁剪并追加到**项目上下文**下方，因此模型无需显式读取即可看到身份和资料上下文：
- `AGENTS.md`
- `SOUL.md`
@ -139,65 +98,42 @@ Bootstrap 文件会被裁剪并追加到**项目上下文**下，使模型无需
- `BOOTSTRAP.md`（仅限全新工作区）
- 存在时的 `MEMORY.md`
除非适用特定文件门控，否则所有这些文件都会在每一轮被**注入上下文窗口**。
当默认智能体禁用 Heartbeats，或
`agents.defaults.heartbeat.includeSystemPromptSection` 为 false 时，
`HEARTBEAT.md` 会在常规运行中省略。保持注入文件简洁，尤其是
`MEMORY.md`，它可能随时间增长，导致上下文使用量意外升高并更频繁压缩。
除非适用文件特定门控，否则所有这些文件都会在每个轮次中**注入到上下文窗口**。当默认智能体禁用 Heartbeat，或 `agents.defaults.heartbeat.includeSystemPromptSection` 为 false 时，正常运行会省略 `HEARTBEAT.md`。保持注入文件简洁，尤其是 `MEMORY.md`，它可能随时间增长，并导致上下文使用量意外升高和更频繁的压缩。
<Note>
`memory/*.md` 每日文件**不是**常规 bootstrap 项目上下文的一部分。在普通轮次中，它们会通过 `memory_search` 和 `memory_get` 工具按需访问，因此除非模型显式读取它们，否则不会计入上下文窗口。裸 `/new` 和 `/reset` 轮次是例外：运行时可以为该第一轮前置近期每日记忆，作为一次性启动上下文块。
`memory/*.md` 每日文件**不是**普通引导项目上下文的一部分。在普通轮次中，它们通过 `memory_search` 和 `memory_get` 工具按需访问，因此除非模型显式读取它们，否则不会计入上下文窗口。裸 `/new` 和 `/reset` 轮次是例外：运行时可以把最近的每日记忆作为一次性启动上下文块前置到第一个轮次。
</Note>
大型文件会用标记截断。每个文件的最大大小由
`agents.defaults.bootstrapMaxChars` 控制（默认：12000）。跨文件的注入 bootstrap
内容总量由 `agents.defaults.bootstrapTotalMaxChars` 封顶
（默认：60000）。缺失文件会注入简短的缺失文件标记。发生截断时，
OpenClaw 可以在项目上下文中注入警告块；使用
`agents.defaults.bootstrapPromptTruncationWarning` 控制它（`off`、`once`、`always`；
默认：`once`）。
大文件会带标记截断。每个文件的最大大小由 `agents.defaults.bootstrapMaxChars` 控制（默认：12000）。跨文件注入的引导内容总量由 `agents.defaults.bootstrapTotalMaxChars` 限制（默认：60000）。缺失文件会注入一个简短的缺失文件标记。发生截断时，OpenClaw 可以在项目上下文中注入警告块；使用 `agents.defaults.bootstrapPromptTruncationWarning` 控制此行为（`off`、`once`、`always`；默认：`once`）。
子智能体会话只注入 `AGENTS.md` 和 `TOOLS.md`（其他 bootstrap 文件
会被过滤掉，以保持子智能体上下文较小）。
子智能体会话仅注入 `AGENTS.md` 和 `TOOLS.md`（其他引导文件会被过滤掉，以保持子智能体上下文较小）。
内部钩子可以通过 `agent:bootstrap` 拦截这一步，以变更或替换
注入的 bootstrap 文件（例如将 `SOUL.md` 替换为另一种人设）。
内部钩子可以通过 `agent:bootstrap` 拦截此步骤，以变更或替换注入的引导文件（例如将 `SOUL.md` 换成另一种 persona）。
如果你想让智能体听起来不那么泛泛，可以从
[SOUL.md 人格指南](/zh-CN/concepts/soul)开始。
如果你想让智能体听起来不那么泛泛而谈，请从 [SOUL.md 人格指南](/zh-CN/concepts/soul)开始。
要检查每个注入文件贡献了多少内容（原始 vs 已注入、截断，以及工具 schema 开销），请使用 `/context list` 或 `/context detail`。参见[上下文](/zh-CN/concepts/context)。
要检查每个注入文件贡献了多少内容（原始 vs 已注入、截断情况，以及工具 schema 开销），请使用 `/context list` 或 `/context detail`。参见[上下文](/zh-CN/concepts/context)。
## 时间处理
当已知用户时区时，系统提示词会包含专门的**当前日期和时间**区段。
为了保持提示词缓存稳定，它现在只包含**时区**（不包含动态时钟或时间格式）。
当已知用户时区时，系统提示词会包含一个专用的**当前日期和时间**章节。为了保持提示词缓存稳定，它现在只包含**时区**（不包含动态时钟或时间格式）。
当智能体需要当前时间时，使用 `session_status`；状态卡片
会包含时间戳行。同一工具还可以选择设置每会话模型
覆盖（`model=default` 会清除它）。
当智能体需要当前时间时，使用 `session_status`；状态卡片包含一个时间戳行。同一工具还可以选择性设置每会话模型覆盖（`model=default` 会清除它）。
使用以下项配置：
- `agents.defaults.userTimezone`
- `agents.defaults.timeFormat`（`auto` | `12` | `24`）
参见[日期和时间](/zh-CN/date-time)了解完整行为细节。
完整行为详情请参见[日期和时间](/zh-CN/date-time)。
## Skills
当存在符合条件的 Skills 时，OpenClaw 会注入紧凑的**可用 Skills 列表**
（`formatSkillsForPrompt`），其中包含每个 Skill 的**文件路径**。
提示词会指示模型使用 `read` 加载所列位置（工作区、托管或内置）中的 SKILL.md。
如果没有符合条件的 Skills，则会省略 Skills 区段。
当存在符合条件的 Skills 时，OpenClaw 会注入一个紧凑的**可用 Skills 列表**（`formatSkillsForPrompt`），其中包含每个 skill 的**文件路径**。提示词会指示模型使用 `read` 加载所列位置（工作区、托管或内置）中的 SKILL.md。如果没有符合条件的 Skills，则省略 Skills 章节。
符合条件包括 Skill 元数据门控、运行时环境/配置检查，
以及在配置了 `agents.defaults.skills` 或
`agents.list[].skills` 时的有效智能体 Skill allowlist。
资格条件包括 skill 元数据门控、运行时环境/配置检查，以及配置了 `agents.defaults.skills` 或 `agents.list[].skills` 时的有效智能体 skill allowlist。
插件内置的 Skills 只有在其所属插件启用时才符合条件。
这让工具插件可以公开更深入的操作指南，而无需将所有
指导直接嵌入每个工具描述中。
插件内置 Skills 只有在其所属插件启用时才符合条件。这让工具插件可以暴露更深入的操作指南，而无需把所有这些指导直接嵌入每个工具描述中。
```
<available_skills>
@ -209,41 +145,28 @@ OpenClaw 可以在项目上下文中注入警告块；使用
</available_skills>
```
这会保持基础提示词小巧，同时仍支持有针对性的 Skills 使用。
这会保持基础提示词较小，同时仍然支持有针对性的 skill 使用。
Skills 列表预算由 Skills 子系统所有：
Skills 列表预算由 Skills 子系统负责：
- 全局默认值：`skills.limits.maxSkillsPromptChars`
- 每智能体覆盖：`agents.list[].skillsLimits.maxSkillsPromptChars`
通用的有界运行时摘录使用不同的表面：
通用有界运行时摘录使用不同的表面：
- `agents.defaults.contextLimits.*`
- `agents.list[].contextLimits.*`
这种拆分让 Skills 大小控制与运行时读取/注入大小控制保持分离，
例如 `memory_get`、实时工具结果，以及压缩后的 AGENTS.md 刷新。
这种拆分让 Skills 大小控制与运行时读取/注入大小控制保持分离，例如 `memory_get`、实时工具结果，以及压缩后的 AGENTS.md 刷新。
## 文档
系统提示词包含一个**文档**区段。当本地文档可用时，它会
指向本地 OpenClaw 文档目录（Git checkout 中的 `docs/`，或内置 npm
package 文档）。如果本地文档不可用，则回退到
[https://docs.openclaw.ai](https://docs.openclaw.ai)。
系统提示包含一个 **文档** 部分。当本地文档可用时，它会指向本地 OpenClaw 文档目录（Git checkout 中的 `docs/`，或内置 npm package docs）。如果本地文档不可用，它会回退到 [https://docs.openclaw.ai](https://docs.openclaw.ai)。
同一区段还包含 OpenClaw 源码位置。Git checkout 会暴露本地
源码根目录，让智能体可以直接检查代码。Package 安装会包含 GitHub
源码 URL，并告诉智能体在文档不完整或过时时去那里查看源码。
提示词还会提到公开文档镜像、社区 Discord，以及用于 Skills 发现的 ClawHub
（[https://clawhub.ai](https://clawhub.ai)）。它告诉模型，针对 OpenClaw 行为、命令、配置或架构，
应先查阅文档，并在可能时自行运行 `openclaw status`（仅在缺少访问权限时询问用户）。
对于配置，它会特别指向 `gateway` 工具动作
`config.schema.lookup`，用于精确的字段级文档和约束，然后指向
`docs/gateway/configuration.md` 和 `docs/gateway/configuration-reference.md`
以获取更广泛的指导。
同一部分还包含 OpenClaw 源码位置。Git checkout 会暴露本地源码根目录，让智能体可以直接检查代码。package install 会包含 GitHub 源码 URL，并告知智能体在文档不完整或过时时前往那里审阅源码。该提示还会注明公共文档镜像、社区 Discord，以及用于 Skills 发现的 ClawHub（[https://clawhub.ai](https://clawhub.ai)）。它会告诉模型，对于 OpenClaw 行为、命令、配置或架构，应先查阅文档，并在可行时自行运行 `openclaw status`（仅在缺少访问权限时询问用户）。对于配置，它会特别指引智能体使用 `gateway` 工具操作 `config.schema.lookup` 获取精确到字段级别的文档和约束，然后再查看 `docs/gateway/configuration.md` 和 `docs/gateway/configuration-reference.md` 获取更广泛的指导。
## 相关
- [Agent 运行时](/zh-CN/concepts/agent)
- [智能体运行时](/zh-CN/concepts/agent)
- [Agent 工作区](/zh-CN/concepts/agent-workspace)
- [上下文引擎](/zh-CN/concepts/context-engine)

182
docs/zh-CN/gateway/local-models.md
View File

@ -1,30 +1,43 @@
---
read_when:
- 你想用自己的 GPU 主机提供模型服务
- 你想从自己的 GPU 机器提供模型服务
- 你正在接入 LM Studio 或 OpenAI 兼容代理
- 你需要最安全的本地模型指导
summary: 在本地 LLM 上运行 OpenClaw（LM Studio、vLLM、LiteLLM、自定义 OpenAI 端点）
summary: 在本地大语言模型上运行 OpenClaw（LM Studio、vLLM、LiteLLM、自定义 OpenAI 端点）
title: 本地模型
x-i18n:
generated_at: "2026-04-30T07:37:57Z"
generated_at: "2026-05-02T21:49:04Z"
model: gpt-5.5
provider: openai
source_hash: 283da11a7896c670d3a249eeb957a252cbda7f7457bd814bb0796f3ca9956723
source_hash: 29ab8530620370e0c213714bf6fef67bafed878055102cea47935c85b6238ffb
source_path: gateway/local-models.md
workflow: 16
---
本地运行可行，但 OpenClaw 需要大上下文 + 对提示注入的强防护。小显卡会截断上下文并削弱安全性。目标配置要高：**≥2 台顶配 Mac Studio 或同等级 GPU 设备（约 $30k+）**。单张 **24 GB** GPU 只适合较轻的提示，并且延迟更高。使用你能运行的**最大 / 全尺寸模型变体**；激进量化或“小型”检查点会提高提示注入风险（参见 [安全](/zh-CN/gateway/security)）。
本地模型是可行的。它们也提高了对硬件、上下文大小和提示注入防御的要求 — 小型或激进量化的显卡会截断上下文并削弱安全性。本页是面向高端本地堆栈和自定义 OpenAI 兼容本地服务器的主观指南。要获得阻力最低的新手引导，请从 [LM Studio](/zh-CN/providers/lmstudio) 或 [Ollama](/zh-CN/providers/ollama) 以及 `openclaw onboard` 开始。
如果你想要阻力最小的本地设置，请从 [LM Studio](/zh-CN/providers/lmstudio) 或 [Ollama](/zh-CN/providers/ollama) 与 `openclaw onboard` 开始。本页是面向高端本地技术栈和自定义 OpenAI 兼容本地服务器的主观指南。
## 硬件下限
目标要高：为了获得舒适的 Agent loop，建议使用 **≥2 台满配 Mac Studio 或等效 GPU 设备（约 $30k+）**。单块 **24 GB** GPU 只适合较轻量的提示，并且延迟更高。始终运行**你能承载的最大/全尺寸变体**；小型或重度量化的检查点会提高提示注入风险（参见 [安全](/zh-CN/gateway/security)）。
## 选择后端
| 后端 | 适用场景 |
| ---------------------------------------------------- | --------------------------------------------------------------------------- |
| [LM Studio](/zh-CN/providers/lmstudio) | 首次本地设置、GUI 加载器、原生 Responses API |
| [Ollama](/zh-CN/providers/ollama) | CLI 工作流、模型库、免维护的 systemd 服务 |
| MLX / vLLM / SGLang | 使用 OpenAI 兼容 HTTP 端点进行高吞吐自托管服务 |
| LiteLLM / OAI-proxy / custom OpenAI-compatible proxy | 你在前面代理另一个模型 API，并需要让 OpenClaw 将其视为 OpenAI |
当后端支持时使用 Responses API（`api: "openai-responses"`）（LM Studio 支持）。否则坚持使用 Chat Completions（`api: "openai-completions"`）。
<Warning>
**WSL2 + Ollama + NVIDIA/CUDA 用户：**官方 Ollama Linux 安装程序会启用一个带有 `Restart=always` 的 systemd 服务。在 WSL2 GPU 设置中，自动启动可能会在启动期间重新加载上一个模型并占满主机内存。如果你的 WSL2 VM 在启用 Ollama 后反复重启，请参见 [WSL2 崩溃循环](/zh-CN/providers/ollama#wsl2-crash-loop-repeated-reboots)。
**WSL2 + Ollama + NVIDIA/CUDA 用户：**官方 Ollama Linux 安装器会启用一个带有 `Restart=always` 的 systemd 服务。在 WSL2 GPU 设置中，自动启动可能会在启动期间重新加载上次的模型并占用宿主机内存。如果你的 WSL2 VM 在启用 Ollama 后反复重启，请参见 [WSL2 崩溃循环](/zh-CN/providers/ollama#wsl2-crash-loop-repeated-reboots)。
</Warning>
## 推荐：LM Studio + 大型本地模型（Responses API）
当前最佳本地技术栈。在 LM Studio 中加载大型模型（例如全尺寸 Qwen、DeepSeek 或 Llama 构建），启用本地服务器（默认 `http://127.0.0.1:1234`），并使用 Responses API 将推理与最终文本分离。
当前最佳本地堆栈。在 LM Studio 中加载大型模型（例如全尺寸 Qwen、DeepSeek 或 Llama 构建），启用本地服务器（默认 `http://127.0.0.1:1234`），并使用 Responses API 将推理与最终文本分离。
```json5
{
@ -64,15 +77,15 @@ x-i18n:
**设置检查清单**
- 安装 LM Studio：[https://lmstudio.ai](https://lmstudio.ai)
- 在 LM Studio 中下载**可用的最大模型构建**（避免“小型”/重度量化变体），启动服务器，确认 `http://127.0.0.1:1234/v1/models` 会列出它。
- 在 LM Studio 中，下载**可用的最大模型构建**（避免“小型”/重度量化变体），启动服务器，确认 `http://127.0.0.1:1234/v1/models` 会列出它。
- 将 `my-local-model` 替换为 LM Studio 中显示的实际模型 ID。
- 保持模型已加载；冷加载会增加启动延迟。
- 如果你的 LM Studio 构建不同，请调整 `contextWindow`/`maxTokens`。
- 对于 WhatsApp，请坚持使用 Responses API，这样只会发送最终文本。
- 对于 WhatsApp，坚持使用 Responses API，这样只会发送最终文本。
即使在本地运行，也保留托管模型配置；使用 `models.mode: "merge"` 让回退保持可用。
即使运行本地模型，也保持托管模型已配置；使用 `models.mode: "merge"`，让回退保持可用。
### 混合配置：托管模型为主，本地作为回退
### 混合配置：托管主模型，本地回退
```json5
{
@ -113,18 +126,18 @@ x-i18n:
}
```
### 本地优先，托管作为安全网
### 本地优先，并保留托管安全网
交换主模型和回退顺序；保持相同的 providers 块与 `models.mode: "merge"`，这样当本地机器不可用时，你可以回退到 Sonnet 或 Opus。
交换主模型和回退的顺序；保留相同的 providers 块和 `models.mode: "merge"`，这样当本地机器不可用时，你可以回退到 Sonnet 或 Opus。
### 区域托管 / 数据路由
### 区域托管/数据路由
- OpenRouter 上也提供托管的 MiniMax/Kimi/GLM 变体，并带有区域固定端点（例如美国托管）。在其中选择区域变体，以便在仍然使用 `models.mode: "merge"` 作为 Anthropic/OpenAI 回退的同时，将流量保留在你选择的司法辖区内。
- 仅本地仍然是隐私性最强的路径；当你需要提供商功能但又想控制数据流时，托管区域路由是折中方案。
- 托管的 MiniMax/Kimi/GLM 变体也存在于 OpenRouter 上，并提供区域固定端点（例如美国托管）。在那里选择区域变体，以便在继续使用 `models.mode: "merge"` 作为 Anthropic/OpenAI 回退的同时，将流量保留在你选择的司法管辖区内。
- 纯本地仍然是最强的隐私路径；当你需要提供商功能但又想控制数据流时，托管区域路由是折中方案。
## 其他 OpenAI 兼容本地代理
如果 MLX (`mlx_lm.server`)、vLLM、SGLang、LiteLLM、OAI-proxy 或自定义 Gateway 网关暴露 OpenAI 风格的 `/v1/chat/completions` 端点，它们就可以工作。除非后端明确记录支持 `/v1/responses`，否则请使用 Chat Completions 适配器。将上面的提供商块替换为你的端点和模型 ID：
MLX（`mlx_lm.server`）、vLLM、SGLang、LiteLLM、OAI-proxy 或自定义 Gateway 网关都可以工作，只要它们公开 OpenAI 风格的 `/v1/chat/completions` 端点即可。除非后端明确记录支持 `/v1/responses`，否则使用 Chat Completions 适配器。将上面的 provider 块替换为你的端点和模型 ID：
```json5
{
@ -158,62 +171,33 @@ x-i18n:
}
```
如果在带有 `baseUrl` 的自定义提供商上省略 `api`，OpenClaw 默认使用 `openai-completions`。诸如 `127.0.0.1` 的 loopback 端点会自动受信任；LAN、tailnet 和私有 DNS 端点仍然需要 `request.allowPrivateNetwork: true`。
如果在带有 `baseUrl` 的自定义 provider 上省略 `api`，OpenClaw 默认使用 `openai-completions`。诸如 `127.0.0.1` 的 loopback 端点会自动受信任；LAN、tailnet 和私有 DNS 端点仍然需要 `request.allowPrivateNetwork: true`。
`models.providers.<id>.models[].id` 值是提供商本地的。不要
在其中包含提供商前缀。例如，使用
`mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit` 启动的 MLX 服务器应使用这个
目录 id 和模型引用：
`models.providers.<id>.models[].id` 值是 provider 本地的。不要在其中包含 provider 前缀。例如，使用 `mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit` 启动的 MLX 服务器应该使用这个目录 ID 和模型引用：
- `models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"`
- `agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"`
在本地或代理的视觉模型上设置 `input: ["text", "image"]`，这样图片
附件会注入到智能体轮次中。交互式自定义提供商
新手引导会推断常见视觉模型 ID，并且只询问未知名称。
非交互式新手引导使用相同的推断；对未知视觉 ID 使用 `--custom-image-input`，
或者当一个看起来已知的模型在你的端点后面实际上仅支持文本时，使用 `--custom-text-input`。
在本地或代理的视觉模型上设置 `input: ["text", "image"]`，让图像附件被注入到智能体轮次中。交互式自定义 provider 新手引导会推断常见视觉模型 ID，并且只询问未知名称。非交互式新手引导使用相同推断；对于未知视觉 ID 使用 `--custom-image-input`，或者当外观看似已知的模型在你的端点后面实际仅支持文本时，使用 `--custom-text-input`。
保留 `models.mode: "merge"`，这样托管模型仍可作为回退。
在提高 `agents.defaults.timeoutSeconds` 之前，对较慢的本地或远程模型
服务器使用 `models.providers.<id>.timeoutSeconds`。提供商超时
仅适用于模型 HTTP 请求，包括连接、标头、正文流式传输，
以及受保护 fetch 的总中止时间。
保持 `models.mode: "merge"`，让托管模型作为回退保持可用。在提高 `agents.defaults.timeoutSeconds` 之前，先为较慢的本地或远程模型服务器使用 `models.providers.<id>.timeoutSeconds`。provider 超时只适用于模型 HTTP 请求，包括连接、标头、正文流式传输，以及受保护 fetch 的总中止时间。
<Note>
对于自定义 OpenAI 兼容提供商，当 `baseUrl` 解析为 loopback、私有 LAN、`.local` 或裸主机名时，持久化非机密本地标记（例如 `apiKey: "ollama-local"`）是可以接受的。OpenClaw 会将其视为有效的本地凭证，而不是报告缺少密钥。对于任何接受公共主机名的提供商，请使用真实值。
对于自定义 OpenAI 兼容 provider，当 `baseUrl` 解析到 loopback、私有 LAN、`.local` 或裸主机名时，允许持久化一个非秘密的本地标记，例如 `apiKey: "ollama-local"`。OpenClaw 会将其视为有效的本地凭证，而不是报告缺少密钥。对任何接受公共主机名的 provider，请使用真实值。
</Note>
本地/代理 `/v1` 后端的行为说明：
- OpenClaw 将这些视为代理风格的 OpenAI 兼容路由，而不是原生
OpenAI 端点
- 原生 OpenAI 专用请求整形不适用于这里：没有
`service_tier`，没有 Responses `store`，没有 OpenAI reasoning 兼容载荷
整形，也没有提示缓存提示
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）
不会注入到这些自定义代理 URL 上
- OpenClaw 将这些视为代理风格的 OpenAI 兼容路由，而不是原生 OpenAI 端点
- 此处不适用仅原生 OpenAI 的请求整形：没有 `service_tier`，没有 Responses `store`，没有 OpenAI 推理兼容载荷整形，也没有提示缓存提示
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）不会注入到这些自定义代理 URL 上
更严格的 OpenAI 兼容后端的兼容性说明：
- 有些服务器在 Chat Completions 上只接受字符串 `messages[].content`，不接受
结构化内容部分数组。对这些端点设置
`models.providers.<provider>.models[].compat.requiresStringContent: true`。
- 有些本地模型会以文本形式发出独立的括号工具请求，例如
`[tool_name]` 后跟 JSON 和 `[END_TOOL_REQUEST]`。OpenClaw 只有在名称与该轮次注册的
工具完全匹配时，才会将其提升为真实工具调用；否则该块会被视为不受支持的文本，并且会
从用户可见回复中隐藏。
- 如果模型发出看起来像工具调用的 JSON、XML 或 ReAct 风格文本，
但提供商没有发出结构化调用，OpenClaw 会将其保留为
文本，并记录一条警告，其中包含运行 id、提供商/模型、检测到的模式，以及
可用时的工具名称。请将其视为提供商/模型工具调用
不兼容，而不是已完成的工具运行。
- 如果工具以助手文本形式出现而不是运行，例如原始 JSON、
XML、ReAct 语法，或者提供商响应中的空 `tool_calls` 数组，
请先验证服务器使用的是具备工具调用能力的聊天模板/解析器。对于
只有在强制使用工具时解析器才工作的 OpenAI 兼容 Chat Completions 后端，
请设置按模型的请求覆盖，而不是依赖文本
解析：
- 一些服务器在 Chat Completions 上只接受字符串 `messages[].content`，不接受结构化 content-part 数组。请为这些端点设置 `models.providers.<provider>.models[].compat.requiresStringContent: true`。
- 一些本地模型会以文本形式发出独立的括号包裹工具请求，例如 `[tool_name]` 后跟 JSON 和 `[END_TOOL_REQUEST]`。只有当名称与该轮次中已注册的工具完全匹配时，OpenClaw 才会将其提升为真实工具调用；否则，该块会被视为不受支持的文本，并从用户可见回复中隐藏。
- 如果模型发出看似工具调用的 JSON、XML 或 ReAct 风格文本，但 provider 没有发出结构化调用，OpenClaw 会将其保留为文本，并在可用时记录一条警告，其中包含运行 ID、provider/模型、检测到的模式以及工具名称。应将其视为 provider/模型工具调用不兼容，而不是已完成的工具运行。
- 如果工具作为 assistant 文本出现而不是运行，例如原始 JSON、XML、ReAct 语法，或 provider 响应中的空 `tool_calls` 数组，请先确认服务器正在使用支持工具调用的 chat template/parser。对于 OpenAI 兼容 Chat Completions 后端，如果其 parser 只有在强制使用工具时才工作，请设置按模型的请求覆盖，而不是依赖文本解析：
```json5
{
@ -233,19 +217,13 @@ x-i18n:
}
```
仅在每个正常轮次都应调用工具的模型/会话中使用它。
它会覆盖 OpenClaw 默认代理值 `tool_choice: "auto"`。
将 `local/my-local-model` 替换为
`openclaw models list` 显示的确切提供商/模型引用。
仅在每个正常轮次都应调用工具的模型/会话中使用此设置。它会覆盖 OpenClaw 默认代理值 `tool_choice: "auto"`。请将 `local/my-local-model` 替换为 `openclaw models list` 显示的确切 provider/模型引用。
```bash
openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
```
- 如果自定义 OpenAI 兼容模型接受内置配置档之外的 OpenAI reasoning effort，
请在模型兼容块上声明它们。在这里添加 `"xhigh"` 会让 `/think xhigh`、
会话选择器、Gateway 网关验证和 `llm-task`
验证为该已配置的提供商/模型引用公开这个级别：
- 如果自定义 OpenAI 兼容模型接受内置档案之外的 OpenAI 推理力度，请在模型 compat 块中声明它们。在这里添加 `"xhigh"` 会让 `/think xhigh`、会话选择器、Gateway 网关验证和 `llm-task` 验证为该已配置的 provider/模型引用公开该级别：
```json5
{
@ -276,63 +254,53 @@ x-i18n:
}
```
- 有些较小或更严格的本地后端在使用 OpenClaw 的完整
智能体运行时提示形态时不稳定，尤其是在包含工具 schema 时。请先
使用精简本地探针验证提供商路径：
## 更小或更严格的后端
```bash
openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json
```
如果模型加载干净，但完整智能体轮次行为异常，请自上而下排查 — 先确认传输，再缩小范围。
要在不使用完整智能体提示形态的情况下验证 Gateway 网关路由，请改用
Gateway 网关模型探针：
1. **确认本地模型本身会响应。** 不使用工具，不带智能体上下文：
```bash
openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
```
```bash
openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json
```
本地和 Gateway 网关模型探针都只发送所提供的提示。
Gateway 网关探针仍会验证 Gateway 网关路由、认证和提供商选择，
但它会有意跳过先前的会话转录、AGENTS/bootstrap 上下文、
上下文引擎组装、工具和内置 MCP 服务器。
2. **确认 Gateway 网关路由。** 只发送提供的提示词 —— 跳过转录、AGENTS 引导、上下文引擎组装、工具和内置 MCP 服务器，但仍会验证 Gateway 网关路由、身份验证和提供商选择：
如果这一步成功，但正常的 OpenClaw 智能体回合失败，请先尝试
`agents.defaults.experimental.localModelLean: true`，以移除 `browser`、`cron`
和 `message` 等重量级默认工具；这是一个实验性
标志，不是稳定的默认模式设置。请参阅
[实验性功能](/zh-CN/concepts/experimental-features)。如果仍然失败，请尝试
`models.providers.<provider>.models[].compat.supportsTools: false`。
```bash
openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
```
- 如果后端仍然只在较大的 OpenClaw 运行中失败，剩余问题
通常是上游模型/服务器容量或后端 bug，而不是 OpenClaw 的
传输层。
3. **尝试精简模式。** 如果两个探测都通过，但真实智能体回合因格式错误的工具调用或过大的提示词而失败，请启用 `agents.defaults.experimental.localModelLean: true`。它会移除三个最重的默认工具（`browser`、`cron`、`message`），让提示词形态更小且不那么脆弱。完整说明、适用场景以及如何确认它已开启，请参阅[实验性功能 → 本地模型精简模式](/zh-CN/concepts/experimental-features#local-model-lean-mode)。
4. **作为最后手段，完全禁用工具。** 如果精简模式还不够，请为该模型条目设置 `models.providers.<provider>.models[].compat.supportsTools: false`。随后该智能体会在该模型上不使用工具调用。
5. **再往后，瓶颈就在上游。** 如果在精简模式和 `supportsTools: false` 之后，后端仍然只在较大的 OpenClaw 运行中失败，剩余问题通常是上游模型或服务器容量 —— 上下文窗口、GPU 内存、kv-cache 驱逐，或者后端缺陷。到这一步，问题就不在 OpenClaw 的传输层了。
## 故障排除
- Gateway 网关能访问代理吗？`curl http://127.0.0.1:1234/v1/models`。
- LM Studio 模型未加载？重新加载；冷启动是常见的“卡住”原因。
- 本地服务器显示 `terminated`、`ECONNRESET`，或在回合中途关闭流？
OpenClaw 会在诊断信息中记录一个低基数的 `model.call.error.failureKind`，以及
OpenClaw 进程 RSS/堆快照。对于 LM Studio/Ollama
- Gateway 网关能连到代理吗？`curl http://127.0.0.1:1234/v1/models`。
- LM Studio 模型是否已卸载？重新加载；冷启动是常见的“卡住”原因。
- 本地服务器提示 `terminated`、`ECONNRESET`，或在回合中途关闭流？
OpenClaw 会在诊断信息中记录低基数的 `model.call.error.failureKind`，以及
OpenClaw 进程的 RSS/堆快照。对于 LM Studio/Ollama
内存压力，请将该时间戳与服务器日志或 macOS 崩溃 /
jetsam 日志对应起来，以确认模型服务器是否被终止。
- OpenClaw 会根据检测到的模型窗口推导上下文窗口预检阈值，或在 `agents.defaults.contextTokens` 降低有效窗口时，根据未封顶的模型窗口推导。低于 20% 时会警告，并设置 **8k** 下限。硬性阻止使用 10% 阈值，并设置 **4k** 下限，且会封顶到有效上下文窗口，因此过大的模型元数据不会拒绝原本有效的用户上限。如果你遇到该预检，请提高服务器/模型上下文限制，或选择更大的模型。
- 上下文错误？降低 `contextWindow`，或提高你的服务器限制。
jetsam 日志进行匹配，以确认模型服务器是否被杀掉。
- OpenClaw 会根据检测到的模型窗口推导上下文窗口预检阈值，或者在 `agents.defaults.contextTokens` 降低有效窗口时，根据未封顶的模型窗口推导阈值。低于 20% 时会发出警告，并设置 **8k** 下限。硬阻断使用 10% 阈值，并设置 **4k** 下限，且会封顶到有效上下文窗口，因此过大的模型元数据不会拒绝原本有效的用户上限。如果你触发该预检，请提高服务器/模型上下文限制，或选择更大的模型。
- 出现上下文错误？降低 `contextWindow`，或提高你的服务器限制。
- OpenAI 兼容服务器返回 `messages[].content ... expected a string`？
在该模型条目上添加 `compat.requiresStringContent: true`。
- 直接的小型 `/v1/chat/completions` 调用可以工作，但 `openclaw infer model run --local`
在 Gemma 或其他本地模型上失败？先检查提供商 URL、模型引用、认证
- 直接的微型 `/v1/chat/completions` 调用可用，但 `openclaw infer model run --local`
在 Gemma 或其他本地模型上失败？先检查提供商 URL、模型引用、身份验证
标记和服务器日志；本地 `model run` 不包含智能体工具。
如果本地 `model run` 成功但较大的智能体回合失败，请用
`localModelLean` 或 `compat.supportsTools: false` 减少智能体
工具面。
如果本地 `model run` 成功但更大的智能体回合失败，请用 `localModelLean` 或 `compat.supportsTools: false` 减少智能体
工具表面。
- 工具调用显示为原始 JSON/XML/ReAct 文本，或提供商返回
空的 `tool_calls` 数组？不要添加一个盲目把助手
空的 `tool_calls` 数组？不要添加会盲目把助手
文本转换为工具执行的代理。先修复服务器聊天模板/解析器。如果
模型只有在强制使用工具时才工作，请添加上面的按模型
`params.extra_body.tool_choice: "required"` 覆盖，并且只在每个回合都预期有工具调用的会话中使用该模型
`params.extra_body.tool_choice: "required"` 覆盖，并且只在预计每个回合都会有工具调用的会话中使用该模型
条目。
- 安全性：本地模型会跳过提供商侧过滤器；保持智能体范围狭窄，并开启压缩以限制提示词注入的影响范围。
- 安全性：本地模型会跳过提供商侧过滤；保持智能体范围收窄，并开启压缩，以限制提示词注入的影响半径。
## 相关