diff --git a/docs/zh-CN/ci.md b/docs/zh-CN/ci.md index 7fbd6c7d5..8594d9768 100644 --- a/docs/zh-CN/ci.md +++ b/docs/zh-CN/ci.md @@ -1,68 +1,68 @@ --- read_when: - - 你需要了解某个 CI 作业为什么运行或未运行 + - 你需要了解为什么 CI 作业运行了或没有运行 - 你正在调试失败的 GitHub Actions 检查 -summary: CI 作业图、范围门禁和本地命令等价项 +summary: CI 作业图、作用域门禁和等效本地命令 title: CI 流水线 x-i18n: - generated_at: "2026-04-29T09:12:46Z" + generated_at: "2026-04-29T10:40:02Z" model: gpt-5.5 provider: openai - source_hash: fe934a27ac3ad314869c9a3995fb83d0fa1bda61f6e31508ce518ce601b0e3d2 + source_hash: 4e4b9dae0e16e5ae701c4dbe5966ac9c4b3d8a3292f1804eef8f595616170e43 source_path: ci.md workflow: 16 --- -CI 会在每次推送到 `main` 和每个拉取请求时运行。它使用智能范围划分，在只有无关区域发生变化时跳过昂贵的作业。手动 `workflow_dispatch` 运行会有意绕过智能范围划分，并为候选发布或广泛验证展开完整的常规 CI 图；对于独立的手动运行，Android lane 可通过 `include_android` 选择启用。仅发布使用的插件预发布 lane 位于单独的 `Plugin Prerelease` 工作流中，并且只会从 `Full Release Validation` 或显式手动调度运行。 +CI 在每次推送到 `main` 以及每个拉取请求时运行。它使用智能作用域，在只有无关区域发生变化时跳过昂贵的作业。手动 `workflow_dispatch` 运行会有意绕过智能作用域，并为发布候选版本或广泛验证展开完整的正常 CI 图；对于独立手动运行，Android 通道通过 `include_android` 选择启用。仅发布用的插件预发布通道位于单独的 `Plugin Prerelease` 工作流中，并且只会从 `Full Release Validation` 或显式手动调度运行。 -`check-dependencies` 分片会运行 `pnpm deadcode:dependencies`，这是一个仅用于生产 Knip 依赖项的检查流程，固定到该脚本使用的最新 Knip 版本，并且为 `dlx` 安装禁用 pnpm 的最小发布年龄。它会拦截新增的未使用、未列出、未解析、二进制或目录依赖项，但不会启用 Knip 的完整未使用文件模式；后者仍然是手动审计，因为 OpenClaw 有意通过清单和字符串说明符加载许多插件和运行时表面。 +`check-dependencies` 分片运行 `pnpm deadcode:dependencies`，这是一个仅依赖项的生产 Knip 检查，固定到该脚本使用的最新 Knip 版本，并且在 `dlx` 安装时禁用 pnpm 的最低发布年龄。它还运行 `pnpm deadcode:unused-files`，将 Knip 的生产未使用文件发现结果与 `scripts/deadcode-unused-files.allowlist.mjs` 进行比较。当 PR 添加新的未审查未使用文件，或在清理后留下过期的允许列表条目时，该保护会失败，同时保留 Knip 无法静态解析的有意动态插件、生成文件、构建、实时测试和包桥接表面。 -`Full Release Validation` 是“发布前运行所有内容”的手动总控工作流。它接受分支、标签或完整提交 SHA，使用该目标调度手动 `CI` 工作流，调度 `Plugin Prerelease` 以提供仅发布使用的插件、包、静态和 Docker 证明，并调度 `OpenClaw Release Checks` 以执行安装冒烟、包验收、Docker 发布路径套件、实时/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram lane。提供已发布包规范时，它还可以运行发布后的 `NPM Telegram Beta E2E` 工作流。`release_profile=minimum|stable|full` 控制传入发布检查的实时/提供商覆盖宽度：`minimum` 保留最快的 OpenAI/核心发布关键 lane，`stable` 增加稳定的提供商/后端集合，`full` 运行广泛的建议提供商/媒体矩阵。该总控工作流会记录已调度的子运行 ID，最终的 `Verify full validation` 作业会重新检查当前子运行结论，并为每个子运行追加最慢作业表。如果某个子工作流重新运行后变绿，只需重新运行父验证器作业即可刷新总控结果和计时摘要。 +`Full Release Validation` 是用于“发布前运行所有内容”的手动总控工作流。它接受一个分支、标签或完整提交 SHA，使用该目标调度手动 `CI` 工作流，调度 `Plugin Prerelease` 以提供仅发布用的插件、包、静态和 Docker 证明，并调度 `OpenClaw Release Checks` 以执行安装冒烟、包验收、Docker 发布路径套件、实时/E2E、OpenWebUI、QA Lab 对等性、Matrix 和 Telegram 通道。当提供已发布包规格时，它也可以运行发布后的 `NPM Telegram Beta E2E` 工作流。`release_profile=minimum|stable|full` 控制传递给发布检查的实时/提供商覆盖广度：`minimum` 保留最快的 OpenAI/核心发布关键通道，`stable` 添加稳定的提供商/后端集合，`full` 运行广泛的顾问提供商/媒体矩阵。该总控工作流会记录已调度的子运行 ID，最终的 `Verify full validation` 作业会重新检查当前子运行结论，并为每个子运行追加最慢作业表。如果某个子工作流重新运行后变绿，只需重新运行父级验证器作业，以刷新总控结果和时间摘要。 -对于恢复，`Full Release Validation` 和 `OpenClaw Release Checks` 都接受 `rerun_group`。对候选发布使用 `all`，仅对常规完整 CI 子项使用 `ci`，对每个发布子项使用 `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`，针对每个发布子项使用 `release-checks`，或者在总控工作流上使用更窄的发布组：`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。这样可以在完成聚焦修复后，将失败发布盒子的重新运行范围限制住。 -发布实时/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-backends`、`native-live-test`、`native-live-extensions-a-k`、`native-live-extensions-l-n`、`native-live-extensions-openai`、`native-live-extensions-o-z-other`、`native-live-extensions-xai`、拆分的媒体音频/视频分片，以及按提供商过滤的音乐分片），而不是一个串行作业。这样可以保持相同的文件覆盖，同时让缓慢的实时提供商失败更容易重新运行和诊断。聚合的 `native-live-extensions-o-z`、`native-live-extensions-media` 和 `native-live-extensions-media-music` 分片名称仍然可用于手动一次性重新运行。 +发布实时/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-backends`、`native-live-test`、`native-live-extensions-a-k`、`native-live-extensions-l-n`、`native-live-extensions-openai`、`native-live-extensions-o-z-other`、`native-live-extensions-xai`、拆分的媒体音频/视频分片，以及按提供商过滤的音乐分片），而不是一个串行作业。这样在保持相同文件覆盖的同时，使慢速实时提供商故障更容易重新运行和诊断。聚合的 `native-live-extensions-o-z`、`native-live-extensions-media` 和 `native-live-extensions-media-music` 分片名称仍然可用于手动一次性重新运行。 -原生实时媒体分片运行在 `Live Media Runner Image` 工作流构建的 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中。该镜像预安装了 `ffmpeg` 和 `ffprobe`；媒体作业只会在设置前验证这些二进制文件。请将 Docker 支撑的实时套件保留在常规 Blacksmith runner 上，因为容器作业并不适合启动嵌套 Docker 测试。 +原生实时媒体分片在 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中运行，该镜像由 `Live Media Runner Image` 工作流构建。该镜像预安装 `ffmpeg` 和 `ffprobe`；媒体作业只会在设置前验证这些二进制文件。将 Docker 支持的实时套件保留在普通 Blacksmith runner 上，因为容器作业不适合启动嵌套 Docker 测试。 -Docker 支撑的实时模型/后端分片会为每个选定提交使用单独的共享 `ghcr.io/openclaw/openclaw-live-test:` 镜像。实时发布工作流会构建并推送该镜像一次，然后 Docker 实时模型、Gateway 网关、CLI 后端、ACP bind 和 Codex harness 分片会以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。如果这些分片独立重建完整源 Docker 目标，说明发布运行配置错误，并会把时间浪费在重复镜像构建上。 +Docker 支持的实时模型/后端分片会为每个选定提交使用单独的共享 `ghcr.io/openclaw/openclaw-live-test:` 镜像。实时发布工作流会构建并推送该镜像一次，然后 Docker 实时模型、Gateway 网关、CLI 后端、ACP 绑定和 Codex harness 分片会使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。如果这些分片独立重新构建完整源 Docker 目标，则说明发布运行配置错误，并会在重复镜像构建上浪费墙钟时间。 -`OpenClaw Release Checks` 使用受信任的工作流引用将选定引用解析一次为 `release-package-under-test` tarball，然后把该工件传递给实时/E2E 发布路径 Docker 工作流和包验收分片。这样可以让发布盒之间的包字节保持一致，并避免在多个子作业中重新打包同一个候选项。 +`OpenClaw Release Checks` 使用受信任的工作流引用，将选定引用一次性解析为 `release-package-under-test` tarball，然后将该产物传递给实时/E2E 发布路径 Docker 工作流和包验收分片。这能确保发布盒子之间的包字节保持一致，并避免在多个子作业中重新打包同一个候选版本。 -`Package Acceptance` 是用于验证包工件而不阻塞发布工作流的旁路运行工作流。它会从已发布的 npm 规范、使用选定 `workflow_ref` harness 构建的受信任 `package_ref`、带 SHA-256 的 HTTPS tarball URL，或另一个 GitHub Actions 运行中的 tarball 工件解析一个候选项，将其作为 `package-under-test` 上传，然后复用 Docker 发布/E2E 调度器，并使用该 tarball，而不是重新打包工作流检出。配置文件覆盖冒烟、包、产品、完整和自定义 Docker lane 选择。`package` 配置文件使用离线插件覆盖，因此已发布包验证不会受实时 ClawHub 可用性影响。可选的 Telegram lane 会在 `NPM Telegram Beta E2E` 工作流中复用 `package-under-test` 工件，同时保留已发布 npm 规范路径用于独立调度。 +`Package Acceptance` 是用于验证包产物且不阻塞发布工作流的旁路运行工作流。它从已发布的 npm 规格、使用选定 `workflow_ref` harness 构建的受信任 `package_ref`、带 SHA-256 的 HTTPS tarball URL，或来自另一个 GitHub Actions 运行的 tarball 产物中解析一个候选版本，将其上传为 `package-under-test`，然后使用该 tarball 复用 Docker 发布/E2E 调度器，而不是重新打包工作流检出。配置文件覆盖冒烟、包、产品、完整和自定义 Docker 通道选择。`package` 配置文件使用离线插件覆盖，因此已发布包验证不会受实时 ClawHub 可用性限制。可选的 Telegram 通道会在 `NPM Telegram Beta E2E` 工作流中复用 `package-under-test` 产物，并为独立调度保留已发布 npm 规格路径。 ## 包验收 -当问题是“这个可安装的 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 清单，在需要时准备 package-digest Docker 镜像，并针对该包运行选定的 Docker lane，而不是打包工作流检出。当某个配置文件选择多个目标 `docker_lanes` 时，可复用工作流会准备一次包和共享镜像，然后将这些 lane 展开为并行的目标 Docker 作业，并使用唯一工件。 -3. `package_telegram` 可选调用 `NPM Telegram Beta E2E`。当 `telegram_mode` 不是 `none` 时运行，并在包验收解析到包时安装同一个 `package-under-test` 工件；独立 Telegram 调度仍然可以安装已发布的 npm 规范。 -4. `summary` 会在包解析、Docker 验收或可选 Telegram lane 失败时让工作流失败。 +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 清单，在需要时准备 package-digest Docker 镜像，并针对该包运行选定的 Docker 通道，而不是打包工作流检出。当某个配置文件选择多个目标 `docker_lanes` 时，可复用工作流会准备一次包和共享镜像，然后将这些通道展开为并行目标 Docker 作业，并使用唯一产物。 +3. `package_telegram` 可选调用 `NPM Telegram Beta E2E`。当 `telegram_mode` 不是 `none` 时运行，并且在 Package Acceptance 已解析某个包时安装同一个 `package-under-test` 产物；独立 Telegram 调度仍然可以安装已发布 npm 规格。 +4. `summary` 会在包解析、Docker 验收或可选 Telegram 通道失败时使工作流失败。 -候选项来源： +候选来源： -- `source=npm`：仅接受 `openclaw@beta`、`openclaw@latest` 或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。用于已发布 beta/稳定版验收。 -- `source=ref`：打包受信任的 `package_ref` 分支、标签或完整提交 SHA。解析器会获取 OpenClaw 分支/标签，验证选定提交可从仓库分支历史或发布标签访问，在分离的工作树中安装依赖项，并使用 `scripts/package-openclaw-for-docker.mjs` 打包。 +- `source=npm`：仅接受 `openclaw@beta`、`openclaw@latest`，或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。用于已发布 beta/稳定版验收。 +- `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` 是可选项，但对于外部共享的工件应提供。 +- `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 可以验证较旧的受信任源提交，而无需运行旧的工作流逻辑。 配置文件映射到 Docker 覆盖： - `smoke`：`npm-onboard-channel-agent`、`gateway-network`、`config-reload` - `package`：`npm-onboard-channel-agent`、`doctor-switch`、`update-channel-switch`、`bundled-channel-deps-compat`、`plugins-offline`、`plugin-update` - `product`：`package` 加上 `mcp-channels`、`cron-mcp-cleanup`、`openai-web-search-minimal`、`openwebui` -- `full`：带 OpenWebUI 的完整 Docker 发布路径块 -- `custom`：精确的 `docker_lanes`；当 `suite_profile=custom` 时必填 +- `full`：包含 OpenWebUI 的完整 Docker 发布路径分块 +- `custom`：精确的 `docker_lanes`；当 `suite_profile=custom` 时必需 -发布检查会使用 `source=ref`、`package_ref=`、`workflow_ref=`、`suite_profile=custom`、`docker_lanes='bundled-channel-deps-compat plugins-offline'` 和 `telegram_mode=mock-openai` 调用包验收。发布路径 Docker 块覆盖重叠的包/更新/插件 lane，而包验收会针对同一个已解析包 tarball 保留工件原生的内置渠道兼容性、离线插件和 Telegram 证明。 -跨 OS 发布检查仍然覆盖 OS 特定的新手引导、安装器和平台行为；包/更新产品验证应从包验收开始。Windows 打包和安装器全新 lane 还会验证已安装包是否可以从原始绝对 Windows 路径导入 browser-control override。 +发布检查会使用 `source=ref`、`package_ref=`、`workflow_ref=`、`suite_profile=custom`、`docker_lanes='bundled-channel-deps-compat plugins-offline'` 和 `telegram_mode=mock-openai` 调用 Package Acceptance。发布路径 Docker 分块覆盖重叠的包/更新/插件通道，而 Package Acceptance 保留针对同一已解析包 tarball 的产物原生内置渠道兼容性、离线插件和 Telegram 证明。 +跨 OS 发布检查仍然覆盖特定于 OS 的新手引导、安装器和平台行为；包/更新产品验证应从 Package Acceptance 开始。Windows 打包和安装器全新通道还会验证已安装包能否从原始绝对 Windows 路径导入 browser-control 覆盖。 -对于已经发布的包，包验收有有界的旧版兼容窗口。到 `2026.4.25` 为止的包（包括 `2026.4.25-beta.*`）可以对 `dist/postinstall-inventory.json` 中指向 tarball 省略文件的已知私有 QA 条目使用兼容路径；当包不暴露该标志时，`doctor-switch` 可以跳过 `gateway install --wrapper` 持久化子用例；`update-channel-switch` 可以从 tarball 派生的假 git fixture 中裁剪缺失的 `pnpm.patchedDependencies`，并可以记录缺失的持久化 `update.channel`；插件冒烟可以读取旧版安装记录位置，或接受缺少 marketplace 安装记录持久化；`plugin-update` 可以允许配置元数据迁移，同时仍要求安装记录和不重新安装行为保持不变。已发布的 `2026.4.26` 包也可以对已经发布的本地构建元数据标记文件发出警告。后续包必须满足现代契约；相同条件会失败，而不是警告或跳过。 +对于已发布的包，Package Acceptance 有有界的旧版兼容窗口。直到 `2026.4.25` 的包（包括 `2026.4.25-beta.*`）可以对 `dist/postinstall-inventory.json` 中指向 tarball 省略文件的已知私有 QA 条目使用兼容路径；当包未暴露 `gateway install --wrapper` 标志时，`doctor-switch` 可以跳过其持久化子用例；`update-channel-switch` 可以从 tarball 派生的假 git fixture 中剪除缺失的 `pnpm.patchedDependencies`，并可以记录缺失的持久化 `update.channel`；插件冒烟可以读取旧版安装记录位置，或接受缺失的 marketplace 安装记录持久化；`plugin-update` 可以允许配置元数据迁移，同时仍要求安装记录和不重新安装行为保持不变。已发布的 `2026.4.26` 包也可以对已经随包发布的本地构建元数据戳文件发出警告。之后的包必须满足现代契约；相同条件会失败，而不是警告或跳过。 示例： @@ -105,115 +105,23 @@ 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 通道，而不是重跑完整发布验证。 -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 租约。发布 -检查会使用确定性模拟提供商和模拟限定模型（`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` 作业中。`OpenClaw Release Checks` 还会 -在发布审批前运行发布关键的 QA Lab 流水线；其 QA 一致性 -门会把候选包和基线包作为并行流水线作业运行，然后将 -两个工件下载到一个小型报告作业中，用于最终一致性比较。 -不要把 PR 落地路径置于 `Parity gate` 之后，除非变更确实 -触及 QA 运行时、模型包一致性，或一致性工作流拥有的表面。 -对于普通渠道、配置、文档或单元测试修复，把它视为可选 -信号，并遵循作用域化的 CI/检查证据。 +QA Lab 有独立于主智能作用域工作流之外的专用 CI 通道。`Parity gate` 工作流会在匹配的 PR 变更和手动派发时运行；它会构建私有 QA 运行时，并比较模拟 GPT-5.5 和 Opus 4.6 智能体包。`QA-Lab - All Lanes` 工作流每晚在 `main` 上运行，也可手动派发；它会将模拟 parity gate、实时 Matrix 通道，以及实时 Telegram 和 Discord 通道作为并行作业展开。实时作业使用 `qa-live-shared` 环境，Telegram/Discord 使用 Convex leases。发布检查使用确定性模拟提供商和模拟限定模型（`mock-openai/gpt-5.5` 和 `mock-openai/gpt-5.5-alt`）运行 Matrix 和 Telegram 实时传输通道，以便将渠道契约与实时模型延迟和正常提供商插件启动隔离开。实时传输 Gateway 网关还会禁用内存搜索，因为 QA parity 会单独覆盖内存行为；提供商连接性由单独的实时模型、原生提供商和 Docker 提供商套件覆盖。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 parity gate 会将候选包和基线包作为并行通道作业运行，然后在一个小型报告作业中下载两者的产物，用于最终 parity 对比。除非变更实际触及 QA 运行时、模型包 parity，或 parity 工作流拥有的表面，否则不要把 PR 落地路径放在 `Parity gate` 后面。对于常规渠道、配置、文档或单元测试修复，将它视为可选信号，并遵循作用域内的 CI/检查证据。 -`Duplicate PRs After Merge` 工作流是用于落地后重复项清理的手动维护者工作流。 -它默认 dry-run，且仅在 `apply=true` 时关闭明确 -列出的 PR。在修改 GitHub 之前，它会验证 -已落地 PR 已合并，并且每个重复项都有共享的引用 issue -或重叠的变更 hunks。 +`Duplicate PRs After Merge` 工作流是用于落地后重复清理的手动维护者工作流。它默认 dry-run，并且仅在 `apply=true` 时关闭显式列出的 PR。在修改 GitHub 前，它会验证落地 PR 已合并，并且每个重复 PR 都有共享的引用 issue 或重叠的变更 hunk。 -`CodeQL` 工作流有意作为窄范围的第一道安全扫描器， -而不是完整仓库扫描。每日和手动运行会使用高精度安全查询扫描 Actions 工作流代码 -以及风险最高的 JavaScript/TypeScript 凭证、密钥、沙箱、cron 和 -网关表面。 -channel-runtime-boundary 作业会在 `/codeql-critical-security/channel-runtime-boundary` -类别下单独扫描核心渠道实现 -契约以及渠道插件运行时、Gateway 网关、插件 SDK、密钥和 -审计触点，这样渠道安全信号就能在不扩大基线 -JS/TS 类别的情况下扩展。 +`CodeQL` 工作流刻意作为窄范围的第一轮安全扫描器，而不是完整仓库扫描。每日和手动运行会使用高精度安全查询扫描 Actions 工作流代码，以及风险最高的 JavaScript/TypeScript 凭证、密钥、沙箱、cron 和 Gateway 网关表面。channel-runtime-boundary 作业会在 `/codeql-critical-security/channel-runtime-boundary` 类别下，单独扫描核心渠道实现契约以及渠道插件运行时、Gateway 网关、插件 SDK、密钥和审计触点，以便渠道安全信号能够扩展，而不需要扩大基线 JS/TS 类别。 -`CodeQL Android Critical Security` 工作流是计划运行的 Android -安全分片。它会在 workflow sanity 接受的最小 Blacksmith Linux runner 标签上为 CodeQL -手动构建 Android 应用，并在 -`/codeql-critical-security/android` 类别下上传结果。 +`CodeQL Android Critical Security` 工作流是计划运行的 Android 安全分片。它会在 workflow sanity 接受的最小 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 macOS Critical Security` 工作流是每周/手动运行的 macOS 安全分片。它会在 Blacksmith macOS 上为 CodeQL 手动构建 macOS 应用，从上传的 SARIF 中过滤掉依赖构建结果，并在 `/codeql-critical-security/macos` 类别下上传结果。将它保持在每日默认工作流之外，因为即使结果干净，macOS 构建也会主导运行时间。 -`CodeQL Critical Quality` 工作流是配套的非安全分片。它 -只在较小的 Blacksmith Linux runner 上，对窄范围高价值表面运行错误严重级别、非安全的 JavaScript/TypeScript 质量查询。其 -core-auth-secrets 作业会在独立的 `/codeql-critical-quality/core-auth-secrets` -类别下扫描凭证、密钥、沙箱、cron 和网关安全 -边界代码。config-boundary -作业会在独立的 `/codeql-critical-quality/config-boundary` 类别下扫描配置 schema、迁移、规范化和 IO 契约。 -gateway-runtime-boundary 作业会在独立的 -`/codeql-critical-quality/gateway-runtime-boundary` 类别下扫描网关协议 schema 和服务器方法 -契约。 -channel-runtime-boundary 作业会在独立的 `/codeql-critical-quality/channel-runtime-boundary` 类别下扫描核心渠道实现契约。 -agent-runtime-boundary 作业会在独立的 `/codeql-critical-quality/agent-runtime-boundary` 类别下扫描命令执行、模型/提供商分派、 -自动回复分派和队列，以及 ACP 控制平面运行时契约。 -mcp-process-runtime-boundary 作业会在独立的 -`/codeql-critical-quality/mcp-process-runtime-boundary` 类别下扫描 MCP 服务器和工具桥、进程 -监管辅助函数，以及出站投递契约。 -memory-runtime-boundary 作业会在独立的 `/codeql-critical-quality/memory-runtime-boundary` -类别下扫描内存主机 SDK、内存运行时 facade、 -内存插件 SDK 别名、内存运行时激活胶水代码，以及内存 Doctor -命令。 -ui-control-plane 作业会在独立的 -`/codeql-critical-quality/ui-control-plane` 类别下扫描 Control UI 引导、本地持久化、Gateway 网关 -控制流和任务控制平面运行时契约。 -web-media-runtime-boundary 作业会在独立的 `/codeql-critical-quality/web-media-runtime-boundary` 类别下扫描核心 Web 获取/搜索、媒体 IO、媒体 -理解、图像生成和媒体生成运行时契约。 -plugin-boundary 作业会在独立的 `/codeql-critical-quality/plugin-boundary` -类别下扫描加载器、注册表、公共表面和插件 SDK -入口点契约。让该工作流与安全分离，这样质量发现就可以 -在不掩盖安全信号的情况下进行计划、度量、禁用或扩展。 -Swift、Python 和内置插件 CodeQL 扩展只应在窄配置文件具备稳定 -运行时和信号之后，作为有作用域或分片的后续工作重新添加。 +`CodeQL Critical Quality` 工作流是对应的非安全分片。它仅在较小的 Blacksmith Linux runner 上，对窄范围高价值表面运行 error 级别、非安全的 JavaScript/TypeScript 质量查询。其 core-auth-secrets 作业会在单独的 `/codeql-critical-quality/core-auth-secrets` 类别下扫描凭证、密钥、沙箱、cron 和 Gateway 网关安全边界代码。config-boundary 作业会在单独的 `/codeql-critical-quality/config-boundary` 类别下扫描配置 schema、迁移、规范化和 IO 契约。gateway-runtime-boundary 作业会在单独的 `/codeql-critical-quality/gateway-runtime-boundary` 类别下扫描 Gateway 网关协议 schema 和服务器方法契约。channel-runtime-boundary 作业会在单独的 `/codeql-critical-quality/channel-runtime-boundary` 类别下扫描核心渠道实现契约。agent-runtime-boundary 作业会在单独的 `/codeql-critical-quality/agent-runtime-boundary` 类别下扫描命令执行、模型/提供商调度、自动回复调度和队列，以及 ACP 控制平面运行时契约。mcp-process-runtime-boundary 作业会在单独的 `/codeql-critical-quality/mcp-process-runtime-boundary` 类别下扫描 MCP 服务器和工具桥、进程监督辅助函数，以及出站投递契约。memory-runtime-boundary 作业会在单独的 `/codeql-critical-quality/memory-runtime-boundary` 类别下扫描内存宿主 SDK、内存运行时 facade、内存插件 SDK 别名、内存运行时激活胶水代码，以及内存 Doctor 命令。ui-control-plane 作业会在单独的 `/codeql-critical-quality/ui-control-plane` 类别下扫描 Control UI 启动、本地持久化、Gateway 网关控制流，以及任务控制平面运行时契约。web-media-runtime-boundary 作业会在单独的 `/codeql-critical-quality/web-media-runtime-boundary` 类别下扫描核心 Web 获取/搜索、媒体 IO、媒体理解、图像生成和媒体生成运行时契约。plugin-boundary 作业会在单独的 `/codeql-critical-quality/plugin-boundary` 类别下扫描加载器、注册表、公共表面和插件 SDK 入口点契约。让该工作流与安全分离，以便质量发现可以被计划、度量、禁用或扩展，而不遮蔽安全信号。Swift、Python 和内置插件的 CodeQL 扩展应仅在这些窄 profile 具备稳定运行时间和信号后，再作为有作用域或分片的后续工作加回。 -`Docs Agent` 工作流是一个事件驱动的 Codex 维护流水线，用于保持 -现有文档与最近落地的变更一致。它没有纯计划：在 `main` 上 -成功的非机器人 push CI 运行可以触发它，手动分派也可以 -直接运行它。当 `main` 已前进，或最近一小时内已创建另一个未跳过的 Docs Agent 运行时，workflow-run 调用会跳过。运行时，它会 -审查从上一个未跳过 Docs Agent 源 SHA 到当前 `main` 的提交范围， -因此一次每小时运行可以覆盖自上次文档检查以来积累的所有 main 变更。 +`Docs Agent` 工作流是事件驱动的 Codex 维护通道，用于让现有文档与最近落地的变更保持一致。它没有纯计划任务：`main` 上成功的非 bot push CI 运行可以触发它，手动派发也可以直接运行它。当 `main` 已前进，或最近一小时内已创建另一个未跳过的 Docs Agent 运行时，workflow-run 调用会跳过。运行时，它会审查从上一个未跳过的 Docs Agent 源 SHA 到当前 `main` 的提交范围，因此一次每小时运行可以覆盖自上次文档通过以来累积的所有 main 变更。 -`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 就能保持与 docs agent 相同的 drop-sudo 安全姿态。 +`Test Performance Agent` 工作流是事件驱动的 Codex 维护通道，用于处理慢测试。它没有纯计划任务：`main` 上成功的非 bot push CI 运行可以触发它，但如果当天 UTC 已经有另一个 workflow-run 调用运行过或正在运行，它会跳过。手动派发会绕过当天活动门禁。该通道会构建完整套件分组 Vitest 性能报告，让 Codex 只进行保留覆盖率的小型测试性能修复，而不是大范围重构，然后重跑完整套件报告，并拒绝降低通过基线测试数量的变更。如果基线存在失败测试，Codex 只能修复明显失败，并且 agent 后的完整套件报告必须通过后才会提交任何内容。当 `main` 在 bot push 落地前前进时，该通道会 rebase 已验证的补丁，重跑 `pnpm check:changed`，并重试 push；有冲突的陈旧补丁会被跳过。它使用 GitHub 托管的 Ubuntu，以便 Codex action 可以保持与 docs agent 相同的 drop-sudo 安全姿态。 ```bash gh workflow run duplicate-after-merge.yml \ @@ -224,30 +132,30 @@ gh workflow run duplicate-after-merge.yml \ ## 作业概览 -| 作业 | 用途 | 运行时机 | +| 作业 | 目的 | 运行时机 | | -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | 检测仅文档变更、变更作用域、变更插件，并构建 CI manifest | 始终在非草稿 push 和 PR 上运行 | -| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 始终在非草稿 push 和 PR 上运行 | -| `security-dependency-audit` | 针对 npm advisory 的无依赖生产 lockfile 审计 | 始终在非草稿 push 和 PR 上运行 | -| `security-fast` | 快速安全作业的必需聚合项 | 始终在非草稿 push 和 PR 上运行 | -| `build-artifacts` | 构建 `dist/`、Control UI、构建工件检查和可复用下游工件 | Node 相关变更 | -| `checks-fast-core` | 快速 Linux 正确性流水线，例如内置/插件契约/协议检查 | Node 相关变更 | -| `checks-fast-contracts-channels` | 带有稳定聚合检查结果的分片渠道契约检查 | Node 相关变更 | -| `checks-node-core-test` | 核心 Node 测试分片，不包括渠道、内置、契约和插件流水线 | Node 相关变更 | -| `check` | 分片主本地门等价项：生产类型、lint、guard、测试类型和严格 smoke | Node 相关变更 | -| `check-additional` | 架构、边界、插件表面 guard、包边界和 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 Skills 相关变更 | -| `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 成功或手动分派 | +| `preflight` | 检测仅文档变更、变更作用域、变更插件，并构建 CI manifest | 始终在非草稿 push 和 PR 上运行 | +| `security-scm-fast` | 通过 `zizmor` 执行私钥检测和工作流审计 | 始终在非草稿 push 和 PR 上运行 | +| `security-dependency-audit` | 对照 npm advisories 执行无依赖生产 lockfile 审计 | 始终在非草稿 push 和 PR 上运行 | +| `security-fast` | 快速安全作业的必需聚合项 | 始终在非草稿 push 和 PR 上运行 | +| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查和可复用下游产物 | Node 相关变更 | +| `checks-fast-core` | 快速 Linux 正确性通道，例如内置/插件契约/协议检查 | Node 相关变更 | +| `checks-fast-contracts-channels` | 分片渠道契约检查，并提供稳定的聚合检查结果 | Node 相关变更 | +| `checks-node-core-test` | 核心 Node 测试分片，不包括渠道、内置、契约和插件通道 | Node 相关变更 | +| `check` | 分片的主本地门禁等价项：生产类型、lint、guard、测试类型和严格 smoke | Node 相关变更 | +| `check-additional` | 架构、边界、插件表面 guard、软件包边界和 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 特定进程/路径测试，以及共享运行时 import specifier 回归 | Windows 相关变更 | +| `macos-node` | 使用共享构建产物的 macOS TypeScript 测试通道 | macOS 相关变更 | +| `macos-swift` | macOS 应用的 Swift lint、构建和测试 | macOS 相关变更 | +| `android` | 两种 flavor 的 Android 单元测试，以及一次 debug APK 构建 | Android 相关变更 | +| `test-performance-agent` | 可信活动后的每日 Codex 慢测试优化 | Main CI 成功或手动派发 | -手动 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 中的工作流文件，针对分支、标签或完整 commit SHA 运行该图。 +手动 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` workflow 且启用发布验证门禁时运行。手动运行使用唯一的并发组，因此发布候选的完整套件不会被同一 ref 上的另一次 push 或 PR 运行取消。可选的 `target_ref` 输入允许受信任的调用方使用所选调度 ref 中的 workflow 文件，针对分支、标签或完整 commit SHA 运行该作业图。 ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -257,65 +165,47 @@ gh workflow run full-release-validation.yml --ref main -f ref= ## 快速失败顺序 -作业按顺序排列，让低成本检查先于高成本作业失败： +作业经过排序，让低成本检查先于高成本检查失败： -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 车道重叠运行，因此下游消费者可在共享构建就绪后立即开始。 +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`。 -作用域逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。手动分发会跳过变更作用域检测，并让预检清单表现得像每个受作用域限制的区域都已变更。 -CI 工作流编辑会验证 Node CI 图以及工作流 lint，但其本身不会强制运行 Windows、Android 或 macOS 原生构建；这些平台车道仍只限于平台源文件变更。 -仅 CI 路由编辑、选定的低成本核心测试 fixture 编辑，以及窄范围插件契约辅助工具/测试路由编辑会使用快速的仅 Node 清单路径：预检、安全检查和单个 `checks-fast-core` 任务。当变更文件仅限于路由或辅助工具表面，且快速任务会直接覆盖这些表面时，此路径会避开构建构件、Node 22 兼容性、渠道契约、完整核心分片、内置插件分片和额外防护矩阵。 -Windows Node 检查的作用域限于 Windows 专用进程/路径包装器、npm/pnpm/UI runner 辅助工具、包管理器配置，以及执行该车道的 CI 工作流表面；无关的源文件、插件、安装冒烟和仅测试变更继续留在 Linux Node 车道上，因此不会为普通测试分片已经覆盖的内容占用一个 16-vCPU Windows worker。 -单独的 `install-smoke` 工作流通过自己的 `preflight` 作业复用同一个作用域脚本。它将冒烟覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。Pull request 会针对 Docker/包表面、内置插件包/清单变更，以及 Docker 冒烟作业会覆盖的核心插件/渠道/Gateway 网关/插件 SDK 表面运行快速路径。仅源代码的内置插件变更、仅测试编辑和仅文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete shared-workspace CLI 冒烟，运行容器 gateway-network e2e，验证一个内置扩展构建参数，并在 240 秒聚合命令超时下运行有界内置插件 Docker profile，同时每个场景的 Docker run 单独设限。完整路径为夜间计划运行、手动分发、workflow-call 发布检查，以及真正触及安装器/包/Docker 表面的 pull request 保留 QR 包安装和安装器 Docker/更新覆盖。`main` push（包括 merge commit）不会强制完整路径；当变更作用域逻辑会在 push 上请求完整覆盖时，工作流保留快速 Docker 冒烟，并将完整安装冒烟留给夜间或发布验证。较慢的 Bun 全局安装 image-provider 冒烟由 `run_bun_global_install_smoke` 单独门控；它会在夜间计划和发布检查工作流中运行，手动 `install-smoke` 分发也可以选择启用，但 pull request 和 `main` push 不会运行它。QR 和安装器 Docker 测试保留各自面向安装的 Dockerfile。本地 `test:docker:all` 会预构建一个共享 live-test 镜像，将 OpenClaw 打包一次为 npm tarball，并构建两个共享的 `scripts/e2e/Dockerfile` 镜像：一个用于安装器/更新/插件依赖车道的裸 Node/Git runner，以及一个将同一 tarball 安装到 `/app`、用于普通功能车道的功能镜像。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` 调整默认 main-pool 槽位数 10，用 `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` 调整对提供商敏感的 tail-pool 槽位数 10。重车道上限默认为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`，这样 npm install 和多服务车道不会让 Docker 过载，同时较轻的车道仍能填满可用槽位。单个比有效上限更重的车道仍可从空池启动，然后独占运行直到释放容量。车道启动默认错开 2 秒，以避免本地 Docker daemon 创建风暴；可用 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` 或其他毫秒值覆盖。本地聚合会预检 Docker、移除陈旧的 OpenClaw E2E 容器、输出活动车道状态、持久化车道耗时以便按最长优先排序，并支持 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 用于检查调度器。默认情况下，它会在首次失败后停止调度新的池化车道，并且每个车道都有 120 分钟的回退超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；选定的 live/tail 车道使用更严格的每车道上限。`OPENCLAW_DOCKER_ALL_LANES=` 会运行精确的调度器车道，包括仅发布车道（如 `install-e2e`）以及拆分的内置更新车道（如 `bundled-channel-update-acpx`），同时跳过清理冒烟，以便 agents 能复现单个失败车道。可复用的 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` 输入或现有包摘要镜像，而不是重新构建。`Package Acceptance` 工作流是高级包门禁：它会从 npm、受信任的 `package_ref`、HTTPS tarball 加 SHA-256，或之前的工作流构件解析候选包，然后把这个单一的 `package-under-test` 构件传给可复用的 Docker E2E 工作流。它将 `workflow_ref` 与 `package_ref` 分开，这样当前验收逻辑无需检出旧工作流代码，就能验证较早的受信任 commit。发布检查会针对目标 ref 运行自定义 Package Acceptance delta：内置渠道兼容性、离线插件 fixture，以及基于已解析 tarball 的 Telegram 包 QA。发布路径 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|plugins-runtime-install-b|plugins-runtime-install-c|plugins-runtime-install-d|bundled-channels`）。当完整 release-path 覆盖请求 OpenWebUI 时，它会并入 `plugins-runtime-services`，只有在仅 OpenWebUI 分发时才保留独立的 `openwebui` 分块。旧版聚合分块名称 `package-update`、`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍可用于手动重跑，但发布工作流使用拆分分块，这样安装器 E2E 和内置插件安装/卸载扫描不会主导关键路径。`install-e2e` 车道别名仍是两个提供商安装器车道的聚合手动重跑别名。`bundled-channels` 分块会运行拆分的 `bundled-channel-*` 和 `bundled-channel-update-*` 车道，而不是串行的全量一体 `bundled-channel-deps` 车道。每个分块都会上传 `.artifacts/docker-tests/`，其中包含车道日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON、慢车道表，以及每车道重跑命令。工作流 `docker_lanes` 输入会在准备好的镜像上运行选定车道，而不是运行分块作业，从而将失败车道调试限制在一个目标 Docker 作业内，并为该运行准备、下载或复用包构件；如果选定车道是 live Docker 车道，目标作业会为该重跑在本地构建 live-test 镜像。生成的每车道 GitHub 重跑命令会在这些值存在时包含 `package_artifact_run_id`、`package_artifact_name` 和准备好的镜像输入，因此失败车道可以复用失败运行中的确切包和镜像。使用 `pnpm test:docker:rerun ` 从 GitHub 运行下载 Docker 构件，并打印组合/每车道目标重跑命令；使用 `pnpm test:docker:timings ` 查看慢车道和阶段关键路径摘要。计划的 live/E2E 工作流每天运行完整 release-path Docker 套件。内置更新矩阵按更新目标拆分，因此重复的 npm update 和 Doctor 修复流程可与其他内置检查一起分片。 +作用域逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。 +手动调度会跳过变更作用域检测，并让预检清单表现得好像每个作用域区域都已更改。 +CI workflow 编辑会验证 Node CI 图和 workflow lint，但其本身不会强制 Windows、Android 或 macOS 原生构建；这些平台车道仍然只针对平台源代码变更启用。 +仅 CI 路由编辑、选定的低成本核心测试 fixture 编辑，以及范围很窄的插件契约辅助/测试路由编辑会使用快速的仅 Node 清单路径：preflight、security 和单个 `checks-fast-core` 任务。当变更文件仅限于该快速任务直接覆盖的路由或辅助表面时，该路径会避开构建制品、Node 22 兼容性、渠道契约、完整核心分片、内置插件分片和额外守护矩阵。 +Windows Node 检查的作用域限定为 Windows 特定的进程/路径包装器、npm/pnpm/UI runner 辅助、包管理器配置，以及执行该车道的 CI workflow 表面；无关的源代码、插件、安装冒烟和仅测试变更会留在 Linux Node 车道上，因此不会为了普通测试分片已覆盖的覆盖范围而占用 16-vCPU Windows worker。 +单独的 `install-smoke` workflow 通过自己的 `preflight` 作业复用同一个作用域脚本。它将冒烟覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。Pull request 会针对 Docker/包表面、内置插件包/manifest 变更，以及 Docker 冒烟作业覆盖的核心插件/渠道/Gateway 网关/插件 SDK 表面运行快速路径。仅源代码的内置插件变更、仅测试编辑和仅文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像、检查 CLI、运行 agents delete shared-workspace CLI 冒烟、运行容器 gateway-network e2e、验证内置插件构建参数，并在 240 秒聚合命令超时内运行有界内置插件 Docker profile，其中每个场景的 Docker run 都单独限时。完整路径为夜间定时运行、手动调度、workflow-call 发布检查，以及真正触及安装器/包/Docker 表面的 pull request 保留 QR 包安装和安装器 Docker/更新覆盖。`main` push，包括 merge commit，不会强制完整路径；当变更作用域逻辑会在 push 上请求完整覆盖时，workflow 会保留快速 Docker 冒烟，并将完整安装冒烟留给夜间或发布验证。较慢的 Bun 全局安装 image-provider 冒烟由 `run_bun_global_install_smoke` 单独 gating；它会在夜间计划任务和发布检查 workflow 中运行，手动 `install-smoke` 调度可以选择启用它，但 pull request 和 `main` push 不会运行它。QR 和安装器 Docker 测试保留各自面向安装的 Dockerfile。本地 `test:docker:all` 会预构建一个共享 live-test 镜像，将 OpenClaw 打包一次为 npm tarball，并构建两个共享的 `scripts/e2e/Dockerfile` 镜像：一个用于安装器/更新/插件依赖车道的裸 Node/Git runner，以及一个将同一个 tarball 安装到 `/app`、用于普通功能车道的功能性镜像。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` 调整默认 main-pool 槽位数 10，并使用 `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` 调整对提供商敏感的 tail-pool 槽位数 10。重型车道上限默认为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`，这样 npm install 和多服务车道不会过度占用 Docker，而较轻的车道仍能填满可用槽位。单个比有效上限更重的车道仍可从空池启动，然后独占运行直到释放容量。默认情况下，车道启动会错开 2 秒，以避免本地 Docker daemon create 风暴；可用 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` 或其他毫秒值覆盖。本地聚合会预检 Docker、移除过期的 OpenClaw E2E 容器、输出活动车道 Status、持久化车道耗时以便按最长优先排序，并支持 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 用于调度器检查。默认情况下，它会在首次失败后停止调度新的池化车道，并且每个车道都有 120 分钟的后备超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；选定的 live/tail 车道使用更严格的单车道上限。`OPENCLAW_DOCKER_ALL_LANES=` 会运行精确的调度器车道，包括仅发布车道，例如 `install-e2e`，以及拆分的内置更新车道，例如 `bundled-channel-update-acpx`，同时跳过清理冒烟，以便 agent 能够复现某个失败车道。可复用的 live/E2E workflow 会询问 `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 stream 会快速重试，而不是消耗 CI 关键路径的大部分时间。`Package Acceptance` workflow 是高级包门禁：它会从 npm、受信任的 `package_ref`、HTTPS tarball 加 SHA-256，或先前的 workflow 制品中解析候选包，然后将这个单一的 `package-under-test` 制品传入可复用 Docker E2E workflow。它将 `workflow_ref` 与 `package_ref` 分开，使当前验收逻辑能够验证较旧的受信任 commit，而无需检出旧 workflow 代码。发布检查会为目标 ref 运行自定义 Package Acceptance delta：内置渠道兼容性、离线插件 fixture，以及针对解析后 tarball 的 Telegram 包 QA。发布路径 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|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|bundled-channels`）。当完整发布路径覆盖请求 OpenWebUI 时，OpenWebUI 会并入 `plugins-runtime-services`，并且仅在 OpenWebUI-only 调度时保留独立的 `openwebui` 分块。旧版聚合分块名称 `package-update`、`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍可用于手动重跑，但发布 workflow 使用拆分分块，这样安装器 E2E 和内置插件安装/卸载扫测不会主导关键路径。`install-e2e` 车道别名仍是两个提供商安装器车道的聚合手动重跑别名。`bundled-channels` 分块会运行拆分的 `bundled-channel-*` 和 `bundled-channel-update-*` 车道，而不是串行 all-in-one 的 `bundled-channel-deps` 车道。每个分块都会上传 `.artifacts/docker-tests/`，其中包含车道日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON、慢车道表和单车道重跑命令。workflow 的 `docker_lanes` 输入会针对准备好的镜像运行选定车道，而不是运行分块作业，这会将失败车道调试限制在一个有针对性的 Docker 作业中，并为该运行准备、下载或复用包制品；如果选定车道是 live Docker 车道，则目标作业会为该次重跑在本地构建 live-test 镜像。生成的单车道 GitHub 重跑命令会在这些值存在时包含 `package_artifact_run_id`、`package_artifact_name` 和准备好的镜像输入，因此失败车道可以复用失败运行中的精确包和镜像。使用 `pnpm test:docker:rerun ` 从 GitHub 运行下载 Docker 制品并打印组合/单车道目标重跑命令；使用 `pnpm test:docker:timings ` 查看慢车道和阶段关键路径摘要。定时 live/E2E workflow 每天运行完整的发布路径 Docker 套件。内置更新矩阵按更新目标拆分，因此重复的 npm update 和 Doctor 修复 pass 可以与其他内置检查一起分片。 -当前发布 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`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-b` 和 `bundled-channels-contracts`。聚合 `bundled-channels` 分块仍可用于手动一次性重新运行，`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍是聚合插件/运行时别名，但发布工作流使用拆分后的分块，让渠道冒烟测试、更新目标、插件运行时检查以及内置插件安装/卸载扫描可以并行运行。定向 `docker_lanes` 调度也会在一次共享包/镜像准备步骤之后，将多个选中的 lane 拆分为并行作业，并且内置渠道更新 lane 会针对临时 npm 网络失败重试一次。 +当前发布版 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`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-discord`、`bundled-channels-update-b` 和 `bundled-channels-contracts`。聚合的 `bundled-channels` 分块仍可用于手动一次性重跑，`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 也仍作为聚合的插件/运行时别名保留，但发布工作流会使用拆分后的分块，这样渠道冒烟测试、更新目标、插件运行时检查以及内置插件安装/卸载扫描就可以并行运行。定向的 `docker_lanes` 调度也会在一次共享的包/镜像准备步骤之后，将多个选中的 lane 拆分为并行作业，并且内置渠道更新 lane 会针对临时 npm 网络故障重试一次。 -本地变更 lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。该本地检查门禁在架构边界上比宽泛的 CI 平台范围更严格：核心生产变更会运行核心生产和核心测试类型检查，以及核心 lint/guard；仅核心测试变更只运行核心测试类型检查和核心 lint；插件生产变更会运行插件生产和插件测试类型检查，以及插件 lint；仅插件测试变更会运行插件测试类型检查和插件 lint。公共插件 SDK 或插件契约变更会扩展到插件类型检查，因为插件依赖这些核心契约，但 Vitest 插件扫描是显式测试工作。仅发布元数据的版本号更新会运行定向版本/配置/根依赖检查。未知的根目录/配置变更会安全回退到所有检查 lane。 -本地变更测试路由位于 `scripts/test-projects.test-support.mjs`，并且 -有意比 `check:changed` 更轻量：直接测试编辑会运行自身， -源代码编辑优先使用显式映射，然后是同级测试和导入图 -依赖项。共享群组房间投递配置是显式映射之一： -对群组可见回复配置、源回复投递模式或 -消息工具系统提示词的变更，会路由到核心回复测试以及 Discord 和 -Slack 投递回归测试，这样共享默认值变更会在第一个 PR -推送之前失败。只有当变更影响整个 harness，导致廉价映射集合不能作为可信代理时，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。 +本地变更 lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。该本地检查门禁对架构边界的要求比宽泛的 CI 平台范围更严格：core 生产变更会运行 core 生产和 core 测试类型检查，以及 core lint/guard；仅 core 测试的变更只运行 core 测试类型检查和 core lint；扩展生产变更会运行扩展生产和扩展测试类型检查，以及扩展 lint；仅扩展测试的变更会运行扩展测试类型检查和扩展 lint。公共插件 SDK 或插件合约变更会扩展到扩展类型检查，因为扩展依赖这些 core 合约，但 Vitest 扩展扫描属于显式测试工作。仅发布元数据的版本号变更会运行定向的版本/配置/根依赖检查。未知的 root/config 变更会故障安全地落到所有检查 lane。 +本地变更测试路由位于 `scripts/test-projects.test-support.mjs`，并且有意比 `check:changed` 更轻量：直接测试编辑会运行自身，源码编辑优先使用显式映射，然后再使用同级测试和 import graph 依赖项。共享群组房间投递配置是显式映射之一：对群组可见回复配置、源回复投递模式或消息工具系统提示词的变更，会通过 core 回复测试以及 Discord 和 Slack 投递回归测试路由，这样共享默认值变更会在第一次 PR push 之前失败。只有当变更覆盖整个 harness，以至于廉价映射集不能作为可信代理时，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。 -对于 Testbox 验证，请从仓库根目录运行，并优先使用新预热的 box 来做 -宽泛证明。在把慢速门禁花在复用、过期或刚报告异常大同步量的 box 上之前， -先在该 -box 内运行 `pnpm testbox:sanity`。当必要的根文件（如 -`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 使用更大的 -毫秒值。 +对于 Testbox 验证，请从仓库根目录运行，并优先为宽泛证明使用新预热的 box。在把缓慢门禁花在一个被复用、已过期或刚报告异常大同步的 box 之前，先在 box 内运行 `pnpm testbox:sanity`。当必需的根文件（例如 `pnpm-lock.yaml`）消失，或 `git status --short` 显示至少 200 个已跟踪删除时，完整性检查会快速失败。这通常意味着远程同步状态不是 PR 的可信副本。停止该 box，并预热一个新的 box，而不是调试产品测试失败。对于有意进行大量删除的 PR，请为该完整性检查运行设置 `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。如果本地 Blacksmith CLI 调用停留在同步阶段超过五分钟且没有同步后输出，`pnpm testbox:run` 也会终止它。设置 `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` 可禁用该 guard，或者为异常大的本地 diff 使用更大的毫秒值。 -手动 CI 调度会运行 `checks-node-compat-node22` 作为宽泛兼容性覆盖。Android 对独立手动 CI 通过 `include_android=true` 选择加入，并且始终为 `Full Release Validation` 启用。`Plugin Prerelease` 是成本更高的产品/包覆盖，因此它是一个独立工作流，由 `Full Release Validation` 调度或由显式操作员调度。普通拉取请求、`main` 推送和独立手动 CI 调度都会关闭该套件。 +手动 CI 调度会运行 `checks-node-compat-node22` 作为宽泛兼容性覆盖。Android 对独立手动 CI 需要通过 `include_android=true` 选择启用，并且对 `Full Release Validation` 始终启用。`Plugin Prerelease` 是更昂贵的产品/包覆盖，因此它是一个由 `Full Release Validation` 或显式操作员调度的独立工作流。普通 pull request、`main` push 和独立手动 CI 调度会关闭该套件。 -最慢的 Node 测试族会被拆分或均衡，让每个作业保持较小且不过度预留 runner：渠道契约作为三个加权分片运行，小型核心单元 lane 会成对运行，自动回复作为四个均衡 worker 运行，并将回复子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片，agentic Gateway 网关/插件配置会分布到现有的仅源代码 agentic Node 作业中，而不是等待构建产物。宽泛浏览器、QA、媒体和杂项插件测试使用它们专用的 Vitest 配置，而不是共享的插件兜底配置。`Plugin Prerelease` 会在八个插件 worker 之间均衡内置插件测试；这些插件分片作业一次最多运行两个插件配置组，每组一个 Vitest worker，并使用更大的 Node 堆，以便导入密集的插件批次不会创建额外的 CI 作业。宽泛智能体 lane 使用共享 Vitest 文件并行调度器，因为它主要受导入/调度限制，而不是由单个慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享运行时分片占据尾部时间。包含模式分片会使用 CI 分片名称记录 timing 条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分整个配置和过滤后的分片。`check-additional` 将包边界编译/canary 工作放在一起，并将运行时拓扑架构与 Gateway 网关 watch 覆盖分开；边界 guard 分片会在一个作业内并发运行其小型独立 guard。Gateway 网关 watch、渠道测试和核心支持边界分片会在 `dist/` 和 `dist-runtime/` 已构建后，在 `build-artifacts` 内并发运行，保留它们旧的检查名称作为轻量验证器作业，同时避免两个额外的 Blacksmith worker 和第二个产物消费者队列。 -Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的 source set 或 manifest；它的单元测试 lane 仍会使用 SMS/通话记录 BuildConfig 标志编译该 flavor，同时避免在每次 Android 相关推送时重复打包 debug APK。 -当较新的推送落在同一个 PR 或 `main` ref 上时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一个 ref 的最新运行也失败，否则将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已被取代后继续排队。 -自动 CI 并发键带有版本号（`CI-v7-*`），因此 GitHub 侧旧队列组中的僵尸项无法无限期阻塞新的 main 运行。手动全套件运行使用 `CI-manual-v1-*`，且不会取消正在进行的运行。 +最慢的 Node 测试族会被拆分或均衡，使每个作业保持较小且不会过度预留 runner：渠道合约作为三个加权 shard 运行，小型 core 单元 lane 成对运行，auto-reply 作为四个均衡 worker 运行，并将 reply 子树拆分为 agent-runner、dispatch 和 commands/state-routing shard，而智能体式 Gateway 网关/插件配置会分散到现有仅源码的智能体式 Node 作业中，而不是等待构建产物。宽泛的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件兜底配置。`Plugin Prerelease` 会在八个扩展 worker 间均衡内置插件测试；这些扩展 shard 作业每次最多运行两个插件配置组，每组使用一个 Vitest worker 和更大的 Node heap，这样 import 密集的插件批次不会创建额外 CI 作业。宽泛的智能体 lane 使用共享的 Vitest 文件并行调度器，因为它主要受 import/调度支配，而不是由单个慢测试文件主导。`runtime-config` 与 infra core-runtime shard 一起运行，避免共享 runtime shard 拖住尾部。Include-pattern shard 使用 CI shard 名称记录计时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分完整配置和过滤后的 shard。`check-additional` 将包边界编译/canary 工作放在一起，并将运行时拓扑架构与 Gateway 网关 watch 覆盖分开；边界 guard shard 会在一个作业内并发运行其小型独立 guard。Gateway 网关 watch、渠道测试和 core support-boundary shard 会在 `dist/` 和 `dist-runtime/` 已经构建完成后，在 `build-artifacts` 内并发运行，保留它们旧有的检查名称作为轻量验证作业，同时避免两个额外的 Blacksmith worker 和第二个 artifact-consumer 队列。 +Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的 source set 或 manifest；它的单元测试 lane 仍会使用 SMS/通话记录 BuildConfig 标志编译该 flavor，同时避免在每次 Android 相关 push 上重复执行 debug APK 打包作业。 +当同一 PR 或 `main` ref 上有更新 push 落地时，GitHub 可能会将已被取代的作业标记为 `cancelled`。除非同一 ref 的最新运行也失败，否则将其视为 CI 噪声。聚合 shard 检查使用 `!cancelled() && always()`，因此它们仍会报告正常的 shard 失败，但不会在整个工作流已经被取代后继续排队。 +自动 CI 并发键带有版本号（`CI-v7-*`），这样 GitHub 端旧队列组里的僵尸项就无法无限期阻塞更新的 main 运行。手动全套件运行使用 `CI-manual-v1-*`，并且不会取消正在进行的运行。 -## Runner +## Runners -| Runner | 作业 | +| 运行器 | 作业 | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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 排队时间带来的成本也高于节省 | +| `ubuntu-24.04` | `preflight`，快速安全作业和聚合（`security-scm-fast`、`security-dependency-audit`、`security-fast`），快速协议/合约/内置检查，分片渠道合约检查，除 lint 外的 `check` shard，`check-additional` shard 和聚合，Node 测试聚合验证器，文档检查，Python Skills，workflow-sanity，labeler，auto-response；install-smoke preflight 也使用 GitHub 托管的 Ubuntu，以便 Blacksmith 矩阵可以更早排队 | +| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`，较低权重的扩展 shard，`checks-fast-core`，`checks-node-compat-node22`，`check-prod-types` 和 `check-test-types` | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node 测试 shard、内置插件测试 shard、`android` | +| `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 @@ -341,7 +231,7 @@ pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-per pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json ``` -## 相关 +## 相关内容 - [安装概览](/zh-CN/install) - [发布渠道](/zh-CN/install/development-channels) diff --git a/docs/zh-CN/gateway/config-agents.md b/docs/zh-CN/gateway/config-agents.md index d26dd3092..8d41296a9 100644 --- a/docs/zh-CN/gateway/config-agents.md +++ b/docs/zh-CN/gateway/config-agents.md @@ -1,20 +1,22 @@ --- read_when: - - 调整智能体默认设置（模型、思考、工作区、心跳、媒体、Skills） + - 调整智能体默认值（模型、思考、工作区、心跳、媒体、Skills） - 配置多智能体路由和绑定 - - 调整会话、消息递送和对话模式行为 + - 调整会话、消息传递和对话模式行为 summary: 智能体默认值、多智能体路由、会话、消息和 talk 配置 title: 配置 — 智能体 x-i18n: - generated_at: "2026-04-29T09:12:55Z" + generated_at: "2026-04-29T10:40:09Z" model: gpt-5.5 provider: openai - source_hash: 0b093332d62836f3564f248e67e68b058777d84f78e8f1e99ab258f44839c400 + source_hash: 76d15861fc92ede737d7d37aeb340eeca42e834b9b2d94f81592825247fd453c source_path: gateway/config-agents.md workflow: 16 --- -智能体作用域的配置键位于 `agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下。对于渠道、工具、Gateway 网关运行时以及其他顶层键，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。 +`agents.*`、`multiAgent.*`、`session.*`、 +`messages.*` 和 `talk.*` 下的智能体作用域配置键。对于渠道、工具、Gateway 网关运行时和其他 +顶层键，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。 ## 智能体默认值 @@ -30,7 +32,7 @@ x-i18n: ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示的运行时行中。如果未设置，OpenClaw 会从工作区开始向上遍历来自动检测。 +系统提示词运行时行中显示的可选仓库根目录。如果未设置，OpenClaw 会从工作区向上遍历来自动检测。 ```json5 { @@ -40,7 +42,8 @@ x-i18n: ### `agents.defaults.skills` -对于未设置 `agents.list[].skills` 的智能体，可选的默认 Skills 允许列表。 +可选的默认 Skills 允许列表，适用于未设置 +`agents.list[].skills` 的智能体。 ```json5 { @@ -57,12 +60,13 @@ x-i18n: - 省略 `agents.defaults.skills`，默认不限制 Skills。 - 省略 `agents.list[].skills` 以继承默认值。 -- 设置 `agents.list[].skills: []` 表示没有 Skills。 -- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。 +- 将 `agents.list[].skills: []` 设置为无 Skills。 +- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它 + 不会与默认值合并。 ### `agents.defaults.skipBootstrap` -禁用自动创建工作区启动文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 +禁用自动创建工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 ```json5 { @@ -72,10 +76,10 @@ x-i18n: ### `agents.defaults.contextInjection` -控制工作区启动文件何时注入到系统提示中。默认值：`"always"`。 +控制何时将工作区引导文件注入系统提示词。默认值：`"always"`。 -- `"continuation-skip"`：安全的延续轮次（在已完成的助手响应之后）会跳过工作区启动重新注入，从而减小提示大小。Heartbeat 运行和压缩后的重试仍会重建上下文。 -- `"never"`：在每一轮禁用工作区启动和上下文文件注入。仅对完全拥有自身提示生命周期的智能体使用此项（自定义上下文引擎、构建自身上下文的原生运行时，或专门的无启动工作流）。Heartbeat 和压缩恢复轮次也会跳过注入。 +- `"continuation-skip"`：安全的续接轮次（在已完成的 assistant 响应之后）会跳过工作区引导的重新注入，从而减少提示词大小。心跳运行和压缩后的重试仍会重建上下文。 +- `"never"`：在每一轮禁用工作区引导和上下文文件注入。仅将其用于完全自行管理提示词生命周期的智能体（自定义上下文引擎、构建自身上下文的原生运行时，或专用的无引导工作流）。心跳和压缩恢复轮次也会跳过注入。 ```json5 { @@ -85,7 +89,7 @@ x-i18n: ### `agents.defaults.bootstrapMaxChars` -每个工作区启动文件在截断前的最大字符数。默认值：`12000`。 +截断前每个工作区引导文件的最大字符数。默认值：`12000`。 ```json5 { @@ -95,7 +99,7 @@ x-i18n: ### `agents.defaults.bootstrapTotalMaxChars` -跨所有工作区启动文件注入的最大总字符数。默认值：`60000`。 +跨所有工作区引导文件注入的总最大字符数。默认值：`60000`。 ```json5 { @@ -105,11 +109,12 @@ x-i18n: ### `agents.defaults.bootstrapPromptTruncationWarning` -控制启动上下文被截断时智能体可见的警告文本。默认值：`"once"`。 +控制引导上下文被截断时智能体可见的警告文本。 +默认值：`"once"`。 -- `"off"`：绝不向系统提示注入警告文本。 -- `"once"`：每个唯一截断签名只注入一次警告（推荐）。 -- `"always"`：存在截断时，每次运行都注入警告。 +- `"off"`：从不向系统提示词注入警告文本。 +- `"once"`：对每个唯一的截断签名注入一次警告（推荐）。 +- `"always"`：存在截断时在每次运行都注入警告。 ```json5 { @@ -119,22 +124,34 @@ x-i18n: ### 上下文预算归属图 -OpenClaw 有多个高容量提示/上下文预算，它们按子系统有意拆分，而不是全部流经一个通用开关。 +OpenClaw 有多个高容量提示词/上下文预算，并且它们 +有意按子系统拆分，而不是全部流经一个通用 +旋钮。 -- `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`：普通工作区启动注入。 -- `agents.defaults.startupContext.*`：一次性重置/启动模型运行前奏，包括最近的每日 `memory/*.md` 文件。裸聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下确认重置。 -- `skills.limits.*`：注入到系统提示中的紧凑 Skills 列表。 -- `agents.defaults.contextLimits.*`：有界运行时摘录和注入的运行时拥有块。 -- `memory.qmd.limits.*`：索引化内存搜索片段和注入大小。 +- `agents.defaults.bootstrapMaxChars` / + `agents.defaults.bootstrapTotalMaxChars`： + 常规工作区引导注入。 +- `agents.defaults.startupContext.*`： + 一次性的重置/启动模型运行前奏，包括最近的每日 + `memory/*.md` 文件。裸聊天 `/new` 和 `/reset` 命令会 + 确认重置，而不调用模型。 +- `skills.limits.*`： + 注入系统提示词的紧凑 Skills 列表。 +- `agents.defaults.contextLimits.*`： + 有界运行时摘录和注入的运行时拥有块。 +- `memory.qmd.limits.*`： + 索引化内存搜索片段和注入大小。 -仅当某个智能体需要不同预算时，使用匹配的每智能体覆盖： +仅当某个智能体需要不同预算时，才使用匹配的按智能体覆盖项： - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -控制在重置/启动模型运行时注入的首轮启动前奏。裸聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下确认重置，因此不会加载此前奏。 +控制在重置/启动模型运行时注入的首轮启动前奏。 +裸聊天 `/new` 和 `/reset` 命令会确认重置而不调用 +模型，因此它们不会加载此前奏。 ```json5 { @@ -155,7 +172,7 @@ OpenClaw 有多个高容量提示/上下文预算，它们按子系统有意拆 #### `agents.defaults.contextLimits` -有界运行时上下文界面的共享默认值。 +有界运行时上下文表面的共享默认值。 ```json5 { @@ -172,14 +189,15 @@ OpenClaw 有多个高容量提示/上下文预算，它们按子系统有意拆 } ``` -- `memoryGetMaxChars`：添加截断元数据和继续提示之前，默认的 `memory_get` 摘录上限。 -- `memoryGetDefaultLines`：省略 `lines` 时，默认的 `memory_get` 行窗口。 +- `memoryGetMaxChars`：添加截断元数据和续接通知前的默认 `memory_get` 摘录上限。 +- `memoryGetDefaultLines`：省略 `lines` 时的默认 `memory_get` 行窗口。 - `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。 - `postCompactionMaxChars`：压缩后刷新注入期间使用的 AGENTS.md 摘录上限。 #### `agents.list[].contextLimits` -共享 `contextLimits` 开关的每智能体覆盖。省略的字段会从 `agents.defaults.contextLimits` 继承。 +共享 `contextLimits` 旋钮的按智能体覆盖项。省略的字段会从 +`agents.defaults.contextLimits` 继承。 ```json5 { @@ -205,7 +223,8 @@ OpenClaw 有多个高容量提示/上下文预算，它们按子系统有意拆 #### `skills.limits.maxSkillsPromptChars` -注入到系统提示中的紧凑 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。 +注入系统提示词的紧凑 Skills 列表的全局上限。这 +不会影响按需读取 `SKILL.md` 文件。 ```json5 { @@ -219,7 +238,7 @@ OpenClaw 有多个高容量提示/上下文预算，它们按子系统有意拆 #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Skills 提示预算的每智能体覆盖。 +Skills 提示词预算的按智能体覆盖项。 ```json5 { @@ -238,9 +257,11 @@ Skills 提示预算的每智能体覆盖。 ### `agents.defaults.imageMaxDimensionPx` -在提供商调用之前，转录/工具图像块中图像最长边的最大像素大小。默认值：`1200`。 +在调用提供商之前，转录/工具图像块中图像最长边的最大像素大小。 +默认值：`1200`。 -较低的值通常会减少大量截图运行中的视觉令牌用量和请求载荷大小。较高的值会保留更多视觉细节。 +较低的值通常会减少大量截图运行中的视觉令牌使用量和请求负载大小。 +较高的值会保留更多视觉细节。 ```json5 { @@ -250,7 +271,7 @@ Skills 提示预算的每智能体覆盖。 ### `agents.defaults.userTimezone` -系统提示上下文使用的时区（不是消息时间戳）。回退到主机时区。 +系统提示词上下文使用的时区（不是消息时间戳）。回退到主机时区。 ```json5 { @@ -260,7 +281,7 @@ Skills 提示预算的每智能体覆盖。 ### `agents.defaults.timeFormat` -系统提示中的时间格式。默认值：`auto`（操作系统偏好设置）。 +系统提示词中的时间格式。默认值：`auto`（操作系统偏好）。 ```json5 { @@ -319,55 +340,56 @@ Skills 提示预算的每智能体覆盖。 - `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 字符串形式只设置主模型。 - - 对象形式设置主模型以及有序故障转移模型。 + - 对象形式设置主模型加有序故障转移模型。 - `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 被 `image` 工具路径用作其视觉模型配置。 + - 由 `image` 工具路径用作其视觉模型配置。 - 当所选/默认模型无法接受图像输入时，也用作回退路由。 - - 优先使用显式的 `provider/model` 引用。为兼容性也接受裸 ID；如果裸 ID 与 `models.providers.*.models` 中已配置且支持图像的条目唯一匹配，OpenClaw 会将其限定到该提供商。已配置匹配存在歧义时，需要显式提供商前缀。 + - 优先使用显式 `provider/model` 引用。为兼容性接受裸 ID；如果裸 ID 唯一匹配 `models.providers.*.models` 中已配置的具备图像能力的条目，OpenClaw 会将其限定到该提供商。配置中存在歧义匹配时，需要显式提供商前缀。 - `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 被共享图像生成能力以及任何未来生成图像的工具/插件界面使用。 - - 典型值：用于原生 Gemini 图像生成的 `google/gemini-3.1-flash-image-preview`、用于 fal 的 `fal/fal-ai/flux/dev`、用于 OpenAI Images 的 `openai/gpt-image-2`，或用于透明背景 OpenAI PNG/WebP 输出的 `openai/gpt-image-1.5`。 - - 如果你直接选择提供商/模型，也要配置匹配的提供商凭证（例如用于 `google/*` 的 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，用于 `openai/gpt-image-2` / `openai/gpt-image-1.5` 的 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，用于 `fal/*` 的 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推断由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。 + - 由共享图像生成能力以及未来任何生成图像的工具/插件表面使用。 + - 典型值：用于 Gemini 原生图像生成的 `google/gemini-3.1-flash-image-preview`，用于 fal 的 `fal/fal-ai/flux/dev`，用于 OpenAI Images 的 `openai/gpt-image-2`，或用于透明背景 OpenAI PNG/WebP 输出的 `openai/gpt-image-1.5`。 + - 如果你直接选择提供商/模型，也要配置匹配的提供商凭证（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` / `openai/gpt-image-1.5` 使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 使用 `FAL_KEY`）。 + - 如果省略，`image_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。 - `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 被共享音乐生成能力和内置 `music_generate` 工具使用。 + - 由共享音乐生成能力和内置 `music_generate` 工具使用。 - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.6`。 - - 如果省略，`music_generate` 仍可推断由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。 + - 如果省略，`music_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。 - 如果你直接选择提供商/模型，也要配置匹配的提供商凭证/API 密钥。 - `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 被共享视频生成能力和内置 `video_generate` 工具使用。 + - 由共享视频生成能力和内置 `video_generate` 工具使用。 - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 - - 如果省略，`video_generate` 仍可推断由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。 + - 如果省略，`video_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。 - 如果你直接选择提供商/模型，也要配置匹配的提供商凭证/API 密钥。 - - 内置 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 + - 内置 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 - `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 被 `pdf` 工具用于模型路由。 - - 如果省略，PDF 工具会回退到 `imageModel`，然后回退到解析出的会话/默认模型。 -- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。 -- `pdfMaxPages`：`pdf` 工具中提取回退模式默认考虑的最大页数。 + - 由 `pdf` 工具用于模型路由。 + - 如果省略，PDF 工具会回退到 `imageModel`，再回退到解析出的会话/默认模型。 +- `pdfMaxBytesMb`：调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。 +- `pdfMaxPages`：`pdf` 工具中提取回退模式考虑的默认最大页数。 - `verboseDefault`：智能体的默认详细级别。值：`"off"`、`"on"`、`"full"`。默认：`"off"`。 - `elevatedDefault`：智能体的默认提升输出级别。值：`"off"`、`"on"`、`"ask"`、`"full"`。默认：`"on"`。 -- `model.primary`：格式为 `provider/model`（例如用于 API 密钥访问的 `openai/gpt-5.5`，或用于 Codex OAuth 的 `openai-codex/gpt-5.5`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该确切模型 ID 唯一匹配的已配置提供商，只有之后才会回退到已配置的默认提供商（已弃用的兼容性行为，因此优先使用显式 `provider/model`）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露过时的已移除提供商默认值。 -- `models`：为 `/model` 配置的模型目录和允许列表。每个条目可以包含 `alias`（快捷方式）和 `params`（提供商特定，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`chat_template_kwargs`、`extra_body`/`extraBody`）。 - - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非你传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换。 - - 按提供商限定范围的配置/新手引导流程会将所选提供商模型合并到此映射中，并保留已配置的无关提供商。 - - 对于直接 OpenAI Responses 模型，会自动启用服务器端压缩。使用 `params.responsesServerCompaction: false` 停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务器端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。 -- `params`：应用到所有模型的全局默认提供商参数。在 `agents.defaults.params` 设置（例如 `{ cacheRetention: "long" }`）。 -- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配的智能体 ID）按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 -- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并到 OpenAI 兼容代理的 `api: "openai-completions"` 请求正文中。如果它与生成的请求键冲突，额外正文优先；非原生 completions 路由之后仍会剥离仅 OpenAI 支持的 `store`。 -- `params.chat_template_kwargs`：vLLM/OpenAI 兼容聊天模板参数，会合并到顶层 `api: "openai-completions"` 请求正文中。对于关闭 thinking 的 `vllm/nemotron-3-*`，内置 vLLM 插件会自动发送 `enable_thinking: false` 和 `force_nonempty_content: true`；显式 `chat_template_kwargs` 会覆盖生成的默认值，而 `extra_body.chat_template_kwargs` 仍拥有最终优先级。对于 vLLM Qwen thinking 控制，请在该模型条目上将 `params.qwenThinkingFormat` 设置为 `"chat-template"` 或 `"top-level"`。 -- `params.preserveThinking`：仅 Z.AI 可选择启用的保留 thinking。启用且 thinking 开启时，OpenClaw 会发送 `thinking.clear_thinking: false` 并重放之前的 `reasoning_content`；参见 [Z.AI thinking 和保留 thinking](/zh-CN/providers/zai#thinking-and-preserved-thinking)。 -- `agentRuntime`：默认低级智能体运行时策略。省略 ID 时默认使用 OpenClaw Pi。使用 `id: "pi"` 强制使用内置 PI 执行框架，使用 `id: "auto"` 让已注册的插件执行框架声明支持的模型，使用已注册的执行框架 ID（如 `id: "codex"`），或使用受支持的 CLI 后端别名（如 `id: "claude-cli"`）。设置 `fallback: "none"` 可禁用自动 PI 回退。显式插件运行时（如 `codex`）默认会失败关闭，除非你在同一覆盖范围内设置 `fallback: "pi"`。保持模型引用规范为 `provider/model`；通过运行时配置选择 Codex、Claude CLI、Gemini CLI 和其他执行后端，而不是使用旧版运行时提供商前缀。参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，了解它与提供商/模型选择的区别。 -- 会变更这些字段的配置写入器（例如 `/models set`、`/models set-image` 和回退添加/移除命令）会保存规范对象形式，并尽可能保留现有回退列表。 -- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍然串行）。默认：4。 +- `model.primary`：格式为 `provider/model`（例如使用 API 密钥访问时为 `openai/gpt-5.5`，使用 Codex OAuth 时为 `openai-codex/gpt-5.5`）。如果省略提供商，OpenClaw 会先尝试别名，然后尝试与该确切模型 ID 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（已弃用的兼容行为，因此优先使用显式 `provider/model`）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露过时的已移除提供商默认值。 +- `models`：为 `/model` 配置的模型目录和允许列表。每个条目可包含 `alias`（快捷方式）和 `params`（提供商特定，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`chat_template_kwargs`、`extra_body`/`extraBody`）。 + - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换。 + - 提供商作用域的配置/新手引导流程会将所选提供商模型合并进此映射，并保留已配置的无关提供商。 + - 对于直接 OpenAI Responses 模型，服务端压缩会自动启用。使用 `params.responsesServerCompaction: false` 停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。 +- `params`：应用到所有模型的全局默认提供商参数。设置在 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 +- `params` 合并优先级（配置）：`agents.defaults.params`（全局基准）会被 `agents.defaults.models["provider/model"].params`（每模型）覆盖，然后 `agents.list[].params`（匹配的智能体 ID）会按键覆盖。详见[提示缓存](/zh-CN/reference/prompt-caching)。 +- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并进 OpenAI 兼容代理的 `api: "openai-completions"` 请求体。如果它与生成的请求键冲突，额外请求体优先；非原生 completions 路由之后仍会剥离仅 OpenAI 使用的 `store`。 +- `params.chat_template_kwargs`：vLLM/OpenAI 兼容聊天模板参数，会合并进顶层 `api: "openai-completions"` 请求体。对于关闭 thinking 的 `vllm/nemotron-3-*`，内置 vLLM 插件会自动发送 `enable_thinking: false` 和 `force_nonempty_content: true`；显式 `chat_template_kwargs` 会覆盖生成的默认值，而 `extra_body.chat_template_kwargs` 仍拥有最终优先级。对于 vLLM Qwen thinking 控制，在该模型条目上将 `params.qwenThinkingFormat` 设为 `"chat-template"` 或 `"top-level"`。 +- `compat.supportedReasoningEfforts`：每模型的 OpenAI 兼容推理力度列表。对于真正接受它的自定义端点，包含 `"xhigh"`；随后 OpenClaw 会在命令菜单、Gateway 网关会话行、会话补丁验证、智能体 CLI 验证和 `llm-task` 验证中，为该已配置的提供商/模型公开 `/think xhigh`。当后端需要规范级别对应的提供商特定值时，使用 `compat.reasoningEffortMap`。 +- `params.preserveThinking`：仅 Z.AI 使用的保留 thinking 可选开关。启用且 thinking 开启时，OpenClaw 会发送 `thinking.clear_thinking: false` 并重放之前的 `reasoning_content`；参见 [Z.AI thinking 与保留 thinking](/zh-CN/providers/zai#thinking-and-preserved-thinking)。 +- `agentRuntime`：默认低级智能体运行时策略。省略 id 时默认使用 OpenClaw Pi。使用 `id: "pi"` 强制使用内置 PI harness，使用 `id: "auto"` 让已注册的插件 harness 认领支持的模型，使用已注册的 harness id（例如 `id: "codex"`），或使用支持的 CLI 后端别名（例如 `id: "claude-cli"`）。设置 `fallback: "none"` 可禁用自动 PI 回退。显式插件运行时（例如 `codex`）默认关闭式失败，除非你在同一覆盖作用域中设置 `fallback: "pi"`。保持模型引用规范为 `provider/model`；通过运行时配置选择 Codex、Claude CLI、Gemini CLI 以及其他执行后端，而不是使用旧版运行时提供商前缀。关于这与提供商/模型选择的区别，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 +- 会变更这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退添加/移除命令）会保存规范对象形式，并尽可能保留现有回退列表。 +- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍会串行化）。默认：4。 ### `agents.defaults.agentRuntime` `agentRuntime` 控制哪个低级执行器运行智能体轮次。大多数 -部署应保持默认 OpenClaw Pi 运行时。当可信 -插件提供原生执行框架（例如内置 Codex app-server 执行框架）， -或你想使用受支持的 CLI 后端（例如 Claude CLI）时，请使用它。关于心智 -模型，请参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 +部署应保持默认的 OpenClaw Pi 运行时。当受信任的 +插件提供原生 harness（例如内置 Codex 应用服务器 harness）时， +或当你需要受支持的 CLI 后端（例如 Claude CLI）时使用它。关于心智 +模型，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 ```json5 { @@ -383,13 +405,13 @@ Skills 提示预算的每智能体覆盖。 } ``` -- `id`：`"auto"`、`"pi"`、已注册的插件执行框架 ID，或受支持的 CLI 后端别名。内置 Codex 插件会注册 `codex`；内置 Anthropic 插件提供 `claude-cli` CLI 后端。 -- `fallback`：`"pi"` 或 `"none"`。在 `id: "auto"` 中，省略的回退默认是 `"pi"`，因此当没有插件执行框架声明某次运行时，旧配置仍可继续使用 PI。在显式插件运行时模式中，例如 `id: "codex"`，省略的回退默认是 `"none"`，因此缺少执行框架时会失败，而不是静默使用 PI。运行时覆盖不会从更广范围继承回退；当你有意需要该兼容性回退时，请与显式运行时一起设置 `fallback: "pi"`。所选插件执行框架失败总是会直接暴露。 -- 环境覆盖：`OPENCLAW_AGENT_RUNTIME=` 覆盖 `id`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 覆盖该进程的回退。 -- 对于仅 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `agentRuntime.id: "codex"`。你也可以显式设置 `agentRuntime.fallback: "none"` 以提高可读性；它是显式插件运行时的默认值。 -- 对于 Claude CLI 部署，优先使用 `model: "anthropic/claude-opus-4-7"` 加 `agentRuntime.id: "claude-cli"`。旧版 `claude-cli/claude-opus-4-7` 模型引用仍可用于兼容性，但新配置应保持提供商/模型选择规范，并将执行后端放入 `agentRuntime.id`。 -- 较旧的运行时策略键会由 `openclaw doctor --fix` 重写为 `agentRuntime`。 -- 第一次嵌入式运行后，执行框架选择会按会话 ID 固定。配置/环境变更会影响新的或重置的会话，而不会影响现有转录。具有转录历史但没有记录固定值的旧会话会被视为固定到 PI。`/status` 会报告有效运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。 +- `id`：`"auto"`、`"pi"`、已注册的插件 harness id，或受支持的 CLI 后端别名。内置 Codex 插件注册 `codex`；内置 Anthropic 插件提供 `claude-cli` CLI 后端。 +- `fallback`：`"pi"` 或 `"none"`。在 `id: "auto"` 中，省略的 fallback 默认值为 `"pi"`，因此旧配置在没有插件 harness 认领运行时仍可继续使用 PI。在显式插件运行时模式中，例如 `id: "codex"`，省略的 fallback 默认值为 `"none"`，因此缺失 harness 会失败，而不是静默使用 PI。运行时覆盖不会从更宽作用域继承 fallback；当你有意需要该兼容回退时，请在显式运行时旁设置 `fallback: "pi"`。所选插件 harness 的失败始终会直接暴露。 +- 环境覆盖：`OPENCLAW_AGENT_RUNTIME=` 覆盖 `id`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 覆盖该进程的 fallback。 +- 对于仅 Codex 部署，设置 `model: "openai/gpt-5.5"` 和 `agentRuntime.id: "codex"`。你也可以显式设置 `agentRuntime.fallback: "none"` 以增强可读性；这是显式插件运行时的默认值。 +- 对于 Claude CLI 部署，优先使用 `model: "anthropic/claude-opus-4-7"` 加 `agentRuntime.id: "claude-cli"`。旧版 `claude-cli/claude-opus-4-7` 模型引用仍可兼容使用，但新配置应保持提供商/模型选择的规范形式，并将执行后端放在 `agentRuntime.id` 中。 +- 旧版运行时策略键会由 `openclaw doctor --fix` 重写为 `agentRuntime`。 +- 首次嵌入式运行后，harness 选择会按会话 ID 固定。配置/环境变更会影响新的或重置后的会话，而不会影响现有转录。具有转录历史但没有记录固定项的旧版会话会被视为已固定到 PI。`/status` 会报告有效运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。 - 这只控制文本智能体轮次执行。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。 **内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： @@ -398,7 +420,7 @@ Skills 提示预算的每智能体覆盖。 | ------------------- | ------------------------------------------ | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.5` 或 `openai-codex/gpt-5.5` | +| `gpt` | `openai/gpt-5.5` or `openai-codex/gpt-5.5` | | `gpt-mini` | `openai/gpt-5.4-mini` | | `gpt-nano` | `openai/gpt-5.4-nano` | | `gemini` | `google/gemini-3.1-pro-preview` | @@ -407,13 +429,13 @@ Skills 提示预算的每智能体覆盖。 你配置的别名始终优先于默认值。 -Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off` 或自行定义 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设置为 `false` 可禁用它。 -Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 `adaptive` thinking。 +Z.AI GLM-4.x 模型会自动启用思考模式，除非你设置 `--thinking off` 或自行定义 `agents.defaults.models["zai/"].params.thinking`。 +Z.AI 模型默认启用 `tool_stream`，用于工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设置为 `false` 可禁用它。 +Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `adaptive` 思考。 ### `agents.defaults.cliBackends` -纯文本回退运行（无工具调用）可选 CLI 后端。当 API 提供商失败时，可用作备用方案。 +用于纯文本回退运行的可选 CLI 后端（无工具调用）。适合作为 API 提供商失败时的备份。 ```json5 { @@ -448,7 +470,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.systemPromptOverride` -用固定字符串替换整个由 OpenClaw 组装的系统提示词。可在默认级别（`agents.defaults.systemPromptOverride`）或每个智能体（`agents.list[].systemPromptOverride`）设置。每个智能体的值优先；空值或仅包含空白字符的值会被忽略。适用于受控的提示词实验。 +用固定字符串替换 OpenClaw 组装的整个系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体（`agents.list[].systemPromptOverride`）设置。按智能体的值优先；空值或仅包含空白字符的值会被忽略。适用于受控提示实验。 ```json5 { @@ -462,7 +484,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.promptOverlays` -按模型系列应用的、与提供商无关的提示词叠加层。GPT-5 系列模型 ID 会在各提供商间接收共享行为契约；`personality` 仅控制友好交互风格层。 +按模型族应用的、与提供商无关的提示覆盖层。GPT-5 系列模型 ID 会跨提供商接收共享行为契约；`personality` 只控制友好的交互风格层。 ```json5 { @@ -478,9 +500,9 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `"friendly"`（默认）和 `"on"` 启用友好交互风格层。 -- `"off"` 仅禁用友好层；带标签的 GPT-5 行为契约仍会启用。 -- 未设置此共享设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。 +- `"friendly"`（默认）和 `"on"` 启用友好的交互风格层。 +- `"off"` 仅禁用友好层；已标记的 GPT-5 行为契约仍会启用。 +- 当未设置此共享设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。 ### `agents.defaults.heartbeat` @@ -512,16 +534,16 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API 密钥认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 -- `includeSystemPromptSection`：为 false 时，会从系统提示词中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入启动上下文。默认值：`true`。 -- `suppressToolErrorWarnings`：为 true 时，会在心跳运行期间抑制工具错误警告载荷。 -- `timeoutSeconds`：心跳智能体轮次在中止前允许的最长秒数。留空则使用 `agents.defaults.timeoutSeconds`。 +- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API 密钥凭证）或 `1h`（OAuth 凭证）。设置为 `0m` 可禁用。 +- `includeSystemPromptSection`：为 false 时，从系统提示中省略 Heartbeat 区段，并跳过将 `HEARTBEAT.md` 注入到启动上下文。默认值：`true`。 +- `suppressToolErrorWarnings`：为 true 时，在心跳运行期间抑制工具错误警告载荷。 +- `timeoutSeconds`：心跳智能体回合在被中止前允许的最长秒数。未设置时使用 `agents.defaults.timeoutSeconds`。 - `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 抑制直接目标投递，并发出 `reason=dm-blocked`。 -- `lightContext`：为 true 时，心跳运行会使用轻量启动上下文，并且只保留工作区启动文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次心跳都会在没有先前对话历史的新会话中运行。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。将每次心跳的 token 成本从约 100K 降至约 2-5K token。 +- `lightContext`：为 true 时，心跳运行使用轻量级启动上下文，并且仅保留工作区启动文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次心跳都在没有先前对话历史的新会话中运行。与 cron `sessionTarget: "isolated"` 相同的隔离模式。将每次心跳的 token 成本从约 100K 降至约 2-5K token。 - `skipWhenBusy`：为 true 时，心跳运行会因额外繁忙通道而推迟：子智能体或嵌套命令工作。即使没有此标志，Cron 通道也始终会推迟心跳。 -- 每个智能体：设置 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。 -- 心跳会运行完整的智能体轮次，间隔越短消耗的 token 越多。 +- 按智能体：设置 `agents.list[].heartbeat`。当任何智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。 +- 心跳会运行完整智能体回合，更短的间隔会消耗更多 token。 ### `agents.defaults.compaction` @@ -556,22 +578,22 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见[压缩](/zh-CN/concepts/compaction)。 -- `provider`：已注册压缩提供商插件的 ID。设置后，会调用该提供商的 `summarize()`，而不是内置 LLM 摘要。失败时回退到内置摘要。设置提供商会强制使用 `mode: "safeguard"`。参见[压缩](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 中止单次压缩操作前允许的最长秒数。默认值：`900`。 -- `keepRecentTokens`：用于逐字保留最近转录尾部的 Pi 截点预算。手动 `/compact` 在显式设置时会遵循此值；否则手动压缩是一个硬检查点。 -- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要期间前置内置的不透明标识符保留指引。 +- `mode`：`default` 或 `safeguard`（用于长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `provider`：已注册压缩提供商插件的 ID。设置后会调用该提供商的 `summarize()`，而不是内置 LLM 摘要。失败时回退到内置方式。设置提供商会强制 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：单次压缩操作在 OpenClaw 中止前允许的最长秒数。默认值：`900`。 +- `keepRecentTokens`：用于逐字保留最近转录尾部的 Pi 截点预算。手动 `/compact` 在显式设置时遵循此值；否则手动压缩是硬检查点。 +- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要期间前置内置的不透明标识符保留指南。 - `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 -- `qualityGuard`：针对 safeguard 摘要格式异常输出的重试检查。默认在 safeguard 模式下启用；设置 `enabled: false` 可跳过审计。 -- `postCompactionSections`：压缩后要重新注入的可选 AGENTS.md H2/H3 章节名称。默认值为 `["Session Startup", "Red Lines"]`；设置 `[]` 可禁用重新注入。当未设置或显式设置为该默认组合时，较旧的 `Every Session`/`Safety` 标题也会作为旧版回退被接受。 -- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖。当主会话应保留一个模型、但压缩摘要应在另一个模型上运行时使用；未设置时，压缩会使用会话的主模型。 -- `maxActiveTranscriptBytes`：可选字节阈值（`number` 或类似 `"20mb"` 的字符串），当活动 JSONL 超过该阈值时，会在运行前触发普通本地压缩。需要 `truncateAfterCompaction`，这样成功压缩后才能轮转到更小的后继转录。未设置或为 `0` 时禁用。 -- `notifyUser`：为 `true` 时，会在压缩开始和完成时向用户发送简短通知（例如 “Compacting context...” 和 “Compaction complete”）。默认禁用，以保持压缩静默。 -- `memoryFlush`：自动压缩前的静默智能体轮次，用于存储持久记忆。当此维护轮次应保持在本地模型上时，将 `model` 设置为精确的提供商/模型，例如 `ollama/qwen3:8b`；该覆盖不会继承活动会话的回退链。工作区为只读时会跳过。 +- `qualityGuard`：对 safeguard 摘要执行格式错误输出的重试检查。默认在 safeguard 模式下启用；设置 `enabled: false` 可跳过审计。 +- `postCompactionSections`：压缩后要重新注入的可选 AGENTS.md H2/H3 区段名称。默认值为 `["Session Startup", "Red Lines"]`；设置 `[]` 可禁用重新注入。当未设置或显式设置为这组默认值时，旧版 `Every Session`/`Safety` 标题也会作为兼容回退被接受。 +- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖。当主会话应保留一个模型、但压缩摘要应在另一个模型上运行时使用；未设置时，压缩使用会话的主模型。 +- `maxActiveTranscriptBytes`：可选字节阈值（`number` 或类似 `"20mb"` 的字符串），当活跃 JSONL 超过该阈值时，会在运行前触发普通本地压缩。需要 `truncateAfterCompaction`，以便成功压缩后可轮转到更小的后继转录。未设置或为 `0` 时禁用。 +- `notifyUser`：为 `true` 时，在压缩开始和完成时向用户发送简短通知（例如“正在压缩上下文...”和“压缩完成”）。默认禁用，以保持压缩静默。 +- `memoryFlush`：在自动压缩前执行的静默智能体回合，用于存储持久记忆。当此维护回合应留在本地模型上时，将 `model` 设置为精确的 provider/model，例如 `ollama/qwen3:8b`；此覆盖不会继承活跃会话的回退链。当工作区为只读时跳过。 ### `agents.defaults.contextPruning` -在发送给 LLM 前，从内存上下文中剪除**旧工具结果**。**不会**修改磁盘上的会话历史。 +在发送给 LLM 之前，从内存上下文中修剪**旧工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -595,23 +617,23 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 -- `mode: "cache-ttl"` 启用剪除流程。 -- `ttl` 控制剪除在上次缓存触碰后多久可以再次运行。 -- 剪除会先软修剪过大的工具结果，然后在需要时硬清除更旧的工具结果。 +- `mode: "cache-ttl"` 启用修剪过程。 +- `ttl` 控制修剪在上次缓存触碰之后多久可以再次运行。 +- 修剪会先软修剪过大的工具结果，然后在需要时硬清除更旧的工具结果。 **软修剪**会保留开头 + 结尾，并在中间插入 `...`。 **硬清除**会用占位符替换整个工具结果。 -说明： +注意： -- 图片块永远不会被修剪/清除。 -- 比率按字符计算（近似值），不是精确的 token 数。 -- 如果助理消息少于 `keepLastAssistants` 条，则会跳过剪除。 +- 图片块绝不会被修剪/清除。 +- 比例基于字符（近似值），不是精确 token 计数。 +- 如果助理消息少于 `keepLastAssistants` 条，则会跳过修剪。 -行为详情请参见[会话剪除](/zh-CN/concepts/session-pruning)。 +有关行为详情，请参见 [Session Pruning](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -630,10 +652,10 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ``` - 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 -- 渠道覆盖：`channels..blockStreamingCoalesce`（以及每账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 -- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。每个智能体覆盖：`agents.list[].humanDelay`。 +- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 +- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。 -行为和分块详情请参见[流式传输](/zh-CN/concepts/streaming)。 +有关行为和分块详情，请参见 [Streaming](/zh-CN/concepts/streaming)。 ### 输入状态指示器 @@ -649,15 +671,15 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ``` - 默认值：直接聊天/提及时为 `instant`，未提及的群聊中为 `message`。 -- 每会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 +- 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 -参见[输入状态指示器](/zh-CN/concepts/typing-indicators)。 +参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南请参见[沙箱隔离](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -757,19 +779,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **后端：** - `docker`：本地 Docker 运行时（默认） -- `ssh`：通用的 SSH 支持远程运行时 +- `ssh`：通用 SSH 支持的远程运行时 - `openshell`：OpenShell 运行时 -选择 `backend: "openshell"` 时，运行时特定设置会移至 +选择 `backend: "openshell"` 时，运行时专用设置会移至 `plugins.entries.openshell.config`。 **SSH 后端配置：** -- `target`：采用 `user@host[:port]` 格式的 SSH 目标 +- `target`：采用 `user@host[:port]` 形式的 SSH 目标 - `command`：SSH 客户端命令（默认：`ssh`） -- `workspaceRoot`：用于按作用域工作区的绝对远程根目录 +- `workspaceRoot`：用于按 scope 创建工作区的绝对远程根目录 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 -- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在运行时物化为临时文件的内联内容或 SecretRef +- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRefs，OpenClaw 会在运行时将其物化为临时文件 - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 **SSH 凭证优先级：** @@ -781,19 +803,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **SSH 后端行为：** -- 在创建或重新创建后，仅初始化一次远程工作区 -- 然后保持远程 SSH 工作区为权威版本 +- 创建或重新创建后，仅初始化一次远程工作区 +- 然后保持远程 SSH 工作区为权威来源 - 通过 SSH 路由 `exec`、文件工具和媒体路径 - 不会自动将远程更改同步回主机 - 不支持沙箱浏览器容器 **工作区访问：** -- `none`：位于 `~/.openclaw/sandboxes` 下的按作用域沙箱工作区 -- `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` -- `rw`：智能体工作区以读写方式挂载到 `/workspace` +- `none`：`~/.openclaw/sandboxes` 下按 scope 创建的沙箱工作区 +- `ro`：沙箱工作区位于 `/workspace`，agent 工作区以只读方式挂载到 `/agent` +- `rw`：agent 工作区以读写方式挂载到 `/workspace` -**作用域：** +**Scope：** - `session`：每个会话一个容器 + 工作区 - `agent`：每个智能体一个容器 + 工作区（默认） @@ -827,30 +849,30 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：执行前从本地初始化远程，执行后同步回来；本地工作区保持为权威版本 -- `remote`：创建沙箱时初始化一次远程，然后保持远程工作区为权威版本 +- `mirror`：exec 前从本地初始化远程，exec 后同步回来；本地工作区保持为权威来源 +- `remote`：创建沙箱时初始化远程一次，然后保持远程工作区为权威来源 -在 `remote` 模式下，在 OpenClaw 外部进行的主机本地编辑不会在初始化步骤后自动同步进沙箱。 -传输方式是通过 SSH 进入 OpenShell 沙箱，但插件拥有沙箱生命周期和可选的镜像同步。 +在 `remote` 模式下，初始化步骤之后，在 OpenClaw 之外进行的主机本地编辑不会自动同步进沙箱。 +传输方式是通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期和可选的镜像同步。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根目录和 root 用户。 +**`setupCommand`** 在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根目录和 root 用户。 -**容器默认为 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义桥接网络）。 -`"host"` 会被阻止。`"container:"` 默认会被阻止，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急破例）。 +**容器默认使用 `network: "none"`**，如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 +`"host"` 会被阻止。默认情况下 `"container:"` 会被阻止，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（应急开关）。 **入站附件** 会暂存到活动工作区中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局绑定和按智能体绑定会合并。 +**`docker.binds`** 会挂载额外的主机目录；全局和按智能体配置的 binds 会合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入系统提示词。不需要在 `openclaw.json` 中启用 `browser.enabled`。 -noVNC 观察者访问默认使用 VNC 凭证，OpenClaw 会发出短期有效的令牌 URL（而不是在共享 URL 中暴露密码）。 +**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入系统提示词。不需要在 `openclaw.json` 中设置 `browser.enabled`。 +noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会生成一个短期有效的 token URL（而不是在共享 URL 中暴露密码）。 -- `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。 -- `network` 默认为 `openclaw-sandbox-browser`（专用桥接网络）。仅当你明确想要全局桥接连通性时，才设置为 `bridge`。 -- `cdpSourceRange` 可选地将容器边缘的 CDP 入站限制为一个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 -- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优： +- `allowHostControl: false`（默认）会阻止沙箱隔离会话定位主机浏览器。 +- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。只有在你明确需要全局 bridge 连接时，才设置为 `bridge`。 +- `cdpSourceRange` 可选择将容器边缘的 CDP 入站限制到一个 CIDR 范围（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 +- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -868,16 +890,11 @@ noVNC 观察者访问默认使用 VNC 凭证，OpenClaw 会发出短期有效的 - `--no-zygote` - `--metrics-recording-only` - `--disable-extensions`（默认启用） - - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` - 默认启用；如果 WebGL/3D 使用需要，可以通过 - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用。 + - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 默认启用；如果 WebGL/3D 使用需要它们，可以通过 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用。 - 如果你的工作流依赖扩展，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展。 - - `--renderer-process-limit=2` 可通过 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 更改；设置为 `0` 可使用 Chromium 的 - 默认进程限制。 - - 当启用 `noSandbox` 时，还会加上 `--no-sandbox`。 - - 默认值是容器镜像基线；使用带自定义 - 入口点的自定义浏览器镜像来更改容器默认值。 + - `--renderer-process-limit=2` 可通过 `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 更改；设为 `0` 可使用 Chromium 的默认进程限制。 + - 当 `noSandbox` 启用时，还会加上 `--no-sandbox`。 + - 默认值是容器镜像基线；如需更改容器默认值，请使用带自定义入口点的自定义浏览器镜像。 @@ -892,13 +909,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `agents.list`（按智能体覆盖） -使用 `agents.list[].tts` 为智能体指定自己的 TTS 提供商、语音、模型、 -风格或自动 TTS 模式。智能体块会深度合并到全局 -`messages.tts` 之上，因此共享凭证可以保留在一个位置，而各个 -智能体只覆盖它们需要的语音或提供商字段。活动智能体的 -覆盖适用于自动语音回复、`/tts audio`、`/tts status` 和 -`tts` 智能体工具。请参阅 [文本转语音](/zh-CN/tools/tts#per-agent-voice-overrides) -了解提供商示例和优先级。 +使用 `agents.list[].tts` 为智能体指定自己的 TTS 提供商、语音、模型、风格或自动 TTS 模式。智能体块会深度合并到全局 `messages.tts` 之上，因此共享凭证可以保留在一个位置，而各个智能体只覆盖它们需要的语音或提供商字段。活动智能体的覆盖会应用于自动语音回复、`/tts audio`、`/tts status` 和 `tts` 智能体工具。有关提供商示例和优先级，请参阅[文本转语音](/zh-CN/tools/tts#per-agent-voice-overrides)。 ```json5 { @@ -952,28 +963,28 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `id`：稳定的智能体 ID（必需）。 -- `default`：设置多个时，第一个生效（会记录警告）。如果都未设置，列表中的第一项为默认值。 -- `model`：字符串形式会设置严格的每智能体主模型，且没有模型回退；对象形式 `{ primary }` 同样严格，除非你添加 `fallbacks`。使用 `{ primary, fallbacks: [...] }` 让该智能体启用回退，或使用 `{ primary, fallbacks: [] }` 明确指定严格行为。只覆盖 `primary` 的 Cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。 -- `params`：每智能体的流参数，会合并覆盖 `agents.defaults.models` 中所选模型条目。用它为智能体设置特定覆盖项，例如 `cacheRetention`、`temperature` 或 `maxTokens`，无需复制整个模型目录。 -- `tts`：可选的每智能体文本转语音覆盖项。该块会深度合并覆盖 `messages.tts`，因此请把共享的提供商凭据和回退策略放在 `messages.tts` 中，并且这里只设置角色特定值，例如提供商、voice、模型、style 或自动模式。 -- `skills`：可选的每智能体 skill 允许列表。如果省略，智能体会在设置了 `agents.defaults.skills` 时继承它；显式列表会替换默认值而不是合并，`[]` 表示没有 skills。 -- `thinkingDefault`：可选的每智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当没有设置每消息或会话级覆盖时，为该智能体覆盖 `agents.defaults.thinkingDefault`。所选提供商/模型配置控制哪些值有效；对于 Google Gemini，`adaptive` 会保留提供商拥有的动态 thinking（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。 -- `reasoningDefault`：可选的每智能体默认 reasoning 可见性（`on | off | stream`）。当没有设置每消息或会话级 reasoning 覆盖时应用。 -- `fastModeDefault`：可选的每智能体 fast mode 默认值（`true | false`）。当没有设置每消息或会话级 fast-mode 覆盖时应用。 -- `agentRuntime`：可选的每智能体底层运行时策略覆盖项。使用 `{ id: "codex" }` 可让一个智能体仅使用 Codex，而其他智能体在 `auto` 模式下保留默认 Pi 回退。 -- `runtime`：可选的每智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 以及 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `id`：稳定的智能体 id（必需）。 +- `default`：设置多个时，第一个生效（会记录警告）。如果未设置，则列表第一项为默认值。 +- `model`：字符串形式会设置严格的按智能体主模型，且没有模型回退；对象形式 `{ primary }` 也同样严格，除非你添加 `fallbacks`。使用 `{ primary, fallbacks: [...] }` 可让该智能体启用回退，或使用 `{ primary, fallbacks: [] }` 明确采用严格行为。仅覆盖 `primary` 的 Cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。 +- `params`：按智能体设置的流参数，会覆盖合并到 `agents.defaults.models` 中选定的模型条目。用它设置特定智能体的覆盖项，例如 `cacheRetention`、`temperature` 或 `maxTokens`，无需复制整个模型目录。 +- `tts`：可选的按智能体文本转语音覆盖项。该块会深度合并到 `messages.tts` 之上，因此请将共享的提供商凭证和回退策略保留在 `messages.tts` 中，并在这里仅设置角色特定值，例如提供商、语音、模型、风格或自动模式。 +- `skills`：可选的按智能体 Skills 允许列表。如果省略，且已设置 `agents.defaults.skills`，该智能体会继承它；显式列表会替换默认值而不是合并，`[]` 表示不启用 Skills。 +- `thinkingDefault`：可选的按智能体默认思考级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。在未设置按消息或会话覆盖项时，为此智能体覆盖 `agents.defaults.thinkingDefault`。所选提供商/模型配置会控制哪些值有效；对于 Google Gemini，`adaptive` 会保留提供商拥有的动态思考（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。 +- `reasoningDefault`：可选的按智能体默认推理可见性（`on | off | stream`）。在未设置按消息或会话推理覆盖项时适用。 +- `fastModeDefault`：可选的按智能体快速模式默认值（`true | false`）。在未设置按消息或会话快速模式覆盖项时适用。 +- `agentRuntime`：可选的按智能体底层运行时策略覆盖项。使用 `{ id: "codex" }` 可让某个智能体仅使用 Codex，而其他智能体在 `auto` 模式下保留默认 PI 回退。 +- `runtime`：可选的按智能体运行时描述符。当该智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 以及 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 - `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。 -- `identity` 会派生默认值：从 `emoji` 派生 `ackReaction`，从 `name`/`emoji` 派生 `mentionPatterns`。 -- `subagents.allowAgents`：用于显式 `sessions_spawn.agentId` 目标的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。当应允许自目标 `agentId` 调用时，请包含请求者 ID。 -- 沙箱继承保护：如果请求者会话处于沙箱隔离中，`sessions_spawn` 会拒绝会以非沙箱隔离方式运行的目标。 -- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件；默认：false）。 +- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。 +- `subagents.allowAgents`：显式 `sessions_spawn.agentId` 目标的智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。当应允许以自身为目标的 `agentId` 调用时，请包含请求方 id。 +- 沙箱继承保护：如果请求方会话是沙箱隔离的，`sessions_spawn` 会拒绝会以非沙箱隔离方式运行的目标。 +- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置档案；默认：false）。 --- ## 多智能体路由 -在一个 Gateway 网关内运行多个隔离的智能体。请参阅[多智能体](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关中运行多个隔离的智能体。参见 [多智能体](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -992,11 +1003,11 @@ scripts/sandbox-browser-setup.sh # optional browser image ### 绑定匹配字段 -- `type`（可选）：`route` 表示普通路由（缺失 type 时默认使用 route），`acp` 表示持久 ACP 对话绑定。 +- `type`（可选）：`route` 表示普通路由（缺失 type 时默认为 route），`acp` 表示持久 ACP 对话绑定。 - `match.channel`（必需） - `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） -- `match.guildId` / `match.teamId`（可选；渠道特定） +- `match.guildId` / `match.teamId`（可选；特定渠道使用） - `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }` **确定性匹配顺序：** @@ -1010,11 +1021,11 @@ scripts/sandbox-browser-setup.sh # optional browser image 在每一层级内，第一个匹配的 `bindings` 条目生效。 -对于 `type: "acp"` 条目，OpenClaw 会按精确对话身份（`match.channel` + 账号 + `match.peer.id`）解析，并且不会使用上面的 route 绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 会按精确的对话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上面的路由绑定层级顺序。 -### 每智能体访问配置文件 +### 按智能体划分的访问配置档案 - + ```json5 { @@ -1032,7 +1043,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1107,7 +1118,7 @@ scripts/sandbox-browser-setup.sh # optional browser image -参见 [多智能体沙箱与工具](/zh-CN/tools/multi-agent-sandbox-tools)，了解优先级详情。 +有关优先级详情，请参阅 [Multi-Agent 沙箱与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1160,34 +1171,34 @@ scripts/sandbox-browser-setup.sh # optional browser image - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：每个发送者在渠道上下文中获得一个隔离的会话。 - - `global`：渠道上下文中的所有参与者共享单个会话（仅在确实需要共享上下文时使用）。 + - `per-sender`（默认）：每个发送者在渠道上下文中获得一个隔离会话。 + - `global`：渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。 - **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - `per-peer`：跨渠道按发送者 ID 隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对端，用于跨渠道共享会话。诸如 `/dock_discord` 的停靠命令使用同一映射，将当前会话的回复路由切换到另一个已关联的渠道对端；参见 [渠道停靠](/zh-CN/concepts/channel-docking)。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。两者都配置时，先过期者生效。每日重置的新鲜度使用会话行的 `sessionStartedAt`；空闲重置的新鲜度使用 `lastInteractionAt`。后台/系统事件写入（如心跳、cron 唤醒、exec 通知和 Gateway 网关记账）可以更新 `updatedAt`，但它们不会让每日/空闲会话保持新鲜。 +- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对端，用于跨渠道会话共享。诸如 `/dock_discord` 的停靠命令会使用同一映射，将当前会话的回复路由切换到另一个已链接的渠道对端；参见[渠道停靠](/zh-CN/concepts/channel-docking)。 +- **`reset`**：主要重置策略。`daily` 在本地时间 `atHour` 重置；`idle` 在 `idleMinutes` 后重置。两者同时配置时，先到期者生效。每日重置的新鲜度使用会话行的 `sessionStartedAt`；空闲重置的新鲜度使用 `lastInteractionAt`。后台/系统事件写入（例如心跳、cron 唤醒、exec 通知和 Gateway 网关簿记）可以更新 `updatedAt`，但它们不会让每日/空闲会话保持新鲜。 - **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建分叉线程会话时允许的父会话 `totalTokens` 最大值（默认 `100000`）。 +- **`parentForkMaxTokens`**：创建分叉线程会话时允许的最大父会话 `totalTokens`（默认 `100000`）。 - 如果父级 `totalTokens` 高于此值，OpenClaw 会启动一个新的线程会话，而不是继承父级转录历史。 - - 设为 `0` 可禁用此保护，并始终允许父级分叉。 -- **`mainKey`**：旧版字段。运行时始终为主直接聊天桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体到智能体交换期间，智能体之间的最大来回回复轮数（整数，范围：`0`–`5`）。`0` 会禁用来回链式回复。 -- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，带旧版 `dm` 别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个拒绝规则胜出。 + - 设置为 `0` 可禁用此保护，并始终允许父级分叉。 +- **`mainKey`**：旧版字段。运行时始终使用 `"main"` 作为主直接聊天桶。 +- **`agentToAgent.maxPingPongTurns`**：agent 到 agent 交换期间，agent 之间的最大往返回复轮数（整数，范围：`0`–`5`）。`0` 会禁用乒乓式链式回复。 +- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，带旧版 `dm` 别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个拒绝规则获胜。 - **`maintenance`**：会话存储清理 + 保留控制。 - `mode`：`warn` 仅发出警告；`enforce` 会执行清理。 - `pruneAfter`：过期条目的年龄截止值（默认 `30d`）。 - - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。运行时会使用一个很小的高水位缓冲区批量写入清理，以适配生产规模上限；`openclaw sessions cleanup --enforce` 会立即应用该上限。 - - `rotateBytes`：已弃用且会被忽略；`openclaw doctor --fix` 会将其从旧配置中移除。 - - `resetArchiveRetention`：`*.reset.` 转录归档的保留时间。默认与 `pruneAfter` 相同；设为 `false` 可禁用。 - - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会先移除最旧的工件/会话。 - - `highWaterBytes`：预算清理后的可选目标。默认是 `maxDiskBytes` 的 `80%`。 + - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。运行时写入批量清理，并为生产规模上限保留一个小的高水位缓冲；`openclaw sessions cleanup --enforce` 会立即应用该上限。 + - `rotateBytes`：已弃用且会被忽略；`openclaw doctor --fix` 会从旧配置中移除它。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留期。默认为 `pruneAfter`；设置为 `false` 可禁用。 + - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的工件/会话。 + - `highWaterBytes`：预算清理后的可选目标。默认为 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - `enabled`：主默认开关（提供商可以覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认的非活动自动取消聚焦小时数（`0` 禁用；提供商可以覆盖） - - `maxAgeHours`：默认的硬性最大年龄小时数（`0` 禁用；提供商可以覆盖） + - `idleHours`：默认非活动自动取消聚焦小时数（`0` 禁用；提供商可以覆盖） + - `maxAgeHours`：默认硬性最大年龄小时数（`0` 禁用；提供商可以覆盖） @@ -1227,34 +1238,34 @@ scripts/sandbox-browser-setup.sh # optional browser image 每个渠道/账号覆盖项：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解析顺序（最具体者优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生 `[{identity.name}]`。 +解析规则（最具体者优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生 `[{identity.name}]`。 **模板变量：** -| 变量 | 说明 | 示例 | +| 变量 | 描述 | 示例 | | ----------------- | -------------------- | --------------------------- | -| `{model}` | 简短模型名称 | `claude-opus-4-6` | +| `{model}` | 短模型名称 | `claude-opus-4-6` | | `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | | `{provider}` | 提供商名称 | `anthropic` | | `{thinkingLevel}` | 当前思考级别 | `high`, `low`, `off` | -| `{identity.name}` | 智能体身份名称 |（与 `"auto"` 相同） | +| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 -### 确认回应表情 +### 确认反应 - 默认为活动智能体的 `identity.emoji`，否则为 `"👀"`。设置为 `""` 可禁用。 - 每个渠道覆盖项：`channels..ackReaction`、`channels..accounts..ackReaction`。 -- 解析顺序：账号 → 渠道 → `messages.ackReaction` → 身份回退值。 -- 范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在支持 reaction 的渠道（如 Slack、Discord、Telegram、WhatsApp 和 BlueBubbles）上，会在回复后移除确认回应。 -- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态 reaction。 - 在 Slack 和 Discord 上，未设置时，如果确认回应 reaction 处于活动状态，会保持状态 reaction 启用。 - 在 Telegram 上，需要显式设置为 `true` 才能启用生命周期状态 reaction。 +- 解析顺序：账号 → 渠道 → `messages.ackReaction` → 身份回退。 +- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。 +- `removeAckAfterReply`：在 Slack、Discord、Telegram、WhatsApp 和 BlueBubbles 等支持反应的渠道上，在回复后移除确认反应。 +- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期 Status 反应。 + 在 Slack 和 Discord 上，未设置时，如果确认反应处于活动状态，则保持启用 Status 反应。 + 在 Telegram 上，需要显式设置为 `true` 才能启用生命周期 Status 反应。 ### 入站防抖 -将同一发送者快速发送的纯文本消息合并为单个智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。 +将同一发送者快速发送的纯文本消息合并为一次智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -1304,19 +1315,19 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` 控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好设置，`/tts status` 会显示生效状态。 -- `summaryModel` 会覆盖 `agents.defaults.model.primary`，用于自动摘要。 +- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好设置，`/tts status` 会显示生效状态。 +- `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。 - `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（选择加入）。 - API 密钥会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 -- 内置语音提供商由插件拥有。如果设置了 `plugins.allow`，请包含你要使用的每个 TTS 提供商插件，例如用于 Edge TTS 的 `microsoft`。旧版 `edge` 提供商 id 会作为 `microsoft` 的别名被接受。 +- 内置语音提供商由插件拥有。如果设置了 `plugins.allow`，请包含你想使用的每个 TTS 提供商插件，例如用于 Edge TTS 的 `microsoft`。旧版 `edge` 提供商 ID 会作为 `microsoft` 的别名被接受。 - `providers.openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置，然后是 `OPENAI_TTS_BASE_URL`，然后是 `https://api.openai.com/v1`。 -- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容的 TTS 服务器，并放宽模型/语音验证。 +- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型/语音校验。 --- -## Talk +## 语音对话 -Talk 模式（macOS/iOS/Android）的默认值。 +语音对话模式（macOS/iOS/Android）的默认值。 ```json5 { @@ -1345,20 +1356,20 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- 配置多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 -- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.`。 -- Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 +- 配置多个语音对话提供商时，`talk.provider` 必须匹配 `talk.providers` 中的一个键。 +- 旧版扁平语音对话键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.`。 +- 语音 ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 - `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 -- `ELEVENLABS_API_KEY` 回退仅在未配置 Talk API 密钥时适用。 -- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 +- 仅在未配置语音对话 API 密钥时，才会应用 `ELEVENLABS_API_KEY` 回退。 +- `providers.*.voiceAliases` 允许语音对话指令使用友好名称。 - `providers.mlx.modelId` 选择 macOS 本地 MLX 辅助程序使用的 Hugging Face 仓库。如果省略，macOS 会使用 `mlx-community/Soprano-80M-bf16`。 -- macOS MLX 播放会在存在时通过内置 `openclaw-mlx-tts` 辅助程序运行，或通过 `PATH` 上的可执行文件运行；`OPENCLAW_MLX_TTS_BIN` 会覆盖开发用的辅助程序路径。 -- `speechLocale` 设置 iOS/macOS Talk 语音识别使用的 BCP 47 区域设置 id。留空则使用设备默认值。 -- `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多久再发送转录。未设置时会保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- macOS MLX 播放会在存在时通过内置 `openclaw-mlx-tts` 辅助程序运行，或通过 `PATH` 上的可执行文件运行；`OPENCLAW_MLX_TTS_BIN` 会覆盖用于开发的辅助程序路径。 +- `speechLocale` 设置 iOS/macOS 语音对话语音识别使用的 BCP 47 区域设置 ID。留空则使用设备默认值。 +- `silenceTimeoutMs` 控制语音对话模式在用户静默后等待多久再发送转录文本。未设置时会保留平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）。 --- -## 相关 +## 相关内容 - [配置参考](/zh-CN/gateway/configuration-reference) — 所有其他配置键 - [配置](/zh-CN/gateway/configuration) — 常见任务和快速设置 diff --git a/docs/zh-CN/gateway/local-models.md b/docs/zh-CN/gateway/local-models.md index 518416db5..626cbc6b8 100644 --- a/docs/zh-CN/gateway/local-models.md +++ b/docs/zh-CN/gateway/local-models.md @@ -2,29 +2,29 @@ read_when: - 你想从自己的 GPU 机器提供模型服务 - 你正在接入 LM Studio 或 OpenAI 兼容代理 - - 你需要最安全的本地模型指导 + - 你需要最安全的本地模型指南 summary: 在本地 LLM 上运行 OpenClaw（LM Studio、vLLM、LiteLLM、自定义 OpenAI 端点） title: 本地模型 x-i18n: - generated_at: "2026-04-28T11:52:56Z" + generated_at: "2026-04-29T10:40:00Z" model: gpt-5.5 provider: openai - source_hash: 4be447ece49ec1b41456db54a223679f4e399b8e9231925fd08d12999af246c9 + source_hash: 2ec1be4eac371328c1efe80b71450019f68fb1114df90db1532a4ff72bfa0ab1 source_path: gateway/local-models.md workflow: 16 --- -本地可行，但 OpenClaw 需要大上下文和强大的提示词注入防护。小显存卡会截断上下文并削弱安全性。目标要高：**≥2 台满配 Mac Studio 或同等级 GPU 设备（约 $30k+）**。单张 **24 GB** GPU 只适合较轻的提示词，且延迟更高。使用你能运行的**最大 / 全尺寸模型变体**；激进量化或“小型”检查点会提高提示词注入风险（见 [安全](/zh-CN/gateway/security)）。 +本地运行可行，但 OpenClaw 需要大上下文 + 强提示注入防御。小显存卡会截断上下文并削弱安全性。目标要高：**至少 2 台满配 Mac Studio 或同等 GPU 主机（约 3 万美元以上）**。单块 **24 GB** GPU 只适合较轻提示，且延迟更高。使用你能运行的**最大 / 完整尺寸模型变体**；激进量化或“小型”检查点会提高提示注入风险（参见 [安全](/zh-CN/gateway/security)）。 -如果你想要阻力最小的本地设置，从 [LM Studio](/zh-CN/providers/lmstudio) 或 [Ollama](/zh-CN/providers/ollama) 和 `openclaw onboard` 开始。本页是面向更高端本地栈和自定义 OpenAI 兼容本地服务器的主观指南。 +如果你想要阻力最小的本地设置，请从 [LM Studio](/zh-CN/providers/lmstudio) 或 [Ollama](/zh-CN/providers/ollama) 和 `openclaw onboard` 开始。本页是面向更高端本地栈和自定义 OpenAI 兼容本地服务器的有主见指南。 -**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)。 ## 推荐：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 { @@ -61,7 +61,7 @@ x-i18n: } ``` -**设置清单** +**设置检查清单** - 安装 LM Studio：[https://lmstudio.ai](https://lmstudio.ai) - 在 LM Studio 中，下载**可用的最大模型构建**（避免“小型”/重度量化变体），启动服务器，确认 `http://127.0.0.1:1234/v1/models` 会列出它。 @@ -70,7 +70,7 @@ x-i18n: - 如果你的 LM Studio 构建不同，请调整 `contextWindow`/`maxTokens`。 - 对于 WhatsApp，坚持使用 Responses API，这样只会发送最终文本。 -即使运行本地模型，也保留托管模型配置；使用 `models.mode: "merge"`，让回退始终可用。 +即使运行本地模型，也保留托管模型配置；使用 `models.mode: "merge"` 让回退保持可用。 ### 混合配置：托管主模型，本地回退 @@ -113,18 +113,18 @@ x-i18n: } ``` -### 本地优先并保留托管安全网 +### 本地优先，托管安全网 -交换主模型和回退的顺序；保留相同的 providers 块和 `models.mode: "merge"`，这样当本地机器宕机时，你可以回退到 Sonnet 或 Opus。 +交换主模型和回退顺序；保留相同的 providers 块和 `models.mode: "merge"`，这样当本地主机不可用时，你可以回退到 Sonnet 或 Opus。 ### 区域托管 / 数据路由 -- 托管的 MiniMax/Kimi/GLM 变体也存在于 OpenRouter 上，并提供区域固定端点（例如美国托管）。在那里选择区域变体，以便在仍然通过 `models.mode: "merge"` 使用 Anthropic/OpenAI 回退的同时，把流量保留在你选择的司法辖区内。 -- 纯本地仍然是隐私最强的路径；当你需要提供商功能但又想控制数据流时，托管区域路由是折中方案。 +- OpenRouter 上也提供托管的 MiniMax/Kimi/GLM 变体，并带有区域固定端点（例如美国托管）。在那里选择区域变体，以便在仍然使用 `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,33 +158,33 @@ x-i18n: } ``` -如果在带有 `baseUrl` 的自定义提供商上省略 `api`，OpenClaw 默认使用 `openai-completions`。诸如 `127.0.0.1` 的回环端点会自动受信任；LAN、tailnet 和私有 DNS 端点仍需要 `request.allowPrivateNetwork: true`。 +如果在带有 `baseUrl` 的自定义 provider 上省略 `api`，OpenClaw 默认使用 `openai-completions`。`127.0.0.1` 这类 loopback 端点会被自动信任；LAN、tailnet 和 private DNS 端点仍然需要 `request.allowPrivateNetwork: true`。 -`models.providers..models[].id` 值是提供商本地的。不要在那里包含提供商前缀。例如，使用 `mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit` 启动的 MLX 服务器应使用此目录 ID 和模型引用： +`models.providers..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"]`，这样图像附件就会注入到 agent 轮次中。交互式自定义 provider 新手引导会推断常见视觉模型 ID，并只询问未知名称。非交互式新手引导使用相同推断；对于未知视觉 ID 使用 `--custom-image-input`，当看似已知的模型在你的端点后面实际仅支持文本时，使用 `--custom-text-input`。 -保持 `models.mode: "merge"`，这样托管模型仍可作为回退使用。对于缓慢的本地或远程模型服务器，先使用 `models.providers..timeoutSeconds`，再提高 `agents.defaults.timeoutSeconds`。提供商超时只适用于模型 HTTP 请求，包括连接、标头、正文流式传输以及受保护 fetch 的总中止时间。 +保留 `models.mode: "merge"`，这样托管模型仍可作为回退使用。对于缓慢的本地或远程模型服务器，请先使用 `models.providers..timeoutSeconds`，再提高 `agents.defaults.timeoutSeconds`。provider 超时仅适用于模型 HTTP 请求，包括连接、headers、body 流式传输以及总的 guarded-fetch 中止。 -对于自定义 OpenAI 兼容提供商，当 `baseUrl` 解析到回环、私有 LAN、`.local` 或裸主机名时，可以持久化一个非密钥本地标记，例如 `apiKey: "ollama-local"`。OpenClaw 会把它当作有效的本地凭证，而不是报告缺少密钥。对于任何接受公共主机名的提供商，请使用真实值。 +对于自定义 OpenAI 兼容提供商，当 `baseUrl` 解析到 loopback、私有 LAN、`.local` 或裸主机名时，允许持久化一个非机密本地标记，例如 `apiKey: "ollama-local"`。OpenClaw 会将其视为有效的本地凭证，而不是报告缺少密钥。对于任何接受公共主机名的 provider，请使用真实值。 本地/代理 `/v1` 后端的行为说明： - OpenClaw 将这些视为代理风格的 OpenAI 兼容路由，而不是原生 OpenAI 端点 -- 仅原生 OpenAI 的请求整形不会在这里应用：没有 `service_tier`，没有 Responses `store`，没有 OpenAI 推理兼容载荷整形，也没有提示词缓存提示 -- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）不会注入这些自定义代理 URL +- 原生 OpenAI 专用请求整形不适用于这里：没有 `service_tier`，没有 Responses `store`，没有 OpenAI reasoning-compat payload 整形，也没有 prompt-cache 提示 +- 隐藏的 OpenClaw 归因 headers（`originator`、`version`、`User-Agent`）不会注入到这些自定义代理 URL 上 -更严格 OpenAI 兼容后端的兼容性说明： +对更严格 OpenAI 兼容后端的兼容性说明： -- 有些服务器在 Chat Completions 上只接受字符串 `messages[].content`，不接受结构化内容部分数组。对这些端点设置 `models.providers..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..models[].compat.requiresStringContent: true`。 +- 某些本地模型会以文本形式发出独立的方括号工具请求，例如 `[tool_name]` 后跟 JSON 和 `[END_TOOL_REQUEST]`。只有当名称与该轮次中已注册的 tool 完全匹配时，OpenClaw 才会将这些提升为真实 tool 调用；否则，该块会被视为不支持的文本，并从用户可见回复中隐藏。 +- 如果模型发出看起来像 tool 调用的 JSON、XML 或 ReAct 风格文本，但 provider 没有发出结构化调用，OpenClaw 会将其保留为文本，并记录一条警告，其中包含运行 ID、provider/model、检测到的模式，以及可用时的 tool 名称。请将其视为 provider/model 工具调用不兼容，而不是已完成的工具运行。 +- 如果工具以 assistant 文本形式出现而没有运行，例如原始 JSON、XML、ReAct 语法，或 provider 响应中的空 `tool_calls` 数组，请先确认服务器正在使用支持 tool-call 的 chat template/parser。对于 parser 仅在强制使用工具时才工作的 OpenAI 兼容 Chat Completions 后端，请设置按模型请求覆盖，而不是依赖文本解析： ```json5 { @@ -204,58 +204,95 @@ 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/model 引用。 ```bash openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge ``` -- 有些较小或更严格的本地后端在处理 OpenClaw 完整智能体运行时提示词形态时不稳定，尤其是在包含工具架构时。先使用精简本地探测验证提供商路径： +- 如果自定义 OpenAI 兼容模型接受内置配置之外的 OpenAI reasoning efforts，请在模型 compat 块中声明它们。在这里添加 `"xhigh"` 会让 `/think xhigh`、会话选择器、Gateway 网关验证以及 `llm-task` 验证为该已配置的 provider/model 引用暴露该级别： + + ```json5 + { + models: { + providers: { + local: { + baseUrl: "http://127.0.0.1:8000/v1", + apiKey: "sk-local", + api: "openai-responses", + models: [ + { + id: "gpt-5.4", + name: "GPT 5.4 via local proxy", + reasoning: true, + input: ["text"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 196608, + maxTokens: 8192, + compat: { + supportedReasoningEfforts: ["low", "medium", "high", "xhigh"], + reasoningEffortMap: { xhigh: "xhigh" }, + }, + }, + ], + }, + }, + }, + } + ``` + +- 某些较小或更严格的本地后端在使用 OpenClaw 完整 agent-runtime prompt 形状时不稳定，尤其是包含工具 schema 时。请先使用精简本地探测来验证 provider 路径： ```bash openclaw infer model run --local --model --prompt "Reply with exactly: pong" --json ``` - 要在不使用完整智能体提示词形态的情况下验证 Gateway 网关路由，请改用 Gateway 网关模型探测： + 要在没有完整 agent prompt 形状的情况下验证 Gateway 网关路由，请改用 Gateway 网关模型探测： ```bash openclaw infer model run --gateway --model --prompt "Reply with exactly: pong" --json ``` - 本地和 Gateway 网关模型探测都只发送提供的提示词。Gateway 网关探测仍会验证 Gateway 网关路由、身份验证和提供商选择，但它有意跳过先前会话转录、AGENTS/bootstrap 上下文、上下文引擎组装、工具和内置 MCP 服务器。 + 本地和 Gateway 网关模型探测都只发送提供的 prompt。Gateway 网关探测仍会验证 Gateway 网关路由、auth 和 provider 选择，但它会有意跳过之前的 session transcript、AGENTS/bootstrap context、context-engine assembly、tools 以及内置 MCP servers。 - 如果这一步成功但普通 OpenClaw 智能体轮次失败，请先尝试 `agents.defaults.experimental.localModelLean: true`，以去掉 `browser`、`cron` 和 `message` 等重量级默认工具；这是一个实验性标志，不是稳定的默认模式设置。请参阅 [实验性功能](/zh-CN/concepts/experimental-features)。如果仍然失败，请尝试 `models.providers..models[].compat.supportsTools: false`。 + 如果这一步成功，但普通 OpenClaw 智能体轮次失败，先尝试 + `agents.defaults.experimental.localModelLean: true`，以去掉 `browser`、`cron` 和 `message` + 等重量级默认工具；这是一个实验性 + 标志，不是稳定的默认模式设置。参见 + [实验性功能](/zh-CN/concepts/experimental-features)。如果仍然失败，尝试 + `models.providers..models[].compat.supportsTools: false`。 -- 如果后端仍然只在较大的 OpenClaw 运行中失败，剩余问题通常是上游模型/服务器容量或后端缺陷，而不是 OpenClaw 的传输层。 +- 如果后端仍然只在较大的 OpenClaw 运行中失败，剩余问题 + 通常是上游模型/服务器容量或后端错误，而不是 OpenClaw 的 + 传输层。 ## 故障排除 - Gateway 网关能访问代理吗？`curl http://127.0.0.1:1234/v1/models`。 -- LM Studio 模型被卸载了？重新加载；冷启动是常见的“卡住”原因。 +- LM Studio 模型已卸载？重新加载；冷启动是常见的“卡住”原因。 - 本地服务器提示 `terminated`、`ECONNRESET`，或在轮次中途关闭流？ - OpenClaw 会在诊断信息中记录一个低基数的 `model.call.error.failureKind`，以及 - OpenClaw 进程的 RSS/堆快照。对于 LM Studio/Ollama + OpenClaw 会在诊断信息中记录低基数的 `model.call.error.failureKind`，以及 + OpenClaw 进程 RSS/堆快照。对于 LM Studio/Ollama 内存压力，请将该时间戳与服务器日志或 macOS 崩溃 / - jetsam 日志进行匹配，以确认模型服务器是否被终止。 -- 当检测到的上下文窗口低于 **32k** 时，OpenClaw 会发出警告；低于 **16k** 时会阻止运行。如果你遇到该预检，请提高服务器/模型上下文限制，或选择更大的模型。 + jetsam 日志匹配，以确认模型服务器是否被终止。 +- 当检测到的上下文窗口低于 **32k** 时，OpenClaw 会发出警告，并在低于 **16k** 时阻止运行。如果你遇到该预检，请提高服务器/模型上下文限制，或选择更大的模型。 - 上下文错误？降低 `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` 缩减智能体 - 工具表面。 -- 工具调用显示为原始 JSON/XML/ReAct 文本，或者提供商返回 - 空的 `tool_calls` 数组？不要添加会盲目把助手 - 文本转换为工具执行的代理。先修复服务器聊天模板/解析器。如果 - 模型只有在强制使用工具时才能工作，请添加上面的按模型 - `params.extra_body.tool_choice: "required"` 覆盖，并仅在每轮都预期有工具调用的会话中使用该模型 + 如果本地 `model run` 成功但更大的智能体轮次失败，请使用 `localModelLean` + 或 `compat.supportsTools: false` 缩减智能体工具暴露面。 +- 工具调用显示为原始 JSON/XML/ReAct 文本，或提供商返回空的 + `tool_calls` 数组？不要添加一个盲目把助手 + 文本转换为工具执行的代理。先修复服务器聊天模板/解析器。如果该 + 模型只有在强制使用工具时才能工作，请添加上面的按模型配置的 + `params.extra_body.tool_choice: "required"` 覆盖，并且仅在预计每轮都会发生工具调用的会话中使用该模型 条目。 -- 安全：本地模型会跳过提供商侧过滤；保持智能体范围收窄并开启压缩，以限制提示注入的影响范围。 +- 安全性：本地模型会跳过提供商侧过滤器；保持智能体范围收窄并开启压缩，以限制提示注入的影响范围。 -## 相关 +## 相关内容 - [配置参考](/zh-CN/gateway/configuration-reference) - [模型故障转移](/zh-CN/concepts/model-failover) diff --git a/docs/zh-CN/reference/RELEASING.md b/docs/zh-CN/reference/RELEASING.md index aa52908e0..7436e3d69 100644 --- a/docs/zh-CN/reference/RELEASING.md +++ b/docs/zh-CN/reference/RELEASING.md @@ -1,134 +1,124 @@ --- read_when: - 正在查找公开发布渠道定义 - - 运行发布验证或包验收 - - 想了解版本命名和发布节奏 + - 运行发布验证或软件包验收 + - 查找版本命名和发布节奏 summary: 发布通道、操作员检查清单、验证环境、版本命名和节奏 title: 发布策略 x-i18n: - generated_at: "2026-04-29T07:25:55Z" + generated_at: "2026-04-29T10:40:12Z" model: gpt-5.5 provider: openai - source_hash: 84c8dcd13f247b5d136d8a675ce53ef12c68a7f7242d485fe4b55570105ef180 + source_hash: 815c4bffe7930384584533e934996592114af510ebd775fc873086d63c74203f source_path: reference/RELEASING.md workflow: 16 --- OpenClaw 有三个公开发布通道： -- 稳定版：带标签的发布，默认发布到 npm `beta`，或在明确请求时发布到 npm `latest` -- 测试版：发布到 npm `beta` 的预发布标签 -- 开发版：`main` 的移动 HEAD +- stable：带标签的发布版本，默认发布到 npm `beta`，或在明确请求时发布到 npm `latest` +- beta：预发布标签，发布到 npm `beta` +- dev：`main` 的移动头部 ## 版本命名 -- 稳定版发布版本：`YYYY.M.D` +- 稳定发布版本：`YYYY.M.D` - Git 标签：`vYYYY.M.D` -- 稳定版修正发布版本：`YYYY.M.D-N` +- 稳定修正发布版本：`YYYY.M.D-N` - Git 标签：`vYYYY.M.D-N` -- 测试版预发布版本：`YYYY.M.D-beta.N` +- Beta 预发布版本：`YYYY.M.D-beta.N` - Git 标签：`vYYYY.M.D-beta.N` -- 不要给月份或日期补零 -- `latest` 表示当前已提升的稳定版 npm 发布 -- `beta` 表示当前测试版安装目标 -- 稳定版和稳定版修正发布默认发布到 npm `beta`；发布操作员可以明确指定 `latest`，或稍后提升一个已验证的测试版构建 -- 每个稳定版 OpenClaw 发布都会同时交付 npm 包和 macOS 应用； - 测试版发布通常会先验证并发布 npm/包路径，而 mac 应用的构建/签名/公证默认保留给稳定版，除非明确请求 +- 月份或日期不要补零 +- `latest` 表示当前已提升的稳定 npm 发布版本 +- `beta` 表示当前的 beta 安装目标 +- 稳定和稳定修正发布版本默认发布到 npm `beta`；发布操作者可以明确指定 `latest`，或稍后提升一个经过验证的 beta 构建 +- 每个稳定的 OpenClaw 发布版本都会同时交付 npm 包和 macOS 应用； + beta 发布通常先验证并发布 npm/包路径，mac 应用构建/签名/公证默认保留给稳定版本，除非明确请求 ## 发布节奏 -- 发布按测试版优先推进 -- 只有在最新测试版验证通过后，才会发布稳定版 -- 维护者通常从当前 `main` 创建的 `release/YYYY.M.D` 分支切出发布， +- 发布按 beta 优先推进 +- 只有在最新 beta 验证通过后才会进入稳定版本 +- 维护者通常从基于当前 `main` 创建的 `release/YYYY.M.D` 分支切出发布版本， 这样发布验证和修复不会阻塞 `main` 上的新开发 -- 如果测试版标签已经推送或发布后需要修复，维护者会切出下一个 - `-beta.N` 标签，而不是删除或重新创建旧的测试版标签 +- 如果 beta 标签已经推送或发布并且需要修复，维护者会切出下一个 `-beta.N` 标签，而不是删除或重新创建旧的 beta 标签 - 详细的发布流程、审批、凭证和恢复说明仅限维护者使用 -## 发布操作员清单 +## 发布操作者清单 -此清单是发布流程的公开形态。私有凭证、签名、公证、dist-tag 恢复和紧急回滚细节保留在仅限维护者使用的发布运行手册中。 +此清单展示发布流程的公开形态。私有凭证、签名、公证、dist-tag 恢复和紧急回滚细节保留在仅限维护者使用的发布运行手册中。 -1. 从当前 `main` 开始：拉取最新代码，确认目标提交已经推送， - 并确认当前 `main` 的 CI 足够健康，可以从它创建分支。 -2. 使用 `/changelog` 基于真实提交历史重写顶部 `CHANGELOG.md` 章节， - 保持条目面向用户，提交并推送，然后在创建分支前再次 rebase/pull。 -3. 审查 - `src/plugins/compat/registry.ts` 和 - `src/commands/doctor/shared/deprecation-compat.ts` 中的发布兼容性记录。只有在升级路径仍被覆盖时才移除过期兼容性，或记录为什么有意继续保留。 +1. 从当前 `main` 开始：拉取最新内容，确认目标提交已推送，并确认当前 `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. 为目标标签更新每个必需的版本位置，然后运行本地确定性预检： - `pnpm check:test-types`、`pnpm check:architecture`、 - `pnpm build && pnpm ui:build` 和 `pnpm release:check`。 -6. 使用 `preflight_only=true` 运行 `OpenClaw NPM Release`。在标签存在之前， - 可以使用完整的 40 字符发布分支 SHA 进行仅验证预检。保存成功的 `preflight_run_id`。 -7. 针对发布分支、标签或完整提交 SHA，使用 `Full Release Validation` - 启动所有预发布测试。这是四个大型发布测试箱的唯一手动入口点：Vitest、Docker、QA Lab 和 Package。 -8. 如果验证失败，在发布分支上修复，并重新运行能够证明修复的最小失败文件、通道、workflow job、包 profile、提供商或模型 allowlist。只有当变更范围使先前证据失效时，才重新运行完整总括流程。 -9. 对于测试版，标记 `vYYYY.M.D-beta.N`，使用 npm dist-tag `beta` 发布，然后针对已发布的 `openclaw@YYYY.M.D-beta.N` - 或 `openclaw@beta` 包运行发布后包验收。如果已推送或已发布的测试版需要修复，切出下一个 `-beta.N`；不要删除或重写旧测试版。 -10. 对于稳定版，只有在已验证的测试版或发布候选版本具备所需验证证据后才继续。稳定版 npm 发布会通过 `preflight_run_id` 复用成功的预检产物；稳定版 macOS 发布就绪还要求 `main` 上有已打包的 `.zip`、`.dmg`、`.dSYM.zip` 和已更新的 `appcast.xml`。 -11. 发布后，运行 npm 发布后验证器；当需要发布后渠道证明时，可选运行独立的已发布 npm Telegram E2E；在需要时执行 dist-tag 提升；根据完整匹配的 `CHANGELOG.md` 章节生成 GitHub 发布/预发布说明；并执行发布公告步骤。 +5. 为目标标签提升每个必需位置的版本号，然后运行本地确定性预检： + `pnpm check:test-types`、`pnpm check:architecture`、`pnpm build && pnpm ui:build` 和 `pnpm release:check`。 +6. 运行 `OpenClaw NPM Release`，并设置 `preflight_only=true`。在标签存在之前，允许使用完整的 40 字符发布分支 SHA 进行仅验证预检。保存成功的 `preflight_run_id`。 +7. 使用 `Full Release Validation` 为发布分支、标签或完整提交 SHA 启动所有预发布测试。这是四个大型发布测试箱的唯一手动入口点：Vitest、Docker、QA Lab 和 Package。 +8. 如果验证失败，在发布分支上修复，并重新运行能够证明修复的最小失败文件、通道、工作流作业、包配置、提供商或模型允许列表。只有当变更表面使先前证据失效时，才重新运行完整总控流程。 +9. 对于 beta，标记 `vYYYY.M.D-beta.N`，使用 npm dist-tag `beta` 发布，然后针对已发布的 `openclaw@YYYY.M.D-beta.N` 或 `openclaw@beta` 包运行发布后包验收。如果已推送或已发布的 beta 需要修复，切出下一个 `-beta.N`；不要删除或重写旧 beta。 +10. 对于稳定版本，只有在经过验证的 beta 或候选发布版本具备所需验证证据后才继续。稳定 npm 发布通过 `preflight_run_id` 复用成功的预检制品；稳定 macOS 发布就绪还要求打包后的 `.zip`、`.dmg`、`.dSYM.zip` 以及更新后的 `appcast.xml` 位于 `main` 上。 +11. 发布后，运行 npm 发布后验证器；在需要发布后渠道证明时，可选运行独立的已发布 npm Telegram E2E；按需执行 dist-tag 提升；根据完整匹配的 `CHANGELOG.md` 章节生成 GitHub 发布/预发布说明；并执行发布公告步骤。 ## 发布预检 -- 在发布预检前运行 `pnpm check:test-types`，确保测试 TypeScript 在更快的本地 `pnpm check` 门禁之外也有覆盖 -- 在发布预检前运行 `pnpm check:architecture`，确保更广泛的导入循环和架构边界检查在更快的本地门禁之外也为绿色 +- 在发布预检前运行 `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 parity、Matrix 和 Telegram 通道。仅在包已经发布且发布后的 Telegram E2E 也应运行时，才提供 `npm_telegram_package_spec`。当私有证据报告应证明验证匹配已发布的 npm 包，但不强制运行 Telegram E2E 时，提供 `evidence_package_spec`。 - 示例： +- 在发布批准前运行手动 `Full Release Validation` workflow，从一个入口点启动所有预发布测试箱。它接受分支、标签或完整提交 SHA，触发手动 `CI`，并触发 `OpenClaw Release Checks`，覆盖安装冒烟、包验收、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram 通道。仅在包已发布且发布后 Telegram E2E 也应运行时，才提供 `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。 +- 当你想在发布工作继续推进的同时，为包候选版本取得旁路证明时，运行手动 `Package Acceptance` workflow。对 `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`。该 workflow 会将候选项解析为 `package-under-test`，针对该 tarball 复用 Docker E2E 发布调度器，并可通过 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 针对同一 tarball 运行 Telegram QA。 示例：`gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f telegram_mode=mock-openai` 常见配置： - - `smoke`：安装/渠道/智能体、Gateway 网关网络和配置重载通道 - - `package`：不含 OpenWebUI 或 live ClawHub 的产物原生包/更新/插件通道 - - `product`：包配置，加上 MCP 渠道、cron/子智能体清理、OpenAI web 搜索和 OpenWebUI + - `smoke`：安装/渠道/智能体、Gateway 网关网络和配置热重载通道 + - `package`：artifact 原生的包/更新/插件通道，不包含 OpenWebUI 或 live ClawHub + - `product`：包配置加上 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` workflow。手动 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` -- 发布检查现在运行在单独的手动工作流中： +- 验证发布遥测时运行 `pnpm qa:otel:smoke`。它会通过本地 OTLP/HTTP 接收器执行 QA-lab，并验证导出的 trace span 名称、有界属性以及内容/标识符脱敏，不需要 Opik、Langfuse 或其他外部 collector。 +- 每次打标签发布前运行 `pnpm release:check` +- 发布检查现在在单独的手动 workflow 中运行： `OpenClaw Release Checks` -- `OpenClaw Release Checks` 还会在发布审批前运行 QA Lab mock parity 门禁，以及快速 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`/release 工作流 ref 派发，以便工作流逻辑和密钥保持受控 -- `OpenClaw Release Checks` 接受分支、标签或完整提交 SHA，前提是解析出的提交可从 OpenClaw 分支或发布标签访问 -- `OpenClaw NPM Release` 仅验证预检也接受当前完整的 40 字符工作流分支提交 SHA，而无需已推送的标签 -- 该 SHA 路径仅用于验证，不能提升为真实发布 -- 在 SHA 模式下，工作流只为包元数据检查合成 `v`；真实发布仍需要真实发布标签 -- 两个工作流都将真实发布和提升路径保留在 GitHub 托管 runner 上，而非变更性验证路径可以使用更大的 Blacksmith Linux runner -- 该工作流使用 `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` 运行，并同时使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 工作流密钥 +- `OpenClaw Release Checks` 还会在发布批准前运行 QA Lab mock parity 门禁，以及快速 live Matrix 配置和 Telegram QA 通道。live 通道使用 `qa-live-shared` 环境；Telegram 还使用 Convex CI 凭证租约。当你想并行运行完整 Matrix 传输、媒体和 E2EE 清单时，用 `matrix_profile=all` 和 `matrix_shards=true` 运行手动 `QA-Lab - All Lanes` workflow。 +- 跨 OS 安装和升级运行时验证是公开 `OpenClaw Release Checks` 和 `Full Release Validation` 的一部分，它们会直接调用可复用 workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` +- 这种拆分是有意的：让真正的 npm 发布路径保持短小、确定且聚焦产物，同时较慢的 live 检查保留在自己的通道中，避免拖慢或阻塞发布 +- 带有 secret 的发布检查应通过 `Full Release Validation` 触发，或从 `main`/release workflow ref 触发，以便 workflow 逻辑和 secret 保持受控 +- `OpenClaw Release Checks` 接受分支、标签或完整提交 SHA，只要解析出的提交可从 OpenClaw 分支或发布标签到达 +- `OpenClaw NPM Release` 的仅验证预检也接受当前 workflow 分支的完整 40 字符提交 SHA，不要求已推送标签 +- 该 SHA 路径仅用于验证，不能提升为真正发布 +- 在 SHA 模式下，workflow 只会为包元数据检查合成 `v`；真正发布仍然需要真实发布标签 +- 两个 workflow 都将真正发布和提升路径保留在 GitHub 托管 runner 上，而非变更性的验证路径可以使用更大的 Blacksmith Linux runner +- 该 workflow 使用 `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` 运行，并同时使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` workflow 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 发布 +- 在批准前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`（或匹配的 beta/correction 标签） +- npm 发布后，运行 `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（或匹配的 beta/correction 版本），在新的临时前缀中验证已发布注册表安装路径 +- 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` workflow，从 GitHub Actions 运行相同的发布后检查。它有意仅限手动，不会在每次合并时运行。 +- 维护者发布自动化现在使用先预检后提升： + - 真正的 npm 发布必须通过一次成功的 npm `preflight_run_id` + - 真正的 npm 发布必须从与成功预检运行相同的 `main` 或 `release/YYYY.M.D` 分支触发 + - stable npm 发布默认使用 `beta` + - stable npm 发布可通过 workflow 输入显式指向 `latest` + - 基于 token 的 npm dist-tag 变更现在位于 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`，出于安全原因，因为 `npm dist-tag add` 仍然需要 `NPM_TOKEN`，而公开仓库保持仅 OIDC 发布 - 公开 `macOS Release` 仅用于验证 - - 真实私有 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，避免再次发布空的浏览器仪表盘 -- 发布后验证还会检查已发布注册表安装是否在根 `dist/*` 布局下包含非空的内置插件运行时依赖。发布版本如果缺失或带有空的内置插件依赖 payload，会导致发布后验证器失败，且不能提升到 `latest`。 -- `pnpm test:install:smoke` 还会对候选更新 tarball 强制执行 npm pack `unpackedSize` 预算，因此安装器 e2e 能在发布路径前捕获意外的打包膨胀 -- 如果发布工作触及 CI 规划、插件 timing manifest 或插件测试矩阵，请在审批前重新生成并审阅 `.github/workflows/plugin-prerelease.yml` 中由规划器拥有的 `plugin-prerelease-extension-shard` 矩阵输出，确保发布说明不会描述过时的 CI 布局 -- 稳定 macOS 发布就绪性还包括更新器表面： + - 真正的私有 mac 发布必须通过成功的私有 mac `preflight_run_id` 和 `validate_run_id` + - 真正发布路径会提升已准备好的产物，而不是再次重建它们 +- 对于 `YYYY.M.D-N` 这样的 stable correction 发布，发布后验证器还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的同一临时前缀升级路径，确保发布修正不会静默地让旧版全局安装停留在基础 stable payload 上 +- npm 发布预检默认失败，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` payload，以避免再次发布空的浏览器仪表盘 +- 发布后验证还会检查已发布注册表安装是否在根 `dist/*` 布局下包含非空的内置插件运行时依赖。若发布缺失或包含空的内置插件依赖 payload，发布后验证器会失败，且不能提升到 `latest`。 +- `pnpm test:install:smoke` 也会对候选更新 tarball 强制执行 npm pack `unpackedSize` 预算，因此 installer e2e 会在发布路径前捕获意外的包体积膨胀 +- 如果发布工作涉及 CI 规划、插件时序清单或插件测试矩阵，请在批准前重新生成并审查 `.github/workflows/plugin-prerelease.yml` 中 planner 拥有的 `plugin-prerelease-extension-shard` 矩阵输出，确保发布说明不会描述过时的 CI 布局 +- stable macOS 发布就绪性还包括 updater 表面： - GitHub 发布最终必须包含打包的 `.zip`、`.dmg` 和 `.dSYM.zip` - - 发布后，`main` 上的 `appcast.xml` 必须指向新的稳定 zip - - 打包应用必须保留非调试 bundle id、非空 Sparkle feed URL，以及等于或高于该发布版本规范 Sparkle 构建下限的 `CFBundleVersion` + - 发布后，`main` 上的 `appcast.xml` 必须指向新的 stable zip + - 打包后的 app 必须保留非 debug bundle id、非空 Sparkle feed URL，以及不低于该发布版本 canonical Sparkle 构建下限的 `CFBundleVersion` ## 发布测试箱 -`Full Release Validation` 是操作员从一个入口点启动所有预发布测试的方式。请从可信的 `main` 工作流 ref 运行它，并将发布分支、标签或完整提交 SHA 作为 `ref` 传入： +`Full Release Validation` 是操作者从一个入口点启动所有预发布测试的方式。从可信的 `main` workflow ref 运行它，并将发布分支、标签或完整提交 SHA 作为 `ref` 传入： ```bash gh workflow run full-release-validation.yml \ @@ -140,21 +130,21 @@ gh workflow run full-release-validation.yml \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -该工作流会解析目标 ref，使用 `target_ref=` 派发手动 `CI`，派发 `OpenClaw Release Checks`，并在设置了 `npm_telegram_package_spec` 时可选地派发独立的发布后 Telegram E2E。随后 `OpenClaw Release Checks` 会展开安装冒烟、跨操作系统发布检查、live/E2E Docker 发布路径覆盖、带 Telegram 包 QA 的 Package Acceptance、QA Lab parity、live Matrix 和 live Telegram。只有当 `Full Release Validation` 摘要显示 `normal_ci` 和 `release_checks` 成功，且任何可选的 `npm_telegram` 子项成功或被有意跳过时，完整运行才可接受。最终验证器摘要包含每个子运行的最慢作业表，因此发布经理无需下载日志也能看到当前关键路径。 -子工作流从运行 `Full Release Validation` 的可信 ref 派发，通常是 `--ref main`，即使目标 `ref` 指向较旧的发布分支或标签。不存在单独的 Full Release Validation 工作流 ref 输入；通过选择工作流运行 ref 来选择可信 harness。 +该 workflow 解析目标 ref，使用 `target_ref=` 触发手动 `CI`，触发 `OpenClaw Release Checks`，并在设置 `npm_telegram_package_spec` 时可选地触发独立的发布后 Telegram E2E。随后 `OpenClaw Release Checks` 会扩展运行安装冒烟、跨 OS 发布检查、live/E2E Docker 发布路径覆盖、带 Telegram 包 QA 的 Package Acceptance、QA Lab parity、live Matrix 和 live Telegram。只有当 `Full Release Validation` 摘要显示 `normal_ci` 和 `release_checks` 成功，且任何可选的 `npm_telegram` 子项成功或有意跳过时，完整运行才可接受。最终验证器摘要包含每个子运行的最慢 job 表，因此发布经理无需下载日志即可看到当前关键路径。 +子 workflow 从运行 `Full Release Validation` 的可信 ref 触发，通常是 `--ref main`，即使目标 `ref` 指向较旧的发布分支或标签。没有单独的 Full Release Validation workflow-ref 输入；通过选择 workflow 运行 ref 来选择可信 harness。 -使用 `release_profile` 选择 live/提供商覆盖范围： +使用 `release_profile` 选择 live/provider 覆盖范围： -- `minimum`：最快的发布关键 OpenAI/核心 live 和 Docker 路径 -- `stable`：minimum 加上用于发布审批的稳定提供商/后端覆盖 -- `full`：stable 加上广泛的 advisory 提供商/媒体覆盖 +- `minimum`：最快的发布关键 OpenAI/core live 和 Docker 路径 +- `stable`：minimum 加上用于发布批准的 stable provider/backend 覆盖 +- `full`：stable 加上广泛的 advisory provider/media 覆盖 -`OpenClaw Release Checks` 使用可信工作流 ref 将目标 ref 解析一次为 `release-package-under-test`，并在发布路径 Docker 检查和 Package Acceptance 中复用该产物。这会让所有面向包的测试箱使用相同字节，并避免重复构建包。 +`OpenClaw Release Checks` 使用可信 workflow ref 将目标 ref 解析一次为 `release-package-under-test`，并在发布路径 Docker 检查和 Package Acceptance 中复用该 artifact。这会让所有面向包的测试箱使用相同字节，并避免重复构建包。 根据发布阶段使用这些变体： ```bash -# 验证未发布的发布候选分支。 +# Validate an unpublished release candidate branch. gh workflow run full-release-validation.yml \ --ref main \ -f ref=release/YYYY.M.D \ @@ -162,14 +152,14 @@ gh workflow run full-release-validation.yml \ -f mode=both \ -f release_profile=stable -# 验证精确的已推送提交。 +# Validate an exact pushed commit. gh workflow run full-release-validation.yml \ --ref main \ -f ref=<40-char-sha> \ -f provider=openai \ -f mode=both -# 发布 beta 后，加入已发布包 Telegram E2E。 +# After publishing a beta, add published-package Telegram E2E. gh workflow run full-release-validation.yml \ --ref main \ -f ref=release/YYYY.M.D \ @@ -180,33 +170,22 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -不要在聚焦修复后的第一次重跑中使用完整总控流程。如果某个 box -失败，请使用失败的子工作流、job、Docker lane、package profile、模型 -提供商或 QA lane 作为下一次验证。只有当修复更改了共享发布编排，或让早前的全 box 证据 -失效时，才再次运行完整总控流程。总控流程的最终验证器会重新检查已记录的子工作流运行 -ID，因此在子工作流成功重跑后，只重跑失败的 -`Verify full validation` 父 job。 +不要在聚焦修复后的第一次重跑中使用完整总流程。如果一个盒子失败，请使用失败的子工作流、作业、Docker 通道、包配置、模型提供商或 QA 通道作为下一次证明。只有当修复更改了共享发布编排，或使之前的所有盒子证据过期时，才再次运行完整总流程。总流程的最终验证器会重新检查记录的子工作流运行 ID，因此在子工作流成功重跑后，只需重跑失败的 `Verify full validation` 父作业。 -对于有界恢复，请向总控流程传递 `rerun_group`。`all` 是真正的 -候选发布运行，`ci` 只运行常规 CI 子流程，`plugin-prerelease` -只运行仅发布使用的插件子流程，`release-checks` 运行每个发布 -box，更窄的发布分组包括 `install-smoke`、`cross-os`、 -`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`，以及在提供 -独立 package Telegram lane 时使用的 `npm-telegram`。 +对于有界恢复，请向总流程传入 `rerun_group`。`all` 是真正的发布候选运行，`ci` 只运行常规 CI 子项，`plugin-prerelease` 只运行仅发布用的插件子项，`release-checks` 运行每个发布盒子，更窄的发布组包括 `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`，以及在提供独立包 Telegram 通道时的 `npm-telegram`。 ### Vitest -Vitest box 是手动 `CI` 子工作流。手动 CI 有意绕过变更范围限定，并为候选发布强制运行常规测试图：Linux Node shards、内置插件 shards、渠道 contracts、Node 22 兼容性、`check`、`check-additional`、构建 smoke、文档检查、Python skills、Windows、macOS、Android 和 Control UI i18n。 +Vitest 盒子是手动 `CI` 子工作流。手动 CI 会有意绕过变更范围限定，并为发布候选强制运行常规测试图：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建烟雾测试、文档检查、Python Skills、Windows、macOS、Android，以及 Control UI i18n。 -使用这个 box 回答“源代码树是否通过了完整的常规测试套件？” -它不同于发布路径的产品验证。需要保留的证据： +使用这个盒子来回答“源代码树是否通过了完整的常规测试套件？”它不同于发布路径的产品验证。需要保留的证据： -- `Full Release Validation` 摘要，其中显示已调度的 `CI` 运行 URL -- `CI` 在精确目标 SHA 上为绿色 -- 调查回归时，来自 CI jobs 的失败或较慢 shard 名称 -- 当某次运行需要性能分析时，保留 Vitest 计时工件，例如 `.artifacts/vitest-shard-timings.json` +- 显示已派发 `CI` 运行 URL 的 `Full Release Validation` 摘要 +- 精确目标 SHA 上绿色通过的 `CI` 运行 +- 调查回归时来自 CI 作业的失败或较慢分片名称 +- 当某次运行需要性能分析时，保留 `.artifacts/vitest-shard-timings.json` 等 Vitest 计时产物 -只有当发布需要确定性的常规 CI，但不需要 Docker、QA Lab、live、cross-OS 或 package box 时，才直接运行手动 CI： +只有当发布需要确定性的常规 CI，但不需要 Docker、QA Lab、实时、跨 OS 或包盒子时，才直接运行手动 CI： ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -214,73 +193,49 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker -Docker box 位于 `OpenClaw Release Checks` 中，通过 -`openclaw-live-and-e2e-checks-reusable.yml` 提供，并包含发布模式的 -`install-smoke` 工作流。它通过打包后的 Docker 环境验证候选发布，而不是只做源代码级测试。 +Docker 盒子通过 `openclaw-live-and-e2e-checks-reusable.yml` 位于 `OpenClaw Release Checks` 中，另外还包括发布模式的 `install-smoke` 工作流。它通过打包后的 Docker 环境验证发布候选，而不只是源码级测试。 发布 Docker 覆盖范围包括： -- 启用较慢 Bun 全局安装 smoke 的完整安装 smoke -- 仓库 E2E lanes -- 发布路径 Docker chunks：`core`、`package-update-openai`、 - `package-update-anthropic`、`package-update-core`、`plugins-runtime-core`、 - `plugins-runtime-install-a`、`plugins-runtime-install-b`、 - `bundled-channels-core`、`bundled-channels-update-a`、 - `bundled-channels-update-b` 和 `bundled-channels-contracts` -- 请求时，在 `plugins-runtime-core` chunk 中覆盖 OpenWebUI -- 将内置渠道依赖 lanes 拆分到 channel-smoke、update-target - 和 setup/runtime contract chunks，而不是一个大型 bundled-channel job -- 拆分内置插件安装/卸载 lanes - `bundled-plugin-install-uninstall-0` 到 - `bundled-plugin-install-uninstall-7` -- 当发布检查包含 live suites 时，覆盖 live/E2E 提供商套件和 Docker live 模型 +- 启用较慢 Bun 全局安装烟雾测试的完整安装烟雾测试 +- 仓库 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-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`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-discord`、`bundled-channels-update-b` 和 `bundled-channels-contracts` +- 请求时，`plugins-runtime-services` 分块内的 OpenWebUI 覆盖 +- 将内置渠道依赖通道拆分到 channel-smoke、update-target 和 setup/runtime 契约分块，而不是一个大型内置渠道作业 +- 拆分内置插件安装/卸载通道 `bundled-plugin-install-uninstall-0` 到 `bundled-plugin-install-uninstall-23` +- 当发布检查包含实时套件时，包含实时/E2E 提供商套件和 Docker 实时模型覆盖 -重跑前先使用 Docker 工件。发布路径调度器会上传 -`.artifacts/docker-tests/`，其中包含 lane 日志、`summary.json`、`failures.json`、 -阶段计时、调度器计划 JSON 和重跑命令。对于聚焦恢复，在可复用 live/E2E 工作流上使用 -`docker_lanes=`，而不是重跑所有发布 chunks。生成的重跑命令会在可用时包含之前的 -`package_artifact_run_id` 和已准备好的 Docker 镜像输入，因此失败的 lane 可以复用同一个 tarball 和 GHCR 镜像。 +重跑前先使用 Docker 产物。发布路径调度器会上传 `.artifacts/docker-tests/`，其中包含通道日志、`summary.json`、`failures.json`、阶段计时、调度器计划 JSON 和重跑命令。对于聚焦恢复，请在可复用实时/E2E 工作流上使用 `docker_lanes=`，而不是重跑所有发布分块。生成的重跑命令会在可用时包含之前的 `package_artifact_run_id` 和已准备的 Docker 镜像输入，因此失败通道可以复用同一个 tarball 和 GHCR 镜像。 ### QA Lab -QA Lab box 也是 `OpenClaw Release Checks` 的一部分。它是 agentic -行为和渠道级发布门禁，独立于 Vitest 和 Docker package 机制。 +QA Lab 盒子也是 `OpenClaw Release Checks` 的一部分。它是智能体行为和渠道级发布门禁，独立于 Vitest 和 Docker 包机制。 发布 QA Lab 覆盖范围包括： -- 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` +- 使用智能体对等包，将 OpenAI 候选通道与 Opus 4.6 基线进行比较的模拟对等门禁 +- 使用 `qa-live-shared` 环境的快速实时 Matrix QA 配置 +- 使用 Convex CI 凭证租约的实时 Telegram QA 通道 +- 当发布遥测需要明确本地证明时运行 `pnpm qa:otel:smoke` -使用这个 box 回答“该发布在 QA 场景和 live 渠道流程中是否行为正确？” -批准发布时，请保留 parity、Matrix 和 Telegram lanes 的工件 URL。完整 Matrix 覆盖仍可作为手动分片 QA-Lab 运行提供，而不是默认的发布关键 lane。 +使用这个盒子来回答“发布在 QA 场景和实时渠道流程中的行为是否正确？”批准发布时，请保留对等、Matrix 和 Telegram 通道的产物 URL。完整 Matrix 覆盖仍可作为手动分片 QA-Lab 运行使用，而不是默认的发布关键通道。 -### Package +### 包 -Package box 是可安装产品门禁。它由 -`Package Acceptance` 和解析器 -`scripts/resolve-openclaw-package-candidate.mjs` 支撑。解析器会将候选项规范化为 Docker E2E 消费的 `package-under-test` tarball，验证 package 清单，记录 package 版本和 SHA-256，并将工作流 harness ref 与 package source ref 分开。 +包盒子是可安装产品门禁。它由 `Package Acceptance` 和解析器 `scripts/resolve-openclaw-package-candidate.mjs` 支撑。解析器会将候选规范化为 Docker E2E 使用的 `package-under-test` tarball，验证包清单，记录包版本和 SHA-256，并将工作流 harness ref 与包源码 ref 分开。 支持的候选来源： - `source=npm`：`openclaw@beta`、`openclaw@latest`，或精确的 OpenClaw 发布版本 -- `source=ref`：使用所选 `workflow_ref` harness 打包受信任的 `package_ref` 分支、tag 或完整 commit SHA -- `source=url`：下载 HTTPS `.tgz`，并要求提供 `package_sha256` +- `source=ref`：用所选 `workflow_ref` harness 打包可信的 `package_ref` 分支、标签或完整提交 SHA +- `source=url`：下载带有必需 `package_sha256` 的 HTTPS `.tgz` - `source=artifact`：复用另一个 GitHub Actions 运行上传的 `.tgz` -`OpenClaw Release Checks` 使用 `source=ref`、 -`package_ref=`、`suite_profile=custom`、 -`docker_lanes=bundled-channel-deps-compat plugins-offline` 和 -`telegram_mode=mock-openai` 运行 Package Acceptance。发布路径 Docker chunks 覆盖重叠的安装、更新和 plugin-update lanes；Package Acceptance 针对同一个已解析 tarball 保留工件原生的内置渠道兼容性、离线插件 fixtures 和 Telegram package QA。它是 GitHub 原生替代方案，用于取代过去大多数需要 Parallels 的 package/update 覆盖。Cross-OS 发布检查对于特定操作系统的新手引导、安装器和平台行为仍然重要，但 package/update 产品验证应优先使用 Package Acceptance。 +`OpenClaw Release Checks` 会以 `source=ref`、`package_ref=`、`suite_profile=custom`、`docker_lanes=bundled-channel-deps-compat plugins-offline` 和 `telegram_mode=mock-openai` 运行 Package Acceptance。发布路径 Docker 分块覆盖重叠的安装、更新和插件更新通道；Package Acceptance 则针对同一个已解析 tarball 保留产物原生的内置渠道兼容性、离线插件 fixture，以及 Telegram 包 QA。它是以前大多数需要 Parallels 的包/更新覆盖的 GitHub 原生替代方案。跨 OS 发布检查对 OS 特定的新手引导、安装器和平台行为仍然重要，但包/更新产品验证应优先使用 Package Acceptance。 -旧版 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 contract；同样的缺口会导致发布验证失败。 +旧版 package-acceptance 宽容路径被有意限定在时间范围内。到 `2026.4.25` 为止的包可以对已经发布到 npm 的元数据缺口使用兼容路径：tarball 中缺失的私有 QA 清单条目、缺失的 `gateway install --wrapper`、tarball 派生 git fixture 中缺失的补丁文件、缺失的持久化 `update.channel`、旧版插件安装记录位置、缺失的 marketplace 安装记录持久化，以及 `plugins update` 期间的配置元数据迁移。已发布的 `2026.4.26` 包可以对已经发布的本地构建元数据戳文件发出警告。之后的包必须满足现代包契约；这些相同缺口会导致发布验证失败。 -当发布问题涉及实际可安装 package 时，使用更广的 Package Acceptance profile： +当发布问题涉及实际可安装包时，使用更广泛的 Package Acceptance 配置： ```bash gh workflow run package-acceptance.yml \ @@ -291,77 +246,58 @@ gh workflow run package-acceptance.yml \ -f suite_profile=product ``` -常见 package profiles： +常见包配置： -- `smoke`：快速 package 安装/channel/agent、Gateway 网关网络和配置重载 lanes -- `package`：不含 live ClawHub 的安装/更新/插件 package contracts；这是 release-check 的默认值 -- `product`：`package` 加上 MCP channels、cron/subagent 清理、OpenAI web - search 和 OpenWebUI -- `full`：包含 OpenWebUI 的 Docker 发布路径 chunks +- `smoke`：快速包安装/渠道/智能体、Gateway 网关网络和配置重载通道 +- `package`：不带实时 ClawHub 的安装/更新/插件包契约；这是 release-check 默认值 +- `product`：`package` 加上 MCP 渠道、cron/subagent 清理、OpenAI web 搜索和 OpenWebUI +- `full`：带 OpenWebUI 的 Docker 发布路径分块 - `custom`：用于聚焦重跑的精确 `docker_lanes` 列表 -对于 package-candidate Telegram 证据，请在 Package Acceptance 上启用 -`telegram_mode=mock-openai` 或 -`telegram_mode=live-frontier`。该工作流会将已解析的 `package-under-test` tarball 传入 Telegram lane；独立 Telegram 工作流仍接受已发布的 npm spec，用于发布后检查。 +对于包候选 Telegram 证明，请在 Package Acceptance 上启用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier`。该工作流会将解析后的 `package-under-test` tarball 传入 Telegram 通道；独立 Telegram 工作流仍接受已发布的 npm 规格，用于发布后检查。 ## NPM 工作流输入 -`OpenClaw NPM Release` 接受以下由操作者控制的输入： +`OpenClaw NPM Release` 接受这些由操作员控制的输入： -- `tag`：必填发布 tag，例如 `v2026.4.2`、`v2026.4.2-1` 或 - `v2026.4.2-beta.1`；当 `preflight_only=true` 时，它也可以是当前 - 完整 40 字符工作流分支 commit SHA，用于仅验证的预检 -- `preflight_only`：`true` 表示仅验证/构建/package，`false` 表示真正的发布路径 -- `preflight_run_id`：真正发布路径必填，这样工作流可以复用成功预检运行准备好的 tarball -- `npm_dist_tag`：发布路径的 npm 目标 tag；默认为 `beta` +- `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 +- `npm_dist_tag`：发布路径的 npm 目标标签；默认为 `beta` -`OpenClaw Release Checks` 接受以下由操作者控制的输入： +`OpenClaw Release Checks` 接受这些由操作员控制的输入： -- `ref`：要验证的分支、tag 或完整 commit SHA。带有密钥的检查要求解析后的 commit 可从 OpenClaw 分支或发布 tag 访问。 +- `ref`：要验证的分支、标签或完整提交 SHA。带密钥的检查要求解析后的提交可从 OpenClaw 分支或发布标签访问。 规则： -- Stable 和 correction tags 可以发布到 `beta` 或 `latest` -- Beta prerelease tags 只能发布到 `beta` -- 对于 `OpenClaw NPM Release`，只有在 - `preflight_only=true` 时才允许输入完整 commit SHA +- 稳定版和修正版标签可以发布到 `beta` 或 `latest` +- Beta 预发布标签只能发布到 `beta` +- 对于 `OpenClaw NPM Release`，只有在 `preflight_only=true` 时才允许完整提交 SHA 输入 - `OpenClaw Release Checks` 和 `Full Release Validation` 始终仅用于验证 -- 真正发布路径必须使用预检期间使用的同一个 `npm_dist_tag`； - 工作流会在继续发布前验证该元数据 +- 真实发布路径必须使用预检期间使用的同一个 `npm_dist_tag`；工作流会在发布继续之前验证该元数据 -## Stable npm 发布流程 +## 稳定版 npm 发布流程 -切 stable npm 发布时： +切稳定版 npm 发布时： -1. 运行 `OpenClaw NPM Release`，并设置 `preflight_only=true` - - 在 tag 存在之前，你可以使用当前完整工作流分支 commit - SHA 对预检工作流做仅验证 dry run -2. 对于常规 beta-first 流程，选择 `npm_dist_tag=beta`；只有在你有意直接发布 stable 时，才选择 `latest` -3. 当你想通过一个手动工作流获得常规 CI 加 live prompt cache、Docker、QA Lab、 - Matrix 和 Telegram 覆盖时，在发布分支、发布 tag 或完整 - commit SHA 上运行 `Full Release Validation` -4. 如果你有意只需要确定性的常规测试图，请改为在 release ref 上运行手动 - `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. 如果你明确只需要确定性的常规测试图，请改为在发布 ref 上运行手动 `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` - 工作流将该 stable 版本从 `beta` 提升到 `latest` -8. 如果发布有意直接发布到 `latest`，并且 `beta` - 应立即跟随同一个 stable build，请使用同一个私有 - 工作流将两个 dist-tags 指向该 stable 版本，或让它的定时 - 自修复同步稍后移动 `beta` +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-tags 都指向该稳定版本，或让它的定时自愈同步稍后移动 `beta` -dist-tag 变更位于私有仓库中是出于安全原因，因为它仍需要 -`NPM_TOKEN`，而公共仓库保持仅使用 OIDC 发布。 +dist-tag 变更位于私有仓库中是出于安全原因，因为它仍然需要 `NPM_TOKEN`，而公开仓库保持仅 OIDC 发布。 -这样可以让直接发布路径和 beta-first 提升路径都得到文档化，并且对操作者可见。 +这会让直接发布路径和先 beta 后提升路径都保持文档化，并对操作员可见。 -如果维护者必须回退到本地 npm 认证，请只在专用 tmux 会话中运行任何 1Password -CLI（`op`）命令。不要从主 agent shell 直接调用 `op`；将它放在 tmux 中可让提示、警报和 OTP 处理保持可观察，并避免重复的主机警报。 +如果维护者必须回退到本地 npm 身份验证，请只在专用 tmux 会话内运行任何 1Password CLI（`op`）命令。不要直接从主智能体 shell 调用 `op`；把它放在 tmux 内可以让提示、警报和 OTP 处理可观察，并防止重复的主机警报。 -## 公共参考 +## 公开参考资料 - [`.github/workflows/full-release-validation.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/full-release-validation.yml) - [`.github/workflows/package-acceptance.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/package-acceptance.yml) @@ -377,6 +313,6 @@ CLI（`op`）命令。不要从主 agent shell 直接调用 `op`；将它放在 [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) 中的私有发布文档作为实际运行手册。 -## 相关 +## 相关内容 - [发布渠道](/zh-CN/install/development-channels) diff --git a/docs/zh-CN/tools/thinking.md b/docs/zh-CN/tools/thinking.md index 2f612b877..7e52e6aa3 100644 --- a/docs/zh-CN/tools/thinking.md +++ b/docs/zh-CN/tools/thinking.md @@ -1,58 +1,59 @@ --- read_when: - - 调整思考、快速模式或详细模式的指令解析或默认值 -summary: '`/think`、`/fast`、`/verbose`、`/trace` 的指令语法以及推理可见性' + - 调整 thinking、fast-mode 或 verbose 指令的解析或默认值 +summary: 用于 /think、/fast、/verbose、/trace 的指令语法和推理可见性 title: 思考级别 x-i18n: - generated_at: "2026-04-27T13:32:07Z" - model: gpt-5.4 + generated_at: "2026-04-29T10:39:56Z" + model: gpt-5.5 provider: openai - source_hash: 0d79dc5a84bb2e695fafb6f2298aabf253126dc20d474bc64ca19a7fe6ac5454 + source_hash: e9fabead8d2f58fc5bce3bf8b281ad9d52da2cd02ba2777bc1597359537b7705 source_path: tools/thinking.md - workflow: 15 + workflow: 16 --- -## 它的作用 +## 作用 -- 任何入站消息体中的内联指令：`/t `、`/think:` 或 `/thinking `。 +- 任意入站正文中的内联指令：`/t `、`/think:` 或 `/thinking `。 - 级别（别名）：`off | minimal | low | medium | high | xhigh | adaptive | max` - - minimal → “思考” - - low → “深入思考” - - medium → “更深入思考” - - high → “超强思考”（最大预算） - - xhigh → “超强思考+”（GPT-5.2+ 和 Codex 模型，以及 Anthropic Claude Opus 4.7 effort） - - adaptive → 提供商管理的自适应思考（Anthropic/Bedrock 上的 Claude 4.6、Anthropic Claude Opus 4.7，以及 Google Gemini 动态思考支持此模式） - - max → 提供商最大推理（Anthropic Claude Opus 4.7；Ollama 会将其映射到其最高原生 `think` effort） - - `x-high`、`x_high`、`extra-high`、`extra high` 和 `extra_high` 都会映射到 `xhigh`。 - - `highest` 会映射到 `high`。 + - minimal → “think” + - low → “think hard” + - medium → “think harder” + - high → “ultrathink”（最大预算） + - xhigh → “ultrathink+”（GPT-5.2+ 和 Codex 模型，以及 Anthropic Claude Opus 4.7 effort） + - adaptive → 由提供商管理的自适应思考（支持 Anthropic/Bedrock 上的 Claude 4.6、Anthropic Claude Opus 4.7，以及 Google Gemini 动态思考） + - max → 提供商最大推理（Anthropic Claude Opus 4.7；Ollama 会将其映射到最高原生 `think` effort） + - `x-high`、`x_high`、`extra-high`、`extra high` 和 `extra_high` 映射到 `xhigh`。 + - `highest` 映射到 `high`。 - 提供商说明： - - 思考菜单和选择器由提供商配置文件驱动。提供商插件会为所选模型声明精确支持的级别集合，包括像二元 `on` 这样的标签。 - - 只有支持这些级别的提供商 / 模型配置文件才会声明 `adaptive`、`xhigh` 和 `max`。如果输入的指令级别不受支持，则会拒绝，并返回该模型的有效选项。 - - 已存储但不受支持的旧级别会按提供商配置文件等级重新映射。`adaptive` 在非自适应模型上会回退到 `medium`，而 `xhigh` 和 `max` 会回退到所选模型支持的最高非 `off` 级别。 - - 当未显式设置思考级别时，Anthropic Claude 4.6 模型默认使用 `adaptive`。 - - Anthropic Claude Opus 4.7 默认不使用自适应思考。除非你显式设置思考级别，否则它的 API effort 默认值仍由提供商决定。 - - Anthropic Claude Opus 4.7 会将 `/think xhigh` 映射为自适应思考加 `output_config.effort: "xhigh"`，因为 `/think` 是思考指令，而 `xhigh` 是 Opus 4.7 的 effort 设置。 - - Anthropic Claude Opus 4.7 还支持 `/think max`；它会映射到同一条由提供商控制的最大 effort 路径。 - - 支持思考的 Ollama 模型会暴露 `/think low|medium|high|max`；`max` 会映射到原生 `think: "high"`，因为 Ollama 的原生 API 接受 `low`、`medium` 和 `high` 这几个 effort 字符串。 - - OpenAI GPT 模型会通过特定模型支持的 Responses API effort 能力来映射 `/think`。`/think off` 只有在目标模型支持时才会发送 `reasoning.effort: "none"`；否则 OpenClaw 会省略禁用推理的 payload，而不是发送不受支持的值。 - - 过时的已配置 OpenRouter Hunter Alpha 引用会跳过代理推理注入，因为该已退役路由可能会通过推理字段返回最终答案文本。 - - Google Gemini 会将 `/think adaptive` 映射到 Gemini 由提供商控制的动态思考。Gemini 3 请求会省略固定的 `thinkingLevel`，而 Gemini 2.5 请求会发送 `thinkingBudget: -1`；固定级别仍会映射到该模型家族最接近的 Gemini `thinkingLevel` 或 budget。 - - Anthropic 兼容流式路径上的 MiniMax（`minimax/*`）默认使用 `thinking: { type: "disabled" }`，除非你在模型参数或请求参数中显式设置思考。这可避免 MiniMax 的非原生 Anthropic 流格式泄露 `reasoning_content` 增量。 + - 思考菜单和选择器由提供商配置档案驱动。提供商插件会为所选模型声明准确的级别集合，包括二元 `on` 等标签。 + - `adaptive`、`xhigh` 和 `max` 只会为支持它们的提供商/模型配置档案展示。针对不支持级别的类型化指令会被拒绝，并返回该模型的有效选项。 + - 已存储的现有不支持级别会按提供商配置档案排名重新映射。`adaptive` 在非自适应模型上回退到 `medium`，而 `xhigh` 和 `max` 会回退到所选模型支持的最大非 off 级别。 + - Anthropic Claude 4.6 模型在未显式设置思考级别时默认为 `adaptive`。 + - Anthropic Claude Opus 4.7 不默认使用自适应思考。除非你显式设置思考级别，否则它的 API effort 默认值仍由提供商拥有。 + - Anthropic Claude Opus 4.7 会将 `/think xhigh` 映射到自适应思考加 `output_config.effort: "xhigh"`，因为 `/think` 是思考指令，而 `xhigh` 是 Opus 4.7 的 effort 设置。 + - Anthropic Claude Opus 4.7 也暴露 `/think max`；它映射到同一个提供商拥有的最大 effort 路径。 + - 支持思考的 Ollama 模型会暴露 `/think low|medium|high|max`；`max` 映射到原生 `think: "high"`，因为 Ollama 的原生 API 接受 `low`、`medium` 和 `high` effort 字符串。 + - OpenAI GPT 模型会通过模型特定的 Responses API effort 支持来映射 `/think`。只有当目标模型支持时，`/think off` 才会发送 `reasoning.effort: "none"`；否则 OpenClaw 会省略已禁用的推理载荷，而不是发送不支持的值。 + - 自定义 OpenAI 兼容目录条目可以通过将 `models.providers..models[].compat.supportedReasoningEfforts` 设置为包含 `"xhigh"` 来选择加入 `/think xhigh`。这会使用与出站 OpenAI 推理 effort 载荷映射相同的兼容元数据，因此菜单、会话验证、智能体 CLI 和 `llm-task` 会与传输行为保持一致。 + - 陈旧配置的 OpenRouter Hunter Alpha 引用会跳过代理推理注入，因为那条已退役路由可能会通过推理字段返回最终答案文本。 + - Google Gemini 会将 `/think adaptive` 映射到 Gemini 的提供商拥有的动态思考。Gemini 3 请求会省略固定的 `thinkingLevel`，而 Gemini 2.5 请求会发送 `thinkingBudget: -1`；固定级别仍会映射到该模型系列最接近的 Gemini `thinkingLevel` 或预算。 + - Anthropic 兼容流式传输路径上的 MiniMax（`minimax/*`）默认为 `thinking: { type: "disabled" }`，除非你在模型参数或请求参数中显式设置思考。这可避免 MiniMax 非原生 Anthropic 流格式泄露 `reasoning_content` 增量。 - Z.AI（`zai/*`）只支持二元思考（`on`/`off`）。任何非 `off` 级别都会被视为 `on`（映射到 `low`）。 - - Moonshot（`moonshot/*`）会将 `/think off` 映射到 `thinking: { type: "disabled" }`，并将任何非 `off` 级别映射到 `thinking: { type: "enabled" }`。启用思考时，Moonshot 只接受 `tool_choice` 为 `auto|none`；OpenClaw 会将不兼容的值规范化为 `auto`。 + - Moonshot（`moonshot/*`）会将 `/think off` 映射到 `thinking: { type: "disabled" }`，并将任何非 `off` 级别映射到 `thinking: { type: "enabled" }`。启用思考时，Moonshot 只接受 `tool_choice` `auto|none`；OpenClaw 会将不兼容的值规范化为 `auto`。 ## 解析顺序 -1. 消息中的内联指令（仅作用于该条消息）。 -2. 会话覆盖（通过发送仅包含指令的消息来设置）。 -3. 每个智能体的默认值（配置中的 `agents.list[].thinkingDefault`）。 +1. 消息上的内联指令（仅应用于该消息）。 +2. 会话覆盖（通过发送仅包含指令的消息设置）。 +3. 每个智能体默认值（配置中的 `agents.list[].thinkingDefault`）。 4. 全局默认值（配置中的 `agents.defaults.thinkingDefault`）。 -5. 回退：如果可用，则使用提供商声明的默认值；否则，支持推理的模型会解析为 `medium` 或该模型最接近的受支持非 `off` 级别，不支持推理的模型则保持为 `off`。 +5. 回退：可用时使用提供商声明的默认值；否则，具备推理能力的模型会解析为 `medium`，或该模型最接近的受支持非 `off` 级别；非推理模型保持 `off`。 ## 设置会话默认值 -- 发送一条**仅包含该指令**的消息（允许空白字符），例如 `/think:medium` 或 `/t high`。 -- 这会在当前会话中持续生效（默认按发送者区分）；可通过 `/think:off` 或会话空闲重置来清除。 +- 发送一条**只包含**指令的消息（允许空白），例如 `/think:medium` 或 `/t high`。 +- 这会在当前会话中保持生效（默认按发送者区分）；通过 `/think:off` 或会话空闲重置清除。 - 会发送确认回复（`Thinking level set to high.` / `Thinking disabled.`）。如果级别无效（例如 `/thinking big`），命令会被拒绝并给出提示，会话状态保持不变。 - 发送不带参数的 `/think`（或 `/think:`）可查看当前思考级别。 @@ -60,78 +61,79 @@ x-i18n: - **嵌入式 Pi**：解析后的级别会传递给进程内 Pi 智能体运行时。 -## 快速模式（`/fast`） +## 快速模式（/fast） - 级别：`on|off`。 -- 仅指令消息会切换会话快速模式覆盖，并回复 `Fast mode enabled.` / `Fast mode disabled.`。 -- 发送不带模式的 `/fast`（或 `/fast status`）可查看当前生效的快速模式状态。 +- 仅包含指令的消息会切换会话快速模式覆盖，并回复 `Fast mode enabled.` / `Fast mode disabled.`。 +- 发送不带模式的 `/fast`（或 `/fast status`）可查看当前有效快速模式状态。 - OpenClaw 按以下顺序解析快速模式： - 1. 内联 / 仅指令 `/fast on|off` + 1. 内联/仅指令 `/fast on|off` 2. 会话覆盖 - 3. 每个智能体的默认值（`agents.list[].fastModeDefault`） - 4. 每个模型的配置：`agents.defaults.models["/"].params.fastMode` + 3. 每个智能体默认值（`agents.list[].fastModeDefault`） + 4. 每个模型配置：`agents.defaults.models["/"].params.fastMode` 5. 回退：`off` -- 对于 `openai/*`，快速模式会通过在支持的 Responses 请求上发送 `service_tier=priority` 映射到 OpenAI 优先处理。 -- 对于 `openai-codex/*`，快速模式会在 Codex Responses 上发送相同的 `service_tier=priority` 标志。OpenClaw 会在两种凭证路径之间共享同一个 `/fast` 切换。 -- 对于直接公共的 `anthropic/*` 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，快速模式会映射到 Anthropic service tiers：`/fast on` 设置 `service_tier=auto`，`/fast off` 设置 `service_tier=standard_only`。 +- 对于 `openai/*`，快速模式会通过在受支持的 Responses 请求上发送 `service_tier=priority` 来映射到 OpenAI 优先处理。 +- 对于 `openai-codex/*`，快速模式会在 Codex Responses 上发送相同的 `service_tier=priority` 标志。OpenClaw 会在两个认证路径之间保持一个共享的 `/fast` 开关。 +- 对于直接公共 `anthropic/*` 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，快速模式会映射到 Anthropic 服务层级：`/fast on` 设置 `service_tier=auto`，`/fast off` 设置 `service_tier=standard_only`。 - 对于 Anthropic 兼容路径上的 `minimax/*`，`/fast on`（或 `params.fastMode: true`）会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -- 当 Anthropic 的显式 `serviceTier` / `service_tier` 模型参数与快速模式默认值同时设置时，前者会覆盖后者。对于非 Anthropic 代理 base URL，OpenClaw 仍会跳过 Anthropic service-tier 注入。 -- 仅当快速模式启用时，`/status` 才会显示 `Fast`。 +- 当两者都设置时，显式 Anthropic `serviceTier` / `service_tier` 模型参数会覆盖快速模式默认值。OpenClaw 仍会对非 Anthropic 代理基础 URL 跳过 Anthropic 服务层级注入。 +- `/status` 仅在启用快速模式时显示 `Fast`。 -## 详细指令（`/verbose` 或 `/v`） +## 详细日志指令（/verbose 或 /v） - 级别：`on`（最小）| `full` | `off`（默认）。 -- 仅指令消息会切换会话详细模式，并回复 `Verbose logging enabled.` / `Verbose logging disabled.`；无效级别会返回提示且不改变状态。 -- `/verbose off` 会存储一个显式的会话覆盖；可在会话 UI 中选择 `inherit` 来清除。 -- 内联指令仅影响该条消息；否则应用会话 / 全局默认值。 -- 发送不带参数的 `/verbose`（或 `/verbose:`）可查看当前详细级别。 -- 当 verbose 为开启时，会输出结构化工具结果的智能体（Pi、其他 JSON 智能体）会将每次工具调用作为单独的仅元数据消息发回，并在可用时以前缀 ` : ` 显示（路径 / 命令）。这些工具摘要会在每个工具启动时立即发送（独立气泡），而不是作为流式增量发送。 -- 工具失败摘要在普通模式下仍然可见，但原始错误详情后缀只有在 verbose 为 `on` 或 `full` 时才会显示。 -- 当 verbose 为 `full` 时，工具输出在完成后也会被转发（独立气泡，截断到安全长度）。如果你在某次运行进行中切换 `/verbose on|full|off`，后续的工具气泡会遵循新的设置。 +- 仅包含指令的消息会切换会话详细日志，并回复 `Verbose logging enabled.` / `Verbose logging disabled.`；无效级别会返回提示且不更改状态。 +- `/verbose off` 会存储显式会话覆盖；可在 Sessions UI 中选择 `inherit` 来清除它。 +- 内联指令只影响该消息；否则应用会话/全局默认值。 +- 发送不带参数的 `/verbose`（或 `/verbose:`）可查看当前详细日志级别。 +- 启用详细日志时，会发出结构化工具结果的智能体（Pi、其他 JSON 智能体）会将每个工具调用作为自己的仅元数据消息发回，可用时前缀为 ` : `（路径/命令）。这些工具摘要会在每个工具启动时立即发送（独立气泡），而不是作为流式增量发送。 +- 工具失败摘要在普通模式下仍可见，但原始错误详情后缀会隐藏，除非详细日志为 `on` 或 `full`。 +- 当详细日志为 `full` 时，工具输出也会在完成后转发（独立气泡，截断到安全长度）。如果你在运行进行中切换 `/verbose on|full|off`，后续工具气泡会遵循新设置。 -## 插件 trace 指令（`/trace`） +## 插件跟踪指令（/trace） - 级别：`on` | `off`（默认）。 -- 仅指令消息会切换会话插件 trace 输出，并回复 `Plugin trace enabled.` / `Plugin trace disabled.`。 -- 内联指令仅影响该条消息；否则应用会话 / 全局默认值。 -- 发送不带参数的 `/trace`（或 `/trace:`）可查看当前 trace 级别。 -- `/trace` 比 `/verbose` 更窄：它只暴露插件拥有的 trace / debug 行，例如 Active Memory 调试摘要。 -- trace 行可以显示在 `/status` 中，也可以作为普通助手回复后的后续诊断消息出现。 +- 仅包含指令的消息会切换会话插件跟踪输出，并回复 `Plugin trace enabled.` / `Plugin trace disabled.`。 +- 内联指令只影响该消息；否则应用会话/全局默认值。 +- 发送不带参数的 `/trace`（或 `/trace:`）可查看当前跟踪级别。 +- `/trace` 比 `/verbose` 范围更窄：它只暴露插件拥有的跟踪/调试行，例如 Active Memory 调试摘要。 +- 跟踪行可能出现在 `/status` 中，也可能在正常助手回复之后作为后续诊断消息出现。 -## 推理可见性（`/reasoning`） +## 推理可见性（/reasoning） - 级别：`on|off|stream`。 -- 仅指令消息会切换是否在回复中显示思考块。 -- 启用后，推理会作为一条**单独消息**发送，并以 `Reasoning:` 为前缀。 -- `stream`（仅 Telegram）：在生成回复时，将推理流式输出到 Telegram 草稿气泡中，然后发送不包含推理的最终答案。 +- 仅包含指令的消息会切换是否在回复中显示思考块。 +- 启用后，推理会作为**单独消息**发送，前缀为 `Reasoning:`。 +- `stream`（仅 Telegram）：在回复生成时将推理流式传输到 Telegram 草稿气泡中，然后发送不含推理的最终答案。 - 别名：`/reason`。 - 发送不带参数的 `/reasoning`（或 `/reasoning:`）可查看当前推理级别。 -- 解析顺序：内联指令，然后是会话覆盖，然后是每个智能体默认值（`agents.list[].reasoningDefault`），最后是回退（`off`）。 +- 解析顺序：内联指令，然后是会话覆盖，然后是每个智能体默认值（`agents.list[].reasoningDefault`），然后是回退（`off`）。 -对于格式错误的本地模型推理标签，会采用保守处理方式。闭合的 `...` 块在普通回复中保持隐藏，而在已出现可见文本之后出现的未闭合推理内容也会隐藏。如果某条回复完全被单个未闭合的起始标签包裹，并且否则会导致发送空文本，OpenClaw 会移除这个格式错误的起始标签，并发送剩余文本。 +格式错误的本地模型推理标签会被保守处理。闭合的 `...` 块在正常回复中保持隐藏，已可见文本之后未闭合的推理也会隐藏。如果回复完全由单个未闭合开标签包裹，且否则会作为空文本投递，OpenClaw 会移除格式错误的开标签并投递剩余文本。 -## 相关内容 +## 相关 -- Elevated mode 文档位于 [Elevated mode](/zh-CN/tools/elevated)。 +- 提权模式文档位于 [提权模式](/zh-CN/tools/elevated)。 ## 心跳 -- 心跳探测消息体为已配置的心跳提示（默认值：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。心跳消息中的内联指令会照常生效（但应避免通过心跳更改会话默认值）。 -- 心跳传递默认只发送最终 payload。若还要发送单独的 `Reasoning:` 消息（如果可用），请设置 `agents.defaults.heartbeat.includeReasoning: true` 或每个智能体的 `agents.list[].heartbeat.includeReasoning: true`。 +- 心跳探测正文是配置的心跳提示（默认值：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。心跳消息中的内联指令会照常应用（但请避免从心跳中更改会话默认值）。 +- 心跳投递默认只发送最终载荷。若还要发送单独的 `Reasoning:` 消息（可用时），请设置 `agents.defaults.heartbeat.includeReasoning: true` 或每个智能体的 `agents.list[].heartbeat.includeReasoning: true`。 ## Web 聊天 UI -- Web 聊天思考选择器在页面加载时，会从入站会话存储 / 配置中镜像该会话已存储的级别。 -- 选择其他级别会立即通过 `sessions.patch` 写入会话覆盖；它不会等到下一次发送，也不是一次性的 `thinkingOnce` 覆盖。 -- 第一个选项始终是 `Default ()`，其中解析后的默认值来自活动会话模型的提供商思考配置文件，以及 `/status` 和 `session_status` 使用的相同回退逻辑。 -- 选择器使用 Gateway 网关会话行 / 默认值返回的 `thinkingLevels`，并将 `thinkingOptions` 保留为旧版标签列表。浏览器 UI 不会维护自己的提供商正则列表；模型特定的级别集合由插件负责。 -- `/think:` 仍然有效，并会更新同一个已存储的会话级别，因此聊天指令和选择器会保持同步。 +- 页面加载时，Web 聊天思考选择器会从入站会话存储/配置中镜像会话已存储的级别。 +- 选择其他级别会立即通过 `sessions.patch` 写入会话覆盖；它不会等待下一次发送，也不是一次性的 `thinkingOnce` 覆盖。 +- 第一个选项始终是 `Default ()`，其中解析后的默认值来自活动会话模型的提供商思考配置档案，以及 `/status` 和 `session_status` 使用的相同回退逻辑。 +- 选择器使用 Gateway 网关会话行/默认值返回的 `thinkingLevels`，并将 `thinkingOptions` 保留为旧版标签列表。浏览器 UI 不保留自己的提供商正则列表；插件拥有模型特定的级别集合。 +- `/think:` 仍然有效，并会更新同一个已存储会话级别，因此聊天指令和选择器会保持同步。 -## 提供商配置文件 +## 提供商配置档案 -- 提供商插件可以暴露 `resolveThinkingProfile(ctx)`，用于定义模型支持的级别及默认值。 -- 代理 Claude 模型的提供商插件应复用 `openclaw/plugin-sdk/provider-model-shared` 中的 `resolveClaudeThinkingProfile(modelId)`，以便让直接 Anthropic 和代理 catalog 保持一致。 -- 每个配置文件级别都有一个已存储的规范 `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive` 或 `max`），并且可以包含一个显示 `label`。二元提供商使用 `{ id: "low", label: "on" }`。 -- 需要校验显式思考覆盖的工具插件应使用 `api.runtime.agent.resolveThinkingPolicy({ provider, model })` 加 `api.runtime.agent.normalizeThinkingLevel(...)`；它们不应维护自己的提供商 / 模型级别列表。 -- 已发布的旧版钩子（`supportsXHighThinking`、`isBinaryThinking` 和 `resolveDefaultThinkingLevel`）仍作为兼容性适配器保留，但新的自定义级别集合应使用 `resolveThinkingProfile`。 -- Gateway 网关行 / 默认值会暴露 `thinkingLevels`、`thinkingOptions` 和 `thinkingDefault`，这样 ACP / 聊天客户端就能渲染与运行时校验相同的配置文件 id 和标签。 +- 提供商插件可以公开 `resolveThinkingProfile(ctx)`，用于定义该模型支持的等级和默认值。 +- 代理 Claude 模型的提供商插件应复用 `openclaw/plugin-sdk/provider-model-shared` 中的 `resolveClaudeThinkingProfile(modelId)`，以便直接 Anthropic 和代理目录保持一致。 +- 每个配置等级都有一个已存储的规范 `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive` 或 `max`），并且可以包含显示用的 `label`。二元提供商使用 `{ id: "low", label: "on" }`。 +- 需要验证显式思考覆盖值的工具插件应使用 `api.runtime.agent.resolveThinkingPolicy({ provider, model })` 加上 `api.runtime.agent.normalizeThinkingLevel(...)`；它们不应保留自己的提供商/模型等级列表。 +- 能访问已配置自定义模型元数据的工具插件可以将 `catalog` 传入 `resolveThinkingPolicy`，这样 `compat.supportedReasoningEfforts` 的选择加入会反映在插件侧验证中。 +- 已发布的旧版钩子（`supportsXHighThinking`、`isBinaryThinking` 和 `resolveDefaultThinkingLevel`）仍作为兼容适配器保留，但新的自定义等级集合应使用 `resolveThinkingProfile`。 +- Gateway 网关行/默认值公开 `thinkingLevels`、`thinkingOptions` 和 `thinkingDefault`，因此 ACP/chat 客户端会渲染与运行时验证所用相同的配置 id 和标签。