diff --git a/docs/zh-CN/ci.md b/docs/zh-CN/ci.md index 0a55445e9..edd2d35a0 100644 --- a/docs/zh-CN/ci.md +++ b/docs/zh-CN/ci.md @@ -1,27 +1,27 @@ --- read_when: - - 你需要了解为什么某个 CI 作业运行了或没有运行 + - 你需要了解某个 CI 作业为什么会运行，或者为什么没有运行 - 你正在调试失败的 GitHub Actions 检查 summary: CI 作业图、范围门禁，以及本地等效命令 title: CI 流水线 x-i18n: - generated_at: "2026-04-25T17:30:19Z" + generated_at: "2026-04-25T22:52:54Z" model: gpt-5.4 provider: openai - source_hash: 841b8036e59b5b03620b301918549670870842cc42681321a9b8f9d01792d950 + source_hash: 1a6c14f785434585f2b3a72bcd2cff3a281e51fe12cc4c14aa7613d47cd8efc4 source_path: ci.md workflow: 15 --- -CI 会在每次推送到 `main` 以及每个拉取请求上运行。它使用智能范围控制，在只修改了无关区域时跳过开销较大的作业。 +CI 会在每次向 `main` 推送以及每个拉取请求上运行。它使用智能范围控制，在只有无关区域发生变更时跳过开销较大的作业。 -QA Lab 在主智能范围工作流之外有专用的 CI 通道。`Parity gate` 工作流会在匹配的 PR 变更和手动触发时运行；它会构建私有 QA 运行时，并比较模拟的 GPT-5.5 和 Opus 4.6 agentic packs。`QA-Lab - All Lanes` 工作流会在 `main` 上每晚运行，并支持手动触发；它会将模拟 parity gate、实时 Matrix 通道和实时 Telegram 通道拆分为并行作业。实时作业使用 `qa-live-shared` environment，而 Telegram 通道使用 Convex leases。`OpenClaw Release Checks` 也会在发布批准前运行同样的 QA Lab 通道。 +QA Lab 在主智能范围工作流之外有专门的 CI 通道。`Parity gate` 工作流会在匹配的 PR 变更以及手动派发时运行；它会构建私有 QA 运行时，并比较模拟的 GPT-5.5 和 Opus 4.6 agentic packs。`QA-Lab - All Lanes` 工作流会在 `main` 上每晚运行，并且也支持手动派发；它会将模拟 parity gate、实时 Matrix 通道和实时 Telegram 通道作为并行作业扇出运行。实时作业使用 `qa-live-shared` 环境，而 Telegram 通道使用 Convex leases。`OpenClaw Release Checks` 也会在发布审批前运行同样的 QA Lab 通道。 -`Duplicate PRs After Merge` 工作流是一个供维护者在合并后清理重复 PR 的手动工作流。它默认以 dry-run 模式运行，只有在 `apply=true` 时才会关闭明确列出的 PR。在修改 GitHub 之前，它会验证已合并的 PR 确实已经合并，并确认每个重复 PR 都具有共享的引用 issue，或存在重叠的变更 hunk。 +`Duplicate PRs After Merge` 工作流是一个供维护者使用的手动工作流，用于合并后的重复 PR 清理。它默认采用 dry-run，仅当 `apply=true` 时才会关闭明确列出的 PR。在对 GitHub 进行修改前，它会验证已落地的 PR 确实已合并，并确认每个重复 PR 都具有共享的引用 issue，或存在重叠的变更 hunk。 -`Docs Agent` 工作流是一个事件驱动的 Codex 维护通道，用于让现有文档与最近已合并的变更保持一致。它没有纯定时调度：在 `main` 上成功完成的、非机器人触发的 push CI 运行可以触发它，手动触发也可以直接运行它。workflow-run 调用会在 `main` 已经继续前进，或过去一小时内已经创建了另一个未被跳过的 Docs Agent 运行时跳过。实际运行时，它会审查从上一个未被跳过的 Docs Agent 源 SHA 到当前 `main` 的提交范围，因此每小时一次的运行可以覆盖自上次文档处理以来累积在 main 上的所有变更。 +`Docs Agent` 工作流是一个事件驱动的 Codex 维护通道，用于让现有文档与最近已落地的变更保持一致。它没有纯定时调度：`main` 上一次成功的非机器人 push CI 运行可以触发它，手动派发也可以直接运行它。workflow-run 调用会在 `main` 已继续前进，或过去一小时内已创建过另一个未跳过的 Docs Agent 运行时跳过。当它运行时，会审查从上一个未跳过的 Docs Agent 源 SHA 到当前 `main` 的提交范围，因此每小时一次运行可以覆盖自上次文档处理以来累积到 `main` 的所有变更。 -`Test Performance Agent` 工作流是一个事件驱动的 Codex 维护通道，用于处理慢测试。它没有纯定时调度：在 `main` 上成功完成的、非机器人触发的 push CI 运行可以触发它，但如果当天 UTC 已经有另一个 workflow-run 调用正在运行或已经运行过，它就会跳过。手动触发会绕过这个按天统计的活动门禁。该通道会构建完整测试套件的分组 Vitest 性能报告，让 Codex 只做小范围、保持覆盖率不变的测试性能修复，而不是进行大范围重构；随后它会重新运行完整测试套件报告，并拒绝任何会降低通过基线测试数量的更改。如果基线中本身存在失败测试，Codex 只能修复明显的失败项，并且 agent 处理后的完整测试套件报告必须通过，之后才允许提交任何内容。当 `main` 在机器人推送落地之前继续前进时，该通道会对已验证的补丁执行 rebase，重新运行 `pnpm check:changed`，并重试推送；存在冲突的过时补丁会被跳过。它使用 GitHub 托管的 Ubuntu，这样 Codex action 就能与 docs agent 保持相同的 drop-sudo 安全策略。 +`Test Performance Agent` 工作流是一个事件驱动的 Codex 维护通道，用于处理慢测试。它没有纯定时调度：`main` 上一次成功的非机器人 push CI 运行可以触发它，但如果同一个 UTC 日内另一个 workflow-run 调用已经运行过或正在运行，它就会跳过。手动派发会绕过这个按日活动门禁。该通道会构建完整测试套件的分组 Vitest 性能报告，让 Codex 仅进行小范围、保留覆盖率的测试性能修复，而不是进行大范围重构，然后重新运行完整测试套件报告，并拒绝任何会降低通过基线测试数量的更改。如果基线存在失败测试，Codex 只能修复明显的失败项，并且智能体处理后的完整测试套件报告必须全部通过，之后才会提交任何内容。当机器人推送落地前 `main` 已经前进时，该通道会对已验证的补丁执行 rebase，重新运行 `pnpm check:changed`，并重试推送；有冲突的过期补丁会被跳过。它使用 GitHub 托管的 Ubuntu，这样 Codex action 就能与 docs agent 保持相同的 drop-sudo 安全策略。 ```bash gh workflow run duplicate-after-merge.yml \ @@ -34,62 +34,61 @@ gh workflow run duplicate-after-merge.yml \ | 作业 | 用途 | 运行时机 | | -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ | -| `preflight` | 检测是否仅有文档变更、变更范围、已变更扩展，并构建 CI 清单 | 在所有非草稿 push 和 PR 上始终运行 | +| `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 相关的变更 | +| `security-dependency-audit` | 针对 npm advisories 执行无依赖的生产 lockfile 审计 | 在所有非草稿 push 和 PR 上始终运行 | +| `security-fast` | 快速安全作业的必需聚合项 | 在所有非草稿 push 和 PR 上始终运行 | +| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查以及可复用的下游产物 | 与 Node 相关的变更 | | `checks-fast-core` | 快速 Linux 正确性通道，例如 bundled/plugin-contract/protocol 检查 | 与 Node 相关的变更 | -| `checks-fast-contracts-channels` | 分片的渠道 contract 检查，并提供稳定的聚合检查结果 | 与 Node 相关的变更 | -| `checks-node-extensions` | 对整个扩展套件执行完整 bundled-plugin 测试分片 | 与 Node 相关的变更 | -| `checks-node-core-test` | Core Node 测试分片，不包含渠道、bundled、contract 和扩展通道 | 与 Node 相关的变更 | -| `extension-fast` | 仅针对已变更 bundled plugins 的聚焦测试 | 带有扩展变更的拉取请求 | -| `check` | 分片后的主本地门禁等效项：生产类型、lint、guard、测试类型和严格 smoke 检查 | 与 Node 相关的变更 | -| `check-additional` | 架构、边界、扩展表面 guard、包边界以及 gateway-watch 分片 | 与 Node 相关的变更 | +| `checks-fast-contracts-channels` | 分片的渠道契约检查，并提供稳定的聚合检查结果 | 与 Node 相关的变更 | +| `checks-node-extensions` | 针对整个扩展套件的完整内置插件测试分片 | 与 Node 相关的变更 | +| `checks-node-core-test` | Core Node 测试分片，不包括渠道、内置、契约和扩展通道 | 与 Node 相关的变更 | +| `extension-fast` | 仅针对已变更内置插件的聚焦测试 | 带有扩展变更的拉取请求 | +| `check` | 分片的主本地门禁等效项：生产类型、lint、守卫、测试类型和严格 smoke | 与 Node 相关的变更 | +| `check-additional` | 架构、边界、扩展表面守卫、包边界以及 gateway-watch 分片 | 与 Node 相关的变更 | | `build-smoke` | 已构建 CLI 的 smoke 测试和启动内存 smoke 测试 | 与 Node 相关的变更 | -| `checks` | 用于已构建产物渠道测试的验证器，以及仅在 push 时运行的 Node 22 兼容性检查 | 与 Node 相关的变更 | -| `check-docs` | 文档格式、lint 和损坏链接检查 | 文档发生变更时 | +| `checks` | 已构建产物渠道测试的验证器，以及仅在 push 上运行的 Node 22 兼容性检查 | 与 Node 相关的变更 | +| `check-docs` | 文档格式、lint 和失效链接检查 | 文档发生变更 | | `skills-python` | 面向 Python 支持的 Skills 的 Ruff + pytest | 与 Python Skills 相关的变更 | -| `checks-windows` | Windows 专用测试通道 | 与 Windows 相关的变更 | +| `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 慢测试优化 | main CI 成功后或手动触发 | +| `android` | 两个 flavor 的 Android 单元测试，以及一次 debug APK 构建 | 与 Android 相关的变更 | +| `test-performance-agent` | 在可信活动后每日执行的 Codex 慢测试优化 | `main` CI 成功后或手动派发 | ## 快速失败顺序 -作业的排序方式是让低成本检查先失败，再决定是否运行高成本作业： +作业的排列顺序经过设计，以便让廉价检查先失败，再决定是否运行昂贵作业： -1. `preflight` 决定哪些通道实际存在。`docs-scope` 和 `changed-scope` 逻辑是这个作业中的步骤，而不是独立作业。 -2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，而不必等待更重的构建产物和平台矩阵作业。 -3. `build-artifacts` 会与快速 Linux 通道并行，这样下游消费者可以在共享构建准备完成后立即开始。 -4. 更重的平台和运行时通道随后展开：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-extensions`、`checks-node-core-test`、仅限 PR 的 `extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 +1. `preflight` 决定哪些通道实际存在。`docs-scope` 和 `changed-scope` 逻辑是该作业中的步骤，而不是独立作业。 +2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，而不会等待更重的产物和平台矩阵作业。 +3. `build-artifacts` 会与快速 Linux 通道并行重叠运行，这样下游消费者就能在共享构建准备好后立即启动。 +4. 之后会扇出更重的平台和运行时通道：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-extensions`、`checks-node-core-test`、仅限 PR 的 `extension-fast`、`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 路由的编辑、特定廉价 core-test fixture 编辑，以及狭窄的 plugin contract helper/test-routing 编辑，会使用快速的仅 Node 清单路径：preflight、安全检查，以及单个 `checks-fast-core` 任务。当前更改文件仅限于该快速任务可直接覆盖的路由或 helper 表面时，这一路径会避开构建产物、Node 22 兼容性、渠道 contract、完整 core 分片、bundled-plugin 分片，以及额外的 guard 矩阵。 -Windows Node 检查的范围限定为 Windows 专用的进程/路径包装器、npm/pnpm/UI runner helpers、包管理器配置，以及执行该通道的 CI 工作流表面；无关的源码、plugin、install-smoke 和仅测试变更会继续留在 Linux Node 通道上，这样就不会为已经由常规测试分片覆盖的内容占用 16 vCPU 的 Windows worker。 -独立的 `install-smoke` 工作流通过其自身的 `preflight` 作业复用相同的范围脚本。它将 smoke 覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。对于拉取请求，Docker/包表面、bundled plugin package/manifest 变更，以及 Docker smoke 作业所覆盖的 core plugin/channel/gateway/Plugin SDK 表面会运行快速路径。仅源码级的 bundled plugin 变更、仅测试编辑和仅文档编辑不会占用 Docker workers。快速路径会构建一次根 Dockerfile 镜像、检查 CLI、运行 agents delete shared-workspace CLI smoke、运行容器 gateway-network e2e、验证一个 bundled extension build arg，并在 240 秒的总命令超时限制下运行有边界的 bundled-plugin Docker profile，同时每个场景的 Docker run 也各自有单独上限。完整路径会为夜间定时运行、手动触发、workflow-call 发布检查，以及真正触及 installer/package/Docker 表面的拉取请求保留 QR package install 和 installer Docker/update 覆盖。推送到 `main`，包括合并提交，不会强制走完整路径；当 changed-scope 逻辑会在 push 上请求完整覆盖时，工作流仍然只保留快速 Docker smoke，而把完整 install smoke 留给夜间任务或发布验证。较慢的 Bun 全局安装 image-provider smoke 由 `run_bun_global_install_smoke` 单独控制；它会在夜间计划任务和发布检查工作流中运行，手动触发 `install-smoke` 时也可以选择启用，但拉取请求和 `main` 推送都不会运行它。QR 和 installer Docker 测试保留各自专注于安装的 Dockerfile。本地 `test:docker:all` 会预构建一个共享的 live-test 镜像和一个共享的 `scripts/e2e/Dockerfile` built-app 镜像，然后使用加权调度器和 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行 live/E2E smoke 通道；默认主池槽位数为 10，可通过 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整；对 provider 敏感的尾部池槽位数默认也是 10，可通过 `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` 调整。重型通道上限默认分别为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=8` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`，以避免 npm install 和多服务通道过度占用 Docker，同时让较轻的通道仍能填满可用槽位。默认情况下，各通道启动会错开 2 秒，以避免本地 Docker daemon 出现 create 风暴；可使用 `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 通道使用更严格的单通道上限。可复用的 live/E2E 工作流也采用相同的共享镜像模式：它会在 Docker 矩阵之前先构建并推送一个带 SHA 标签的 GHCR Docker E2E 镜像，然后用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行矩阵。定时的 live/E2E 工作流每天运行完整的发布路径 Docker 套件。bundled update 矩阵按 update target 拆分，以便重复的 npm update 和 doctor repair 过程可以与其他 bundled 检查一起分片运行。 +CI 工作流编辑会验证 Node CI 作业图以及工作流 lint，但本身不会强制触发 Windows、Android 或 macOS 原生构建；这些平台通道仍然只针对平台源码变更按范围运行。 +仅涉及 CI 路由的编辑、部分精选的廉价 core-test fixture 编辑，以及狭窄的插件契约辅助函数/测试路由编辑，会使用快速的仅 Node manifest 路径：preflight、安全检查，以及单个 `checks-fast-core` 任务。当变更文件仅限于该快速任务可直接覆盖的路由或辅助表面时，这条路径会跳过构建产物、Node 22 兼容性、渠道契约、完整 core 分片、内置插件分片以及额外守卫矩阵。 +Windows Node 检查的范围限定在 Windows 特定的进程/路径包装器、npm/pnpm/UI runner 辅助函数、包管理器配置，以及执行该通道的 CI 工作流表面；无关的源码、插件、install-smoke 和仅测试变更会保留在 Linux Node 通道上，这样就不会为了正常测试分片已经覆盖的内容而占用一个 16 vCPU 的 Windows worker。 +独立的 `install-smoke` 工作流通过它自己的 `preflight` 作业复用同一个范围脚本。它将 smoke 覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。对于拉取请求，Docker/包表面、内置插件包/manifest 变更，以及 Docker smoke 作业所覆盖的 core 插件/渠道/Gateway 网关/插件 SDK 表面，会运行快速路径。仅源码的内置插件变更、仅测试编辑以及仅文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete shared-workspace CLI smoke，运行容器 `gateway-network` e2e，验证一个内置扩展构建参数，并在 240 秒总命令超时下运行有界的内置插件 Docker profile，同时对每个场景的 Docker run 分别设置上限。完整路径会为夜间定时运行、手动派发、workflow-call 发布检查，以及真正触及 installer/package/Docker 表面的拉取请求保留 QR 包安装和 installer Docker/update 覆盖。对 `main` 的推送，包括 merge commit，不会强制执行完整路径；当 changed-scope 逻辑会在一次 push 上请求完整覆盖时，工作流仍会保留快速 Docker smoke，而将完整 install smoke 留给夜间或发布验证。较慢的 Bun 全局安装 image-provider smoke 由 `run_bun_global_install_smoke` 单独控制；它会在夜间计划任务和 release checks 工作流中运行，手动 `install-smoke` 派发也可以选择启用它，但拉取请求和 `main` 推送不会运行它。QR 和 installer Docker 测试保留各自专注安装的 Dockerfile。本地 `test:docker:all` 会预构建一个共享的 live-test 镜像和一个共享的 `scripts/e2e/Dockerfile` built-app 镜像，然后在设置了 `OPENCLAW_SKIP_DOCKER_BUILD=1` 的情况下，使用带权重的调度器运行 live/E2E smoke 通道；默认主池槽位数为 10，可通过 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整；对 provider 敏感的尾池槽位数默认也是 10，可通过 `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` 调整。重型通道上限默认分别为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=8` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`，这样 npm install 和多服务通道就不会让 Docker 过度超配，而较轻的通道仍能填满可用槽位。默认情况下，各通道启动会错开 2 秒，以避免本地 Docker daemon 出现 create 风暴；可通过 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` 或其他毫秒值覆盖。这个本地聚合器会先对 Docker 做 preflight，移除陈旧的 OpenClaw E2E 容器，输出活动通道状态，持久化通道耗时以支持“最长优先”排序，并支持 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 用于调度器检查。默认情况下，它会在第一次失败后停止调度新的池化通道，并且每个通道都有一个 120 分钟的兜底超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；部分 live/tail 通道会使用更严格的单通道上限。可复用的 live/E2E 工作流通过在 Docker 矩阵之前先构建并推送一个以 SHA 标记的 GHCR Docker E2E 镜像，来复用共享镜像模式，然后使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行该矩阵。计划中的 live/E2E 工作流每天运行完整的发布路径 Docker 套件。内置更新矩阵按更新目标拆分，这样重复的 npm update 和 doctor repair 过程就可以与其他内置检查一起分片执行。 -本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，由 `scripts/check-changed.mjs` 执行。这个本地门禁在架构边界方面比宽泛的 CI 平台范围更严格：core 生产变更会运行 core 生产 typecheck 加 core 测试，core 仅测试变更只运行 core 测试 typecheck/测试，扩展生产变更会运行扩展生产 typecheck 加扩展测试，而扩展仅测试变更只运行扩展测试 typecheck/测试。公开的 Plugin SDK 或 plugin-contract 变更会扩展到扩展验证，因为扩展依赖这些 core contract。仅发布元数据的版本提升会运行定向的版本/配置/根依赖检查。未知的根目录/配置变更会以保守方式回退到所有通道。 +本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。这个本地门禁在架构边界方面比广义的 CI 平台范围更严格：core 生产变更会运行 core 生产 typecheck 加 core 测试，core 仅测试变更只运行 core 测试 typecheck/测试，扩展生产变更会运行扩展生产 typecheck 加扩展测试，而扩展仅测试变更只运行扩展测试 typecheck/测试。公开的插件 SDK 或插件契约变更会扩大到扩展验证，因为扩展依赖这些 core 契约。仅发布元数据的版本提升会运行定向的版本/配置/根依赖检查。未知的根目录/配置变更会以安全优先方式回退到所有通道。 -在 push 上，`checks` 矩阵会额外加入仅在 push 时运行的 `compat-node22` 通道。在拉取请求中，这个通道会被跳过，矩阵会继续聚焦于常规测试/渠道通道。 +在 push 上，`checks` 矩阵会增加仅限 push 的 `compat-node22` 通道。在拉取请求上，该通道会被跳过，矩阵会继续专注于常规测试/渠道通道。 -最慢的 Node 测试族会被拆分或重新平衡，以便每个作业都保持较小规模而不会过度预留 runner：渠道 contract 以三个加权分片运行，bundled plugin 测试在六个扩展 worker 之间平衡分配，小型 core 单元通道会成对组合，auto-reply 以三个平衡 worker 运行而不是六个很小的 worker，而 agentic gateway/plugin configs 会分散到现有的仅源码 agentic Node 作业中，而不是等待构建产物。范围较广的 browser、QA、media 和杂项 plugin 测试使用各自专用的 Vitest 配置，而不是共享的 plugin 兜底配置。扩展分片作业一次最多运行两组 plugin config，每组使用一个 Vitest worker，并分配更大的 Node 堆，以避免导入密集型 plugin 批次产生额外的 CI 作业。广泛的 agents 通道使用共享的 Vitest 文件并行调度器，因为它受导入/调度影响更大，而不是由某个单独的慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以免共享运行时分片承担尾部长任务。`check-additional` 会把 package-boundary compile/canary 工作保留在一起，并把运行时拓扑架构与 gateway watch 覆盖分开；boundary guard 分片会在一个作业内部并发运行其几个较小且相互独立的 guards。Gateway watch、渠道测试以及 core support-boundary 分片会在 `dist/` 和 `dist-runtime/` 已构建完成后，于 `build-artifacts` 内部并发运行；这样既保留了它们原有的检查名称作为轻量验证作业，又避免再额外占用两个 Blacksmith workers 和第二个产物消费者队列。 -Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的源码集或 manifest；其单元测试通道仍会在带有 SMS/call-log BuildConfig 标志的情况下编译该 flavor，同时避免在每次与 Android 相关的 push 上重复执行 debug APK 打包作业。 -`extension-fast` 仅在 PR 上运行，因为 push 运行已经会执行完整的 bundled plugin 分片。这样既能为评审提供已变更 plugin 的反馈，又不会在 `main` 上为 `checks-node-extensions` 已经覆盖的内容额外占用一个 Blacksmith worker。 +最慢的 Node 测试家族会被拆分或平衡，以便每个作业都保持较小规模，同时避免过度预留 runner：渠道契约会作为三个带权分片运行，内置插件测试会在六个扩展 worker 间平衡分配，小型 core 单元通道会两两配对，自动回复会作为四个平衡 worker 运行，并把 reply 子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片，而 agentic Gateway 网关/插件配置则分散到现有的仅源码 agentic Node 作业中，而不是等待构建产物。广泛的 browser、QA、media 以及杂项插件测试使用它们专用的 Vitest 配置，而不是共享的插件兜底配置。扩展分片作业一次最多运行两组插件配置，每组只用一个 Vitest worker，并分配更大的 Node heap，以避免导入密集型插件批次生成额外的 CI 作业。广泛的 agents 通道使用共享的 Vitest 文件并行调度器，因为它主要受导入/调度影响，而不是由某个单独的慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享运行时分片独自承担尾部耗时。包含模式分片会使用 CI 分片名称记录耗时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分整个配置和经过过滤的分片。`check-additional` 会将包边界编译/canary 工作保留在一起，并将运行时拓扑架构与 gateway watch 覆盖拆开；边界守卫分片会在一个作业内并发运行其小型独立守卫。Gateway 网关 watch、渠道测试以及 core support-boundary 分片会在 `dist/` 和 `dist-runtime/` 已构建完成后，在 `build-artifacts` 内并发运行；这样既保留它们原有的检查名称作为轻量验证器作业，又避免额外占用两个 Blacksmith worker 和第二个产物消费者队列。 +Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的源码集或 manifest；它的单元测试通道仍会在带有 SMS/通话日志 BuildConfig 标志的情况下编译该 flavor，同时避免在每次与 Android 相关的 push 上重复执行 debug APK 打包作业。 +`extension-fast` 仅用于 PR，因为 push 运行已经会执行完整的内置插件分片。这样既能为评审提供已变更插件的反馈，又不会在 `main` 上额外占用一个 Blacksmith worker，去重复 `checks-node-extensions` 中已有的覆盖。 -当同一 PR 或 `main` 引用上有更新的 push 到达时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一引用的最新运行也失败了，否则应把这视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会正常报告分片失败，但不会在整个工作流已经被更新运行取代后继续排队。 +当同一个 PR 或 `main` 引用上有新的 push 到达时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一引用上的最新一次运行也失败，否则应将其视为 CI 噪音。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但在整个工作流已经被更新运行取代后不会继续排队。 +CI 并发键采用版本化形式（`CI-v7-*`），这样 GitHub 端旧队列组中的僵尸任务就不会无限期阻塞更新的 `main` 运行。 -CI 并发键带有版本号（`CI-v7-*`），因此 GitHub 端旧队列组中的僵尸任务不会无限期阻塞较新的 main 运行。 +## Runner 类型 -## 运行器 - -| 运行器 | 作业 | +| Runner 类型 | 作业 | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`、快速安全作业及其聚合项（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速 protocol/contract/bundled 检查、分片的渠道 contract 检查、除 lint 之外的 `check` 分片、`check-additional` 分片及聚合项、Node 测试聚合验证器、文档检查、Python Skills、workflow-sanity、labeler、auto-response；install-smoke 的 preflight 也使用 GitHub 托管的 Ubuntu，这样 Blacksmith 矩阵可以更早开始排队 | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node 测试分片、bundled plugin 测试分片、`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`）、快速 protocol/contract/bundled 检查、分片的渠道契约检查、除 lint 之外的 `check` 分片、`check-additional` 分片及其聚合项、Node 测试聚合验证器、文档检查、Python Skills、workflow-sanity、labeler、auto-response；install-smoke 的 preflight 也使用 GitHub 托管的 Ubuntu，这样 Blacksmith 矩阵可以更早进入队列 | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node 测试分片、内置插件测试分片、`android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`，它仍然对 CPU 足够敏感，以至于 8 vCPU 的成本高于节省；install-smoke Docker 构建也是如此，因为 32 vCPU 的排队时间成本高于节省 | | `blacksmith-16vcpu-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` | @@ -99,19 +98,22 @@ CI 并发键带有版本号（`CI-v7-*`），因此 GitHub 端旧队列组中的 ```bash pnpm changed:lanes # 检查 origin/main...HEAD 的本地 changed-lane 分类器 pnpm check:changed # 智能本地门禁：按边界通道运行变更相关的 typecheck/lint/测试 -pnpm check # 快速本地门禁：生产 tsgo + 分片 lint + 并行快速 guards +pnpm check # 快速本地门禁：生产 tsgo + 分片 lint + 并行快速守卫 pnpm check:test-types -pnpm check:timed # 相同门禁，但带每个阶段的耗时统计 +pnpm check:timed # 相同的门禁，但带有每个阶段的耗时 pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression pnpm test # vitest 测试 pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # 文档格式 + lint + 损坏链接检查 -pnpm build # 当 CI 构建产物/build-smoke 通道相关时，构建 dist -node scripts/ci-run-timings.mjs # 汇总总耗时、排队时间和最慢的作业 -node scripts/ci-run-timings.mjs --recent 10 # 对比最近成功的 10 次 main CI 运行 +pnpm check:docs # 文档格式 + lint + 失效链接 +pnpm build # 当 CI 产物/build-smoke 通道相关时，构建 dist +pnpm ci:timings # 汇总最近一次 origin/main push CI 运行 +pnpm ci:timings:recent # 比较最近成功的 main CI 运行 +node scripts/ci-run-timings.mjs # 汇总总耗时、排队时间和最慢作业 +node scripts/ci-run-timings.mjs --latest-main # 忽略 issue/comment 噪音并选择 origin/main push CI +node scripts/ci-run-timings.mjs --recent 10 # 比较最近成功的 main CI 运行 pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json ``` diff --git a/docs/zh-CN/help/testing.md b/docs/zh-CN/help/testing.md index 0c3225868..991f2ea4d 100644 --- a/docs/zh-CN/help/testing.md +++ b/docs/zh-CN/help/testing.md @@ -1,145 +1,144 @@ --- read_when: - 在本地或 CI 中运行测试 - - 为模型 / 提供商缺陷添加回归测试 + - 为模型/提供商缺陷添加回归测试 - 调试 Gateway 网关 + 智能体行为 -summary: 测试工具包：单元 / e2e / live 测试套件、Docker 运行器，以及每项测试覆盖的内容 +summary: 测试套件：unit/e2e/live 套件、Docker 运行器，以及每项测试所覆盖的内容 title: 测试 x-i18n: - generated_at: "2026-04-25T12:43:49Z" + generated_at: "2026-04-25T22:52:55Z" model: gpt-5.4 provider: openai - source_hash: c8352a695890b2bef8d15337c6371f33363222ec371f91dd0e6a8ba84cccbbc8 + source_hash: f75a132d527cc81329a93cdf47859622e2ac5347d7e9ab922bbd604948a43bf4 source_path: help/testing.md workflow: 15 --- -OpenClaw 有三个 Vitest 测试套件（unit / integration、e2e、live）以及一小组 Docker 运行器。本文档是一份“我们如何测试”的指南： +OpenClaw 有三个 Vitest 测试套件（unit/integration、e2e、live）以及一小组 Docker 运行器。本文档是一份“我们如何测试”的指南： -- 每个测试套件覆盖什么（以及它刻意**不**覆盖什么）。 +- 每个套件覆盖什么内容（以及它刻意 _不_ 覆盖什么）。 - 常见工作流应运行哪些命令（本地、推送前、调试）。 -- live 测试如何发现凭证并选择模型 / 提供商。 -- 如何为真实世界中的模型 / 提供商问题添加回归测试。 +- live 测试如何发现凭证，以及如何选择模型/提供商。 +- 如何为真实世界中的模型/提供商问题添加回归测试。 ## 快速开始 大多数时候： -- 完整门禁（推送前预期执行）：`pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- 在配置充足的机器上更快地运行本地完整测试套件：`pnpm test:max` +- 完整门禁（预期在推送前执行）：`pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- 在配置充裕的机器上更快地运行本地完整套件：`pnpm test:max` - 直接进入 Vitest 监听循环：`pnpm test:watch` -- 直接按文件定位现在也会路由 extension / channel 路径：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- 当你在迭代单个失败用例时，优先先运行定向测试。 -- 基于 Docker 的 QA 站点：`pnpm qa:lab:up` -- 基于 Linux VM 的 QA 通道：`pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- 现在可将扩展/渠道路径直接路由到目标文件：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- 当你在迭代处理单个失败用例时，优先使用定向运行。 +- Docker 支持的 QA 站点：`pnpm qa:lab:up` +- Linux VM 支持的 QA 通道：`pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -当你修改了测试，或想获得更高信心时： +当你修改了测试或希望获得更高信心时： - 覆盖率门禁：`pnpm test:coverage` - E2E 套件：`pnpm test:e2e` -当调试真实提供商 / 模型时（需要真实凭证）： +当你在调试真实的提供商/模型时（需要真实凭证）： -- live 套件（模型 + Gateway 网关工具 / 图像探测）：`pnpm test:live` +- live 套件（模型 + Gateway 网关工具/图像探测）：`pnpm test:live` - 安静地只运行一个 live 文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker live 模型扫描：`pnpm test:docker:live-models` - - 现在每个选中的模型都会运行一次文本轮次外加一个小型 file-read 风格探测。元数据声明支持 `image` 输入的模型还会运行一个微型图像轮次。隔离提供商故障时，可用 `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` 或 `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` 禁用这些额外探测。 - - CI 覆盖：每日 `OpenClaw Scheduled Live And E2E Checks` 和手动 `OpenClaw Release Checks` 都会调用可复用的 live / E2E 工作流，并设置 `include_live_suites: true`，其中包含按提供商分片的独立 Docker live 模型矩阵作业。 - - 如需聚焦的 CI 重跑，可派发 `OpenClaw Live And E2E Checks (Reusable)`，并设置 `include_live_suites: true` 与 `live_models_only: true`。 - - 将新的高信号提供商密钥添加到 `scripts/ci-hydrate-live-auth.sh`，以及 `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` 和其 scheduled / release 调用方中。 +- Docker live 模型全量扫描：`pnpm test:docker:live-models` + - 现在每个选定模型都会运行一轮文本交互以及一个小型文件读取风格探测。元数据声明支持 `image` 输入的模型还会运行一次微型图像交互。在隔离提供商故障时，可通过 `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` 或 `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` 禁用这些额外探测。 + - CI 覆盖：每日执行的 `OpenClaw Scheduled Live And E2E Checks` 和手动执行的 `OpenClaw Release Checks` 都会调用可复用的 live/E2E 工作流，并设置 `include_live_suites: true`，其中包含按提供商分片的独立 Docker live 模型矩阵作业。 + - 如需进行聚焦的 CI 重跑，可分发 `OpenClaw Live And E2E Checks (Reusable)`，并设置 `include_live_suites: true` 与 `live_models_only: true`。 + - 将新的高信号提供商密钥添加到 `scripts/ci-hydrate-live-auth.sh`、`.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` 以及其定时/发布调用方中。 - 原生 Codex 绑定聊天冒烟测试：`pnpm test:docker:live-codex-bind` - - 在 Codex app-server 路径上运行一个 Docker live 通道，使用 `/codex bind` 绑定一个合成 Slack 私信，执行 `/codex fast` 和 `/codex permissions`，然后验证普通回复和图像附件都通过原生插件绑定而不是 ACP 路由。 -- Crestodian rescue command 冒烟测试：`pnpm test:live:crestodian-rescue-channel` - - 针对消息渠道 rescue command 表面的可选双保险检查。它会执行 `/crestodian status`，排入一个持久模型更改，回复 `/crestodian yes`，并验证审计 / 配置写入路径。 + - 在 Docker live 通道中针对 Codex app-server 路径运行测试，使用 `/codex bind` 绑定一个合成的 Slack 私信，执行 `/codex fast` 和 `/codex permissions`，然后验证普通回复和图像附件是通过原生插件绑定路由，而不是通过 ACP。 +- Crestodian rescue 命令冒烟测试：`pnpm test:live:crestodian-rescue-channel` + - 这是消息渠道 rescue 命令表面的一个可选、双重保险检查。它会执行 `/crestodian status`，排队一个持久化模型变更，回复 `/crestodian yes`，并验证审计/配置写入路径。 - Crestodian planner Docker 冒烟测试：`pnpm test:docker:crestodian-planner` - - 在一个无配置容器中运行 Crestodian，并在 `PATH` 上放置一个假的 Claude CLI，验证模糊 planner 回退会转换为带审计的类型化配置写入。 + - 在一个无配置容器中运行 Crestodian，并在 `PATH` 上放置一个假的 Claude CLI，验证模糊规划器回退会转化为一条带审计的类型化配置写入。 - Crestodian 首次运行 Docker 冒烟测试：`pnpm test:docker:crestodian-first-run` - - 从空的 OpenClaw 状态目录启动，将裸 `openclaw` 路由到 Crestodian，应用 setup / model / agent / Discord plugin + SecretRef 写入，校验配置，并验证审计条目。同一 Ring 0 设置路径也在 QA Lab 中通过 `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup` 覆盖。 -- Moonshot / Kimi 成本冒烟测试：设置 `MOONSHOT_API_KEY` 后，运行 `openclaw models list --provider moonshot --json`，然后针对 `moonshot/kimi-k2.6` 运行独立命令 `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - 。验证 JSON 报告的是 Moonshot / K2.6，并且 assistant transcript 存储了规范化的 `usage.cost`。 + - 从一个空的 OpenClaw 状态目录启动，将裸 `openclaw` 路由到 Crestodian，应用 setup/model/agent/Discord plugin + SecretRef 写入，验证配置，并校验审计条目。相同的 Ring 0 设置路径也会在 QA Lab 中通过 `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup` 覆盖。 +- Moonshot/Kimi 成本冒烟测试：设置 `MOONSHOT_API_KEY` 后，运行 `openclaw models list --provider moonshot --json`，然后针对 `moonshot/kimi-k2.6` 运行隔离的 `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json`。验证 JSON 报告的是 Moonshot/K2.6，且 assistant transcript 存储了归一化后的 `usage.cost`。 -提示：如果你只需要一个失败用例，优先使用下面描述的 allowlist 环境变量来缩小 live 测试范围。 +提示：当你只需要一个失败用例时，优先使用下文所述的 allowlist 环境变量来缩小 live 测试范围。 ## QA 专用运行器 -当你需要 QA-lab 级别的真实感时，这些命令与主测试套件配套使用： +当你需要接近 QA-lab 的真实环境时，这些命令与主测试套件并列使用： -CI 会在专用工作流中运行 QA Lab。`Parity gate` 会在匹配的 PR 上以及手动派发时以 mock 提供商运行。`QA-Lab - All Lanes` 会在 `main` 上每晚运行，也可手动派发，作为并行作业运行 mock parity gate、live Matrix 通道以及 Convex 管理的 live Telegram 通道。`OpenClaw Release Checks` 会在发布审批前运行相同通道。 +CI 会在专用工作流中运行 QA Lab。`Parity gate` 会在匹配的 PR 上运行，也可以通过手动分发使用 mock 提供商运行。`QA-Lab - All Lanes` 会在 `main` 上每晚运行，也可通过手动分发运行，并将 mock parity gate、live Matrix 通道以及 Convex 管理的 live Telegram 通道作为并行作业执行。`OpenClaw Release Checks` 会在发布批准前运行相同的通道。 - `pnpm openclaw qa suite` - 直接在主机上运行基于仓库的 QA 场景。 - - 默认并行运行多个选定场景，并使用隔离的 Gateway 网关 worker。`qa-channel` 默认并发数为 4（受所选场景数量限制）。使用 `--concurrency ` 调整 worker 数量，或使用 `--concurrency 1` 运行旧的串行通道。 - - 任一场景失败时以非零状态退出。如果你想获取产物但不希望退出码失败，可使用 `--allow-failures`。 - - 支持提供商模式 `live-frontier`、`mock-openai` 和 `aimock`。`aimock` 会启动一个本地的 AIMock 支持的 provider 服务器，用于实验性 fixture 和协议 mock 覆盖，而不会替代具备场景感知能力的 `mock-openai` 通道。 + - 默认情况下会使用隔离的 Gateway 网关工作进程并行运行多个选定场景。`qa-channel` 默认并发度为 4（受所选场景数量限制）。使用 `--concurrency ` 调整工作进程数量，或使用 `--concurrency 1` 回退到旧的串行通道。 + - 任一场景失败时将以非零状态退出。当你希望保留产物但不返回失败退出码时，使用 `--allow-failures`。 + - 支持提供商模式 `live-frontier`、`mock-openai` 和 `aimock`。`aimock` 会启动一个本地的 AIMock 支持提供商服务器，用于实验性的夹具和协议 mock 覆盖，但不会替代带有场景感知能力的 `mock-openai` 通道。 - `pnpm openclaw qa suite --runner multipass` - - 在一次性的 Multipass Linux VM 中运行同一 QA 套件。 + - 在一次性 Multipass Linux VM 中运行相同的 QA 套件。 - 保持与主机上 `qa suite` 相同的场景选择行为。 - - 复用与 `qa suite` 相同的 provider / model 选择标志。 - - live 运行会转发对来宾系统切实可行的受支持 QA 认证输入：基于环境变量的 provider 密钥、QA live provider 配置路径，以及存在时的 `CODEX_HOME`。 - - 输出目录必须保持在仓库根目录下，这样来宾系统才能通过挂载的工作区写回内容。 - - 在 `.artifacts/qa-e2e/...` 下写入常规 QA 报告 + 摘要以及 Multipass 日志。 + - 复用与 `qa suite` 相同的提供商/模型选择标志。 + - live 运行会转发对来宾系统可行的受支持 QA 认证输入：基于环境变量的提供商密钥、QA live 提供商配置路径，以及存在时的 `CODEX_HOME`。 + - 输出目录必须保留在仓库根目录下，以便来宾系统可以通过挂载的工作区回写。 + - 会在 `.artifacts/qa-e2e/...` 下写入常规 QA 报告 + 摘要以及 Multipass 日志。 - `pnpm qa:lab:up` - - 启动基于 Docker 的 QA 站点，用于偏操作员风格的 QA 工作。 + - 启动 Docker 支持的 QA 站点，用于偏操作员风格的 QA 工作。 - `pnpm test:docker:npm-onboard-channel-agent` - - 从当前 checkout 构建一个 npm tarball，在 Docker 中全局安装，运行非交互式 OpenAI API key 新手引导，默认配置 Telegram，验证启用该 plugin 会按需安装运行时依赖，运行 doctor，并对一个 mocked OpenAI 端点执行一次本地智能体轮次。 - - 使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 可在 Discord 上运行同样的打包安装通道。 + - 从当前 checkout 构建一个 npm tarball，在 Docker 中全局安装，以非交互方式完成 OpenAI API 密钥新手引导，默认配置 Telegram，验证启用插件会按需安装运行时依赖，运行 doctor，并针对一个 mocked OpenAI 端点执行一次本地智能体交互。 + - 使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 可在 Discord 上运行相同的打包安装通道。 - `pnpm test:docker:npm-telegram-live` - - 在 Docker 中安装一个已发布的 OpenClaw 包，运行已安装包的新手引导，通过已安装的 CLI 配置 Telegram，然后复用 live Telegram QA 通道，并将该已安装包作为被测 Gateway 网关。 - - 默认使用 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`。 - - 使用与 `pnpm openclaw qa telegram` 相同的 Telegram 环境变量凭证或 Convex 凭证来源。对于 CI / 发布自动化，设置 `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex`，以及 `OPENCLAW_QA_CONVEX_SITE_URL` 和角色密钥。如果在 CI 中存在 `OPENCLAW_QA_CONVEX_SITE_URL` 和 Convex 角色密钥，Docker 包装器会自动选择 Convex。 - - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` 仅为该通道覆盖共享的 `OPENCLAW_QA_CREDENTIAL_ROLE`。 - - GitHub Actions 将该通道暴露为手动维护者工作流 `NPM Telegram Beta E2E`。它不会在合并时运行。该工作流使用 `qa-live-shared` 环境和 Convex CI 凭证租约。 + - 在 Docker 中安装一个已发布的 OpenClaw 包，运行已安装包的新手引导，通过已安装的 CLI 配置 Telegram，然后复用 live Telegram QA 通道，并将该已安装包作为 SUT Gateway 网关。 + - 默认为 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`。 + - 与 `pnpm openclaw qa telegram` 使用相同的 Telegram 环境变量凭证或 Convex 凭证源。对于 CI/发布自动化，设置 `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex`，再加上 `OPENCLAW_QA_CONVEX_SITE_URL` 和角色密钥。如果在 CI 中存在 `OPENCLAW_QA_CONVEX_SITE_URL` 和 Convex 角色密钥，则 Docker 包装器会自动选择 Convex。 + - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` 仅为此通道覆盖共享的 `OPENCLAW_QA_CREDENTIAL_ROLE`。 + - GitHub Actions 将此通道暴露为手动维护者工作流 `NPM Telegram Beta E2E`。它不会在合并时运行。该工作流使用 `qa-live-shared` 环境和 Convex CI 凭证租约。 - `pnpm test:docker:bundled-channel-deps` - - 在 Docker 中打包并安装当前 OpenClaw 构建，启动已配置 OpenAI 的 Gateway 网关，然后通过配置编辑启用内置 channel / plugins。 - - 验证 setup 发现流程会让未配置 plugin 的运行时依赖保持缺失状态，首次运行已配置的 Gateway 网关或 doctor 时会按需安装每个内置 plugin 的运行时依赖，而第二次重启不会重新安装已激活的依赖。 - - 还会安装一个已知的较旧 npm 基线版本，在运行 `openclaw update --tag ` 之前启用 Telegram，并验证候选版本的更新后 doctor 会修复内置 channel 的运行时依赖，而不依赖 harness 侧的 postinstall 修复。 + - 在 Docker 中打包并安装当前 OpenClaw 构建，使用已配置的 OpenAI 启动 Gateway 网关，然后通过编辑配置启用内置渠道/plugin。 + - 验证 setup 发现流程会让未配置 plugin 的运行时依赖保持缺失状态；首次运行已配置的 Gateway 网关或 doctor 时，会按需安装每个内置 plugin 的运行时依赖；第二次重启不会重复安装已经激活的依赖。 + - 还会安装一个已知的较旧 npm 基线版本，在运行 `openclaw update --tag ` 前启用 Telegram，并验证候选版本的更新后 doctor 能修复内置渠道运行时依赖，而无需 harness 侧的 postinstall 修复。 - `pnpm test:parallels:npm-update` - - 在 Parallels 来宾系统中运行原生打包安装更新冒烟测试。每个选中的平台都会先安装请求的基线包，然后在同一来宾中运行已安装的 `openclaw update` 命令，并验证已安装版本、更新状态、gateway 就绪情况，以及一次本地智能体轮次。 - - 在迭代单个来宾时使用 `--platform macos`、`--platform windows` 或 `--platform linux`。使用 `--json` 获取摘要产物路径和各通道状态。 - - 将长时间本地运行包装在主机超时内，这样 Parallels 传输停顿就不会耗尽整个测试窗口： + - 在 Parallels 来宾系统中运行原生打包安装更新冒烟测试。每个选定平台都会先安装所请求的基线包，然后在同一个来宾系统中运行已安装的 `openclaw update` 命令，并验证已安装版本、更新状态、gateway 就绪情况以及一次本地智能体交互。 + - 在迭代单个来宾系统时，可使用 `--platform macos`、`--platform windows` 或 `--platform linux`。使用 `--json` 获取摘要产物路径和每个通道的状态。 + - 将较长的本地运行包装在主机超时中，以免 Parallels 传输停滞占用剩余测试窗口： ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - 该脚本会将嵌套通道日志写入 `/tmp/openclaw-parallels-npm-update.*`。在假定外层包装器卡住之前，先检查 `windows-update.log`、`macos-update.log` 或 `linux-update.log`。 - - 在冷启动来宾上，Windows 更新在更新后的 doctor / 运行时依赖修复阶段可能花费 10 到 15 分钟；只要嵌套的 npm 调试日志仍在推进，这仍然是健康状态。 - - 不要将这个聚合包装器与单独的 Parallels macOS、Windows 或 Linux 冒烟通道并行运行。它们共享 VM 状态，可能会在快照恢复、包服务或来宾 gateway 状态上发生冲突。 - - 更新后的验证会运行常规的内置 plugin 表面，因为诸如语音、图像生成和媒体理解等能力外观层是通过内置运行时 API 加载的，即使智能体轮次本身只检查一个简单的文本响应。 + - 该脚本会将嵌套通道日志写入 `/tmp/openclaw-parallels-npm-update.*`。在认为外层包装器卡住之前，请先检查 `windows-update.log`、`macos-update.log` 或 `linux-update.log`。 + - Windows 更新在冷启动来宾系统上，更新后的 doctor/运行时依赖修复阶段可能需要 10 到 15 分钟；只要嵌套的 npm 调试日志仍在推进，这就仍属健康状态。 + - 不要将这个聚合包装器与单独的 Parallels macOS、Windows 或 Linux 冒烟通道并行运行。它们共享 VM 状态，可能在快照恢复、包服务或来宾 gateway 状态上发生冲突。 + - 更新后验证会运行常规的内置 plugin 表面，因为即使智能体交互本身只检查简单的文本响应，诸如语音、图像生成和媒体理解等能力外观层，仍是通过内置运行时 API 加载的。 - `pnpm openclaw qa aimock` - - 仅启动本地 AIMock provider 服务器，用于直接协议冒烟测试。 + - 仅启动本地 AIMock 提供商服务器，用于直接的协议冒烟测试。 - `pnpm openclaw qa matrix` - - 针对一次性的、基于 Docker 的 Tuwunel homeserver 运行 Matrix live QA 通道。 - - 这个 QA 主机目前仅供仓库 / 开发使用。打包安装的 OpenClaw 不包含 `qa-lab`，因此不会暴露 `openclaw qa`。 - - 仓库 checkout 会直接加载内置运行器；不需要单独安装 plugin。 - - 预配三个临时 Matrix 用户（`driver`、`sut`、`observer`）以及一个私有房间，然后启动一个 QA gateway 子进程，并使用真实的 Matrix plugin 作为 SUT 传输层。 - - 默认使用固定的稳定版 Tuwunel 镜像 `ghcr.io/matrix-construct/tuwunel:v1.5.1`。当你需要测试其他镜像时，可用 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 覆盖。 - - Matrix 不暴露共享 credential-source 标志，因为该通道会在本地预配一次性用户。 - - 在 `.artifacts/qa-e2e/...` 下写入 Matrix QA 报告、摘要、observed-events 产物，以及合并的 stdout / stderr 输出日志。 - - 默认输出进度，并通过 `OPENCLAW_QA_MATRIX_TIMEOUT_MS` 强制执行硬性运行超时（默认 30 分钟）。清理由 `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` 限定，失败信息中会包含用于恢复的 `docker compose ... down --remove-orphans` 命令。 + - 针对一次性的 Docker 支持 Tuwunel homeserver 运行 Matrix live QA 通道。 + - 这个 QA 主机目前仅供仓库/开发环境使用。打包后的 OpenClaw 安装不附带 `qa-lab`，因此不会暴露 `openclaw qa`。 + - 仓库 checkout 会直接加载内置运行器；无需单独的插件安装步骤。 + - 预配三个临时 Matrix 用户（`driver`、`sut`、`observer`）以及一个私有房间，然后启动一个以真实 Matrix plugin 作为 SUT 传输层的 QA gateway 子进程。 + - 默认使用固定稳定版 Tuwunel 镜像 `ghcr.io/matrix-construct/tuwunel:v1.5.1`。如果你需要测试其他镜像，可使用 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 覆盖。 + - Matrix 不暴露共享凭证源标志，因为该通道会在本地预配一次性用户。 + - 会在 `.artifacts/qa-e2e/...` 下写入 Matrix QA 报告、摘要、observed-events 产物，以及合并后的 stdout/stderr 输出日志。 + - 默认会输出进度，并通过 `OPENCLAW_QA_MATRIX_TIMEOUT_MS` 强制执行硬性运行超时（默认 30 分钟）。清理由 `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` 限制，失败时会包含恢复命令 `docker compose ... down --remove-orphans`。 - `pnpm openclaw qa telegram` - - 使用来自环境变量的 driver 和 SUT bot token，针对真实私有群组运行 Telegram live QA 通道。 + - 使用环境变量中的 driver 和 SUT bot token，针对真实私有群组运行 Telegram live QA 通道。 - 需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`。群组 id 必须是 Telegram chat 的数字 id。 - - 支持 `--credential-source convex` 以使用共享池化凭证。默认使用环境变量模式，或设置 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` 以启用池化租约。 - - 任一场景失败时以非零状态退出。如果你想获取产物但不希望退出码失败，可使用 `--allow-failures`。 - - 需要同一私有群组中的两个不同 bot，并且 SUT bot 必须暴露 Telegram 用户名。 - - 为了稳定地观察 bot 与 bot 之间的交互，请在 `@BotFather` 中为两个 bot 启用 Bot-to-Bot Communication Mode，并确保 driver bot 能观察群组中的 bot 流量。 - - 在 `.artifacts/qa-e2e/...` 下写入 Telegram QA 报告、摘要和 observed-messages 产物。回复场景会包含从 driver 发送请求到观察到 SUT 回复之间的 RTT。 + - 支持 `--credential-source convex` 以使用共享凭证池。默认使用环境变量模式，或设置 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` 以启用池化租约。 + - 任一场景失败时将以非零状态退出。当你希望保留产物但不返回失败退出码时，使用 `--allow-failures`。 + - 需要同一私有群组中的两个不同 bot，且 SUT bot 必须暴露 Telegram 用户名。 + - 为了稳定观察 bot 与 bot 之间的交互，请在 `@BotFather` 中为两个 bot 启用 Bot-to-Bot Communication Mode，并确保 driver bot 可以观察群组中的 bot 流量。 + - 会在 `.artifacts/qa-e2e/...` 下写入 Telegram QA 报告、摘要和 observed-messages 产物。回复类场景还会包含从 driver 发送请求到观察到 SUT 回复的 RTT。 -live 传输通道共享一个标准契约，因此新传输不会发生漂移： +live 传输通道共享一套标准契约，以防新传输层发生漂移： -`qa-channel` 仍然是广泛的合成 QA 套件，不属于 live 传输覆盖矩阵的一部分。 +`qa-channel` 仍然是覆盖面更广的合成 QA 套件，不属于 live 传输覆盖矩阵的一部分。 -| 通道 | Canary | Mention gating | Allowlist block | 顶层回复 | 重启恢复 | 线程后续跟进 | 线程隔离 | 表情反应观测 | 帮助命令 | -| ---- | ------ | -------------- | --------------- | -------- | -------- | ------------ | -------- | ------------ | -------- | +| 通道 | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | +| ---- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | | Matrix | x | x | x | x | x | x | x | x | | | Telegram | x | | | | | | | | x | ### 通过 Convex 共享 Telegram 凭证（v1） -当为 `openclaw qa telegram` 启用 `--credential-source convex`（或 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）时，QA lab 会从一个由 Convex 支持的凭证池中获取独占租约，在通道运行期间为该租约发送心跳，并在关闭时释放租约。 +当为 `openclaw qa telegram` 启用 `--credential-source convex`（或 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）时，QA lab 会从 Convex 支持的凭证池中获取一个独占租约，在通道运行期间为该租约发送心跳，并在关闭时释放该租约。 参考 Convex 项目脚手架： @@ -148,12 +147,12 @@ live 传输通道共享一个标准契约，因此新传输不会发生漂移： 必需的环境变量： - `OPENCLAW_QA_CONVEX_SITE_URL`（例如 `https://your-deployment.convex.site`） -- 为所选角色提供一个 secret： - - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`，用于 `maintainer` - - `OPENCLAW_QA_CONVEX_SECRET_CI`，用于 `ci` +- 所选角色对应的一个密钥： + - `maintainer` 使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` + - `ci` 使用 `OPENCLAW_QA_CONVEX_SECRET_CI` - 凭证角色选择： - CLI：`--credential-role maintainer|ci` - - 默认环境变量：`OPENCLAW_QA_CREDENTIAL_ROLE`（在 CI 中默认是 `ci`，否则默认是 `maintainer`） + - 环境变量默认值：`OPENCLAW_QA_CREDENTIAL_ROLE`（在 CI 中默认为 `ci`，否则默认为 `maintainer`） 可选环境变量： @@ -167,10 +166,9 @@ live 传输通道共享一个标准契约，因此新传输不会发生漂移： 正常运行时，`OPENCLAW_QA_CONVEX_SITE_URL` 应使用 `https://`。 -维护者管理命令（池添加 / 删除 / 列表）必须明确要求 -`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`。 +维护者管理命令（池的添加/移除/列出）必须专门使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`。 -维护者的 CLI 辅助命令： +供维护者使用的 CLI 辅助命令： ```bash pnpm openclaw qa credentials doctor @@ -179,85 +177,85 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -在 live 运行前使用 `doctor` 检查 Convex 站点 URL、broker secret、端点前缀、HTTP 超时以及管理 / 列表可达性，且不会打印 secret 值。在脚本和 CI 工具中使用 `--json` 获取机器可读输出。 +在 live 运行前使用 `doctor`，以检查 Convex site URL、broker 密钥、端点前缀、HTTP 超时和 admin/list 可达性，同时不会打印密钥值。在脚本和 CI 工具中可使用 `--json` 获取机器可读输出。 默认端点契约（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）： - `POST /acquire` - 请求：`{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - 成功：`{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - 耗尽 / 可重试：`{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - 资源耗尽/可重试：`{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - 请求：`{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - 成功：`{ status: "ok" }`（或空的 `2xx`） - `POST /release` - 请求：`{ kind, ownerId, actorRole, credentialId, leaseToken }` - 成功：`{ status: "ok" }`（或空的 `2xx`） -- `POST /admin/add`（仅限 maintainer secret） +- `POST /admin/add`（仅限 maintainer 密钥） - 请求：`{ kind, actorId, payload, note?, status? }` - 成功：`{ status: "ok", credential }` -- `POST /admin/remove`（仅限 maintainer secret） +- `POST /admin/remove`（仅限 maintainer 密钥） - 请求：`{ credentialId, actorId }` - 成功：`{ status: "ok", changed, credential }` - 活跃租约保护：`{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list`（仅限 maintainer secret） +- `POST /admin/list`（仅限 maintainer 密钥） - 请求：`{ kind?, status?, includePayload?, limit? }` - 成功：`{ status: "ok", credentials, count }` -Telegram 类型的负载结构： +Telegram 类型的 payload 结构： - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` 必须是 Telegram chat 的数字 id 字符串。 -- 对于 `kind: "telegram"`，`admin/add` 会校验该结构，并拒绝格式错误的负载。 +- `groupId` 必须是 Telegram chat 数字 id 的字符串形式。 +- `admin/add` 会对 `kind: "telegram"` 校验该结构，并拒绝格式错误的 payload。 ### 向 QA 添加一个渠道 -向 Markdown QA 系统添加一个渠道，严格来说只需要两样东西： +向 Markdown QA 系统添加一个渠道，严格只需要两样东西： 1. 该渠道的传输适配器。 -2. 一个用于验证该渠道契约的场景包。 +2. 一组用于验证渠道契约的场景包。 -当共享的 `qa-lab` 主机能够承载流程时，不要新增顶层 QA 命令根。 +如果共享的 `qa-lab` 主机可以承载流程，就不要新增顶层 QA 命令根。 `qa-lab` 负责共享主机机制： - `openclaw qa` 命令根 - 套件启动与拆除 -- worker 并发 +- 工作进程并发 - 产物写入 - 报告生成 - 场景执行 -- 旧 `qa-channel` 场景的兼容性别名 +- 对旧 `qa-channel` 场景的兼容别名 -运行器 plugins 负责传输契约： +运行器 plugin 负责传输契约： -- `openclaw qa ` 如何挂载到共享 `qa` 根命令下 +- 如何将 `openclaw qa ` 挂载到共享 `qa` 根之下 - 如何为该传输配置 gateway - 如何检查就绪状态 - 如何注入入站事件 -- 如何观测出站消息 -- 如何暴露 transcript 和标准化传输状态 -- 如何执行由传输支持的动作 -- 如何处理传输专属的重置或清理 +- 如何观察出站消息 +- 如何暴露 transcript 和归一化后的传输状态 +- 如何执行传输支持的动作 +- 如何处理传输特定的重置或清理 -新渠道的最低采纳门槛是： +新渠道的最低接入门槛是： -1. 保持由 `qa-lab` 作为共享 `qa` 根命令的拥有者。 +1. 保持由 `qa-lab` 拥有共享的 `qa` 根。 2. 在共享的 `qa-lab` 主机接缝上实现传输运行器。 -3. 将传输专属机制保留在运行器 plugin 或 channel harness 内部。 -4. 将运行器挂载为 `openclaw qa `，而不是注册一个竞争性的根命令。运行器 plugins 应在 `openclaw.plugin.json` 中声明 `qaRunners`，并从 `runtime-api.ts` 导出匹配的 `qaRunnerCliRegistrations` 数组。保持 `runtime-api.ts` 轻量；延迟 CLI 和运行器执行应置于独立入口点之后。 +3. 将传输特定机制保留在运行器 plugin 或渠道 harness 内部。 +4. 将运行器挂载为 `openclaw qa `，而不是注册一个相互竞争的根命令。运行器 plugin 应在 `openclaw.plugin.json` 中声明 `qaRunners`，并从 `runtime-api.ts` 导出匹配的 `qaRunnerCliRegistrations` 数组。保持 `runtime-api.ts` 轻量；惰性 CLI 与运行器执行应保留在独立入口点之后。 5. 在主题化的 `qa/scenarios/` 目录下编写或改造 Markdown 场景。 -6. 对新场景使用通用场景辅助函数。 -7. 除非仓库正在进行有意迁移，否则保持现有兼容性别名继续可用。 +6. 为新场景使用通用场景辅助工具。 +7. 保持现有兼容别名继续可用，除非仓库正在进行有意的迁移。 决策规则很严格： -- 如果某种行为可以在 `qa-lab` 中统一表达一次，就把它放在 `qa-lab`。 -- 如果某种行为依赖某一个渠道传输，就把它保留在对应的运行器 plugin 或 plugin harness 中。 -- 如果某个场景需要一个以上渠道可用的新能力，请添加一个通用辅助函数，而不是在 `suite.ts` 中加入渠道专属分支。 -- 如果某种行为只对一个传输有意义，请让该场景保持传输专属，并在场景契约中明确说明。 +- 如果某项行为可以在 `qa-lab` 中统一表达一次，就放到 `qa-lab` 中。 +- 如果某项行为依赖某一个渠道传输层，就把它保留在该运行器 plugin 或 plugin harness 中。 +- 如果某个场景需要一种可被多个渠道复用的新能力，就添加一个通用辅助工具，而不是在 `suite.ts` 中加入渠道专属分支。 +- 如果某项行为只对一种传输有意义，就让该场景保持传输专属，并在场景契约中明确说明。 -新场景推荐使用的通用辅助函数名称： +新场景推荐的通用辅助工具名称： - `waitForTransportReady` - `waitForChannelReady` @@ -272,7 +270,7 @@ Telegram 类型的负载结构： - `formatTransportTranscript` - `resetTransport` -现有场景仍可使用兼容性别名，包括： +现有场景仍可使用的兼容别名包括： - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -280,20 +278,20 @@ Telegram 类型的负载结构： - `formatConversationTranscript` - `resetBus` -新的渠道工作应使用通用辅助函数名称。 -兼容性别名的存在是为了避免一次性大迁移，而不是作为新场景编写的范式。 +新的渠道工作应使用通用辅助工具名称。 +兼容别名的存在是为了避免一次性迁移，而不是作为新场景编写的范式。 -## 测试套件（哪些内容在哪里运行） +## 测试套件（各自运行位置） -可以把这些套件理解为“真实度逐步提升”（同时脆弱性 / 成本也逐步增加）： +可以把这些套件理解为“真实性逐步提高”（同时不稳定性/成本也逐步提高）： -### 单元 / 集成（默认） +### Unit / integration（默认） - 命令：`pnpm test` -- 配置：未定向运行使用 `vitest.full-*.config.ts` 分片集合，并且可能会将多项目分片展开为逐项目配置，以进行并行调度 -- 文件：核心 / 单元清单位于 `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts`，以及 `vitest.unit.config.ts` 覆盖的白名单 `ui` Node 测试 +- 配置：未定向运行会使用 `vitest.full-*.config.ts` 分片集合，并可能将多项目分片展开为逐项目配置，以便进行并行调度 +- 文件：核心/unit 清单位于 `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts`，以及 `vitest.unit.config.ts` 覆盖的白名单 `ui` node 测试 - 范围： - - 纯单元测试 + - 纯 unit 测试 - 进程内集成测试（gateway 认证、路由、工具、解析、配置） - 已知缺陷的确定性回归测试 - 预期： @@ -302,100 +300,101 @@ Telegram 类型的负载结构： - 应该快速且稳定 - + - - 未定向的 `pnpm test` 会运行十二个更小的分片配置（`core-unit-fast`、`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`），而不是一个巨大的原生根项目进程。这样可以降低繁忙机器上的峰值 RSS，并避免 auto-reply / extension 工作拖累无关套件。 - - `pnpm test --watch` 仍然使用原生根 `vitest.config.ts` 项目图，因为多分片 watch 循环并不实际。 - - `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 会先通过定向通道来路由显式文件 / 目录目标，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 无需承担完整根项目启动成本。 - - 当 diff 只触及可路由的源文件 / 测试文件时，`pnpm test:changed` 会将变更的 git 路径展开到相同的定向通道；配置 / setup 编辑则仍会回退到更广泛的根项目重跑。 - - `pnpm check:changed` 是针对窄范围工作的常规智能本地门禁。它会将 diff 分类为 core、core tests、extensions、extension tests、apps、docs、release metadata 和 tooling，然后运行匹配的 typecheck / lint / test 通道。公开的 Plugin SDK 和 plugin 契约变更会额外包含一次 extension 校验，因为 extensions 依赖这些 core 契约。仅涉及发布元数据的版本提升会运行定向的版本 / 配置 / 根依赖检查，而不是完整套件，并带有一个保护机制，用于拒绝顶层版本字段以外的包变更。 - - 来自 agents、commands、plugins、auto-reply 辅助函数、`plugin-sdk` 以及类似纯工具区域的轻导入单元测试会路由到 `unit-fast` 通道，该通道会跳过 `test/setup-openclaw-runtime.ts`；有状态 / 运行时负担较重的文件仍保留在现有通道中。 - - 部分选定的 `plugin-sdk` 和 `commands` 辅助源文件，也会在 changed 模式运行时映射到这些轻量通道中的显式同级测试，因此辅助函数编辑无需为该目录重跑完整的重型套件。 - - `auto-reply` 有三个专用桶：顶层 core 辅助函数、顶层 `reply.*` 集成测试，以及 `src/auto-reply/reply/**` 子树。这使最重的 reply harness 工作不会落到廉价的 status / chunk / token 测试上。 + - 未定向的 `pnpm test` 会运行 12 个更小的分片配置（`core-unit-fast`、`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`），而不是一个巨大的原生根项目进程。这样可以降低高负载机器上的 RSS 峰值，并避免 auto-reply/扩展工作拖慢无关套件。 + - `pnpm test --watch` 仍然使用原生根 `vitest.config.ts` 项目图，因为多分片监听循环并不现实。 + - `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 会先通过定向通道来路由显式的文件/目录目标，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 可以避免承担完整根项目启动的成本。 + - `pnpm test:changed` 会在差异仅涉及可路由的源码/测试文件时，将变更的 git 路径展开到相同的定向通道；配置/setup 编辑仍会回退到更广泛的根项目重跑。 + - `pnpm check:changed` 是窄范围工作时常规的智能本地门禁。它会将差异分类为 core、core tests、extensions、extension tests、apps、docs、发布元数据和工具链，然后运行匹配的 typecheck/lint/test 通道。公开的 Plugin SDK 和 plugin-contract 变更会额外包含一次扩展验证，因为扩展依赖这些 core 契约。仅包含发布元数据版本号变更的情况，会运行定向的版本/配置/根依赖检查，而不是完整套件，并带有一个保护机制，用于拒绝顶层版本字段之外的包变更。 + - 来自 agents、commands、plugins、auto-reply 辅助工具、`plugin-sdk` 以及类似纯工具区域的轻导入 unit 测试，会路由到 `unit-fast` 通道，该通道会跳过 `test/setup-openclaw-runtime.ts`；有状态/运行时较重的文件则保留在现有通道中。 + - 部分选定的 `plugin-sdk` 和 `commands` 辅助源码文件，也会在 changed 模式运行中映射到这些轻量通道中的显式同级测试，因此辅助工具编辑无需为该目录重跑完整的重型套件。 + - `auto-reply` 为顶层 core 辅助工具、顶层 `reply.*` 集成测试以及 `src/auto-reply/reply/**` 子树提供了专用分桶。CI 还会将 reply 子树进一步拆分为 agent-runner、dispatch 以及 commands/state-routing 分片，这样单个导入较重的桶就不会独占完整的 Node 尾部执行时间。 - + - - 当你修改消息工具发现输入或 compaction 运行时上下文时，要保持两个层级的覆盖都在。 - - 为纯路由和标准化边界添加聚焦的辅助函数回归测试。 - - 保持内嵌运行器集成套件健康： + - 当你更改消息工具发现输入或压缩运行时上下文时，请同时保留两个层级的覆盖。 + - 为纯路由和归一化边界添加聚焦的辅助工具回归测试。 + - 保持嵌入式运行器集成套件健康： `src/agents/pi-embedded-runner/compact.hooks.test.ts`、 `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` 和 `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`。 - - 这些套件会验证带作用域的 id 和 compaction 行为仍然经过真实的 `run.ts` / `compact.ts` 路径；仅有辅助函数测试并不能充分替代这些集成路径。 + - 这些套件用于验证作用域 id 和压缩行为仍会流经真实的 `run.ts` / `compact.ts` 路径；仅有辅助工具测试并不能充分替代这些集成路径。 - + - 基础 Vitest 配置默认使用 `threads`。 - - 共享的 Vitest 配置固定 `isolate: false`，并在根项目、e2e 和 live 配置中使用非隔离运行器。 - - 根 UI 通道保留其 `jsdom` setup 和优化器，但同样运行在共享的非隔离运行器上。 - - 每个 `pnpm test` 分片都从共享的 Vitest 配置继承相同的 `threads` + `isolate: false` 默认值。 - - `scripts/run-vitest.mjs` 默认会为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行期间的 V8 编译抖动。设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1` 可与默认 V8 行为进行对比。 + - 共享 Vitest 配置固定为 `isolate: false`，并在根项目、e2e 和 live 配置中使用非隔离运行器。 + - 根 UI 通道保留其 `jsdom` setup 和优化器，但也运行在共享的非隔离运行器上。 + - 每个 `pnpm test` 分片都会从共享 Vitest 配置继承相同的 `threads` + `isolate: false` 默认值。 + - `scripts/run-vitest.mjs` 默认会为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行期间的 V8 编译抖动。设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1` 可对比原生 V8 行为。 - - `pnpm changed:lanes` 会显示某个 diff 会触发哪些架构通道。 - - pre-commit hook 只做格式化。它会重新暂存已格式化文件，不会运行 lint、typecheck 或测试。 - - 当你需要智能本地门禁时，在交接或 push 之前显式运行 `pnpm check:changed`。公开的 Plugin SDK 和 plugin 契约变更会包含一次 extension 校验。 - - 当变更路径能明确映射到更小的套件时，`pnpm test:changed` 会通过定向通道进行路由。 + - `pnpm changed:lanes` 会显示某个差异会触发哪些架构通道。 + - pre-commit hook 仅做格式化。它会重新暂存已格式化的文件，但不会运行 lint、typecheck 或测试。 + - 在交接或推送前，如果你需要智能本地门禁，请显式运行 `pnpm check:changed`。公开的 Plugin SDK 和 plugin-contract 变更会包含一次扩展验证。 + - 当变更路径可以清晰映射到较小套件时，`pnpm test:changed` 会通过定向通道进行路由。 - `pnpm test:max` 和 `pnpm test:changed:max` 保持相同的路由行为，只是使用更高的 worker 上限。 - - 本地 worker 自动伸缩是有意保守的；当主机负载平均值已经较高时会主动回退，因此默认情况下多个并发 Vitest 运行造成的影响会更小。 - - 基础 Vitest 配置将项目 / 配置文件标记为 `forceRerunTriggers`，以便在测试接线变更时，changed 模式重跑仍然保持正确。 - - 该配置会在受支持的主机上保持启用 `OPENCLAW_VITEST_FS_MODULE_CACHE`；如果你希望为直接分析指定一个明确的缓存位置，请设置 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`。 + - 本地 worker 自动扩缩容故意采取保守策略，当主机负载平均值已经很高时会回退，因此默认情况下多个并发 Vitest 运行造成的影响会更小。 + - 基础 Vitest 配置会将项目/配置文件标记为 `forceRerunTriggers`，以便在测试布线发生变化时，changed 模式重跑仍保持正确。 + - 配置会在受支持主机上保持启用 `OPENCLAW_VITEST_FS_MODULE_CACHE`；如果你想为直接性能分析指定一个明确缓存位置，可设置 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`。 - - `pnpm test:perf:imports` 会启用 Vitest 导入时长报告以及导入细分输出。 - - `pnpm test:perf:imports:changed` 会将相同的性能分析视图限定到自 `origin/main` 以来发生变更的文件。 - - 当某个热点测试的大部分时间仍然花在启动导入上时，应将重依赖放在狭窄的本地 `*.runtime.ts` 接缝之后，并直接 mock 该接缝，而不是仅为了传给 `vi.mock(...)` 就深度导入运行时辅助函数。 - - `pnpm test:perf:changed:bench -- --ref ` 会将定向的 `test:changed` 与该已提交 diff 的原生根项目路径进行对比，并打印 wall time 以及 macOS 最大 RSS。 - - `pnpm test:perf:changed:bench -- --worktree` 会通过将变更文件列表路由到 `scripts/test-projects.mjs` 和根 Vitest 配置，对当前脏工作树进行基准测试。 - - `pnpm test:perf:profile:main` 会为 Vitest / Vite 启动与 transform 开销写出主线程 CPU profile。 - - `pnpm test:perf:profile:runner` 会在禁用文件并行的情况下，为单元套件写出运行器 CPU + heap profile。 + - `pnpm test:perf:imports` 会启用 Vitest 导入耗时报告以及导入明细输出。 + - `pnpm test:perf:imports:changed` 会将相同的性能分析视图限定为自 `origin/main` 以来发生变更的文件。 + - 分片耗时数据会写入 `.artifacts/vitest-shard-timings.json`。整份配置运行使用配置路径作为键；基于 include-pattern 的 CI 分片会附加分片名，以便可单独跟踪经过过滤的分片。 + - 当某个热点测试仍将大部分时间花在启动导入上时，应将重型依赖放在狭窄的本地 `*.runtime.ts` 接缝之后，并直接 mock 该接缝，而不是为了传给 `vi.mock(...)` 就深度导入运行时辅助工具。 + - `pnpm test:perf:changed:bench -- --ref ` 会将该提交差异下经路由的 `test:changed` 与原生根项目路径进行比较，并输出总耗时以及 macOS 最大 RSS。 + - `pnpm test:perf:changed:bench -- --worktree` 会通过将变更文件列表路由到 `scripts/test-projects.mjs` 和根 Vitest 配置，对当前未提交工作树进行基准测试。 + - `pnpm test:perf:profile:main` 会为 Vitest/Vite 启动和转换开销写出主线程 CPU profile。 + - `pnpm test:perf:profile:runner` 会在禁用文件并行的情况下，为 unit 套件写出运行器 CPU + heap profile。 -### 稳定性（Gateway 网关） +### 稳定性（gateway） - 命令：`pnpm test:stability:gateway` -- 配置：`vitest.gateway.config.ts`，强制使用一个 worker +- 配置：`vitest.gateway.config.ts`，强制单 worker - 范围： - - 启动一个默认启用诊断的真实 loopback Gateway 网关 - - 通过诊断事件路径驱动合成的 gateway 消息、memory 和大负载抖动 + - 启动一个默认启用诊断功能的真实 loopback Gateway 网关 + - 通过诊断事件路径驱动合成的 gateway 消息、内存和大负载 churn - 通过 Gateway 网关 WS RPC 查询 `diagnostics.stability` - - 覆盖诊断稳定性 bundle 持久化辅助函数 - - 断言记录器保持有界、合成 RSS 样本保持在压力预算之下，并且每个会话的队列深度都会回落到零 + - 覆盖诊断稳定性 bundle 持久化辅助工具 + - 断言记录器保持有界、合成 RSS 样本低于压力预算，并且每个会话的队列深度会回落到零 - 预期： - - 对 CI 安全且不需要密钥 - - 是用于稳定性回归跟进的窄通道，不是完整 Gateway 网关套件的替代品 + - 对 CI 安全且无需密钥 + - 这是用于稳定性回归跟进的窄通道，不可替代完整的 Gateway 网关套件 -### E2E（Gateway 网关冒烟） +### E2E（gateway 冒烟） - 命令：`pnpm test:e2e` - 配置：`vitest.e2e.config.ts` - 文件：`src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`，以及 `extensions/` 下的内置 plugin E2E 测试 - 运行时默认值： - - 使用 Vitest `threads`，并设置 `isolate: false`，与仓库其余部分保持一致。 + - 使用带 `isolate: false` 的 Vitest `threads`，与仓库其余部分保持一致。 - 使用自适应 worker（CI：最多 2 个，本地：默认 1 个）。 - 默认以静默模式运行，以减少控制台 I/O 开销。 -- 实用覆盖项： - - `OPENCLAW_E2E_WORKERS=` 用于强制指定 worker 数量（上限为 16）。 - - `OPENCLAW_E2E_VERBOSE=1` 用于重新启用详细控制台输出。 +- 常用覆盖项： + - `OPENCLAW_E2E_WORKERS=` 强制设置 worker 数量（上限为 16）。 + - `OPENCLAW_E2E_VERBOSE=1` 重新启用详细控制台输出。 - 范围： - 多实例 gateway 端到端行为 - - WebSocket / HTTP 表面、节点配对以及更重的网络交互 + - WebSocket/HTTP 表面、节点配对和更重的网络行为 - 预期： - - 在 CI 中运行（当在流水线中启用时） + - 会在 CI 中运行（当流水线中启用时） - 不需要真实密钥 - - 比单元测试有更多活动部件（可能更慢） + - 比 unit 测试涉及更多可变因素（可能更慢） ### E2E：OpenShell 后端冒烟 @@ -404,236 +403,234 @@ Telegram 类型的负载结构： - 范围： - 通过 Docker 在主机上启动一个隔离的 OpenShell gateway - 从临时本地 Dockerfile 创建一个沙箱 - - 通过真实的 `sandbox ssh-config` + SSH exec 练习 OpenClaw 的 OpenShell 后端 + - 通过真实的 `sandbox ssh-config` + SSH exec 来验证 OpenClaw 的 OpenShell 后端 - 通过沙箱 fs bridge 验证远端规范文件系统行为 - 预期： - 仅按需启用；不属于默认 `pnpm test:e2e` 运行的一部分 - 需要本地 `openshell` CLI 以及可用的 Docker daemon - 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，然后销毁测试 gateway 和沙箱 -- 实用覆盖项： - - `OPENCLAW_E2E_OPENSHELL=1` 用于在手动运行更广泛的 e2e 套件时启用该测试 - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` 用于指向非默认 CLI 二进制或包装脚本 +- 常用覆盖项： + - `OPENCLAW_E2E_OPENSHELL=1` 在手动运行更广泛的 e2e 套件时启用此测试 + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` 指向非默认 CLI 二进制或包装脚本 -### live（真实提供商 + 真实模型） +### Live（真实提供商 + 真实模型） - 命令：`pnpm test:live` - 配置：`vitest.live.config.ts` - 文件：`src/**/*.live.test.ts`、`test/**/*.live.test.ts`，以及 `extensions/` 下的内置 plugin live 测试 - 默认值：由 `pnpm test:live` **启用**（设置 `OPENCLAW_LIVE_TEST=1`） - 范围： - - “这个 provider / model 今天是否真的能配合真实凭证工作？” - - 捕获 provider 格式变化、工具调用怪癖、认证问题以及速率限制行为 + - “这个提供商/模型 _今天_ 在真实凭证下是否真的可用？” + - 捕捉提供商格式变化、工具调用怪癖、认证问题和限速行为 - 预期： - - 按设计并非 CI 稳定（真实网络、真实 provider 策略、配额、故障） - - 会花钱 / 占用速率限制 - - 优先运行缩小范围的子集，而不是“全部” -- live 运行会读取 `~/.profile` 以获取缺失的 API key。 -- 默认情况下，live 运行仍会隔离 `HOME`，并将配置 / 认证材料复制到临时测试 home 中，这样单元 fixture 就不会修改你真实的 `~/.openclaw`。 -- 只有当你明确需要 live 测试使用真实 home 目录时，才设置 `OPENCLAW_LIVE_USE_REAL_HOME=1`。 -- `pnpm test:live` 现在默认更安静：会保留 `[live] ...` 进度输出，但会抑制额外的 `~/.profile` 提示，并静音 gateway 启动日志 / Bonjour 杂音。如果你希望恢复完整启动日志，请设置 `OPENCLAW_LIVE_TEST_QUIET=0`。 -- API key 轮换（provider 专属）：设置 `*_API_KEYS`，使用逗号 / 分号格式，或设置 `*_API_KEY_1`、`*_API_KEY_2`（例如 `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`），或者通过 `OPENCLAW_LIVE_*_KEY` 进行每次 live 运行覆盖；测试会在收到 rate limit 响应时重试。 -- 进度 / 心跳输出： - - live 套件现在会将进度行输出到 stderr，因此即使 Vitest 控制台捕获较安静，长时间 provider 调用期间也能看见仍在活动。 - - `vitest.live.config.ts` 会禁用 Vitest 的控制台拦截，因此 provider / gateway 进度行会在 live 运行期间立即流式输出。 - - 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整 direct-model 心跳。 - - 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 gateway / probe 心跳。 + - 按设计并非 CI 稳定（真实网络、真实提供商策略、配额、故障） + - 会花钱 / 消耗速率限制 + - 更推荐运行收窄后的子集，而不是“全部” +- Live 运行会读取 `~/.profile`，以补齐缺失的 API 密钥。 +- 默认情况下，live 运行仍会隔离 `HOME`，并将配置/认证材料复制到一个临时测试 home 中，以防 unit 夹具改动你的真实 `~/.openclaw`。 +- 仅当你明确需要 live 测试使用真实 home 目录时，才设置 `OPENCLAW_LIVE_USE_REAL_HOME=1`。 +- `pnpm test:live` 现在默认采用更安静的模式：会保留 `[live] ...` 进度输出，但会隐藏额外的 `~/.profile` 提示，并静音 gateway 启动日志/Bonjour 噪声。如果你想恢复完整启动日志，可设置 `OPENCLAW_LIVE_TEST_QUIET=0`。 +- API 密钥轮换（按提供商）：设置逗号/分号格式的 `*_API_KEYS` 或 `*_API_KEY_1`、`*_API_KEY_2`（例如 `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`），或者通过 `OPENCLAW_LIVE_*_KEY` 为 live 单独覆盖；测试在收到限速响应时会重试。 +- 进度/心跳输出： + - live 套件现在会将进度行输出到 stderr，因此即便 Vitest 控制台捕获较安静，长时间的提供商调用也能明确显示仍在活动。 + - `vitest.live.config.ts` 会禁用 Vitest 控制台拦截，因此在 live 运行期间，提供商/gateway 进度行会立即流式输出。 + - 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整直接模型心跳。 + - 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 gateway/探测心跳。 ## 我应该运行哪个套件？ -使用这个决策表： +使用这张决策表： -- 编辑逻辑 / 测试：运行 `pnpm test`（如果你改动很多，再运行 `pnpm test:coverage`） -- 触及 gateway 网络 / WS 协议 / 配对：额外运行 `pnpm test:e2e` -- 调试“我的 bot 挂了” / provider 专属故障 / 工具调用：运行一个缩小范围的 `pnpm test:live` +- 编辑逻辑/测试：运行 `pnpm test`（如果你改动很多，也运行 `pnpm test:coverage`） +- 触及 gateway 网络 / WS 协议 / 配对：加上 `pnpm test:e2e` +- 调试“我的 bot 挂了”/提供商特定故障/工具调用：运行收窄后的 `pnpm test:live` -## live（触网）测试 +## Live（涉及网络）测试 -关于 live 模型矩阵、CLI 后端冒烟、ACP 冒烟、Codex app-server -harness，以及所有媒体 provider live 测试（Deepgram、BytePlus（国际版）、ComfyUI、image、music、video、media harness）——以及 live 运行的凭证处理 —— 请参见 +关于 live 模型矩阵、CLI 后端冒烟、ACP 冒烟、Codex app-server harness，以及所有媒体提供商 live 测试（Deepgram、BytePlus（国际版）、ComfyUI、图像、音乐、视频、媒体 harness）——以及 live 运行的凭证处理——请参见 [测试 — live 套件](/zh-CN/help/testing-live)。 ## Docker 运行器（可选的“在 Linux 中可用”检查） 这些 Docker 运行器分为两类： -- live 模型运行器：`test:docker:live-models` 和 `test:docker:live-gateway` 只会在仓库 Docker 镜像内运行与各自 profile-key 匹配的 live 文件（`src/agents/models.profiles.live.test.ts` 和 `src/gateway/gateway-models.profiles.live.test.ts`），并挂载你的本地配置目录与工作区（如果已挂载，也会读取 `~/.profile`）。对应的本地入口点是 `test:live:models-profiles` 和 `test:live:gateway-profiles`。 -- Docker live 运行器默认使用更小的冒烟上限，以便完整的 Docker 扫描仍然可行： - `test:docker:live-models` 默认使用 `OPENCLAW_LIVE_MAX_MODELS=12`，而 - `test:docker:live-gateway` 默认使用 `OPENCLAW_LIVE_GATEWAY_SMOKE=1`、 +- live 模型运行器：`test:docker:live-models` 和 `test:docker:live-gateway` 只会在仓库 Docker 镜像中运行与其匹配的 profile-key live 文件（`src/agents/models.profiles.live.test.ts` 和 `src/gateway/gateway-models.profiles.live.test.ts`），并挂载你的本地配置目录与工作区（如果已挂载，也会读取 `~/.profile`）。对应的本地入口点是 `test:live:models-profiles` 和 `test:live:gateway-profiles`。 +- Docker live 运行器默认使用较小的冒烟上限，以便完整的 Docker 扫描仍然可行： + `test:docker:live-models` 默认设置 `OPENCLAW_LIVE_MAX_MODELS=12`，而 + `test:docker:live-gateway` 默认设置 `OPENCLAW_LIVE_GATEWAY_SMOKE=1`、 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`、 - `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`，以及 - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。当你明确想进行更大范围的穷尽扫描时，可覆盖这些环境变量。 -- `test:docker:all` 会先通过 `test:docker:live-build` 构建一次 live Docker 镜像，然后在各个 live Docker 通道中复用它。它还会通过 `test:docker:e2e-build` 构建一个共享的 `scripts/e2e/Dockerfile` 镜像，并在验证构建后应用的 E2E 容器冒烟运行器中复用。这个聚合器使用加权本地调度器：`OPENCLAW_DOCKER_ALL_PARALLELISM` 控制进程槽位，而资源上限可防止重型 live、npm-install 和多服务通道同时全部启动。默认值是 10 个槽位，`OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=8` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`；只有当 Docker 主机有更多余量时，才调整 `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` 或 `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`。运行器默认会执行 Docker 预检，移除陈旧的 OpenClaw E2E 容器，每 30 秒打印一次状态，将成功通道的耗时存储到 `.artifacts/docker-tests/lane-timings.json`，并在后续运行中使用这些耗时让更长的通道优先启动。使用 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 可在不构建或运行 Docker 的情况下打印加权通道清单。 + `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` 和 + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。当你明确想进行更大的穷举扫描时，可覆盖这些环境变量。 +- `test:docker:all` 会先通过 `test:docker:live-build` 构建一次 live Docker 镜像，然后在 live Docker 通道中复用它。它还会通过 `test:docker:e2e-build` 构建一个共享的 `scripts/e2e/Dockerfile` 镜像，并在验证已构建应用的 E2E 容器冒烟运行器中复用。该聚合器使用带权重的本地调度器：`OPENCLAW_DOCKER_ALL_PARALLELISM` 控制进程槽位，而资源上限可防止重型 live、npm-install 和多服务通道同时全部启动。默认值为 10 个槽位、`OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=8` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`；只有当 Docker 主机有更多余量时，才调整 `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` 或 `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`。运行器默认会执行 Docker 预检，移除陈旧的 OpenClaw E2E 容器，每 30 秒打印一次状态，将成功通道的耗时保存到 `.artifacts/docker-tests/lane-timings.json`，并在后续运行中利用这些耗时优先启动较长的通道。使用 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 可仅打印带权重的通道清单，而不构建或运行 Docker。 - 容器冒烟运行器：`test:docker:openwebui`、`test:docker:onboard`、`test:docker:npm-onboard-channel-agent`、`test:docker:agents-delete-shared-workspace`、`test:docker:gateway-network`、`test:docker:mcp-channels`、`test:docker:pi-bundle-mcp-tools`、`test:docker:cron-mcp-cleanup`、`test:docker:plugins`、`test:docker:plugin-update` 和 `test:docker:config-reload` 会启动一个或多个真实容器，并验证更高层级的集成路径。 -live 模型 Docker 运行器还会只 bind-mount 所需的 CLI 认证 home（如果运行未缩小范围，则挂载所有支持的），然后在运行前将它们复制到容器 home 中，这样外部 CLI OAuth 就可以刷新 token，而不会修改宿主机的认证存储： +live 模型 Docker 运行器还会仅 bind-mount 所需的 CLI 认证 home（若运行未收窄，则挂载所有受支持的 home），然后在运行前将其复制到容器 home 中，这样外部 CLI OAuth 就可以刷新 token，而不会修改主机认证存储： - 直接模型：`pnpm test:docker:live-models`（脚本：`scripts/test-live-models-docker.sh`） -- ACP 绑定冒烟：`pnpm test:docker:live-acp-bind`（脚本：`scripts/test-live-acp-bind-docker.sh`；默认覆盖 Claude、Codex 和 Gemini，对 OpenCode 的严格覆盖可使用 `pnpm test:docker:live-acp-bind:opencode`） +- ACP 绑定冒烟：`pnpm test:docker:live-acp-bind`（脚本：`scripts/test-live-acp-bind-docker.sh`；默认覆盖 Claude、Codex 和 Gemini，若需严格的 OpenCode 覆盖则使用 `pnpm test:docker:live-acp-bind:opencode`） - CLI 后端冒烟：`pnpm test:docker:live-cli-backend`（脚本：`scripts/test-live-cli-backend-docker.sh`） - Codex app-server harness 冒烟：`pnpm test:docker:live-codex-harness`（脚本：`scripts/test-live-codex-harness-docker.sh`） -- Gateway 网关 + 开发智能体：`pnpm test:docker:live-gateway`（脚本：`scripts/test-live-gateway-models-docker.sh`） +- Gateway 网关 + dev 智能体：`pnpm test:docker:live-gateway`（脚本：`scripts/test-live-gateway-models-docker.sh`） - Open WebUI live 冒烟：`pnpm test:docker:openwebui`（脚本：`scripts/e2e/openwebui-docker.sh`） -- onboarding 向导（TTY，完整脚手架）：`pnpm test:docker:onboard`（脚本：`scripts/e2e/onboard-docker.sh`） -- npm tarball onboarding / 渠道 / 智能体冒烟：`pnpm test:docker:npm-onboard-channel-agent` 会在 Docker 中全局安装打包后的 OpenClaw tarball，通过 env-ref onboarding 配置 OpenAI，并默认配置 Telegram，验证 doctor 会修复已激活 plugin 的运行时依赖，并运行一次 mocked OpenAI 智能体轮次。使用 `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 复用预构建 tarball，使用 `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` 跳过宿主机构建，或使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 切换渠道。 -- Bun 全局安装冒烟：`bash scripts/e2e/bun-global-install-smoke.sh` 会打包当前工作树，在隔离 home 中使用 `bun install -g` 安装，并验证 `openclaw infer image providers --json` 返回的是内置图像提供商，而不是卡住。使用 `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 复用预构建 tarball，使用 `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` 跳过宿主机构建，或使用 `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` 从已构建的 Docker 镜像复制 `dist/`。 -- 安装器 Docker 冒烟：`bash scripts/test-install-sh-docker.sh` 会在其 root、update 和 direct-npm 容器之间共享一个 npm 缓存。更新冒烟默认使用 npm `latest` 作为稳定基线，然后升级到候选 tarball。非 root 安装器检查会保持独立的 npm 缓存，这样 root 拥有的缓存条目就不会掩盖用户本地安装行为。设置 `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` 可在本地重复运行之间复用 root / update / direct-npm 缓存。 -- Install Smoke CI 会通过 `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` 跳过重复的 direct-npm 全局更新；当需要覆盖直接 `npm install -g` 时，请在本地运行该脚本且不要设置这个环境变量。 -- 智能体删除共享工作区 CLI 冒烟：`pnpm test:docker:agents-delete-shared-workspace`（脚本：`scripts/e2e/agents-delete-shared-workspace-docker.sh`）默认会构建根 Dockerfile 镜像，在隔离容器 home 中为两个智能体植入一个工作区，运行 `agents delete --json`，并验证 JSON 有效且工作区保留行为正确。使用 `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1` 可复用 install-smoke 镜像。 +- 新手引导向导（TTY，完整脚手架）：`pnpm test:docker:onboard`（脚本：`scripts/e2e/onboard-docker.sh`） +- Npm tarball 新手引导/渠道/智能体冒烟：`pnpm test:docker:npm-onboard-channel-agent` 会在 Docker 中全局安装打包后的 OpenClaw tarball，通过 env-ref 新手引导配置 OpenAI，默认还会配置 Telegram，验证 doctor 会修复已激活 plugin 的运行时依赖，并运行一次 mocked OpenAI 智能体交互。可通过 `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 复用预构建 tarball，通过 `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` 跳过主机构建，或通过 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 切换渠道。 +- Bun 全局安装冒烟：`bash scripts/e2e/bun-global-install-smoke.sh` 会打包当前工作树，在隔离 home 中使用 `bun install -g` 安装，并验证 `openclaw infer image providers --json` 会返回内置图像提供商，而不是挂起。可通过 `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 复用预构建 tarball，通过 `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` 跳过主机构建，或通过 `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` 从已构建的 Docker 镜像复制 `dist/`。 +- 安装器 Docker 冒烟：`bash scripts/test-install-sh-docker.sh` 会在其 root、update 和 direct-npm 容器之间共享一个 npm 缓存。更新冒烟默认使用 npm `latest` 作为稳定基线，然后再升级到候选 tarball。非 root 安装器检查会保留隔离的 npm 缓存，以免 root 拥有的缓存条目掩盖用户本地安装行为。设置 `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` 可在本地重跑之间复用 root/update/direct-npm 缓存。 +- Install Smoke CI 会通过 `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` 跳过重复的 direct-npm 全局更新；如果需要覆盖直接 `npm install -g`，请在本地运行脚本时不要设置该环境变量。 +- Agents 删除共享工作区 CLI 冒烟：`pnpm test:docker:agents-delete-shared-workspace`（脚本：`scripts/e2e/agents-delete-shared-workspace-docker.sh`）默认会构建根 Dockerfile 镜像，在隔离的容器 home 中为两个智能体播种一个工作区，运行 `agents delete --json`，并验证 JSON 有效以及工作区保留行为。可通过 `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1` 复用 install-smoke 镜像。 - Gateway 网关网络（两个容器，WS 认证 + 健康检查）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`） -- OpenAI Responses `web_search` 最小 reasoning 回归：`pnpm test:docker:openai-web-search-minimal`（脚本：`scripts/e2e/openai-web-search-minimal-docker.sh`）会通过 Gateway 网关运行一个 mocked OpenAI 服务器，验证 `web_search` 会将 `reasoning.effort` 从 `minimal` 提升到 `low`，然后强制 provider schema 拒绝，并检查原始细节是否出现在 Gateway 网关日志中。 -- MCP 渠道桥接（预植入的 Gateway 网关 + stdio bridge + 原始 Claude notification-frame 冒烟）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`） -- Pi 内置 MCP 工具（真实 stdio MCP 服务器 + 内嵌 Pi 配置文件 allow / deny 冒烟）：`pnpm test:docker:pi-bundle-mcp-tools`（脚本：`scripts/e2e/pi-bundle-mcp-tools-docker.sh`） -- Cron / 子智能体 MCP 清理（真实 Gateway 网关 + 在隔离 cron 和一次性子智能体运行后拆除 stdio MCP 子进程）：`pnpm test:docker:cron-mcp-cleanup`（脚本：`scripts/e2e/cron-mcp-cleanup-docker.sh`） +- OpenAI Responses `web_search` 最低推理回归：`pnpm test:docker:openai-web-search-minimal`（脚本：`scripts/e2e/openai-web-search-minimal-docker.sh`）会通过 Gateway 网关运行一个 mocked OpenAI 服务器，验证 `web_search` 会将 `reasoning.effort` 从 `minimal` 提升为 `low`，然后强制提供商 schema 拒绝，并检查原始细节是否出现在 Gateway 网关日志中。 +- MCP 渠道桥接（已播种 Gateway 网关 + stdio bridge + 原始 Claude notification-frame 冒烟）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`） +- Pi bundle MCP 工具（真实 stdio MCP 服务器 + 嵌入式 Pi profile allow/deny 冒烟）：`pnpm test:docker:pi-bundle-mcp-tools`（脚本：`scripts/e2e/pi-bundle-mcp-tools-docker.sh`） +- Cron/subagent MCP 清理（真实 Gateway 网关 + 在隔离 cron 和一次性 subagent 运行后拆除 stdio MCP 子进程）：`pnpm test:docker:cron-mcp-cleanup`（脚本：`scripts/e2e/cron-mcp-cleanup-docker.sh`） - Plugins（安装冒烟 + `/plugin` 别名 + Claude bundle 重启语义）：`pnpm test:docker:plugins`（脚本：`scripts/e2e/plugins-docker.sh`） -- plugin 更新未变更冒烟：`pnpm test:docker:plugin-update`（脚本：`scripts/e2e/plugin-update-unchanged-docker.sh`） -- 配置热重载元数据冒烟：`pnpm test:docker:config-reload`（脚本：`scripts/e2e/config-reload-source-docker.sh`） -- 内置 plugin 运行时依赖：`pnpm test:docker:bundled-channel-deps` 默认会构建一个小型 Docker 运行器镜像，在宿主机上构建并打包一次 OpenClaw，然后将该 tarball 挂载到每个 Linux 安装场景中。使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 复用镜像，使用 `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` 在本地刚完成构建后跳过宿主机重建，或使用 `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 指向现有 tarball。完整 Docker 聚合器会先预打包一次该 tarball，然后将内置渠道检查分片为独立通道，其中包括 Telegram、Discord、Slack、Feishu、memory-lancedb 和 ACPX 的独立更新通道。直接运行该内置通道时，使用 `OPENCLAW_BUNDLED_CHANNELS=telegram,slack` 缩小渠道矩阵，或使用 `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx` 缩小更新场景。该通道还会验证 `channels..enabled=false` 和 `plugins.entries..enabled=false` 会抑制 doctor / 运行时依赖修复。 -- 在迭代时缩小内置 plugin 运行时依赖范围，可禁用无关场景，例如： +- Plugin update unchanged 冒烟：`pnpm test:docker:plugin-update`（脚本：`scripts/e2e/plugin-update-unchanged-docker.sh`） +- Config 重新加载元数据冒烟：`pnpm test:docker:config-reload`（脚本：`scripts/e2e/config-reload-source-docker.sh`） +- 内置 plugin 运行时依赖：`pnpm test:docker:bundled-channel-deps` 默认会构建一个小型 Docker 运行器镜像，在主机上构建并打包一次 OpenClaw，然后将该 tarball 挂载到每个 Linux 安装场景中。可通过 `OPENCLAW_SKIP_DOCKER_BUILD=1` 复用镜像，在刚完成本地构建后通过 `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` 跳过主机重建，或通过 `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 指向现有 tarball。完整 Docker 聚合器会预先打包该 tarball 一次，然后将内置渠道检查分片为独立通道，其中包括 Telegram、Discord、Slack、Feishu、memory-lancedb 和 ACPX 的独立更新通道。直接运行该内置通道时，可使用 `OPENCLAW_BUNDLED_CHANNELS=telegram,slack` 收窄渠道矩阵，或使用 `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx` 收窄更新场景。该通道还会验证 `channels..enabled=false` 和 `plugins.entries..enabled=false` 会抑制 doctor/运行时依赖修复。 +- 在迭代时若要收窄内置 plugin 运行时依赖，可禁用无关场景，例如： `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`。 -如需手动预构建并复用共享的已构建应用镜像： +若要手动预构建并复用共享的 built-app 镜像： ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -设置后，诸如 `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` 这样的套件专属镜像覆盖仍然优先生效。当 `OPENCLAW_SKIP_DOCKER_BUILD=1` 指向远程共享镜像时，如果本地尚不存在，这些脚本会先拉取它。QR 和安装器 Docker 测试保留各自独立的 Dockerfile，因为它们验证的是包 / 安装行为，而不是共享的已构建应用运行时。 +当设置了诸如 `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` 之类的套件专属镜像覆盖项时，它们仍具有更高优先级。当 `OPENCLAW_SKIP_DOCKER_BUILD=1` 指向远端共享镜像时，如果镜像尚未在本地存在，脚本会拉取它。QR 和安装器 Docker 测试保留各自独立的 Dockerfile，因为它们验证的是打包/安装行为，而不是共享的 built-app 运行时。 -live 模型 Docker 运行器还会将当前 checkout 以只读方式 bind-mount 进去，并在容器内暂存到一个临时工作目录中。这样既能保持运行时镜像精简，又仍然可以针对你本地的精确 source / config 运行 Vitest。该暂存步骤会跳过大型本地专用缓存和应用构建输出，例如 `.pnpm-store`、`.worktrees`、`__openclaw_vitest__`，以及应用本地的 `.build` 或 Gradle 输出目录，因此 Docker live 运行不会花上数分钟复制与机器绑定的产物。 -它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，因此 gateway live 探测不会在容器内启动真实的 Telegram / Discord / 等渠道 worker。 -`test:docker:live-models` 仍然运行 `pnpm test:live`，所以当你需要缩小或排除该 Docker 通道中的 gateway live 覆盖时，也要一并传入 `OPENCLAW_LIVE_GATEWAY_*`。 -`test:docker:openwebui` 是一个更高层级的兼容性冒烟测试：它会启动一个启用了 OpenAI 兼容 HTTP 端点的 OpenClaw gateway 容器，再启动一个固定版本的 Open WebUI 容器并连接到该 gateway，通过 Open WebUI 完成登录，验证 `/api/models` 暴露了 `openclaw/default`，然后通过 Open WebUI 的 `/api/chat/completions` 代理发送一个真实聊天请求。 -首次运行可能会明显更慢，因为 Docker 可能需要拉取 Open WebUI 镜像，而 Open WebUI 也可能需要完成自身的冷启动设置。 -该通道需要可用的 live 模型 key，而 `OPENCLAW_PROFILE_FILE` -（默认 `~/.profile`）是在 Docker 化运行中提供该 key 的主要方式。 -成功运行时会打印一个小型 JSON 负载，例如 `{ "ok": true, "model": +live 模型 Docker 运行器还会以只读方式 bind-mount 当前 checkout，并将其暂存到容器内的临时工作目录中。这样既能保持运行时镜像精简，又仍然可以针对你本地精确的源码/配置运行 Vitest。暂存步骤会跳过大型仅本地缓存和应用构建输出，例如 `.pnpm-store`、`.worktrees`、`__openclaw_vitest__` 以及应用本地的 `.build` 或 Gradle 输出目录，因此 Docker live 运行不会花上几分钟去复制机器特定产物。 +它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，这样 gateway live 探测就不会在容器内启动真实的 Telegram/Discord 等渠道工作进程。 +`test:docker:live-models` 仍然会运行 `pnpm test:live`，因此当你需要缩小或排除该 Docker 通道中的 gateway live 覆盖时，也要一并传入 `OPENCLAW_LIVE_GATEWAY_*`。 +`test:docker:openwebui` 是一个更高层级的兼容性冒烟测试：它会启动一个启用了 OpenAI 兼容 HTTP 端点的 OpenClaw gateway 容器，再针对该 gateway 启动一个固定版本的 Open WebUI 容器，通过 Open WebUI 登录，验证 `/api/models` 暴露了 `openclaw/default`，然后通过 Open WebUI 的 `/api/chat/completions` 代理发送一个真实聊天请求。 +首次运行可能明显更慢，因为 Docker 可能需要拉取 Open WebUI 镜像，而 Open WebUI 也可能需要完成自己的冷启动 setup。 +这个通道需要可用的 live 模型密钥，而 `OPENCLAW_PROFILE_FILE`（默认为 `~/.profile`）是在 Docker 化运行中提供该密钥的主要方式。 +成功运行时会打印一小段 JSON 负载，例如 `{ "ok": true, "model": "openclaw/default", ... }`。 -`test:docker:mcp-channels` 是刻意设计为确定性的，不需要真实的 Telegram、Discord 或 iMessage 账号。它会启动一个已植入数据的 Gateway 容器，再启动第二个容器来拉起 `openclaw mcp serve`，然后验证路由后的会话发现、transcript 读取、附件元数据、live 事件队列行为、出站发送路由，以及通过真实 stdio MCP bridge 传递的 Claude 风格渠道 + 权限通知。通知检查会直接检查原始 stdio MCP frame，因此这个冒烟测试验证的是 bridge 实际发出的内容，而不只是某个特定客户端 SDK 恰好暴露出来的内容。 -`test:docker:pi-bundle-mcp-tools` 是确定性的，不需要 live 模型 key。它会构建仓库 Docker 镜像，在容器内启动一个真实的 stdio MCP probe 服务器，通过内嵌 Pi 内置 MCP 运行时将该服务器实体化，执行工具，然后验证 `coding` 和 `messaging` 会保留 `bundle-mcp` 工具，而 `minimal` 和 `tools.deny: ["bundle-mcp"]` 会将其过滤掉。 -`test:docker:cron-mcp-cleanup` 是确定性的，不需要 live 模型 key。它会启动一个带有真实 stdio MCP probe 服务器的已植入 Gateway，运行一次隔离的 cron 轮次以及一次 `/subagents spawn` 的单次子智能体轮次，然后验证 MCP 子进程会在每次运行后退出。 +`test:docker:mcp-channels` 是刻意设计为确定性的，不需要真实的 Telegram、Discord 或 iMessage 账号。它会启动一个已播种的 Gateway 网关容器，再启动第二个容器来生成 `openclaw mcp serve`，然后通过真实的 stdio MCP bridge 验证路由后的会话发现、transcript 读取、附件元数据、live 事件队列行为、出站发送路由，以及 Claude 风格的渠道 + 权限通知。通知检查会直接检视原始 stdio MCP 帧，因此该冒烟测试验证的是 bridge 实际发出的内容，而不仅仅是某个特定客户端 SDK 恰好暴露出来的内容。 +`test:docker:pi-bundle-mcp-tools` 具有确定性，不需要 live 模型密钥。它会构建仓库 Docker 镜像，在容器内启动一个真实的 stdio MCP 探测服务器，通过嵌入式 Pi bundle MCP 运行时将该服务器实例化，执行该工具，然后验证 `coding` 和 `messaging` 会保留 `bundle-mcp` 工具，而 `minimal` 和 `tools.deny: ["bundle-mcp"]` 会将其过滤掉。 +`test:docker:cron-mcp-cleanup` 具有确定性，不需要 live 模型密钥。它会启动一个带有真实 stdio MCP 探测服务器的已播种 Gateway 网关，运行一次隔离的 cron 交互和一次 `/subagents spawn` 一次性子智能体交互，然后验证每次运行后 MCP 子进程都会退出。 -手动 ACP plain-language 线程冒烟测试（非 CI）： +手动 ACP 通俗语言线程冒烟测试（非 CI）： - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- 保留这个脚本用于回归 / 调试工作流。它未来可能还会用于 ACP 线程路由校验，所以不要删除它。 +- 为回归/调试工作流保留此脚本。它未来可能还需要用于 ACP 线程路由验证，因此不要删除它。 -实用环境变量： +有用的环境变量： - `OPENCLAW_CONFIG_DIR=...`（默认：`~/.openclaw`）挂载到 `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...`（默认：`~/.openclaw/workspace`）挂载到 `/home/node/.openclaw/workspace` - `OPENCLAW_PROFILE_FILE=...`（默认：`~/.profile`）挂载到 `/home/node/.profile`，并在运行测试前读取 -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` 用于仅验证来自 `OPENCLAW_PROFILE_FILE` 的环境变量，使用临时 config / workspace 目录，且不挂载外部 CLI 认证 -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（默认：`~/.cache/openclaw/docker-cli-tools`）挂载到 `/home/node/.npm-global`，用于缓存 Docker 内部安装的 CLI -- `$HOME` 下的外部 CLI 认证目录 / 文件会以只读方式挂载到 `/host-auth...` 下，然后在测试开始前复制到 `/home/node/...` +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` 用于只验证从 `OPENCLAW_PROFILE_FILE` 读取的环境变量，此时会使用临时配置/工作区目录，并且不挂载外部 CLI 认证 +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（默认：`~/.cache/openclaw/docker-cli-tools`）挂载到 `/home/node/.npm-global`，用于 Docker 内缓存的 CLI 安装 +- `$HOME` 下的外部 CLI 认证目录/文件会以只读方式挂载到 `/host-auth...` 下，然后在测试开始前复制到 `/home/node/...` - 默认目录：`.minimax` - 默认文件：`~/.codex/auth.json`、`~/.codex/config.toml`、`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json` - - 缩小 provider 范围的运行只会挂载从 `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` 推断出的必需目录 / 文件 - - 可通过 `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`，或逗号列表如 `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` 手动覆盖 -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` 用于缩小运行范围 -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` 用于在容器内过滤 provider -- `OPENCLAW_SKIP_DOCKER_BUILD=1` 用于复用已有的 `openclaw:local-live` 镜像，以便在无需重建时重复运行 + - 收窄后的提供商运行只会挂载从 `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` 推断出的所需目录/文件 + - 可通过 `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none` 或类似 `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` 的逗号列表手动覆盖 +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` 用于收窄运行范围 +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` 用于在容器内筛选提供商 +- `OPENCLAW_SKIP_DOCKER_BUILD=1` 用于复用现有的 `openclaw:local-live` 镜像，以便在无需重建时重跑 - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 用于确保凭证来自 profile 存储（而不是环境变量） -- `OPENCLAW_OPENWEBUI_MODEL=...` 用于选择在 Open WebUI 冒烟测试中由 gateway 暴露的模型 -- `OPENCLAW_OPENWEBUI_PROMPT=...` 用于覆盖 Open WebUI 冒烟测试中使用的 nonce-check 提示词 +- `OPENCLAW_OPENWEBUI_MODEL=...` 用于选择 Gateway 网关为 Open WebUI 冒烟测试暴露的模型 +- `OPENCLAW_OPENWEBUI_PROMPT=...` 用于覆盖 Open WebUI 冒烟测试使用的 nonce 校验提示词 - `OPENWEBUI_IMAGE=...` 用于覆盖固定的 Open WebUI 镜像标签 ## 文档完整性检查 -编辑文档后运行文档检查：`pnpm check:docs`。 -当你还需要页内标题检查时，运行完整的 Mintlify anchor 校验：`pnpm docs:check-links:anchors`。 +在修改文档后运行文档检查：`pnpm check:docs`。 +当你还需要检查页面内标题锚点时，运行完整的 Mintlify 锚点校验：`pnpm docs:check-links:anchors`。 ## 离线回归（对 CI 安全） -这些是不依赖真实 provider 的“真实流水线”回归测试： +这些是不依赖真实提供商的“真实流水线”回归测试： - Gateway 网关工具调用（mock OpenAI、真实 gateway + Agent loop）：`src/gateway/gateway.test.ts`（用例：“runs a mock OpenAI tool call end-to-end via gateway agent loop”） -- Gateway 网关向导（WS `wizard.start` / `wizard.next`，强制写入 config + auth）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”） +- Gateway 网关向导（WS `wizard.start`/`wizard.next`，强制写入配置 + 认证）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”） ## 智能体可靠性评估（Skills） 我们已经有一些对 CI 安全、行为类似“智能体可靠性评估”的测试： -- 通过真实 gateway + Agent loop 进行 mock 工具调用（`src/gateway/gateway.test.ts`）。 -- 用于验证会话接线和配置影响的端到端向导流程（`src/gateway/gateway.test.ts`）。 +- 通过真实 gateway + Agent loop 的 mock 工具调用（`src/gateway/gateway.test.ts`）。 +- 验证会话布线和配置效果的端到端向导流程（`src/gateway/gateway.test.ts`）。 -对于 Skills（参见 [Skills](/zh-CN/tools/skills)），目前仍然缺少的内容： +对于 Skills（参见 [Skills](/zh-CN/tools/skills)），目前仍缺少的是： -- **决策**：当 Skills 在提示词中列出时，智能体是否会选择正确的 Skills（或避开无关的 Skills）？ -- **遵从性**：智能体是否会在使用前读取 `SKILL.md`，并遵循要求的步骤 / 参数？ -- **工作流契约**：断言工具顺序、会话历史继承以及沙箱边界的多轮场景。 +- **决策能力：** 当提示词中列出了 Skills 时，智能体是否会选择正确的 Skill（或避免无关 Skill）？ +- **合规性：** 智能体在使用前是否会读取 `SKILL.md`，并遵循必需步骤/参数？ +- **工作流契约：** 断言工具顺序、会话历史延续和沙箱边界的多轮场景。 -未来的评估应优先保持确定性： +未来的评估应当先保持确定性： -- 一个使用 mock provider 的场景运行器，用于断言工具调用 + 顺序、skill 文件读取以及会话接线。 -- 一小组聚焦 skill 的场景（使用 vs 避免、门控、提示注入）。 -- 只有在 CI 安全套件就位之后，才添加可选 live 评估（按需启用、由环境变量控制）。 +- 一个使用 mock 提供商的场景运行器，用于断言工具调用 + 顺序、Skill 文件读取和会话布线。 +- 一小组聚焦 Skill 的场景（使用与避免、门控、提示词注入）。 +- 只有在对 CI 安全的套件到位之后，才添加可选的 live 评估（选择加入、由环境变量门控）。 ## 契约测试（plugin 和渠道形状） -契约测试用于验证每个已注册的 plugin 和渠道都符合其接口契约。它们会遍历所有已发现的 plugins，并运行一组关于形状和行为的断言。默认的 `pnpm test` 单元通道会刻意跳过这些共享接缝和冒烟文件；当你修改共享渠道或 provider 表面时，请显式运行这些契约命令。 +契约测试用于验证每个已注册 plugin 和渠道都符合其接口契约。它们会遍历所有已发现的 plugin，并运行一组关于形状和行为的断言。默认的 `pnpm test` unit 通道会刻意跳过这些共享接缝和冒烟文件；当你修改共享渠道或提供商表面时，请显式运行这些契约命令。 ### 命令 - 所有契约：`pnpm test:contracts` - 仅渠道契约：`pnpm test:contracts:channels` -- 仅 provider 契约：`pnpm test:contracts:plugins` +- 仅提供商契约：`pnpm test:contracts:plugins` ### 渠道契约 位于 `src/channels/plugins/contracts/*.contract.test.ts`： - **plugin** - 基本 plugin 形状（id、name、capabilities） -- **setup** - 向导设置契约 +- **setup** - setup 向导契约 - **session-binding** - 会话绑定行为 - **outbound-payload** - 消息负载结构 - **inbound** - 入站消息处理 - **actions** - 渠道动作处理器 - **threading** - 线程 ID 处理 -- **directory** - 目录 / roster API -- **group-policy** - 群组策略强制执行 +- **directory** - 目录/成员表 API +- **group-policy** - 群组策略执行 -### provider Status 契约 +### 提供商 Status 契约 位于 `src/plugins/contracts/*.contract.test.ts`。 - **status** - 渠道 Status 探测 - **registry** - plugin 注册表形状 -### provider 契约 +### 提供商契约 位于 `src/plugins/contracts/*.contract.test.ts`： -- **auth** - 认证流程契约 -- **auth-choice** - 认证选项 / 选择 +- **auth** - 认证流契约 +- **auth-choice** - 认证选择/挑选 - **catalog** - 模型目录 API - **discovery** - plugin 发现 - **loader** - plugin 加载 -- **runtime** - provider 运行时 -- **shape** - plugin 形状 / 接口 +- **runtime** - 提供商运行时 +- **shape** - plugin 形状/接口 - **wizard** - 设置向导 ### 何时运行 -- 修改 plugin-sdk 导出或子路径之后 -- 添加或修改渠道或 provider plugin 之后 -- 重构 plugin 注册或发现逻辑之后 +- 在更改 plugin-sdk 导出或子路径之后 +- 在添加或修改渠道或提供商 plugin 之后 +- 在重构 plugin 注册或发现之后 -契约测试会在 CI 中运行，不需要真实 API key。 +契约测试会在 CI 中运行，不需要真实 API 密钥。 -## 添加回归测试（指南） +## 添加回归测试（指导） -当你修复一个在 live 中发现的 provider / model 问题时： +当你修复了在 live 中发现的提供商/模型问题时： -- 如果可能，添加一个对 CI 安全的回归测试（mock / stub provider，或捕获精确的请求形状转换） -- 如果它本质上只能在 live 中复现（速率限制、认证策略），就让 live 测试保持窄范围，并通过环境变量按需启用 -- 优先针对能捕获该缺陷的最小层级： - - provider 请求转换 / 重放缺陷 → 直接模型测试 - - gateway 会话 / 历史 / 工具管线缺陷 → gateway live 冒烟测试或对 CI 安全的 gateway mock 测试 -- SecretRef 遍历护栏： - - `src/secrets/exec-secret-ref-id-parity.test.ts` 会从注册表元数据（`listSecretTargetRegistryEntries()`）中为每个 SecretRef 类派生一个采样目标，然后断言遍历片段 exec id 会被拒绝。 - - 如果你在 `src/secrets/target-registry-data.ts` 中添加了新的 `includeInPlan` SecretRef 目标族，请更新该测试中的 `classifyTargetClass`。该测试会在目标 id 未分类时故意失败，这样新类别就无法被静默跳过。 +- 如果可能，添加一个对 CI 安全的回归测试（mock/stub 提供商，或捕获精确的请求形状转换） +- 如果它本质上只能在 live 中复现（限速、认证策略），那就让 live 测试保持收窄，并通过环境变量选择加入 +- 优先定位到能捕获该缺陷的最小层级： + - 提供商请求转换/重放缺陷 → 直接模型测试 + - gateway 会话/历史/工具流水线缺陷 → gateway live 冒烟或对 CI 安全的 gateway mock 测试 +- SecretRef 遍历防护栏： + - `src/secrets/exec-secret-ref-id-parity.test.ts` 会从注册表元数据（`listSecretTargetRegistryEntries()`）中为每个 SecretRef 类派生一个采样目标，然后断言遍历段 exec id 会被拒绝。 + - 如果你在 `src/secrets/target-registry-data.ts` 中新增了 `includeInPlan` SecretRef 目标族，请更新该测试中的 `classifyTargetClass`。该测试会有意在遇到未分类 target id 时失败，这样新类别就不能被悄悄跳过。 ## 相关内容 diff --git a/docs/zh-CN/providers/volcengine.md b/docs/zh-CN/providers/volcengine.md index e87eb6c55..081b74d3d 100644 --- a/docs/zh-CN/providers/volcengine.md +++ b/docs/zh-CN/providers/volcengine.md @@ -1,37 +1,39 @@ --- read_when: - - 你想在 OpenClaw 中使用 Volcano Engine 或 Doubao 模型 - - 你需要 Volcengine API key 设置指南 -summary: 火山引擎设置（Doubao 模型、通用端点 + 编码端点） -title: Volcengine（Doubao） + - 你想在 OpenClaw 中使用火山引擎或 Doubao 模型 + - 你需要设置 Volcengine API 密钥 + - 你想使用 Volcengine Speech 文本转语音功能 +summary: Volcano Engine 设置（Doubao 模型、编码端点和 Seed Speech TTS） +title: 火山引擎（Doubao） x-i18n: - generated_at: "2026-04-23T23:03:15Z" + generated_at: "2026-04-25T22:53:00Z" model: gpt-5.4 provider: openai - source_hash: 6091da50fbab3a01cdc4337a496f361987f1991a2e2b7764e7a9c8c464e9757a + source_hash: b7948a26cc898e125d445e9ae091704f5cf442266d29e712c0dcedbe0dc0cce7 source_path: providers/volcengine.md workflow: 15 --- -Volcengine 提供商可访问由火山引擎托管的 Doubao 模型和第三方模型，并为通用工作负载和编码工作负载提供独立端点。 +Volcengine 提供商可访问托管在火山引擎上的 Doubao 模型和第三方模型，并为通用工作负载和编码工作负载提供独立端点。同一个内置插件还可以将 Volcengine Speech 注册为 TTS 提供商。 | 详情 | 值 | -| --------- | --------------------------------------------------- | -| 提供商 | `volcengine`（通用）+ `volcengine-plan`（编码） | -| 身份验证 | `VOLCANO_ENGINE_API_KEY` | -| API | OpenAI 兼容 | +| ---------- | ---------------------------------------------------------- | +| 提供商 | `volcengine`（通用 + TTS）+ `volcengine-plan`（编码） | +| 模型凭证 | `VOLCANO_ENGINE_API_KEY` | +| TTS 凭证 | `VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY` | +| API | 与 OpenAI 兼容的模型，BytePlus Seed Speech TTS | ## 入门指南 - + 运行交互式新手引导： ```bash openclaw onboard --auth-choice volcengine-api-key ``` - 这会通过一个 API key 同时注册通用（`volcengine`）和编码（`volcengine-plan`）两个提供商。 + 这会使用同一个 API 密钥同时注册通用提供商（`volcengine`）和编码提供商（`volcengine-plan`）。 @@ -45,7 +47,7 @@ Volcengine 提供商可访问由火山引擎托管的 Doubao 模型和第三方 } ``` - + ```bash openclaw models list --provider volcengine openclaw models list --provider volcengine-plan @@ -67,13 +69,13 @@ openclaw onboard --non-interactive \ ## 提供商和端点 -| 提供商 | 端点 | 使用场景 | +| 提供商 | 端点 | 用例 | | ----------------- | ----------------------------------------- | -------------- | | `volcengine` | `ark.cn-beijing.volces.com/api/v3` | 通用模型 | | `volcengine-plan` | `ark.cn-beijing.volces.com/api/coding/v3` | 编码模型 | -两个提供商都通过同一个 API key 配置。设置时会自动同时注册两者。 +这两个提供商都通过同一个 API 密钥进行配置。设置时会自动同时注册两者。 ## 内置目录 @@ -82,48 +84,94 @@ openclaw onboard --non-interactive \ | 模型引用 | 名称 | 输入 | 上下文 | | -------------------------------------------- | ------------------------------- | ----------- | ------- | - | `volcengine/doubao-seed-1-8-251228` | Doubao Seed 1.8 | text, image | 256,000 | - | `volcengine/doubao-seed-code-preview-251028` | doubao-seed-code-preview-251028 | text, image | 256,000 | - | `volcengine/kimi-k2-5-260127` | Kimi K2.5 | text, image | 256,000 | - | `volcengine/glm-4-7-251222` | GLM 4.7 | text, image | 200,000 | - | `volcengine/deepseek-v3-2-251201` | DeepSeek V3.2 | text, image | 128,000 | + | `volcengine/doubao-seed-1-8-251228` | Doubao Seed 1.8 | 文本、图像 | 256,000 | + | `volcengine/doubao-seed-code-preview-251028` | doubao-seed-code-preview-251028 | 文本、图像 | 256,000 | + | `volcengine/kimi-k2-5-260127` | Kimi K2.5 | 文本、图像 | 256,000 | + | `volcengine/glm-4-7-251222` | GLM 4.7 | 文本、图像 | 200,000 | + | `volcengine/deepseek-v3-2-251201` | DeepSeek V3.2 | 文本、图像 | 128,000 | | 模型引用 | 名称 | 输入 | 上下文 | | ------------------------------------------------- | ------------------------ | ----- | ------- | - | `volcengine-plan/ark-code-latest` | Ark Coding Plan | text | 256,000 | - | `volcengine-plan/doubao-seed-code` | Doubao Seed Code | text | 256,000 | - | `volcengine-plan/glm-4.7` | GLM 4.7 Coding | text | 200,000 | - | `volcengine-plan/kimi-k2-thinking` | Kimi K2 Thinking | text | 256,000 | - | `volcengine-plan/kimi-k2.5` | Kimi K2.5 Coding | text | 256,000 | - | `volcengine-plan/doubao-seed-code-preview-251028` | Doubao Seed Code Preview | text | 256,000 | + | `volcengine-plan/ark-code-latest` | Ark Coding Plan | 文本 | 256,000 | + | `volcengine-plan/doubao-seed-code` | Doubao Seed Code | 文本 | 256,000 | + | `volcengine-plan/glm-4.7` | GLM 4.7 Coding | 文本 | 200,000 | + | `volcengine-plan/kimi-k2-thinking` | Kimi K2 Thinking | 文本 | 256,000 | + | `volcengine-plan/kimi-k2.5` | Kimi K2.5 Coding | 文本 | 256,000 | + | `volcengine-plan/doubao-seed-code-preview-251028` | Doubao Seed Code Preview | 文本 | 256,000 | +## 文本转语音 + +Volcengine TTS 使用 BytePlus Seed Speech HTTP API，并且与兼容 OpenAI 的 Doubao 模型 API 密钥分开配置。在 BytePlus 控制台中，打开 Seed Speech > Settings > API Keys，复制 API 密钥，然后设置： + +```bash +export VOLCENGINE_TTS_API_KEY="byteplus_seed_speech_api_key" +export VOLCENGINE_TTS_RESOURCE_ID="seed-tts-1.0" +``` + +然后在 `openclaw.json` 中启用它： + +```json5 +{ + messages: { + tts: { + auto: "always", + provider: "volcengine", + providers: { + volcengine: { + apiKey: "byteplus_seed_speech_api_key", + voice: "en_female_anna_mars_bigtts", + speedRatio: 1.0, + }, + }, + }, + }, +} +``` + +对于语音便笺目标，OpenClaw 会向 Volcengine 请求提供商原生的 `ogg_opus`。对于普通音频附件，则会请求 `mp3`。提供商别名 `bytedance` 和 `doubao` 也会解析到同一个语音提供商。 + +默认资源 ID 是 `seed-tts-1.0`，因为 BytePlus 会将它授予默认项目中新创建的 Seed Speech API 密钥。如果你的项目具有 TTS 2.0 权限，请设置 `VOLCENGINE_TTS_RESOURCE_ID=seed-tts-2.0`。 + + +`VOLCANO_ENGINE_API_KEY` 用于 ModelArk/Doubao 模型端点，并不是 Seed Speech API 密钥。TTS 需要来自 BytePlus Speech Console 的 Seed Speech API 密钥，或者旧版 Speech Console AppID/token 对。 + + +旧版 AppID/token 凭证方式仍然支持较早的 Speech Console 应用： + +```bash +export VOLCENGINE_TTS_APPID="speech_app_id" +export VOLCENGINE_TTS_TOKEN="speech_access_token" +export VOLCENGINE_TTS_CLUSTER="volcano_tts" +``` + ## 高级配置 - `openclaw onboard --auth-choice volcengine-api-key` 当前会将 - `volcengine-plan/ark-code-latest` 设置为默认模型，同时也会注册 - 通用 `volcengine` 目录。 + `openclaw onboard --auth-choice volcengine-api-key` 目前会将 + `volcengine-plan/ark-code-latest` 设置为默认模型，同时也会注册通用的 `volcengine` 目录。 - 在新手引导/配置的模型选择过程中，Volcengine 身份验证选项会优先显示 - `volcengine/*` 和 `volcengine-plan/*` 条目。如果这些模型尚未加载， - OpenClaw 会回退到未过滤目录，而不是显示一个空的按提供商限定的选择器。 + 在新手引导/配置模型选择期间，Volcengine 凭证选项会优先选择 + `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载， + OpenClaw 会回退到未筛选的目录，而不是显示一个空的按提供商范围筛选的选择器。 - 如果 Gateway 网关以守护进程形式运行（launchd/systemd），请确保 - `VOLCANO_ENGINE_API_KEY` 对该进程可用（例如放在 + 如果 Gateway 网关 以守护进程方式运行（launchd/systemd），请确保模型和 TTS + 环境变量（如 `VOLCANO_ENGINE_API_KEY`、`VOLCENGINE_TTS_API_KEY`、 + `BYTEPLUS_SEED_SPEECH_API_KEY`、`VOLCENGINE_TTS_APPID` 和 + `VOLCENGINE_TTS_TOKEN`）对该进程可用（例如在 `~/.openclaw/.env` 中，或通过 `env.shellEnv` 提供）。 -当 OpenClaw 作为后台服务运行时，你在交互式 shell 中设置的环境变量不会自动继承。请参见上面的守护进程说明。 +当 OpenClaw 作为后台服务运行时，你在交互式 shell 中设置的环境变量不会自动被继承。参见上面的守护进程说明。 ## 相关内容 @@ -139,6 +187,6 @@ openclaw onboard --non-interactive \ 常见问题和调试步骤。 - 关于 OpenClaw 设置的常见问题。 + 关于 OpenClaw 设置的常见问题解答。 diff --git a/docs/zh-CN/reference/test.md b/docs/zh-CN/reference/test.md index d951b81be..7abb4cbad 100644 --- a/docs/zh-CN/reference/test.md +++ b/docs/zh-CN/reference/test.md @@ -1,52 +1,52 @@ --- read_when: - 运行或修复测试 -summary: 如何在本地运行测试（`vitest`），以及何时使用 `force` / `coverage` 模式 +summary: 如何在本地运行测试（vitest），以及何时使用 force/coverage 模式 title: 测试 x-i18n: - generated_at: "2026-04-25T09:05:00Z" + generated_at: "2026-04-25T22:52:55Z" model: gpt-5.4 provider: openai - source_hash: dc138f5e3543b45598ab27b9f7bc9ce43979510b4508580a0cf95c43f97bac53 + source_hash: d1f8b33a3a9b7769b7abe34095029b147fe6e18fa24925cf62243ff5c51032eb source_path: reference/test.md workflow: 15 --- -- 完整测试工具包（测试套件、live、Docker）：[测试](/zh-CN/help/testing) +- 完整测试工具包（测试套件、实时测试、Docker）：[测试](/zh-CN/help/testing) -- `pnpm test:force`：终止任何仍在占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整的 Vitest 测试套件，避免服务端测试与正在运行的实例发生冲突。当先前的 Gateway 网关运行遗留了对端口 `18789` 的占用时，使用此命令。 -- `pnpm test:coverage`：使用 V8 覆盖率运行单元测试套件（通过 `vitest.unit.config.ts`）。这是一个针对已加载文件的单元覆盖率门禁，而不是整个仓库的全文件覆盖率。阈值为 70% 的行数/函数/语句覆盖率，以及 55% 的分支覆盖率。由于 `coverage.all` 为 false，该门禁统计的是单元覆盖率套件中已加载的文件，而不是将拆分测试通道中的每个源文件都视为未覆盖。 -- `pnpm test:coverage:changed`：仅对相对于 `origin/main` 发生变更的文件运行单元覆盖率。 -- `pnpm test:changed`：当 diff 仅涉及可路由的源文件/测试文件时，会将变更的 Git 路径展开到有范围限制的 Vitest 通道中。配置/设置变更仍会回退到原生根项目运行，因此在修改连接逻辑时会更广泛地重新运行测试。 -- `pnpm changed:lanes`：显示相对于 `origin/main` 的 diff 所触发的架构通道。 -- `pnpm check:changed`：针对相对于 `origin/main` 的 diff 运行智能变更门禁。它会让核心改动运行核心测试通道，让扩展改动运行扩展测试通道，让仅测试改动只运行测试类型检查/测试，将公共 Plugin SDK 或插件契约变更扩展为一次扩展验证，并让仅发布元数据的版本变更保持在有针对性的版本/配置/根依赖检查范围内。 -- `pnpm test`：通过有范围限制的 Vitest 通道来路由显式文件/目录目标。未指定目标的运行会使用固定的分片组，并展开到叶子配置以便本地并行执行；扩展组始终会展开为每个扩展的分片配置，而不是一个巨大的根项目进程。 -- 完整测试和扩展分片运行会在 `.artifacts/vitest-shard-timings.json` 中更新本地耗时数据；后续运行会使用这些耗时来平衡慢分片和快分片。设置 `OPENCLAW_TEST_PROJECTS_TIMINGS=0` 可忽略本地耗时产物。 -- 选定的 `plugin-sdk` 和 `commands` 测试文件现在会通过专用的轻量通道进行路由，这些通道只保留 `test/setup.ts`，而运行时负担较重的用例仍保留在原有通道中。 -- 选定的 `plugin-sdk` 和 `commands` 辅助源文件也会将 `pnpm test:changed` 映射到这些轻量通道中的显式同级测试，因此对小型辅助函数的修改可以避免重新运行依赖重量级运行时的测试套件。 -- `auto-reply` 现在也被拆分为三个专用配置（`core`、`top-level`、`reply`），这样 reply harness 就不会主导那些更轻量的顶层 status/token/helper 测试。 -- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并在整个仓库配置中启用了共享的非隔离运行器。 +- `pnpm test:force`：终止任何仍占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整的 Vitest 测试套件，这样服务器测试就不会与正在运行的实例发生冲突。当之前的 Gateway 网关运行导致端口 18789 仍被占用时，请使用此命令。 +- `pnpm test:coverage`：使用 V8 覆盖率运行单元测试套件（通过 `vitest.unit.config.ts`）。这是一个针对已加载文件的单元覆盖率门禁，而不是整个仓库所有文件的覆盖率。阈值为：行数 / 函数 / 语句 70%，分支 55%。由于 `coverage.all` 为 false，此门禁只统计单元覆盖率套件已加载的文件，而不会将每个拆分测试通道中的源文件都视为未覆盖。 +- `pnpm test:coverage:changed`：仅对相对于 `origin/main` 有变更的文件运行单元覆盖率。 +- `pnpm test:changed`：当 diff 仅涉及可路由的源文件 / 测试文件时，会将变更过的 Git 路径展开为有范围限制的 Vitest 测试通道。配置 / setup 变更仍会回退到原生根项目运行，以便在需要时广泛重新运行接线相关修改。 +- `pnpm changed:lanes`：显示针对 `origin/main` 的 diff 所触发的架构测试通道。 +- `pnpm check:changed`：针对 `origin/main` 的 diff 运行智能变更门禁。它会将核心工作与核心测试通道一起运行，将扩展工作与扩展测试通道一起运行，将纯测试类工作限制为测试类型检查 / 测试本身，将公开的 插件 SDK 或插件契约变更扩展为一次扩展验证流程，并对仅涉及发布元数据的版本号变更保持在定向版本 / 配置 / 根依赖检查范围内。 +- `pnpm test`：通过有范围限制的 Vitest 测试通道路由显式的文件 / 目录目标。未指定目标的运行会使用固定的分片组，并展开为叶子配置以便在本地并行执行；扩展组始终会展开为按扩展划分的分片配置，而不是一个巨大的根项目进程。 +- 完整、扩展以及 include-pattern 分片运行会将本地计时数据更新到 `.artifacts/vitest-shard-timings.json`；后续的整配置运行会使用这些计时数据来平衡慢速和快速分片。include-pattern CI 分片会将分片名称追加到计时键名中，这样可以保留筛选后分片的计时信息，而不会替换整配置的计时数据。设置 `OPENCLAW_TEST_PROJECTS_TIMINGS=0` 可忽略本地计时产物。 +- 选定的 `plugin-sdk` 和 `commands` 测试文件现在会路由到专用的轻量测试通道，这些通道仅保留 `test/setup.ts`，而运行时较重的用例仍保留在现有测试通道中。 +- 选定的 `plugin-sdk` 和 `commands` 辅助源文件也会将 `pnpm test:changed` 映射到这些轻量测试通道中的显式同级测试，因此小型辅助文件修改无需重新运行重量级、依赖运行时的测试套件。 +- `auto-reply` 现在也被拆分为三个专用配置（`core`、`top-level`、`reply`），因此 reply harness 不会主导较轻量的顶层 status / token / helper 测试。 +- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并在整个仓库配置中启用了共享的非隔离 runner。 - `pnpm test:channels` 运行 `vitest.channels.config.ts`。 -- `pnpm test:extensions` 和 `pnpm test extensions` 运行所有扩展/插件分片。重量级渠道插件、浏览器插件和 OpenAI 会作为专用分片运行；其他插件组仍保持批量运行。对某个内置插件通道使用 `pnpm test extensions/`。 -- `pnpm test:perf:imports`：启用 Vitest 的导入耗时和导入明细报告，同时仍对显式文件/目录目标使用有范围限制的通道路由。 -- `pnpm test:perf:imports:changed`：相同的导入性能分析，但仅针对相对于 `origin/main` 发生变更的文件。 -- `pnpm test:perf:changed:bench -- --ref `：针对同一份已提交 Git diff，将路由后的 changed 模式路径与原生根项目运行进行基准对比。 -- `pnpm test:perf:changed:bench -- --worktree`：无需先提交，直接对当前工作树的变更集进行基准测试。 +- `pnpm test:extensions` 和 `pnpm test extensions` 会运行所有扩展 / 插件分片。重量级渠道插件、浏览器插件以及 OpenAI 会作为专用分片运行；其他插件组仍保持批量运行。对单个内置插件测试通道，请使用 `pnpm test extensions/`。 +- `pnpm test:perf:imports`：启用 Vitest 导入时长 + 导入明细报告，同时仍对显式文件 / 目录目标使用有范围限制的测试通道路由。 +- `pnpm test:perf:imports:changed`：同样进行导入性能分析，但仅针对相对于 `origin/main` 有变更的文件。 +- `pnpm test:perf:changed:bench -- --ref `：针对同一份已提交的 Git diff，对路由后的 changed 模式路径与原生根项目运行进行基准对比。 +- `pnpm test:perf:changed:bench -- --worktree`：无需先提交，直接对当前工作树变更集进行基准测试。 - `pnpm test:perf:profile:main`：为 Vitest 主线程写入 CPU profile（`.artifacts/vitest-main-profile`）。 -- `pnpm test:perf:profile:runner`：为单元测试运行器写入 CPU + heap profile（`.artifacts/vitest-runner-profile`）。 -- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`：串行运行每个完整测试套件的 Vitest 叶子配置，并写入分组耗时数据以及每个配置对应的 JSON/日志产物。Test Performance Agent 会在尝试修复慢测试之前，将其用作基线。 -- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`：在一次面向性能的变更之后，对分组报告进行比较。 -- Gateway 网关集成测试：通过 `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` 或 `pnpm test:gateway` 选择启用。 -- `pnpm test:e2e`：运行 Gateway 网关端到端冒烟测试（多实例 WS/HTTP/节点配对）。在 `vitest.e2e.config.ts` 中默认使用 `threads` + `isolate: false`，并启用自适应 worker；可用 `OPENCLAW_E2E_WORKERS=` 调整，设置 `OPENCLAW_E2E_VERBOSE=1` 可输出详细日志。 -- `pnpm test:live`：运行提供商 live 测试（minimax/zai）。需要 API 密钥以及 `LIVE=1`（或提供商专用的 `*_LIVE_TEST=1`）才能取消跳过。 -- `pnpm test:docker:all`：先构建一次共享的 live-test 镜像和 Docker E2E 镜像，然后通过加权调度器在 `OPENCLAW_SKIP_DOCKER_BUILD=1` 下运行 Docker 冒烟测试通道。`OPENCLAW_DOCKER_ALL_PARALLELISM=` 控制进程槽位，默认值为 10；`OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=` 控制对提供商敏感的尾部池，默认值为 10。重量级通道上限默认分别为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`；提供商上限默认通过 `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`、`OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` 和 `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4` 设置为每个提供商一个重量级通道。更大的主机可使用 `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` 或 `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`。默认情况下，通道启动会间隔 2 秒，以避免本地 Docker daemon 出现创建风暴；可通过 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=` 覆盖。运行器默认会先对 Docker 做预检，清理陈旧的 OpenClaw E2E 容器，每 30 秒输出一次活动通道状态，在兼容通道之间共享提供商 CLI 工具缓存，默认对瞬时的 live 提供商失败重试一次（`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=`），并将通道耗时存储到 `.artifacts/docker-tests/lane-timings.json`，供后续运行按最长优先排序。使用 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 可仅打印通道清单而不运行 Docker，使用 `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=` 可调整状态输出频率，或使用 `OPENCLAW_DOCKER_ALL_TIMINGS=0` 禁用耗时复用。对只需要确定性/本地通道时，使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip`；对只需要 live 提供商通道时，使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=only`；对应的包别名为 `pnpm test:docker:local:all` 和 `pnpm test:docker:live:all`。live-only 模式会将主 live 通道和尾部 live 通道合并为一个按最长优先排序的池，以便提供商桶能将 Claude、Codex 和 Gemini 的任务一起打包。除非设置了 `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`，否则运行器会在首次失败后停止调度新的池化通道；每个通道都有默认 120 分钟的后备超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；部分选定的 live/tail 通道使用更严格的单通道上限。CLI 后端 Docker 设置命令有单独的超时控制，使用 `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS`（默认 180）。每个通道的日志会写入 `.artifacts/docker-tests//`。 -- CLI 后端 live Docker 探测可以作为聚焦通道运行，例如 `pnpm test:docker:live-cli-backend:codex`、`pnpm test:docker:live-cli-backend:codex:resume` 或 `pnpm test:docker:live-cli-backend:codex:mcp`。Claude 和 Gemini 也有对应的 `:resume` 与 `:mcp` 别名。 -- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行一次真实的代理聊天。它需要可用的 live 模型密钥（例如 `~/.profile` 中的 OpenAI），会拉取外部 Open WebUI 镜像，并不像常规 unit/e2e 测试套件那样预期具备 CI 稳定性。 -- `pnpm test:docker:mcp-channels`：启动一个带种子数据的 Gateway 网关容器和第二个客户端容器，后者会启动 `openclaw mcp serve`，然后验证经路由的会话发现、转录读取、附件元数据、live 事件队列行为、出站发送路由，以及通过真实 stdio bridge 传输的 Claude 风格渠道 + 权限通知。Claude 通知断言会直接读取原始 stdio MCP 帧，因此该冒烟测试反映的是 bridge 实际发出的内容。 +- `pnpm test:perf:profile:runner`：为单元测试 runner 写入 CPU + 堆 profile（`.artifacts/vitest-runner-profile`）。 +- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`：串行运行完整测试套件中的每个 Vitest 叶子配置，并写入分组时长数据以及每个配置对应的 JSON / 日志产物。Test Performance Agent 会在尝试修复慢测试之前，将其用作基线。 +- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`：对以性能为重点的变更前后进行分组报告比较。 +- Gateway 网关集成测试：通过 `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` 或 `pnpm test:gateway` 选择性启用。 +- `pnpm test:e2e`：运行 Gateway 网关端到端冒烟测试（多实例 WS/HTTP/节点配对）。在 `vitest.e2e.config.ts` 中默认使用 `threads` + `isolate: false`，并采用自适应 worker；可通过 `OPENCLAW_E2E_WORKERS=` 调整，并设置 `OPENCLAW_E2E_VERBOSE=1` 以输出详细日志。 +- `pnpm test:live`：运行提供商实时测试（minimax/zai）。需要 API 密钥以及 `LIVE=1`（或特定提供商的 `*_LIVE_TEST=1`）才能取消跳过。 +- `pnpm test:docker:all`：构建共享的实时测试镜像和 Docker E2E 镜像各一次，然后通过加权调度器在 `OPENCLAW_SKIP_DOCKER_BUILD=1` 下运行 Docker 冒烟测试通道。`OPENCLAW_DOCKER_ALL_PARALLELISM=` 控制进程槽位，默认值为 10；`OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=` 控制对提供商敏感的尾部池，默认值也为 10。重量级测试通道上限默认分别为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`；提供商上限默认是每个提供商一个重量级测试通道桶，对应 `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`、`OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` 和 `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`。对于更大的主机，可使用 `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` 或 `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`。默认情况下，各测试通道会错开 2 秒启动，以避免本地 Docker daemon 在创建容器时出现风暴；可通过 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=` 覆盖。runner 默认会先执行 Docker 预检查、清理陈旧的 OpenClaw E2E 容器、每 30 秒输出一次活跃测试通道状态、在兼容测试通道之间共享提供商 CLI 工具缓存、默认对瞬时的实时提供商失败重试一次（`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=`），并将测试通道计时信息存储到 `.artifacts/docker-tests/lane-timings.json`，以便后续运行按“最长优先”排序。使用 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 可仅打印测试通道清单而不运行 Docker，使用 `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=` 可调整状态输出频率，使用 `OPENCLAW_DOCKER_ALL_TIMINGS=0` 可禁用计时复用。若仅需确定性 / 本地测试通道，请使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip`；若仅需实时提供商测试通道，请使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=only`；对应的软件包别名为 `pnpm test:docker:local:all` 和 `pnpm test:docker:live:all`。仅实时模式会将 main 和 tail 的实时测试通道合并为一个按最长优先排序的池，以便提供商桶可以一起打包 Claude、Codex 和 Gemini 工作。除非设置 `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`，否则 runner 会在首次失败后停止调度新的池化测试通道；每个测试通道都有 120 分钟的后备超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；部分选定的实时 / 尾部测试通道使用更严格的单通道上限。CLI 后端 Docker setup 命令拥有单独的超时设置，可通过 `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` 控制（默认 180）。每个测试通道的日志会写入 `.artifacts/docker-tests//`。 +- CLI 后端实时 Docker 探测可以作为聚焦测试通道运行，例如 `pnpm test:docker:live-cli-backend:codex`、`pnpm test:docker:live-cli-backend:codex:resume` 或 `pnpm test:docker:live-cli-backend:codex:mcp`。Claude 和 Gemini 也有对应的 `:resume` 和 `:mcp` 别名。 +- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行一次真实的代理聊天。它需要一个可用的实时模型密钥（例如在 `~/.profile` 中配置的 OpenAI），会拉取外部 Open WebUI 镜像，而且不像常规单元 / e2e 测试套件那样预期具备 CI 稳定性。 +- `pnpm test:docker:mcp-channels`：启动一个带种子数据的 Gateway 网关容器和第二个客户端容器，后者会启动 `openclaw mcp serve`，然后验证路由会话发现、转录读取、附件元数据、实时事件队列行为、出站发送路由，以及通过真实 stdio bridge 传递的类 Claude 渠道 + 权限通知。Claude 通知断言会直接读取原始 stdio MCP 帧，因此该冒烟测试能够反映 bridge 实际发出的内容。 ## 本地 PR 门禁 -对于本地 PR 合并/门禁检查，运行： +对于本地 PR 合并 / 门禁检查，请运行： - `pnpm check:changed` - `pnpm check` @@ -55,12 +55,12 @@ x-i18n: - `pnpm test` - `pnpm check:docs` -如果 `pnpm test` 在高负载主机上偶发失败，先重跑一次，再决定是否将其视为回归，然后使用 `pnpm test ` 进行定位。对于内存受限的主机，使用： +如果 `pnpm test` 在高负载主机上偶发失败，请先重跑一次，再判断是否为回归问题；之后可使用 `pnpm test ` 进行隔离。对于内存受限的主机，请使用： - `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test` - `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed` -## 模型延迟基准（本地密钥） +## 模型延迟基准测试（本地密钥） 脚本：[`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts) @@ -75,7 +75,7 @@ x-i18n: - minimax 中位数 1279ms（最小 1114，最大 2431） - opus 中位数 2454ms（最小 1224，最大 3170） -## CLI 启动基准 +## CLI 启动基准测试 脚本：[`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts) @@ -100,15 +100,15 @@ x-i18n: - `startup`：`--version`、`--help`、`health`、`health --json`、`status --json`、`status` - `real`：`health`、`status`、`status --json`、`sessions`、`sessions --json`、`agents list --json`、`gateway status`、`gateway status --json`、`gateway health --json`、`config get gateway.port` -- `all`：同时包含两个预设 +- `all`：以上两个预设的组合 -输出包括每个命令的 `sampleCount`、平均值、p50、p95、最小/最大值、退出码/信号分布，以及最大 RSS 汇总。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写入 V8 profile，以便耗时统计和 profile 捕获使用同一个 harness。 +输出内容包括每个命令的 `sampleCount`、平均值、p50、p95、最小 / 最大值、退出码 / signal 分布，以及最大 RSS 摘要。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写入 V8 profile，这样计时与 profile 捕获就会使用同一个 harness。 -保存输出约定： +已保存输出约定： -- `pnpm test:startup:bench:smoke` 会将目标冒烟产物写入 `.artifacts/cli-startup-bench-smoke.json` -- `pnpm test:startup:bench:save` 会以 `runs=5` 和 `warmup=1` 将完整测试套件产物写入 `.artifacts/cli-startup-bench-all.json` -- `pnpm test:startup:bench:update` 会以 `runs=5` 和 `warmup=1` 刷新已提交的基线 fixture：`test/fixtures/cli-startup-bench.json` +- `pnpm test:startup:bench:smoke` 会将定向冒烟产物写入 `.artifacts/cli-startup-bench-smoke.json` +- `pnpm test:startup:bench:save` 会使用 `runs=5` 和 `warmup=1` 将完整测试套件产物写入 `.artifacts/cli-startup-bench-all.json` +- `pnpm test:startup:bench:update` 会使用 `runs=5` 和 `warmup=1` 刷新已提交的基线 fixture，路径为 `test/fixtures/cli-startup-bench.json` 已提交的 fixture： @@ -118,19 +118,19 @@ x-i18n: ## 新手引导 E2E（Docker） -Docker 是可选的；只有在进行容器化的新手引导冒烟测试时才需要。 +Docker 是可选的；只有在需要容器化的新手引导冒烟测试时才需要它。 -在一个干净的 Linux 容器中运行完整冷启动流程： +在干净的 Linux 容器中执行完整的冷启动流程： ```bash scripts/e2e/onboard-docker.sh ``` -该脚本通过伪终端驱动交互式向导，验证配置/工作区/会话文件，然后启动 Gateway 网关并运行 `openclaw health`。 +该脚本会通过伪终端驱动交互式向导，验证配置 / 工作区 / 会话文件，然后启动 Gateway 网关并运行 `openclaw health`。 -## 二维码导入冒烟测试（Docker） +## QR 导入冒烟测试（Docker） -确保维护中的二维码运行时辅助模块能够在受支持的 Docker Node 运行时下加载（默认 Node 24，兼容 Node 22）： +确保受维护的 QR 运行时辅助工具可在受支持的 Docker Node 运行时下加载（默认 Node 24，兼容 Node 22）： ```bash pnpm test:docker:qr @@ -139,4 +139,4 @@ pnpm test:docker:qr ## 相关内容 - [测试](/zh-CN/help/testing) -- [live 测试](/zh-CN/help/testing-live) +- [实时测试](/zh-CN/help/testing-live) diff --git a/docs/zh-CN/tools/tts.md b/docs/zh-CN/tools/tts.md index 77ef69783..19adbb58b 100644 --- a/docs/zh-CN/tools/tts.md +++ b/docs/zh-CN/tools/tts.md @@ -3,84 +3,91 @@ read_when: - 为回复启用文本转语音 - 配置 TTS 提供商或限制 - 使用 `/tts` 命令 -summary: 用于发送回复的文本转语音（TTS） +summary: 用于外发回复的文本转语音（TTS） title: 文本转语音 x-i18n: - generated_at: "2026-04-25T21:40:07Z" + generated_at: "2026-04-25T22:52:57Z" model: gpt-5.4 provider: openai - source_hash: 2c428bb47d626446ca0a8cafac66f3c244af83df921dd3ab9a16c3cb8e321f6b + source_hash: cde18cee5061f315fb60cc23c07d11f20cf51b8b094a85cc100c1402a5ea0f4d source_path: tools/tts.md workflow: 15 --- -OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Inworld、Local CLI、Microsoft、MiniMax、OpenAI、Vydra、xAI 或 Xiaomi MiMo，将发送出去的回复转换为音频。 -它适用于 OpenClaw 可以发送音频的任何地方。 +OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Inworld、Local CLI、Microsoft、MiniMax、OpenAI、Volcengine、Vydra、xAI 或 Xiaomi MiMo，将外发回复转换为音频。 +它适用于 OpenClaw 能发送音频的任何地方。 ## 支持的服务 -- **ElevenLabs**（主提供商或回退提供商） -- **Google Gemini**（主提供商或回退提供商；使用 Gemini API TTS） -- **Gradium**（主提供商或回退提供商；支持语音便笺和电话输出） -- **Inworld**（主提供商或回退提供商；使用 Inworld 流式 TTS API） -- **Local CLI**（主提供商或回退提供商；运行已配置的本地 TTS 命令） -- **Microsoft**（主提供商或回退提供商；当前内置实现使用 `node-edge-tts`） -- **MiniMax**（主提供商或回退提供商；使用 T2A v2 API） -- **OpenAI**（主提供商或回退提供商；也用于摘要） -- **Vydra**（主提供商或回退提供商；共享的图像、视频和语音提供商） -- **xAI**（主提供商或回退提供商；使用 xAI TTS API） -- **Xiaomi MiMo**（主提供商或回退提供商；通过 Xiaomi chat completions 使用 MiMo TTS） +- **ElevenLabs**（主要或回退提供商） +- **Google Gemini**（主要或回退提供商；使用 Gemini API TTS） +- **Gradium**（主要或回退提供商；支持语音便笺和电话输出） +- **Inworld**（主要或回退提供商；使用 Inworld 流式 TTS API） +- **Local CLI**（主要或回退提供商；运行已配置的本地 TTS 命令） +- **Microsoft**（主要或回退提供商；当前内置实现使用 `node-edge-tts`） +- **MiniMax**（主要或回退提供商；使用 T2A v2 API） +- **OpenAI**（主要或回退提供商；也用于摘要） +- **Volcengine**（主要或回退提供商；使用 BytePlus Seed Speech HTTP API） +- **Vydra**（主要或回退提供商；共享图像、视频和语音提供商） +- **xAI**（主要或回退提供商；使用 xAI TTS API） +- **Xiaomi MiMo**（主要或回退提供商；通过 Xiaomi 聊天补全使用 MiMo TTS） ### Microsoft 语音说明 -当前内置的 Microsoft 语音提供商通过 `node-edge-tts` 库，使用 Microsoft Edge 在线神经网络 TTS 服务。它是托管服务（不是本地服务），使用 Microsoft 端点，并且不需要 API 密钥。 -`node-edge-tts` 提供语音配置选项和输出格式，但并非所有选项都受该服务支持。使用 `edge` 的旧版配置和指令输入仍然有效，并会被规范化为 `microsoft`。 +当前内置的 Microsoft 语音提供商通过 `node-edge-tts` 库使用 Microsoft Edge 的在线神经网络 TTS 服务。它是托管服务（不是本地服务），使用 Microsoft 端点，并且不需要 API 密钥。 +`node-edge-tts` 提供语音配置选项和输出格式，但并非所有选项都受该服务支持。使用 `edge` 的旧版配置和指令输入仍然有效，并会规范化为 `microsoft`。 -由于这一路径是公共 Web 服务，没有公开发布的 SLA 或配额，因此应将其视为尽力而为的服务。如果你需要有保证的限额和支持，请使用 OpenAI 或 ElevenLabs。 +由于这一路径是一个未公布 SLA 或配额的公共 Web 服务，请将其视为尽力而为的服务。如果你需要有保障的限制和支持，请使用 OpenAI 或 ElevenLabs。 -## 可选键 +## 可选密钥 -如果你想使用 ElevenLabs、Google Gemini、Gradium、Inworld、MiniMax、OpenAI、Vydra、xAI 或 Xiaomi MiMo： +如果你想使用 ElevenLabs、Google Gemini、Gradium、Inworld、MiniMax、OpenAI、Volcengine、Vydra、xAI 或 Xiaomi MiMo： - `ELEVENLABS_API_KEY`（或 `XI_API_KEY`） - `GEMINI_API_KEY`（或 `GOOGLE_API_KEY`） - `GRADIUM_API_KEY` - `INWORLD_API_KEY` -- `MINIMAX_API_KEY`；MiniMax TTS 也接受通过 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_CODING_API_KEY` 提供的 Token Plan 认证 +- `MINIMAX_API_KEY`；MiniMax TTS 还接受通过以下方式进行 Token Plan 认证： + `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 + `MINIMAX_CODING_API_KEY` - `OPENAI_API_KEY` +- `VOLCENGINE_TTS_API_KEY`（或 `BYTEPLUS_SEED_SPEECH_API_KEY`）； + 旧版 AppID/token 认证也接受 `VOLCENGINE_TTS_APPID` 和 + `VOLCENGINE_TTS_TOKEN` - `VYDRA_API_KEY` - `XAI_API_KEY` - `XIAOMI_API_KEY` -Local CLI 和 Microsoft 语音 **不** 需要 API 密钥。 +Local CLI 和 Microsoft 语音**不**需要 API 密钥。 -如果配置了多个提供商，则会优先使用选定的提供商，其他提供商将作为回退选项。 -自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用摘要，该提供商也必须完成认证。 +如果配置了多个提供商，则会优先使用已选提供商，其他提供商作为回退选项。 +自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用了摘要，对应提供商也必须完成认证。 ## 服务链接 -- [OpenAI Text-to-Speech guide](https://platform.openai.com/docs/guides/text-to-speech) -- [OpenAI Audio API reference](https://platform.openai.com/docs/api-reference/audio) -- [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech) -- [ElevenLabs Authentication](https://elevenlabs.io/docs/api-reference/authentication) +- [OpenAI 文本转语音指南](https://platform.openai.com/docs/guides/text-to-speech) +- [OpenAI Audio API 参考](https://platform.openai.com/docs/api-reference/audio) +- [ElevenLabs 文本转语音](https://elevenlabs.io/docs/api-reference/text-to-speech) +- [ElevenLabs 认证](https://elevenlabs.io/docs/api-reference/authentication) - [Gradium](/zh-CN/providers/gradium) - [Inworld TTS API](https://docs.inworld.ai/tts/tts) - [MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2) -- [Xiaomi MiMo speech synthesis](/zh-CN/providers/xiaomi#text-to-speech) +- [Volcengine TTS HTTP API](/zh-CN/providers/volcengine#text-to-speech) +- [Xiaomi MiMo 语音合成](/zh-CN/providers/xiaomi#text-to-speech) - [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts) -- [Microsoft Speech output formats](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) -- [xAI Text to Speech](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest) +- [Microsoft Speech 输出格式](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) +- [xAI 文本转语音](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest) ## 默认启用吗？ -不是。自动 TTS 默认 **关闭**。可在配置中通过 `messages.tts.auto` 启用，或在本地通过 `/tts on` 启用。 +不会。自动 TTS 默认**关闭**。可通过配置中的 `messages.tts.auto` 启用，或在本地使用 `/tts on` 启用。 -当未设置 `messages.tts.provider` 时，OpenClaw 会按照注册表自动选择顺序，选择第一个已配置的语音提供商。 +当未设置 `messages.tts.provider` 时，OpenClaw 会按注册表自动选择顺序挑选第一个已配置的语音提供商。 ## 配置 -TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 -完整 schema 见 [Gateway 网关配置](/zh-CN/gateway/configuration)。 +TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 +完整 schema 请见 [Gateway 网关配置](/zh-CN/gateway/configuration)。 ### 最小配置（启用 + 提供商） @@ -95,7 +102,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### OpenAI 主提供商，ElevenLabs 回退 +### OpenAI 为主，ElevenLabs 为回退 ```json5 { @@ -136,7 +143,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### Microsoft 主提供商（无 API 密钥） +### Microsoft 为主（无 API 密钥） ```json5 { @@ -159,7 +166,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### MiniMax 主提供商 +### MiniMax 为主 ```json5 { @@ -183,9 +190,9 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -MiniMax TTS 的认证解析顺序为 `messages.tts.providers.minimax.apiKey`，然后是已存储的 `minimax-portal` OAuth/token 配置文件，然后是 Token Plan 环境变量键（`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`），最后是 `MINIMAX_API_KEY`。当未显式设置 TTS `baseUrl` 时，OpenClaw 可以复用已配置的 `minimax-portal` OAuth 主机用于 Token Plan 语音。 +MiniMax TTS 的认证解析顺序为 `messages.tts.providers.minimax.apiKey`，然后是已存储的 `minimax-portal` OAuth/token 配置文件，再然后是 Token Plan 环境变量键（`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`），最后是 `MINIMAX_API_KEY`。当未显式设置 TTS `baseUrl` 时，OpenClaw 可以为 Token Plan 语音复用已配置的 `minimax-portal` OAuth 主机。 -### Google Gemini 主提供商 +### Google Gemini 为主 ```json5 { @@ -205,9 +212,9 @@ MiniMax TTS 的认证解析顺序为 `messages.tts.providers.minimax.apiKey`， } ``` -Google Gemini TTS 使用 Gemini API 密钥路径。这里可以使用限制为 Gemini API 的 Google Cloud Console API 密钥，其密钥样式与内置 Google 图像生成提供商使用的相同。解析顺序为 `messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` -> `GEMINI_API_KEY` -> `GOOGLE_API_KEY`。 +Google Gemini TTS 使用 Gemini API 密钥路径。这里可以使用限制为 Gemini API 的 Google Cloud Console API 密钥，而且它与内置 Google 图像生成提供商所用的密钥类型相同。解析顺序为 `messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` -> `GEMINI_API_KEY` -> `GOOGLE_API_KEY`。 -### Inworld 主提供商 +### Inworld 为主 ```json5 { @@ -229,9 +236,32 @@ Google Gemini TTS 使用 Gemini API 密钥路径。这里可以使用限制为 G } ``` -`apiKey` 值必须是从 Inworld 控制台（Workspace > API Keys）原样复制的 Base64 编码凭证字符串。提供商会将它作为 `Authorization: Basic ` 发送，而不会进行任何额外编码，因此不要传入原始 bearer token，也不要自行进行 Base64 编码。该密钥会回退到 `INWORLD_API_KEY` 环境变量。完整设置请参见 [Inworld provider](/zh-CN/providers/inworld)。 +`apiKey` 的值必须是从 Inworld 控制台逐字复制的 Base64 编码凭证字符串（Workspace > API Keys）。提供商会将其作为 `Authorization: Basic ` 发送，不会进行任何额外编码，因此不要传入原始 bearer token，也不要自行再次进行 Base64 编码。该密钥会回退到 `INWORLD_API_KEY` 环境变量。完整设置请参见 [Inworld 提供商](/zh-CN/providers/inworld)。 -### xAI 主提供商 +### Volcengine 为主 + +```json5 +{ + messages: { + tts: { + auto: "always", + provider: "volcengine", + providers: { + volcengine: { + apiKey: "byteplus_seed_speech_api_key", + resourceId: "seed-tts-1.0", + voice: "en_female_anna_mars_bigtts", + speedRatio: 1.0, + }, + }, + }, + }, +} +``` + +Volcengine TTS 使用来自 Speech Console 的 BytePlus Seed Speech API 密钥，而不是 Doubao 模型提供商所使用的 OpenAI 兼容 `VOLCANO_ENGINE_API_KEY`。解析顺序为 `messages.tts.providers.volcengine.apiKey` -> `VOLCENGINE_TTS_API_KEY` -> `BYTEPLUS_SEED_SPEECH_API_KEY`。旧版 AppID/token 认证仍可通过 `messages.tts.providers.volcengine.appId` / `token` 或 `VOLCENGINE_TTS_APPID` / `VOLCENGINE_TTS_TOKEN` 使用。语音便笺目标会请求提供商原生的 `ogg_opus`；普通音频文件目标会请求 `mp3`。 + +### xAI 为主 ```json5 { @@ -253,9 +283,9 @@ Google Gemini TTS 使用 Gemini API 密钥路径。这里可以使用限制为 G } ``` -xAI TTS 使用与内置 Grok 模型提供商相同的 `XAI_API_KEY` 路径。解析顺序为 `messages.tts.providers.xai.apiKey` -> `XAI_API_KEY`。当前可用语音为 `ara`、`eve`、`leo`、`rex`、`sal` 和 `una`；默认值是 `eve`。`language` 接受 BCP-47 标签或 `auto`。 +xAI TTS 使用与内置 Grok 模型提供商相同的 `XAI_API_KEY` 路径。解析顺序为 `messages.tts.providers.xai.apiKey` -> `XAI_API_KEY`。当前可用的实时语音有 `ara`、`eve`、`leo`、`rex`、`sal` 和 `una`；默认值为 `eve`。`language` 接受 BCP-47 标签或 `auto`。 -### Xiaomi MiMo 主提供商 +### Xiaomi MiMo 为主 ```json5 { @@ -278,9 +308,9 @@ xAI TTS 使用与内置 Grok 模型提供商相同的 `XAI_API_KEY` 路径。解 } ``` -Xiaomi MiMo TTS 使用与内置 Xiaomi 模型提供商相同的 `XIAOMI_API_KEY` 路径。语音提供商 id 为 `xiaomi`；`mimo` 也可作为别名使用。目标文本会作为 assistant message 发送，以匹配 Xiaomi 的 TTS 契约。可选的 `style` 会作为用户指令发送，不会被朗读。 +Xiaomi MiMo TTS 使用与内置 Xiaomi 模型提供商相同的 `XIAOMI_API_KEY` 路径。语音提供商 id 为 `xiaomi`；`mimo` 也可作为别名使用。目标文本会作为 assistant 消息发送，这与 Xiaomi 的 TTS 协议一致。可选的 `style` 会作为用户指令发送，不会被朗读。 -### OpenRouter 主提供商 +### OpenRouter 为主 ```json5 { @@ -301,9 +331,10 @@ Xiaomi MiMo TTS 使用与内置 Xiaomi 模型提供商相同的 `XIAOMI_API_KEY` } ``` -OpenRouter TTS 使用与内置 OpenRouter 模型提供商相同的 `OPENROUTER_API_KEY` 路径。解析顺序为 `messages.tts.providers.openrouter.apiKey` -> `models.providers.openrouter.apiKey` -> `OPENROUTER_API_KEY`。 +OpenRouter TTS 使用与内置 OpenRouter 模型提供商相同的 `OPENROUTER_API_KEY` 路径。解析顺序为 `messages.tts.providers.openrouter.apiKey` -> +`models.providers.openrouter.apiKey` -> `OPENROUTER_API_KEY`。 -### Local CLI 主提供商 +### Local CLI 为主 ```json5 { @@ -324,10 +355,9 @@ OpenRouter TTS 使用与内置 OpenRouter 模型提供商相同的 `OPENROUTER_A } ``` -Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}` 和 `{{OutputBase}}` 占位符会在 `args` 中展开；如果不存在 `{{Text}}` 占位符，OpenClaw 会将待朗读文本写入 stdin。`outputFormat` 接受 `mp3`、`opus` 或 `wav`。 -语音便笺目标会被转码为 Ogg/Opus，电话输出会使用 `ffmpeg` 转码为原始 16 kHz 单声道 PCM。旧版提供商别名 `cli` 仍然可用，但新配置应使用 `tts-local-cli`。 +Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`args` 中的 `{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}` 和 `{{OutputBase}}` 占位符会被展开；如果不存在 `{{Text}}` 占位符，OpenClaw 会将要朗读的文本写入 stdin。`outputFormat` 接受 `mp3`、`opus` 或 `wav`。语音便笺目标会被转码为 Ogg/Opus，电话输出会通过 `ffmpeg` 转码为原始 16 kHz 单声道 PCM。旧版提供商别名 `cli` 仍然有效，但新配置应使用 `tts-local-cli`。 -### Gradium 主提供商 +### Gradium 为主 ```json5 { @@ -378,7 +408,7 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} } ``` -### 仅在收到语音消息后用音频回复 +### 自定义限制 + prefs 路径 ```json5 { @@ -390,7 +420,7 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} } ``` -### 为长回复禁用自动摘要 +### 仅在收到入站语音消息后用音频回复 ```json5 { @@ -402,6 +432,8 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} } ``` +### 为长回复禁用自动摘要 + 然后运行： ``` @@ -411,41 +443,41 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} ### 字段说明 - `auto`：自动 TTS 模式（`off`、`always`、`inbound`、`tagged`）。 - - `inbound` 仅会在收到语音消息后发送音频。 - - `tagged` 仅会在回复包含 `[[tts:key=value]]` 指令或 `[[tts:text]]...[[/tts:text]]` 块时发送音频。 -- `enabled`：旧版开关（`doctor` 会将其迁移为 `auto`）。 + - `inbound` 仅在收到入站语音消息后发送音频。 + - `tagged` 仅当回复包含 `[[tts:key=value]]` 指令或 `[[tts:text]]...[[/tts:text]]` 块时发送音频。 +- `enabled`：旧版开关（Doctor 会将其迁移到 `auto`）。 - `mode`：`"final"`（默认）或 `"all"`（包含工具/分块回复）。 -- `provider`：语音提供商 id，例如 `"elevenlabs"`、`"google"`、`"gradium"`、`"inworld"`、`"microsoft"`、`"minimax"`、`"openai"`、`"vydra"`、`"xai"` 或 `"xiaomi"`（回退会自动处理）。 -- 如果未设置 `provider`，OpenClaw 会按注册表自动选择顺序使用第一个已配置的语音提供商。 -- 旧版 `provider: "edge"` 配置可由 `openclaw doctor --fix` 修复，并重写为 `provider: "microsoft"`。 -- `summaryModel`：用于自动摘要的可选低成本模型；默认值为 `agents.defaults.model.primary`。 +- `provider`：语音提供商 id，例如 `"elevenlabs"`、`"google"`、`"gradium"`、`"inworld"`、`"microsoft"`、`"minimax"`、`"openai"`、`"volcengine"`、`"vydra"`、`"xai"` 或 `"xiaomi"`（回退会自动处理）。 +- 如果 `provider` **未设置**，OpenClaw 会按注册表自动选择顺序使用第一个已配置的语音提供商。 +- 旧版 `provider: "edge"` 配置可通过 `openclaw doctor --fix` 修复，并重写为 `provider: "microsoft"`。 +- `summaryModel`：用于自动摘要的可选低成本模型；默认为 `agents.defaults.model.primary`。 - 接受 `provider/model` 或已配置的模型别名。 - `modelOverrides`：允许模型发出 TTS 指令（默认开启）。 - - `allowProvider` 默认是 `false`（切换提供商需要显式启用）。 -- `providers.`：由提供商自行管理的设置，按语音提供商 id 键控。 -- 旧版直接提供商块（`messages.tts.openai`、`messages.tts.elevenlabs`、`messages.tts.microsoft`、`messages.tts.edge`）可由 `openclaw doctor --fix` 修复；已提交的配置应使用 `messages.tts.providers.`。 -- 旧版 `messages.tts.providers.edge` 也可由 `openclaw doctor --fix` 修复；已提交的配置应使用 `messages.tts.providers.microsoft`。 -- `maxTextLength`：TTS 输入的硬性上限（字符数）。超过时，`/tts audio` 会失败。 -- `timeoutMs`：请求超时时间（毫秒）。 + - `allowProvider` 默认为 `false`（切换提供商需要显式启用）。 +- `providers.`：由提供商拥有的设置，按语音提供商 id 键控。 +- 旧版直接提供商配置块（`messages.tts.openai`、`messages.tts.elevenlabs`、`messages.tts.microsoft`、`messages.tts.edge`）可通过 `openclaw doctor --fix` 修复；已提交的配置应使用 `messages.tts.providers.`。 +- 旧版 `messages.tts.providers.edge` 也可通过 `openclaw doctor --fix` 修复；已提交的配置应使用 `messages.tts.providers.microsoft`。 +- `maxTextLength`：TTS 输入的硬性上限（字符数）。如果超过，`/tts audio` 会失败。 +- `timeoutMs`：请求超时（毫秒）。 - `prefsPath`：覆盖本地 prefs JSON 路径（provider/limit/summary）。 -- `apiKey` 值会回退到环境变量（`ELEVENLABS_API_KEY`/`XI_API_KEY`、`GEMINI_API_KEY`/`GOOGLE_API_KEY`、`GRADIUM_API_KEY`、`INWORLD_API_KEY`、`MINIMAX_API_KEY`、`OPENAI_API_KEY`、`VYDRA_API_KEY`、`XAI_API_KEY`、`XIAOMI_API_KEY`）。 +- `apiKey` 值会回退到环境变量（`ELEVENLABS_API_KEY`/`XI_API_KEY`、`GEMINI_API_KEY`/`GOOGLE_API_KEY`、`GRADIUM_API_KEY`、`INWORLD_API_KEY`、`MINIMAX_API_KEY`、`OPENAI_API_KEY`、`VYDRA_API_KEY`、`XAI_API_KEY`、`XIAOMI_API_KEY`）。Volcengine 则使用 `appId`/`token`。 - `providers.elevenlabs.baseUrl`：覆盖 ElevenLabs API 基础 URL。 - `providers.openai.baseUrl`：覆盖 OpenAI TTS 端点。 - 解析顺序：`messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` - - 非默认值会被视为与 OpenAI 兼容的 TTS 端点，因此可接受自定义模型名和语音名。 + - 非默认值会被视为 OpenAI 兼容 TTS 端点，因此接受自定义模型名和语音名。 - `providers.elevenlabs.voiceSettings`： - `stability`、`similarityBoost`、`style`：`0..1` - `useSpeakerBoost`：`true|false` - `speed`：`0.5..2.0`（1.0 = 正常） - `providers.elevenlabs.applyTextNormalization`：`auto|on|off` -- `providers.elevenlabs.languageCode`：2 位 ISO 639-1 代码（例如 `en`、`de`） -- `providers.elevenlabs.seed`：整数 `0..4294967295`（尽力实现确定性） +- `providers.elevenlabs.languageCode`：2 字母 ISO 639-1 代码（例如 `en`、`de`） +- `providers.elevenlabs.seed`：整数 `0..4294967295`（尽力保证确定性） - `providers.minimax.baseUrl`：覆盖 MiniMax API 基础 URL（默认 `https://api.minimax.io`，环境变量：`MINIMAX_API_HOST`）。 - `providers.minimax.model`：TTS 模型（默认 `speech-2.8-hd`，环境变量：`MINIMAX_TTS_MODEL`）。 - `providers.minimax.voiceId`：语音标识符（默认 `English_expressive_narrator`，环境变量：`MINIMAX_TTS_VOICE_ID`）。 - `providers.minimax.speed`：播放速度 `0.5..2.0`（默认 1.0）。 - `providers.minimax.vol`：音量 `(0, 10]`（默认 1.0；必须大于 0）。 -- `providers.minimax.pitch`：整数音高偏移 `-12..12`（默认 0）。小数值在调用 MiniMax T2A 之前会被截断，因为 API 会拒绝非整数音高值。 +- `providers.minimax.pitch`：整数音高偏移 `-12..12`（默认 0）。在调用 MiniMax T2A 之前，小数值会被截断，因为该 API 拒绝非整数的音高值。 - `providers.tts-local-cli.command`：用于 CLI TTS 的本地可执行文件或命令字符串。 - `providers.tts-local-cli.args`：命令参数；支持 `{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}` 和 `{{OutputBase}}` 占位符。 - `providers.tts-local-cli.outputFormat`：预期的 CLI 输出格式（`mp3`、`opus` 或 `wav`；音频附件默认值为 `mp3`）。 @@ -459,14 +491,28 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} - `providers.google.model`：Gemini TTS 模型（默认 `gemini-3.1-flash-tts-preview`）。 - `providers.google.voiceName`：Gemini 预置语音名称（默认 `Kore`；也接受 `voice`）。 - `providers.google.audioProfile`：在朗读文本前附加的自然语言风格提示。 -- `providers.google.speakerName`：当你的 TTS 提示使用具名说话人时，在朗读文本前附加的可选说话人标签。 -- `providers.google.baseUrl`：覆盖 Gemini API 基础 URL。仅接受 `https://generativelanguage.googleapis.com`。 - - 如果省略 `messages.tts.providers.google.apiKey`，则 TTS 可以在回退到环境变量前复用 `models.providers.google.apiKey`。 +- `providers.google.speakerName`：可选的说话人标签；当你的 TTS 提示使用具名说话人时，会在朗读文本前附加。 +- `providers.google.baseUrl`：覆盖 Gemini API 基础 URL。只接受 `https://generativelanguage.googleapis.com`。 + - 如果省略 `messages.tts.providers.google.apiKey`，TTS 可以在回退到环境变量之前复用 `models.providers.google.apiKey`。 - `providers.gradium.baseUrl`：覆盖 Gradium API 基础 URL（默认 `https://api.gradium.ai`）。 - `providers.gradium.voiceId`：Gradium 语音标识符（默认 Emma，`YTpq7expH9539ERJ`）。 +- `providers.volcengine.apiKey`：BytePlus Seed Speech API 密钥（环境变量： + `VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`）。 +- `providers.volcengine.resourceId`：BytePlus Seed Speech 资源 id（默认 + `seed-tts-1.0`，环境变量：`VOLCENGINE_TTS_RESOURCE_ID`；如果你的 BytePlus 项目具有 TTS 2.0 权限，请使用 `seed-tts-2.0`）。 +- `providers.volcengine.appKey`：BytePlus Seed Speech app key 请求头（默认 + `aGjiRDfUWi`，环境变量：`VOLCENGINE_TTS_APP_KEY`）。 +- `providers.volcengine.baseUrl`：覆盖 Seed Speech TTS HTTP 端点 + （环境变量：`VOLCENGINE_TTS_BASE_URL`）。 +- `providers.volcengine.appId`：旧版 Volcengine Speech Console 应用 id（环境变量：`VOLCENGINE_TTS_APPID`）。 +- `providers.volcengine.token`：旧版 Volcengine Speech Console 访问令牌（环境变量：`VOLCENGINE_TTS_TOKEN`）。 +- `providers.volcengine.cluster`：旧版 Volcengine TTS 集群（默认 `volcano_tts`，环境变量：`VOLCENGINE_TTS_CLUSTER`）。 +- `providers.volcengine.voice`：语音类型（默认 `en_female_anna_mars_bigtts`，环境变量：`VOLCENGINE_TTS_VOICE`）。 +- `providers.volcengine.speedRatio`：提供商原生速度比率。 +- `providers.volcengine.emotion`：提供商原生情感标签。 - `providers.xai.apiKey`：xAI TTS API 密钥（环境变量：`XAI_API_KEY`）。 - `providers.xai.baseUrl`：覆盖 xAI TTS 基础 URL（默认 `https://api.x.ai/v1`，环境变量：`XAI_BASE_URL`）。 -- `providers.xai.voiceId`：xAI 语音 id（默认 `eve`；当前在线语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`）。 +- `providers.xai.voiceId`：xAI 语音 id（默认 `eve`；当前可用的实时语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`）。 - `providers.xai.language`：BCP-47 语言代码或 `auto`（默认 `en`）。 - `providers.xai.responseFormat`：`mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`（默认 `mp3`）。 - `providers.xai.speed`：提供商原生速度覆盖。 @@ -475,34 +521,36 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} - `providers.xiaomi.model`：TTS 模型（默认 `mimo-v2.5-tts`，环境变量：`XIAOMI_TTS_MODEL`；也支持 `mimo-v2-tts`）。 - `providers.xiaomi.voice`：MiMo 语音 id（默认 `mimo_default`，环境变量：`XIAOMI_TTS_VOICE`）。 - `providers.xiaomi.format`：`mp3` 或 `wav`（默认 `mp3`，环境变量：`XIAOMI_TTS_FORMAT`）。 -- `providers.xiaomi.style`：可选的自然语言风格指令，会作为用户消息发送；不会被朗读。 +- `providers.xiaomi.style`：可选的自然语言风格指令，作为用户消息发送；不会被朗读。 - `providers.openrouter.apiKey`：OpenRouter API 密钥（环境变量：`OPENROUTER_API_KEY`；可复用 `models.providers.openrouter.apiKey`）。 - `providers.openrouter.baseUrl`：覆盖 OpenRouter TTS 基础 URL（默认 `https://openrouter.ai/api/v1`；旧版 `https://openrouter.ai/v1` 会被规范化）。 - `providers.openrouter.model`：OpenRouter TTS 模型 id（默认 `hexgrad/kokoro-82m`；也接受 `modelId`）。 -- `providers.openrouter.voice`：提供商特定语音 id（默认 `af_alloy`；也接受 `voiceId`）。 +- `providers.openrouter.voice`：提供商特定的语音 id（默认 `af_alloy`；也接受 `voiceId`）。 - `providers.openrouter.responseFormat`：`mp3` 或 `pcm`（默认 `mp3`）。 - `providers.openrouter.speed`：提供商原生速度覆盖。 - `providers.microsoft.enabled`：允许使用 Microsoft 语音（默认 `true`；无 API 密钥）。 -- `providers.microsoft.voice`：Microsoft 神经语音名称（例如 `en-US-MichelleNeural`）。 +- `providers.microsoft.voice`：Microsoft 神经网络语音名称（例如 `en-US-MichelleNeural`）。 - `providers.microsoft.lang`：语言代码（例如 `en-US`）。 - `providers.microsoft.outputFormat`：Microsoft 输出格式（例如 `audio-24khz-48kbitrate-mono-mp3`）。 - - 有效值请参见 Microsoft Speech output formats；并非所有格式都受内置的 Edge 后端传输支持。 + - 有效值请参见 Microsoft Speech 输出格式；并非所有格式都受内置的 Edge 后端传输支持。 - `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`：百分比字符串（例如 `+10%`、`-5%`）。 - `providers.microsoft.saveSubtitles`：在音频文件旁写入 JSON 字幕。 - `providers.microsoft.proxy`：Microsoft 语音请求的代理 URL。 - `providers.microsoft.timeoutMs`：请求超时覆盖（毫秒）。 -- `edge.*`：同一组 Microsoft 设置的旧版别名。运行 `openclaw doctor --fix` 可将已持久化配置重写为 `providers.microsoft`。 +- `edge.*`：同一组 Microsoft 设置的旧版别名。运行 + `openclaw doctor --fix` 可将持久化配置重写为 `providers.microsoft`。 ## 模型驱动的覆盖（默认开启） 默认情况下，模型**可以**为单条回复发出 TTS 指令。 当 `messages.tts.auto` 为 `tagged` 时，必须使用这些指令才能触发音频。 -启用后，模型可以发出 `[[tts:...]]` 指令来覆盖单条回复的语音设置，还可以附带一个可选的 `[[tts:text]]...[[/tts:text]]` 块，用于提供仅应出现在音频中的表现性标签（笑声、唱歌提示等）。 +启用后，模型可以发出 `[[tts:...]]` 指令来为单条回复覆盖语音， +并可选地使用 `[[tts:text]]...[[/tts:text]]` 块提供仅应出现在音频中的表现性标签（笑声、歌唱提示等）。 -除非设置 `modelOverrides.allowProvider: true`，否则 `provider=...` 指令会被忽略。 +除非设置了 `modelOverrides.allowProvider: true`，否则 `provider=...` 指令会被忽略。 -示例回复载荷： +示例回复负载： ``` Here you go. @@ -513,12 +561,13 @@ Here you go. 可用的指令键（启用时）： -- `provider`（已注册的语音提供商 id，例如 `openai`、`elevenlabs`、`google`、`gradium`、`minimax`、`microsoft`、`vydra`、`xai` 或 `xiaomi`；需要 `allowProvider: true`） -- `voice`（OpenAI、Gradium 或 Xiaomi 语音）、`voiceName` / `voice_name` / `google_voice`（Google 语音）或 `voiceId`（ElevenLabs / Gradium / MiniMax / xAI） -- `model`（OpenAI TTS 模型、ElevenLabs 模型 id、MiniMax 模型或 Xiaomi MiMo TTS 模型）或 `google_model`（Google TTS 模型） +- `provider`（已注册的语音提供商 id，例如 `openai`、`elevenlabs`、`google`、`gradium`、`minimax`、`microsoft`、`volcengine`、`vydra`、`xai` 或 `xiaomi`；需要 `allowProvider: true`） +- `voice`（OpenAI、Gradium、Volcengine 或 Xiaomi 语音）、`voiceName` / `voice_name` / `google_voice`（Google 语音）或 `voiceId`（ElevenLabs / Gradium / MiniMax / xAI） +- `model`（OpenAI TTS 模型、ElevenLabs model id、MiniMax 模型或 Xiaomi MiMo TTS 模型）或 `google_model`（Google TTS 模型） - `stability`、`similarityBoost`、`style`、`speed`、`useSpeakerBoost` - `vol` / `volume`（MiniMax 音量，0-10） - `pitch`（MiniMax 整数音高，-12 到 12；小数值会在发起 MiniMax 请求前被截断） +- `emotion`（Volcengine 情感标签） - `applyTextNormalization`（`auto|on|off`） - `languageCode`（ISO 639-1） - `seed` @@ -537,7 +586,7 @@ Here you go. } ``` -可选允许列表（启用提供商切换，同时保留其他旋钮可配置）： +可选 allowlist（启用提供商切换，同时保留其他参数可配置）： ```json5 { @@ -559,36 +608,40 @@ Here you go. `~/.openclaw/settings/tts.json`，可通过 `OPENCLAW_TTS_PREFS` 或 `messages.tts.prefsPath` 覆盖）。 -存储字段： +存储的字段： - `enabled` - `provider` - `maxLength`（摘要阈值；默认 1500 个字符） - `summarize`（默认 `true`） -这些设置会覆盖该主机上的 `messages.tts.*`。 +这些字段会覆盖该主机上的 `messages.tts.*`。 ## 输出格式（固定） - **Feishu / Matrix / Telegram / WhatsApp**：语音便笺回复优先使用 Opus（ElevenLabs 使用 `opus_48000_64`，OpenAI 使用 `opus`）。 - - 48 kHz / 64 kbps 是语音消息中兼顾效果与体积的较好折中。 -- **Feishu**：当语音便笺回复生成结果为 MP3/WAV/M4A 或其他可能的音频文件时，Feishu 插件会在发送原生 `audio` 气泡前，使用 `ffmpeg` 将其转码为 48 kHz Ogg/Opus。如果转换失败，Feishu 会收到原始文件作为附件。 + - 48 kHz / 64 kbps 是语音消息较好的折中方案。 +- **Feishu**：当语音便笺回复以 MP3/WAV/M4A 或其他 + 可能的音频文件格式生成时，Feishu 插件会在发送原生 `audio` 气泡之前使用 + `ffmpeg` 将其转码为 48 kHz Ogg/Opus。如果转换失败，Feishu + 会接收原始文件作为附件。 - **其他渠道**：MP3（ElevenLabs 使用 `mp3_44100_128`，OpenAI 使用 `mp3`）。 - - 44.1 kHz / 128 kbps 是语音清晰度的默认平衡选择。 -- **MiniMax**：普通音频附件使用 MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。对于 Feishu 和 Telegram 等语音便笺目标，OpenClaw 会在发送前使用 `ffmpeg` 将 MiniMax MP3 转码为 48 kHz Opus。 -- **Xiaomi MiMo**：默认使用 MP3，配置时也可使用 WAV。对于 Feishu 和 Telegram 等语音便笺目标，OpenClaw 会在发送前使用 `ffmpeg` 将 Xiaomi 输出转码为 48 kHz Opus。 -- **Local CLI**：使用已配置的 `outputFormat`。语音便笺目标会被转换为 Ogg/Opus，电话输出会使用 `ffmpeg` 转换为原始 16 kHz 单声道 PCM。 -- **Google Gemini**：Gemini API TTS 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 用于音频附件，为语音便笺目标转码为 48 kHz Opus，并为 Talk/电话场景直接返回 PCM。 -- **Gradium**：音频附件使用 WAV，语音便笺目标使用 Opus，电话场景使用 8 kHz 的 `ulaw_8000`。 -- **Inworld**：普通音频附件使用 MP3，语音便笺目标使用原生 `OGG_OPUS`，Talk/电话场景使用 22050 Hz 的原始 `PCM`。 -- **xAI**：默认使用 MP3；`responseFormat` 可为 `mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`。OpenClaw 使用 xAI 的批处理 REST TTS 端点，并返回完整音频附件；此提供商路径不使用 xAI 的流式 TTS WebSocket。此路径不支持原生 Opus 语音便笺格式。 + - 44.1 kHz / 128 kbps 是语音清晰度的默认平衡。 +- **MiniMax**：普通音频附件使用 MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。对于 Feishu 和 Telegram 等语音便笺目标，OpenClaw 会在投递前使用 `ffmpeg` 将 MiniMax MP3 转码为 48 kHz Opus。 +- **Xiaomi MiMo**：默认使用 MP3，或在配置时使用 WAV。对于 Feishu 和 Telegram 等语音便笺目标，OpenClaw 会在投递前使用 `ffmpeg` 将 Xiaomi 输出转码为 48 kHz Opus。 +- **Local CLI**：使用已配置的 `outputFormat`。语音便笺目标会被转换为 Ogg/Opus，电话输出会通过 `ffmpeg` 转换为原始 16 kHz 单声道 PCM。 +- **Google Gemini**：Gemini API TTS 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 以用于音频附件，为语音便笺目标转码为 48 kHz Opus，并为 Talk/电话直接返回 PCM。 +- **Gradium**：音频附件使用 WAV，语音便笺目标使用 Opus，电话使用 8 kHz 的 `ulaw_8000`。 +- **Inworld**：普通音频附件使用 MP3，语音便笺目标使用原生 `OGG_OPUS`，Talk/电话使用 22050 Hz 的原始 `PCM`。 +- **xAI**：默认使用 MP3；`responseFormat` 可以是 `mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`。OpenClaw 使用 xAI 的批量 REST TTS 端点并返回完整音频附件；此提供商路径不使用 xAI 的流式 TTS WebSocket。此路径不支持原生 Opus 语音便笺格式。 - **Microsoft**：使用 `microsoft.outputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。 - - 内置传输支持 `outputFormat`，但服务并不提供所有格式。 - - 输出格式值遵循 Microsoft Speech output formats（包括 Ogg/WebM Opus）。 - - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保证的 Opus 语音消息，请使用 OpenAI/ElevenLabs。 - - 如果已配置的 Microsoft 输出格式失败，OpenClaw 会回退重试 MP3。 + - 内置传输接受 `outputFormat`，但并非所有格式都可从该服务获得。 + - 输出格式值遵循 Microsoft Speech 输出格式（包括 Ogg/WebM Opus）。 + - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要 + 有保障的 Opus 语音消息，请使用 OpenAI/ElevenLabs。 + - 如果已配置的 Microsoft 输出格式失败，OpenClaw 会使用 MP3 重试。 -OpenAI/ElevenLabs 的输出格式按渠道固定（见上文）。 +OpenAI/ElevenLabs 输出格式按渠道固定（见上文）。 ## 自动 TTS 行为 @@ -596,32 +649,33 @@ OpenAI/ElevenLabs 的输出格式按渠道固定（见上文）。 - 如果回复已包含媒体或 `MEDIA:` 指令，则跳过 TTS。 - 跳过过短的回复（少于 10 个字符）。 -- 在启用时，使用 `agents.defaults.model.primary`（或 `summaryModel`）对较长回复生成摘要。 +- 如果启用，会使用 `agents.defaults.model.primary`（或 `summaryModel`）对长回复进行摘要。 - 将生成的音频附加到回复中。 -如果回复超过 `maxLength` 且摘要关闭（或摘要模型没有 API 密钥），则会跳过音频，并发送普通文本回复。 +如果回复超过 `maxLength` 且摘要已关闭（或摘要模型没有 API 密钥），则会跳过音频，并发送普通文本回复。 ## 流程图 ``` -Reply -> 启用 TTS？ - no -> 发送文本 - yes -> 有媒体 / MEDIA: / 太短？ - yes -> 发送文本 - no -> 长度 > 限制？ - no -> TTS -> 附加音频 - yes -> 启用摘要？ - no -> 发送文本 - yes -> 生成摘要（summaryModel 或 agents.defaults.model.primary） - -> TTS -> 附加音频 +Reply -> TTS enabled? + no -> send text + yes -> has media / MEDIA: / short? + yes -> send text + no -> length > limit? + no -> TTS -> attach audio + yes -> summary enabled? + no -> send text + yes -> summarize (summaryModel or agents.defaults.model.primary) + -> TTS -> attach audio ``` -## Slash 命令用法 +## 斜杠命令用法 只有一个命令：`/tts`。 -启用细节请参见 [Slash commands](/zh-CN/tools/slash-commands)。 +启用详情请参见 [斜杠命令](/zh-CN/tools/slash-commands)。 -Discord 说明：`/tts` 是 Discord 内置命令，因此 OpenClaw 会在那里注册 `/voice` 作为原生命令。文本形式的 `/tts ...` 仍然可用。 +Discord 说明：`/tts` 是 Discord 内置命令，因此 OpenClaw 会在那里注册 +`/voice` 作为原生命令。文本形式的 `/tts ...` 仍然可用。 ``` /tts off @@ -635,25 +689,25 @@ Discord 说明：`/tts` 是 Discord 内置命令，因此 OpenClaw 会在那里 说明： -- 命令需要已授权的发送者（仍适用 allowlist/owner 规则）。 +- 命令需要经过授权的发送者（allowlist/owner 规则仍然适用）。 - 必须启用 `commands.text` 或原生命令注册。 - 配置 `messages.tts.auto` 接受 `off|always|inbound|tagged`。 -- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会写为 `off`。 -- 当你希望默认值为 `inbound` 或 `tagged` 时，请使用配置。 -- `limit` 和 `summary` 存储在本地偏好中，而不是主配置中。 -- `/tts audio` 会生成一次性音频回复（不会切换 TTS 开关）。 +- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会将其写为 `off`。 +- 如果你希望默认使用 `inbound` 或 `tagged`，请使用配置。 +- `limit` 和 `summary` 存储在本地 prefs 中，而不是主配置中。 +- `/tts audio` 会生成一次性音频回复（不会切换 TTS 为开启状态）。 - `/tts status` 包含最近一次尝试的回退可见性： - 成功回退：`Fallback: -> ` 加 `Attempts: ...` - 失败：`Error: ...` 加 `Attempts: ...` - 详细诊断：`Attempt details: provider:outcome(reasonCode) latency` -- OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误详情和请求 id（如果提供商返回），这些信息会显示在 TTS 错误/日志中。 +- OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误详情和请求 id（当提供商返回时），这些信息会显示在 TTS 错误/日志中。 ## 智能体工具 -`tts` 工具可将文本转换为语音，并返回用于回复投递的音频附件。当渠道为 Feishu、Matrix、Telegram 或 WhatsApp 时，音频会作为语音消息而不是文件附件发送。 -当 `ffmpeg` 可用时，Feishu 可在此路径上转码非 Opus 的 TTS 输出。 -WhatsApp 会将可见文本与 PTT 语音便笺音频分开发送，因为客户端对语音便笺字幕的渲染并不一致。 -它接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是单次调用的提供商请求超时时间，单位为毫秒。 +`tts` 工具可将文本转换为语音，并返回一个用于回复投递的音频附件。当渠道为 Feishu、Matrix、Telegram 或 WhatsApp 时，音频会以语音消息而不是文件附件的形式投递。 +当 `ffmpeg` 可用时，Feishu 可以在此路径上对非 Opus 的 TTS 输出进行转码。 +WhatsApp 会将可见文本与 PTT 语音便笺音频分开发送，因为客户端对语音便笺上的字幕渲染并不一致。 +它接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是按调用设置的提供商请求超时时间（毫秒）。 ## Gateway 网关 RPC