diff --git a/docs/zh-CN/ci.md b/docs/zh-CN/ci.md index badf4b025..6fa94ebd8 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 作业图、范围门禁，以及本地等效命令 +summary: CI 作业图、范围门控，以及本地等效命令 title: CI 流水线 x-i18n: - generated_at: "2026-04-25T00:40:25Z" + generated_at: "2026-04-25T01:51:43Z" model: gpt-5.4 provider: openai - source_hash: 03105fd06cf6a913ef0fb8cbe84c64ed89edbc09652f347b4508552a2f33bb71 + source_hash: da983f025479feb82baf407e723bb663b1239f1abd931827a4c9f419ea88df67 source_path: ci.md workflow: 15 --- -CI 会在每次推送到 `main` 以及每个拉取请求时运行。它使用智能范围控制，当只有不相关区域发生变更时，会跳过开销较大的作业。 +CI 会在每次推送到 `main` 以及每个拉取请求时运行。它使用智能范围控制，在仅更改了不相关区域时跳过高开销作业。 -QA Lab 在主智能范围工作流之外还有专门的 CI 通道。`Parity gate` 工作流会在匹配的 PR 变更以及手动触发时运行；它会构建私有 QA 运行时，并比较模拟的 GPT-5.4 和 Opus 4.6 智能体 pack。`QA-Lab - All Lanes` 工作流会在 `main` 上每晚运行，并支持手动触发；它会将模拟 parity gate、实时 Matrix 通道和实时 Telegram 通道作为并行作业展开。实时作业使用 `qa-live-shared` 环境，而 Telegram 通道使用 Convex leases。`OpenClaw Release Checks` 也会在发布审批前运行相同的 QA Lab 通道。 +QA Lab 在主智能范围工作流之外有专用的 CI 通道。`Parity gate` 工作流会在匹配的 PR 变更以及手动触发时运行；它会构建私有 QA 运行时，并比较模拟的 GPT-5.4 和 Opus 4.6 agentic 包。`QA-Lab - All Lanes` 工作流会在 `main` 上每晚运行，并支持手动触发；它会将模拟 parity gate、实时 Matrix 通道和实时 Telegram 通道作为并行作业扇出执行。实时作业使用 `qa-live-shared` 环境，而 Telegram 通道使用 Convex 租约。`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，或存在重叠的变更代码块。 -`Docs Agent` 工作流是一个事件驱动的 Codex 维护通道，用于让现有文档与最近已落地的变更保持一致。它没有纯定时调度：`main` 上一次成功的、非机器人触发的 push CI 运行可以触发它，手动触发也可以直接运行它。工作流运行触发的调用会在 `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 只能修复明显的失败；并且在提交任何内容之前，智能体处理后的完整测试套件报告必须通过。当 `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,73 +34,72 @@ gh workflow run duplicate-after-merge.yml \ | 作业 | 用途 | 运行时机 | | -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ | -| `preflight` | 检测是否仅有文档变更、变更范围、变更的扩展，并构建 CI 清单 | 所有非 draft 的 push 和 PR | -| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 所有非 draft 的 push 和 PR | -| `security-dependency-audit` | 针对 npm advisory 执行无依赖的生产 lockfile 审计 | 所有非 draft 的 push 和 PR | -| `security-fast` | 快速安全作业的必需聚合作业 | 所有非 draft 的 push 和 PR | -| `build-artifacts` | 构建 `dist/`、Control UI、内置产物检查，以及可复用的下游产物 | 与 Node 相关的变更 | +| `preflight` | 检测是否仅有文档变更、变更的范围、变更的扩展，并构建 CI 清单 | 在所有非草稿 push 和 PR 上始终运行 | +| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 在所有非草稿 push 和 PR 上始终运行 | +| `security-dependency-audit` | 针对 npm advisories 执行无依赖的生产 lockfile 审计 | 在所有非草稿 push 和 PR 上始终运行 | +| `security-fast` | 快速安全作业的必需聚合作业 | 在所有非草稿 push 和 PR 上始终运行 | +| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查以及可复用的下游产物 | 与 Node 相关的变更 | | `checks-fast-core` | 快速 Linux 正确性通道，例如 bundled/plugin-contract/protocol 检查 | 与 Node 相关的变更 | -| `checks-fast-contracts-channels` | 分片的渠道 contract 检查，并带有稳定的聚合检查结果 | 与 Node 相关的变更 | -| `checks-node-extensions` | 对整个扩展套件执行完整的内置插件测试分片 | 与 Node 相关的变更 | -| `checks-node-core-test` | Core Node 测试分片，不包括渠道、内置、contract 和扩展通道 | 与 Node 相关的变更 | -| `extension-fast` | 仅针对已变更的内置插件执行聚焦测试 | 带有扩展变更的拉取请求 | -| `check` | 分片后的主本地门禁等效项：生产类型、lint、守卫、测试类型和严格 smoke | 与 Node 相关的变更 | -| `check-additional` | 架构、边界、扩展表面守卫、包边界以及 gateway-watch 分片 | 与 Node 相关的变更 | +| `checks-fast-contracts-channels` | 分片的渠道契约检查，并提供稳定的聚合检查结果 | 与 Node 相关的变更 | +| `checks-node-extensions` | 针对整个扩展套件的完整内置插件测试分片 | 与 Node 相关的变更 | +| `checks-node-core-test` | 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 和失效链接检查 | 文档有变更时 | +| `check-docs` | 文档格式化、lint 和失效链接检查 | 文档发生变更 | | `skills-python` | 面向 Python 支持的 Skills 的 Ruff + pytest | 与 Python Skills 相关的变更 | | `checks-windows` | Windows 专用测试通道 | 与 Windows 相关的变更 | -| `macos-node` | 使用共享已构建产物的 macOS TypeScript 测试通道 | 与 macOS 相关的变更 | +| `macos-node` | 使用共享构建产物的 macOS TypeScript 测试通道 | 与 macOS 相关的变更 | | `macos-swift` | macOS 应用的 Swift lint、构建和测试 | 与 macOS 相关的变更 | -| `android` | 两个 flavor 的 Android 单元测试，以及一个 debug APK 构建 | 与 Android 相关的变更 | -| `test-performance-agent` | 在受信任活动之后每日运行的 Codex 慢测试优化 | 主 CI 成功后或手动触发 | +| `android` | 两个 flavor 的 Android 单元测试，以及一次 debug APK 构建 | 与 Android 相关的变更 | +| `test-performance-agent` | 在可信活动之后进行的每日 Codex 慢测试优化 | `main` CI 成功后或手动触发 | -## Fail-Fast 顺序 +## 快速失败顺序 -作业按顺序排列，以便让廉价检查先失败，再运行昂贵作业： +作业的排列顺序经过设计，使低成本检查先失败，再决定是否运行高成本作业： -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 原生构建；这些平台通道仍然仅针对对应平台源码变更进行范围控制。 -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 plugin/channel/Gateway 网关/插件 SDK 表面。仅源码级的内置插件变更、仅测试编辑以及仅文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行容器 gateway-network e2e，验证一个内置扩展 build arg，并在 120 秒命令超时限制下运行受限的内置插件 Docker profile。完整路径则保留 QR 包安装以及 installer Docker/update 覆盖，用于每晚定时运行、手动触发、workflow-call 发布检查，以及真正触及 installer/package/Docker 表面的拉取请求。推送到 `main`，包括 merge commit，不会强制走完整路径；当 changed-scope 逻辑在 push 上请求完整覆盖时，工作流仍只保留快速 Docker smoke，而将完整 install smoke 留给夜间或发布验证。较慢的 Bun 全局安装 image-provider smoke 由 `run_bun_global_install_smoke` 单独控制；它会在夜间计划任务和发布检查工作流中运行，手动触发 `install-smoke` 时也可以选择启用，但拉取请求和 `main` push 不会运行它。QR 和 installer Docker 测试保留它们各自以安装为重点的 Dockerfile。本地 `test:docker:all` 会预先构建一个共享的实时测试镜像，以及一个共享的 `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 出现创建风暴；你可以用 `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 套件。内置更新矩阵按更新目标进行拆分，以便重复的 npm update 和 doctor repair 轮次可以与其他内置检查一起分片运行。 +CI 工作流编辑会验证 Node CI 图以及工作流 lint，但不会仅因自身修改就强制触发 Windows、Android 或 macOS 原生构建；这些平台通道仍然只针对对应平台源码变更进行范围控制。 +Windows Node 检查的范围仅限于 Windows 专用的进程/路径包装器、npm/pnpm/UI 运行器辅助工具、包管理器配置，以及执行该通道的 CI 工作流表面；不相关的源码、插件、install-smoke 和纯测试更改仍然只会进入 Linux Node 通道，这样就不会为了已由常规测试分片覆盖的内容而占用一台 16 vCPU 的 Windows worker。 +单独的 `install-smoke` 工作流会通过它自己的 `preflight` 作业复用同一个范围脚本。它将 smoke 覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。拉取请求会针对 Docker/包表面、内置插件包/清单变更，以及 Docker smoke 作业会覆盖到的核心插件/渠道/Gateway 网关/插件 SDK 表面运行快速路径。仅源码层面的内置插件变更、纯测试编辑和仅文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete shared-workspace CLI smoke，运行容器 gateway-network e2e，验证一个内置扩展构建参数，并在 120 秒命令超时限制下运行受限的内置插件 Docker profile。完整路径则保留 QR 包安装以及 installer Docker/update 覆盖，用于每晚定时运行、手动触发、workflow-call 发布检查，以及真正触及 installer/package/Docker 表面的拉取请求。推送到 `main`，包括 merge commit，不会强制走完整路径；当 changed-scope 逻辑在 push 上本会请求完整覆盖时，工作流仍会保留快速 Docker smoke，而将完整 install smoke 留给每晚运行或发布验证。较慢的 Bun 全局安装 image-provider smoke 由 `run_bun_global_install_smoke` 单独控制；它会在每晚定时任务以及发布检查工作流中运行，手动触发 `install-smoke` 时也可以选择启用，但拉取请求和 `main` push 不会运行它。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 守护进程在创建阶段发生风暴；可通过 `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 套件。内置更新矩阵会按更新目标拆分，这样重复的 npm update 和 doctor repair 过程就可以与其他内置检查一起分片运行。 -本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，由 `scripts/check-changed.mjs` 执行。这个本地门禁在架构边界方面比宽泛的 CI 平台范围更严格：core 生产变更会运行 core prod typecheck 加 core tests，core 仅测试变更只运行 core test typecheck/tests，扩展生产变更会运行 extension prod typecheck 加 extension tests，而扩展仅测试变更只运行 extension test typecheck/tests。公开的插件 SDK 或 plugin-contract 变更会扩展到扩展验证，因为扩展依赖这些 core contract。仅包含发布元数据的版本号提升会运行定向的版本/配置/root-dependency 检查。未知的 root/config 变更会以安全优先方式落到所有通道。 +本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。这个本地门控在架构边界方面比宽泛的 CI 平台范围更严格：核心生产代码变更会运行核心生产 typecheck 加核心测试，核心仅测试变更只运行核心测试 typecheck/测试，扩展生产代码变更会运行扩展生产 typecheck 加扩展测试，而扩展仅测试变更只运行扩展测试 typecheck/测试。公共插件 SDK 或 plugin-contract 变更会扩展到扩展验证，因为扩展依赖这些核心契约。仅发布元数据的版本号提升会运行定向的版本/配置/根依赖检查。未知的根目录/配置变更会以安全优先的方式回退到所有通道。 -在 push 上，`checks` 矩阵会增加仅限 push 的 `compat-node22` 通道。在拉取请求上，这个通道会被跳过，矩阵会继续专注于常规测试/渠道通道。 +在 push 上，`checks` 矩阵会添加仅限 push 的 `compat-node22` 通道。在拉取请求上，这个通道会被跳过，矩阵仍聚焦于常规测试/渠道通道。 -最慢的 Node 测试族会被拆分或重新平衡，以便每个作业都保持较小规模而不会过度占用 runner：渠道 contract 会作为 3 个加权分片运行，内置插件测试会在 6 个扩展 worker 之间做平衡，小型 core 单元通道会成对组合，自动回复会作为 3 个平衡 worker 运行而不是 6 个微小 worker，而 agentic Gateway 网关/插件配置会分散到现有的仅源码 agentic Node 作业中，而不是等待已构建产物。宽泛的浏览器、QA、媒体和杂项插件测试使用它们各自专用的 Vitest 配置，而不是共享的插件兜底配置。扩展分片作业一次最多运行两组插件配置，每组使用一个 Vitest worker，并配备更大的 Node heap，这样导入密集型的插件批次就不会产生额外的 CI 作业。宽泛的 agents 通道使用共享的 Vitest 文件级并行调度器，因为它主要受导入/调度影响，而不是由单个慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享 runtime 分片成为尾部瓶颈。`check-additional` 会将 package-boundary compile/canary 工作放在一起，并将 runtime topology 架构与 gateway watch 覆盖拆分开；boundary guard 分片会在一个作业内部并发运行其小型独立守卫。Gateway watch、渠道测试以及 core support-boundary 分片会在 `build-artifacts` 内部并发运行，此时 `dist/` 和 `dist-runtime/` 已经构建完成；这样就能保留它们旧有的检查名称作为轻量验证作业，同时避免额外两个 Blacksmith worker 和第二个产物消费者队列。 +最慢的 Node 测试家族会被拆分或平衡，以便每个作业都足够小，同时不过度预留 runner：渠道契约会作为三个加权分片运行，内置插件测试会在六个扩展 worker 间平衡分配，小型核心单元通道会成对组合，auto-reply 作为三个平衡 worker 运行而不是六个很小的 worker，而 agentic Gateway 网关/插件配置会分布到现有仅源码的 agentic Node 作业中，而不是等待构建产物。宽泛的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件兜底配置。扩展分片作业一次最多运行两个插件配置组，每组只用一个 Vitest worker，并使用更大的 Node heap，这样导入密集型的插件批次就不会产生额外的 CI 作业。宽泛的 agents 通道使用共享的 Vitest 文件级并行调度器，因为它主要受导入/调度开销支配，而不是由某个单独的慢测试文件主导。`runtime-config` 会与 infra core-runtime 分片一起运行，以避免共享运行时分片承担拖尾。`check-additional` 将 package-boundary 的 compile/canary 工作保留在一起，并将运行时拓扑架构与 gateway watch 覆盖拆开；boundary guard 分片会在一个作业内部并发运行其小型且相互独立的 guard。Gateway watch、渠道测试以及核心 support-boundary 分片会在 `dist/` 和 `dist-runtime/` 已构建完成后，在 `build-artifacts` 内部并发运行，保留它们原有的检查名称作为轻量验证作业，同时避免额外占用两个 Blacksmith worker 和第二条产物消费者队列。 +Android CI 会运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的 source set 或 manifest；它的单元测试通道仍会使用 SMS/通话日志 BuildConfig 标志编译该 flavor，同时避免在每次与 Android 相关的 push 上重复执行 debug APK 打包作业。 +`extension-fast` 仅限 PR，因为 push 运行已经会执行完整的内置插件分片。这样可以为评审保留已更改插件的反馈，同时不会在 `main` 上额外占用一个 Blacksmith worker 去做 `checks-node-extensions` 已经覆盖的内容。 -Android CI 会运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的 source set 或 manifest；它的单元测试通道仍会在带有 SMS/call-log BuildConfig 标志的情况下编译该 flavor，同时避免在每次与 Android 相关的 push 上重复执行 debug APK 打包作业。 -`extension-fast` 仅用于 PR，因为 push 运行已经会执行完整的内置插件分片。这样既能为评审保留变更插件的反馈，又不会在 `main` 上额外占用一个 Blacksmith worker 去覆盖 `checks-node-extensions` 中已经存在的内容。 - -当同一个 PR 或 `main` 引用上有更新的 push 落地时，GitHub 可能会将被替代的作业标记为 `cancelled`。除非同一引用的最新运行也失败，否则应将其视为 CI 噪音。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已经被替代后继续排队。 -CI 并发键是带版本号的（`CI-v7-*`），这样 GitHub 端旧队列组中的僵尸任务就不会无限期阻塞更新的 `main` 运行。 +当同一个 PR 或 `main` 引用上有更新的 push 落地时，GitHub 可能会将被替代的作业标记为 `cancelled`。除非同一引用的最新运行也失败，否则应将其视为 CI 噪音。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会正常报告分片失败，但不会在整个工作流已经被替代后继续排队。 +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 矩阵可以更早排队 | +| `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-ubuntu-2404` | `check-lint`，它对 CPU 仍足够敏感，以至于 8 vCPU 的成本高于节省；install-smoke Docker 构建，在这里 32 vCPU 的排队时间成本高于其带来的收益 | | `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `macos-node`，用于 `openclaw/openclaw`；fork 会回退到 `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `macos-swift`，用于 `openclaw/openclaw`；fork 会回退到 `macos-latest` | +| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-node`；fork 会回退到 `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-swift`；fork 会回退到 `macos-latest` | ## 本地等效命令 ```bash pnpm changed:lanes # 检查 origin/main...HEAD 的本地 changed-lane 分类器 -pnpm check:changed # 智能本地门禁：按边界通道运行变更的 typecheck/lint/tests -pnpm check # 快速本地门禁：生产 tsgo + 分片 lint + 并行快速守卫 +pnpm check:changed # 智能本地门控：按边界通道运行变更相关的 typecheck/lint/测试 +pnpm check # 快速本地门控：生产 tsgo + 分片 lint + 并行快速 guard pnpm check:test-types -pnpm check:timed # 相同门禁，但带有各阶段耗时 +pnpm check:timed # 同样的门控，但带有各阶段耗时 pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression diff --git a/docs/zh-CN/cli/status.md b/docs/zh-CN/cli/status.md index 10a2e2f95..ef059c1f1 100644 --- a/docs/zh-CN/cli/status.md +++ b/docs/zh-CN/cli/status.md @@ -1,14 +1,14 @@ --- read_when: - - 你想快速诊断渠道健康状态 + 最近会话接收者 - - 你想要一个可直接粘贴的“全部”状态用于调试 + - 你想快速诊断渠道健康状况 + 最近会话的接收者 + - 你想要一个可直接粘贴的 “all” 状态输出，用于调试 summary: '`openclaw status` 的 CLI 参考（诊断、探测、用法快照）' title: 状态 x-i18n: - generated_at: "2026-04-25T00:40:13Z" + generated_at: "2026-04-25T01:51:43Z" model: gpt-5.4 provider: openai - source_hash: ef182b95eabdb2c24d5d011ed3c3291308373620b893750d6d27470bd88ca3dc + source_hash: b191b8d78d43fb9426bfad495815fd06ab7188b413beff6fb7eb90f811b6d261 source_path: cli/status.md workflow: 15 --- @@ -24,25 +24,25 @@ openclaw status --deep openclaw status --usage ``` -注意： +说明： - `--deep` 会运行实时探测（WhatsApp Web + Telegram + Discord + Slack + Signal）。 -- `--usage` 会将标准化后的提供商用量窗口打印为 `X% left`。 -- 会话状态输出会将 `Execution:` 与 `Runtime:` 分开显示。`Execution` 是沙箱路径（`direct`、`docker/*`），而 `Runtime` 会告诉你该会话正在使用 `OpenClaw Pi Default`、`OpenAI Codex`、某个 CLI 后端，或是 ACP 后端，例如 `codex (acp/acpx)`。 -- MiniMax 的原始 `usage_percent` / `usagePercent` 字段表示剩余额度，因此 OpenClaw 会在显示前将其反转；如果存在按计数字段，则优先使用按计数字段。`model_remains` 响应会优先选择聊天模型条目，必要时根据时间戳推导窗口标签，并在套餐标签中包含模型名称。 +- `--usage` 会以 `X% left` 的形式打印标准化后的提供商用量窗口。 +- 会话状态输出会将 `Execution:` 与 `Runtime:` 分开显示。`Execution` 是沙箱路径（`direct`、`docker/*`），而 `Runtime` 会告诉你该会话使用的是 `OpenClaw Pi Default`、`OpenAI Codex`、某个 CLI 后端，还是像 `codex (acp/acpx)` 这样的 ACP 后端。有关提供商 / 模型 / 运行时之间区别的说明，请参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 +- MiniMax 的原始 `usage_percent` / `usagePercent` 字段表示剩余额度，因此 OpenClaw 会在显示前将其反转；如果存在基于计数的字段，则优先使用这些字段。`model_remains` 响应会优先选择聊天模型条目，在需要时根据时间戳推导窗口标签，并在套餐标签中包含模型名称。 - 当当前会话快照信息较少时，`/status` 可以从最近的转录用量日志中回填 token 和缓存计数器。现有的非零实时值仍然优先于转录回填值。 -- 转录回填还可以在实时会话条目缺少活动运行时模型标签时恢复该标签。如果该转录模型与所选模型不同，状态会根据恢复出的运行时模型而不是所选模型来解析上下文窗口。 -- 对于提示词大小统计，当会话元数据缺失或更小时，转录回填会优先选择更大的、面向提示词的总量，因此自定义提供商会话不会显示为 `0` token。 +- 转录回填还可以在实时会话条目缺少活动运行时模型标签时恢复该标签。如果该转录模型与所选模型不同，状态会根据恢复出的运行时模型，而不是所选模型，来解析上下文窗口。 +- 对于提示大小统计，当会话元数据缺失或更小时，转录回填会优先选择更大的、面向提示的总量，这样自定义提供商会话就不会退化为显示 `0` token。 - 当配置了多个智能体时，输出会包含每个智能体的会话存储。 -- 概览在可用时会包含 Gateway 网关 + 节点主机服务的安装 / 运行时状态。 -- 概览会包含更新渠道 + git SHA（适用于源码检出）。 -- 更新信息会显示在概览中；如果有可用更新，状态会打印运行 `openclaw update` 的提示（参见 [更新](/zh-CN/install/updating)）。 -- 只读状态展示接口（`status`、`status --json`、`status --all`）会在可能的情况下，为其目标配置路径解析受支持的 SecretRef。 -- 如果配置了受支持的渠道 SecretRef，但在当前命令路径中不可用，状态会保持只读，并报告降级输出而不是崩溃。人类可读输出会显示诸如“configured token unavailable in this command path”之类的警告，而 JSON 输出会包含 `secretDiagnostics`。 -- 当命令本地 SecretRef 解析成功时，状态会优先使用解析后的快照，并从最终输出中清除临时的“secret unavailable”渠道标记。 -- `status --all` 包含一个 Secrets 概览行和一个诊断部分，用于汇总 Secret 诊断（为便于阅读会截断），同时不会停止报告生成。 +- 概览会在可用时包含 Gateway 网关 + 节点主机服务的安装 / 运行时状态。 +- 概览会包含更新频道 + git SHA（适用于源码检出）。 +- 更新信息会显示在概览中；如果有可用更新，status 会打印运行 `openclaw update` 的提示（参见 [Updating](/zh-CN/install/updating)）。 +- 只读状态界面（`status`、`status --json`、`status --all`）会在可能的情况下，为其目标配置路径解析受支持的 SecretRef。 +- 如果已配置受支持的渠道 SecretRef，但在当前命令路径中不可用，status 会保持只读，并报告降级输出，而不是崩溃。人类可读输出会显示类似“在此命令路径中，已配置的令牌不可用”的警告，JSON 输出则会包含 `secretDiagnostics`。 +- 当命令本地 SecretRef 解析成功时，status 会优先使用解析后的快照，并清除最终输出中临时的“secret unavailable” 渠道标记。 +- `status --all` 包含一个 Secrets 概览行和一个诊断部分，该部分会汇总密钥诊断信息（为便于阅读会进行截断），同时不会停止报告生成。 -## 相关内容 +## 相关 - [CLI 参考](/zh-CN/cli) - [Doctor](/zh-CN/gateway/doctor) diff --git a/docs/zh-CN/concepts/agent-runtimes.md b/docs/zh-CN/concepts/agent-runtimes.md new file mode 100644 index 000000000..426ce1a69 --- /dev/null +++ b/docs/zh-CN/concepts/agent-runtimes.md @@ -0,0 +1,112 @@ +--- +read_when: + - 你正在 PI、Codex、ACP 或其他原生智能体运行时之间进行选择 + - 你对状态或配置中的提供商 / 模型 / 运行时标签感到困惑 + - 你正在为原生 harness 记录支持对齐情况 +summary: OpenClaw 如何区分提供商、模型、渠道和 Agent Runtimes +title: Agent Runtimes +x-i18n: + generated_at: "2026-04-25T01:51:46Z" + model: gpt-5.4 + provider: openai + source_hash: 1e7da189f66ee57a17ea2df1a3364ba9554d94cb4c6ebad30b0c261daf5496af + source_path: concepts/agent-runtimes.md + workflow: 15 +--- + +**智能体运行时**是负责一个已准备好的模型循环的组件：它接收提示词，驱动模型输出，处理原生工具调用，并将完成的轮次返回给 OpenClaw。 + +运行时很容易与提供商混淆，因为两者都会出现在模型配置附近。它们是不同的层级： + +| 层级 | 示例 | 含义 | +| ------------- | ------------------------------------- | ------------------------------------------------------------------- | +| 提供商 | `openai`, `anthropic`, `openai-codex` | OpenClaw 如何进行认证、发现模型以及命名模型引用。 | +| 模型 | `gpt-5.5`, `claude-opus-4-6` | 为智能体轮次选择的模型。 | +| Agent Runtimes | `pi`, `codex`, ACP 支持的运行时 | 执行已准备轮次的底层循环。 | +| 渠道 | Telegram, Discord, Slack, WhatsApp | 消息进入和离开 OpenClaw 的位置。 | + +你还会在代码和配置中看到 **harness** 这个词。harness 是提供智能体运行时的实现。例如，内置的 Codex harness 实现了 `codex` 运行时。出于兼容性原因，配置键仍然叫作 `embeddedHarness`，但面向用户的文档和状态输出通常应使用“运行时”。 + +常见的 Codex 设置使用 `openai` 提供商和 `codex` 运行时： + +```json5 +{ + agents: { + defaults: { + model: "openai/gpt-5.5", + embeddedHarness: { + runtime: "codex", + }, + }, + }, +} +``` + +这意味着 OpenClaw 先选择一个 OpenAI 模型引用，然后请求 Codex app-server 运行时运行嵌入式智能体轮次。这并不意味着渠道、模型提供商目录或 OpenClaw 会话存储会变成 Codex。 + +## 运行时归属 + +不同运行时负责循环中的不同部分。 + +| 范围 | OpenClaw PI 嵌入式 | Codex app-server | +| --------------------------- | --------------------------------------- | --------------------------------------------------------------------------- | +| 模型循环所有者 | OpenClaw 通过 PI 嵌入式运行器 | Codex app-server | +| 规范线程状态 | OpenClaw 转录记录 | Codex 线程，加上 OpenClaw 转录镜像 | +| OpenClaw 动态工具 | 原生 OpenClaw 工具循环 | 通过 Codex 适配器桥接 | +| 原生 shell 和文件工具 | PI / OpenClaw 路径 | Codex 原生工具，在支持时通过原生钩子桥接 | +| 上下文引擎 | 原生 OpenClaw 上下文组装 | OpenClaw 项目将上下文组装进 Codex 轮次 | +| 压缩 | OpenClaw 或所选上下文引擎 | Codex 原生压缩，并带有 OpenClaw 通知和镜像维护 | +| 渠道投递 | OpenClaw | OpenClaw | + +这种归属划分是主要的设计规则： + +- 如果某个范围由 OpenClaw 负责，OpenClaw 就可以提供正常的插件钩子行为。 +- 如果某个范围由原生运行时负责，OpenClaw 就需要运行时事件或原生钩子。 +- 如果原生运行时拥有规范线程状态，OpenClaw 应该镜像并投射上下文，而不是重写不受支持的内部机制。 + +## 运行时选择 + +OpenClaw 会在提供商和模型解析之后选择一个嵌入式运行时： + +1. 会话中已记录的运行时优先。配置变更不会将现有转录记录热切换到不同的原生线程系统。 +2. `OPENCLAW_AGENT_RUNTIME=` 会为新的或重置后的会话强制指定该运行时。 +3. `agents.defaults.embeddedHarness.runtime` 或 `agents.list[].embeddedHarness.runtime` 可以设置为 `auto`、`pi` 或已注册的运行时 id，例如 `codex`。 +4. 在 `auto` 模式下，已注册的插件运行时可以声明自己支持的提供商 / 模型组合。 +5. 如果在 `auto` 模式下没有运行时接管某个轮次，并且设置了 `fallback: "pi"`（默认值），OpenClaw 会使用 PI 作为兼容性回退。将 `fallback: "none"` 设置为无，以便让未匹配的 `auto` 模式选择直接失败。 + +显式插件运行时默认会以封闭失败方式处理。例如，`runtime: "codex"` 表示必须使用 Codex，否则给出明确的选择错误，除非你在同一覆盖作用域中设置 `fallback: "pi"`。 + +## 兼容性契约 + +当运行时不是 PI 时，它应记录自己支持哪些 OpenClaw 范围。运行时文档应使用如下结构： + +| 问题 | 重要原因 | +| -------------------------------------- | ------------------------------------------------------------------------------------------------- | +| 谁拥有模型循环？ | 这决定了重试、工具续接以及最终答案决策发生在哪里。 | +| 谁拥有规范线程历史？ | 这决定了 OpenClaw 能编辑历史，还是只能镜像它。 | +| OpenClaw 动态工具是否可用？ | 消息传递、会话、cron 和 OpenClaw 自有工具都依赖这一点。 | +| 动态工具钩子是否可用？ | 插件期望在 OpenClaw 自有工具周围使用 `before_tool_call`、`after_tool_call` 和中间件。 | +| 原生工具钩子是否可用？ | shell、patch 和运行时自有工具需要原生钩子来实现策略与观测。 | +| 上下文引擎生命周期是否运行？ | Memory 和上下文插件依赖 assemble、ingest、after-turn 和 compaction 生命周期。 | +| 暴露了哪些压缩数据？ | 有些插件只需要通知，而另一些插件需要保留 / 丢弃元数据。 | +| 哪些内容是有意不支持的？ | 当原生运行时拥有更多状态时，用户不应假定它与 PI 等价。 | + +Codex 运行时支持契约记录在 +[Codex harness](/zh-CN/plugins/codex-harness#v1-support-contract) 中。 + +## 状态标签 + +状态输出可能同时显示 `Execution` 和 `Runtime` 标签。应将它们视为诊断信息，而不是提供商名称。 + +- 像 `openai/gpt-5.5` 这样的模型引用，表示已选择的提供商 / 模型。 +- 像 `codex` 这样的运行时 id，表示哪个循环正在执行该轮次。 +- 像 Telegram 或 Discord 这样的渠道标签，表示对话发生的位置。 + +如果你在更改运行时配置后，会话仍显示为 PI，请使用 `/new` 开启新会话，或使用 `/reset` 清除当前会话。现有会话会保留其记录的运行时，这样转录记录就不会被通过两个不兼容的原生会话系统重复回放。 + +## 相关内容 + +- [Codex harness](/zh-CN/plugins/codex-harness) +- [Agent harness plugins](/zh-CN/plugins/sdk-agent-harness) +- [Agent loop](/zh-CN/concepts/agent-loop) +- [Models](/zh-CN/concepts/models) diff --git a/docs/zh-CN/concepts/models.md b/docs/zh-CN/concepts/models.md index 1656bab90..e669c5604 100644 --- a/docs/zh-CN/concepts/models.md +++ b/docs/zh-CN/concepts/models.md @@ -1,45 +1,47 @@ --- read_when: - - 添加或修改模型 CLI（`models list`/`set`/`scan`/`aliases`/`fallbacks`） + - 添加或修改 Models CLI（`models list`/`set`/`scan`/`aliases`/`fallbacks`） - 更改模型回退行为或选择 UX - 更新模型扫描探测项（工具 / 图像） -summary: 模型 CLI：列表、设置、别名、回退、扫描、状态 -title: 模型 CLI +summary: Models CLI：列出、设置、别名、回退、扫描、状态 +title: Models CLI x-i18n: - generated_at: "2026-04-24T18:58:36Z" + generated_at: "2026-04-25T01:51:44Z" model: gpt-5.4 provider: openai - source_hash: be8d474b525f2605a332d1a509dcbbecda0e3f8f705e636ec9379fae1505c233 + source_hash: f6a98f44872d5de81f02dc7318bb8ecdff3860996d286b6aa9d42abbd8ce6670 source_path: concepts/models.md workflow: 15 --- -有关凭证配置文件轮换、冷却时间及其与回退如何交互的信息，请参阅 [/concepts/model-failover](/zh-CN/concepts/model-failover)。 -提供商快速概览 + 示例：[/concepts/model-providers](/zh-CN/concepts/model-providers)。 +有关凭证配置轮换、冷却时间，以及它们如何与回退机制交互，请参阅 [/concepts/model-failover](/zh-CN/concepts/model-failover)。 +提供商快速概览与示例：[/concepts/model-providers](/zh-CN/concepts/model-providers)。 +模型引用会选择一个提供商和模型。它们通常不会选择底层的 Agent Runtimes。例如，`openai/gpt-5.5` 可以通过常规的 OpenAI 提供商路径运行，也可以通过 Codex 应用服务器运行时运行，具体取决于 `agents.defaults.embeddedHarness.runtime`。请参阅 +[/concepts/agent-runtimes](/zh-CN/concepts/agent-runtimes)。 -## 模型选择的工作方式 +## 模型选择如何工作 OpenClaw 按以下顺序选择模型： -1. **主**模型（`agents.defaults.model.primary` 或 `agents.defaults.model`）。 -2. `agents.defaults.model.fallbacks` 中的**回退模型**（按顺序）。 -3. **提供商凭证故障转移**会先在提供商内部发生，然后才会切换到下一个模型。 +1. **主模型**（`agents.defaults.model.primary` 或 `agents.defaults.model`）。 +2. `agents.defaults.model.fallbacks` 中的 **回退模型**（按顺序）。 +3. **提供商凭证故障切换** 会在提供商内部发生，然后才会切换到下一个模型。 相关内容： -- `agents.defaults.models` 是 OpenClaw 可使用模型的允许列表 / 目录（也包括别名）。 -- `agents.defaults.imageModel` **仅在**主模型无法接受图像时使用。 -- `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会依次回退到 `agents.defaults.imageModel`，然后是解析后的会话 / 默认模型。 -- `agents.defaults.imageGenerationModel` 用于共享的图像生成能力。如果省略，`image_generate` 仍可推断出一个具备凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。如果你设置了特定的提供商 / 模型，也要同时配置该提供商的凭证 / API 密钥。 -- `agents.defaults.musicGenerationModel` 用于共享的音乐生成能力。如果省略，`music_generate` 仍可推断出一个具备凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定的提供商 / 模型，也要同时配置该提供商的凭证 / API 密钥。 -- `agents.defaults.videoGenerationModel` 用于共享的视频生成能力。如果省略，`video_generate` 仍可推断出一个具备凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定的提供商 / 模型，也要同时配置该提供商的凭证 / API 密钥。 -- 每个智能体的默认值可以通过 `agents.list[].model` 加上绑定来覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/zh-CN/concepts/multi-agent)）。 +- `agents.defaults.models` 是 OpenClaw 可使用模型的允许列表 / 目录（以及别名）。 +- `agents.defaults.imageModel` **仅在** 主模型无法接受图像时使用。 +- `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，工具会依次回退到 `agents.defaults.imageModel`，然后是解析后的当前会话 / 默认模型。 +- `agents.defaults.imageGenerationModel` 由共享图像生成功能使用。如果省略，`image_generate` 仍然可以推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的图像生成提供商。如果你设置了特定的提供商 / 模型，也请配置该提供商的凭证 / API 密钥。 +- `agents.defaults.musicGenerationModel` 由共享音乐生成功能使用。如果省略，`music_generate` 仍然可以推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定的提供商 / 模型，也请配置该提供商的凭证 / API 密钥。 +- `agents.defaults.videoGenerationModel` 由共享视频生成功能使用。如果省略，`video_generate` 仍然可以推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的视频生成提供商。如果你设置了特定的提供商 / 模型，也请配置该提供商的凭证 / API 密钥。 +- 每个智能体的默认值可以通过 `agents.list[].model` 加上绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/zh-CN/concepts/multi-agent)）。 ## 快速模型策略 -- 将主模型设置为你可用的最强、最新一代模型。 -- 对成本 / 延迟敏感的任务以及风险较低的聊天，使用回退模型。 -- 对启用了工具的智能体或不受信任的输入，避免使用较旧 / 较弱的模型层级。 +- 将你的主模型设置为你当前可用的、能力最强的最新一代模型。 +- 对于对成本 / 延迟敏感的任务和风险较低的聊天，使用回退模型。 +- 对于启用了工具的智能体或不受信任的输入，避免使用较旧 / 较弱的模型层级。 ## 新手引导（推荐） @@ -49,7 +51,7 @@ OpenClaw 按以下顺序选择模型： openclaw onboard ``` -它可以为常见提供商设置模型 + 凭证，包括 **OpenAI Code（Codex）订阅** +它可以为常见提供商设置模型和凭证，包括 **OpenAI Code（Codex）订阅** （OAuth）和 **Anthropic**（API 密钥或 Claude CLI）。 ## 配置键名（概览） @@ -62,40 +64,45 @@ openclaw onboard - `agents.defaults.models`（允许列表 + 别名 + 提供商参数） - `models.providers`（写入 `models.json` 的自定义提供商） -模型引用会被规范化为小写。像 `z.ai/*` 这样的提供商别名会被规范化 -为 `zai/*`。 +模型引用会被规范化为小写。像 `z.ai/*` 这样的提供商别名会规范化为 +`zai/*`。 提供商配置示例（包括 OpenCode）位于 [/providers/opencode](/zh-CN/providers/opencode)。 -### 安全地编辑允许列表 +### 安全编辑允许列表 -手动更新 `agents.defaults.models` 时，请使用追加式写入： +手动更新 `agents.defaults.models` 时，使用追加式写入： ```bash openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge ``` -`openclaw config set` 会保护模型 / 提供商映射，避免被意外覆盖。对 `agents.defaults.models`、`models.providers` 或 `models.providers..models` 进行普通对象赋值时，如果会删除现有条目，就会被拒绝。追加式更改请使用 `--merge`；仅当提供的值应成为完整目标值时，才使用 `--replace`。 +`openclaw config set` 会保护模型 / 提供商映射，防止被意外覆盖。对 +`agents.defaults.models`、`models.providers` 或 +`models.providers..models` 进行普通对象赋值时，如果会删除现有条目，则会被拒绝。对于追加式更改，请使用 `--merge`；仅当提供的值应成为完整目标值时，才使用 `--replace`。 -交互式提供商设置和 `openclaw configure --section model` 也会把提供商作用域的选择合并到现有允许列表中，因此添加 Codex、Ollama 或其他提供商时，不会删除无关的模型条目。 +交互式提供商设置和 `openclaw configure --section model` 也会将按提供商划分的选择合并到现有允许列表中，因此添加 Codex、 +Ollama 或其他提供商时，不会丢失无关的模型条目。 当重新应用提供商凭证时，Configure 会保留现有的 `agents.defaults.model.primary`。像 -`openclaw models auth login --provider --set-default` 和 -`openclaw models set ` 这样的显式默认值设置命令，仍会替换 `agents.defaults.model.primary`。 +`openclaw models auth login --provider --set-default>` 和 +`openclaw models set ` 这类显式设置默认值的命令，仍然会替换 `agents.defaults.model.primary`。 ## “Model is not allowed”（以及为什么回复会停止） -如果设置了 `agents.defaults.models`，它就会成为 `/model` 以及会话覆盖的**允许列表**。当用户选择了不在该允许列表中的模型时， +如果设置了 `agents.defaults.models`，它就会成为 `/model` 和 +会话覆盖的**允许列表**。当用户选择了不在该允许列表中的模型时， OpenClaw 会返回： ``` Model "provider/model" is not allowed. Use /model to list available models. ``` -这会发生在生成正常回复**之前**，因此消息看起来会像是“没有响应”。解决方法是： +这会发生在生成正常回复**之前**，因此消息会让人感觉像“没有响应”。 +修复方法包括： - 将该模型添加到 `agents.defaults.models`，或 -- 清空允许列表（移除 `agents.defaults.models`），或 +- 清除允许列表（删除 `agents.defaults.models`），或 - 从 `/model list` 中选择一个模型。 允许列表示例配置： @@ -114,7 +121,7 @@ Model "provider/model" is not allowed. Use /model to list available models. ## 在聊天中切换模型（`/model`） -你可以在不重启的情况下切换当前会话使用的模型： +你可以为当前会话切换模型，而无需重启： ``` /model @@ -127,24 +134,24 @@ Model "provider/model" is not allowed. Use /model to list available models. 注意： - `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型家族 + 可用提供商）。 -- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个 Submit 步骤。 -- `/models add` 已弃用，现在不会再从聊天中注册模型，而是返回一条弃用提示信息。 +- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个提交步骤。 +- `/models add` 已弃用，现在会返回弃用提示消息，而不是从聊天中注册模型。 - `/model <#>` 会从该选择器中进行选择。 - `/model` 会立即持久化新的会话选择。 - 如果智能体处于空闲状态，下一次运行会立即使用新模型。 -- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并只会在一个干净的重试点重启到新模型。 -- 如果工具活动或回复输出已经开始，待处理切换可能会继续排队，直到之后的重试机会或下一轮用户输入。 -- `/model status` 是详细视图（凭证候选项，以及在已配置时的提供商端点 `baseUrl` + `api` 模式）。 -- 模型引用通过按**第一个** `/` 进行拆分来解析。输入 `/model ` 时请使用 `provider/model`。 -- 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（例如：`/model openrouter/moonshotai/kimi-k2`）。 -- 如果你省略提供商，OpenClaw 会按以下顺序解析输入： +- 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只会在一个干净的重试点重启到新模型。 +- 如果工具活动或回复输出已经开始，待处理的切换可能会保持排队状态，直到稍后的重试机会或下一个用户轮次。 +- `/model status` 是详细视图（凭证候选项，以及在已配置时显示提供商端点 `baseUrl` + `api` 模式）。 +- 模型引用通过在**第一个** `/` 处分割来解析。输入 `/model ` 时请使用 `provider/model`。 +- 如果模型 id 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（例如：`/model openrouter/moonshotai/kimi-k2`）。 +- 如果你省略了提供商，OpenClaw 会按以下顺序解析输入： 1. 别名匹配 - 2. 对该精确无前缀模型 ID 的唯一已配置提供商匹配 + 2. 对该精确无前缀模型 id 的唯一已配置提供商匹配 3. 已弃用的回退：使用已配置的默认提供商 如果该提供商不再公开已配置的默认模型，OpenClaw - 将改为回退到第一个已配置的提供商 / 模型，以避免暴露已过时、已移除提供商的默认值。 + 会改为回退到第一个已配置的提供商 / 模型，以避免向用户暴露一个过时的、已移除提供商默认值。 -完整的命令行为 / 配置： [Slash commands](/zh-CN/tools/slash-commands)。 +完整命令行为 / 配置： [斜杠命令](/zh-CN/tools/slash-commands)。 ## CLI 命令 @@ -177,25 +184,26 @@ openclaw models image-fallbacks clear - `--all`：完整目录 - `--local`：仅本地提供商 -- `--provider `：按提供商 ID 过滤，例如 `moonshot`；不接受交互式选择器中的显示标签 +- `--provider `：按提供商 id 过滤，例如 `moonshot`；不接受交互式选择器中的显示标签 - `--plain`：每行一个模型 - `--json`：机器可读输出 -`--all` 会在配置凭证之前，先包含内置的、由提供商拥有的静态目录行，因此仅发现视图也可以显示那些在你添加匹配提供商凭证之前不可用的模型。 +`--all` 会在配置凭证之前包含提供商自带的静态目录条目，因此仅发现用途的视图可以显示那些在你添加匹配提供商凭证之前不可用的模型。 ### `models status` -显示解析后的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示在凭证存储中找到的配置文件的 OAuth 过期状态（默认会在 24 小时内到期时发出警告）。`--plain` 只输出解析后的主模型。 -OAuth 状态始终会显示（并包含在 `--json` 输出中）。如果某个已配置提供商没有凭证，`models status` 会输出一个 **Missing auth** 部分。 +显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示凭证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内到期时发出警告）。`--plain` 只打印已解析的主模型。 +OAuth 状态始终会显示（并包含在 `--json` 输出中）。如果某个已配置的提供商没有凭证，`models status` 会打印一个 **缺少凭证** 部分。 JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers` （每个提供商的生效凭证，包括基于环境变量的凭证）。`auth.oauth` -仅表示凭证存储中配置文件的健康状态；仅使用环境变量的提供商不会出现在其中。 -自动化场景请使用 `--check`（缺失 / 已过期时退出码为 `1`，即将过期时为 `2`）。 -实时凭证检查请使用 `--probe`；探测行可能来自凭证配置文件、环境变量凭证，或 `models.json`。 -如果显式的 `auth.order.` 省略了一个已存储配置文件，探测会报告 -`excluded_by_auth_order`，而不是尝试它。如果存在凭证，但无法为该提供商解析出可探测模型，则探测会报告 `status: no_model`。 +仅表示凭证存储中的配置文件健康状态；仅使用环境变量的提供商不会出现在其中。 +对自动化场景，请使用 `--check`（缺失 / 已过期时退出码为 `1`，即将过期时为 `2`）。 +对实时凭证检查，请使用 `--probe`；探测行可以来自凭证配置文件、环境变量凭证，或 `models.json`。 +如果显式的 `auth.order.` 省略了某个已存储配置文件，探测会报告 +`excluded_by_auth_order`，而不是尝试它。如果存在凭证，但无法为该提供商解析出可探测的模型，探测会报告 `status: no_model`。 -凭证选择取决于提供商 / 账户。对于始终在线的 Gateway 网关主机，API 密钥通常最可预测；也支持复用 Claude CLI，以及现有的 Anthropic OAuth / token 配置文件。 +凭证选择取决于提供商 / 账户。对于始终在线的 Gateway 网关主机，API 密钥通常最可预测；也支持复用 Claude CLI 和现有的 Anthropic +OAuth / token 配置文件。 示例（Claude CLI）： @@ -212,11 +220,11 @@ openclaw models status - `--no-probe`：跳过实时探测（仅元数据） - `--min-params `：最小参数规模（十亿） -- `--max-age-days `：跳过较旧的模型 +- `--max-age-days `：跳过较旧模型 - `--provider `：提供商前缀过滤 - `--max-candidates `：回退列表大小 -- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选中的项 -- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选中的项 +- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选择项 +- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选择项 探测需要 OpenRouter API 密钥（来自凭证配置文件或 `OPENROUTER_API_KEY`）。如果没有密钥，请使用 `--no-probe` 仅列出候选项。 @@ -230,33 +238,34 @@ openclaw models status 输入 -- OpenRouter `/models` 列表（过滤 `:free`） +- OpenRouter `/models` 列表（筛选 `:free`） - 需要来自凭证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/zh-CN/help/environment)） -- 可选过滤条件：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates` +- 可选过滤器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates` - 探测控制：`--timeout`、`--concurrency` -在 TTY 中运行时，你可以交互式选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。 +在 TTY 中运行时，你可以以交互方式选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。 -## 模型注册表（`models.json`） +## Models 注册表（`models.json`） -`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json` -（默认路径为 `~/.openclaw/agents//agent/models.json`）。默认情况下，该文件会被合并，除非 `models.mode` 被设置为 `replace`。 +`models.providers` 中的自定义提供商会被写入智能体目录下的 `models.json` +（默认路径为 `~/.openclaw/agents//agent/models.json`）。默认情况下会合并此文件，除非 `models.mode` 被设置为 `replace`。 -匹配提供商 ID 时，合并模式的优先级： +匹配提供商 id 的合并模式优先级： -- 智能体 `models.json` 中已存在的非空 `baseUrl` 优先。 -- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商在当前配置 / 凭证配置文件上下文中**不是**由 SecretRef 管理时优先。 -- 由 SecretRef 管理的提供商 `apiKey` 值会从源标记中刷新（环境变量引用使用 `ENV_VAR_NAME`，文件 / exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。 -- 由 SecretRef 管理的提供商请求头值会从源标记中刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件 / exec 引用使用 `secretref-managed`）。 +- 智能体 `models.json` 中已存在的非空 `baseUrl` 优先生效。 +- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商在当前配置 / 凭证配置文件上下文中不受 SecretRef 管理时优先生效。 +- 受 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件 / exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。 +- 受 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件 / exec 引用使用 `secretref-managed`）。 - 空的或缺失的智能体 `apiKey` / `baseUrl` 会回退到配置中的 `models.providers`。 - 其他提供商字段会从配置和规范化后的目录数据中刷新。 -标记持久化以源为权威：OpenClaw 会根据当前活动源配置快照（预解析），而不是根据运行时已解析的密钥值来写入标记。 -这适用于 OpenClaw 重新生成 `models.json` 的任何场景，包括像 `openclaw agent` 这样的命令驱动路径。 +标记持久化以源为准：OpenClaw 从当前激活的源配置快照（解析前）写入标记，而不是从已解析的运行时密钥值写入。 +这适用于 OpenClaw 重新生成 `models.json` 的所有情况，包括 `openclaw agent` 这类由命令驱动的路径。 ## 相关内容 -- [Model Providers](/zh-CN/concepts/model-providers) — 提供商路由和凭证 +- [Model Providers](/zh-CN/concepts/model-providers) — 提供商路由与凭证 +- [Agent Runtimes](/zh-CN/concepts/agent-runtimes) — PI、Codex 和其他 Agent loop 运行时 - [Model Failover](/zh-CN/concepts/model-failover) — 回退链 - [Image Generation](/zh-CN/tools/image-generation) — 图像模型配置 - [Music Generation](/zh-CN/tools/music-generation) — 音乐模型配置 diff --git a/docs/zh-CN/gateway/config-agents.md b/docs/zh-CN/gateway/config-agents.md index 2baaaeae1..72af279ca 100644 --- a/docs/zh-CN/gateway/config-agents.md +++ b/docs/zh-CN/gateway/config-agents.md @@ -2,19 +2,19 @@ read_when: - 调整智能体默认设置（模型、思考、工作区、心跳、媒体、Skills） - 配置多智能体路由和绑定 - - 调整会话、消息传递和通话模式行为 -summary: 智能体默认设置、多智能体路由、会话、消息和通话配置 + - 调整会话、消息投递和对话模式行为 +summary: 智能体默认设置、多智能体路由、会话、消息和对话配置 title: 配置 — 智能体 x-i18n: - generated_at: "2026-04-25T01:27:31Z" + generated_at: "2026-04-25T01:51:44Z" model: gpt-5.4 provider: openai - source_hash: 3df297e134f10215ac30bb582180dc06413f81f80c3f673926bf26f8c36a640e + source_hash: a0b90bb7a1d46dc2ae68d44de45f0861ec6400bb19ba36d2066d642ecbecc0b3 source_path: gateway/config-agents.md workflow: 15 --- -`agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下按智能体作用域划分的配置键。关于渠道、工具、Gateway 网关运行时以及其他顶层键，请参见 [配置参考](/zh-CN/gateway/configuration-reference)。 +位于 `agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下的智能体作用域配置键。关于渠道、工具、Gateway 网关运行时以及其他顶层键，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。 ## 智能体默认设置 @@ -55,14 +55,14 @@ x-i18n: } ``` -- 省略 `agents.defaults.skills` 可使默认 Skills 不受限制。 -- 省略 `agents.list[].skills` 以继承默认值。 -- 设置 `agents.list[].skills: []` 表示没有 Skills。 +- 省略 `agents.defaults.skills`，则默认不限制 Skills。 +- 省略 `agents.list[].skills`，则继承默认值。 +- 将 `agents.list[].skills: []` 设为空 Skills。 - 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。 ### `agents.defaults.skipBootstrap` -禁用工作区引导文件的自动创建（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 +禁用自动创建工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 ```json5 { @@ -74,7 +74,7 @@ x-i18n: 控制何时将工作区引导文件注入系统提示。默认值：`"always"`。 -- `"continuation-skip"`：安全的续接轮次（在助手完成响应之后）会跳过重新注入工作区引导内容，从而减小提示大小。Heartbeat 运行和压缩后的重试仍会重建上下文。 +- `"continuation-skip"`：安全的续接轮次（在助手完成一次响应之后）会跳过工作区引导内容的重新注入，从而减小提示大小。心跳运行和压缩后的重试仍会重建上下文。 ```json5 { @@ -84,7 +84,7 @@ x-i18n: ### `agents.defaults.bootstrapMaxChars` -每个工作区引导文件在被截断前允许的最大字符数。默认值：`12000`。 +单个工作区引导文件在截断前允许的最大字符数。默认值：`12000`。 ```json5 { @@ -94,7 +94,7 @@ x-i18n: ### `agents.defaults.bootstrapTotalMaxChars` -跨所有工作区引导文件注入的总最大字符数。默认值：`60000`。 +所有工作区引导文件注入内容的总最大字符数。默认值：`60000`。 ```json5 { @@ -104,11 +104,12 @@ x-i18n: ### `agents.defaults.bootstrapPromptTruncationWarning` -控制在引导上下文被截断时，向智能体显示的警告文本。默认值：`"once"`。 +控制在引导上下文被截断时，向智能体显示的警告文本。 +默认值：`"once"`。 - `"off"`：绝不将警告文本注入系统提示。 -- `"once"`：每个唯一的截断签名只注入一次警告（推荐）。 -- `"always"`：只要存在截断，就在每次运行时注入警告。 +- `"once"`：对每个唯一的截断签名只注入一次警告（推荐）。 +- `"always"`：只要存在截断，每次运行都注入警告。 ```json5 { @@ -118,20 +119,20 @@ x-i18n: ### 上下文预算归属映射 -OpenClaw 有多个高容量提示 / 上下文预算，并且这些预算会按子系统有意拆分，而不是全都通过一个通用开关控制。 +OpenClaw 有多个高容量的提示/上下文预算，并且它们是按子系统有意拆分的，而不是都通过一个通用旋钮来控制。 - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`： - 常规工作区引导内容注入。 + 常规工作区引导注入。 - `agents.defaults.startupContext.*`： 一次性的 `/new` 和 `/reset` 启动前导内容，包括最近的每日 `memory/*.md` 文件。 - `skills.limits.*`： - 注入系统提示中的紧凑 Skills 列表。 + 注入系统提示中的精简 Skills 列表。 - `agents.defaults.contextLimits.*`： - 有界的运行时摘录以及注入的运行时自有区块。 + 有界运行时摘录和由运行时注入的内容块。 - `memory.qmd.limits.*`： - 已索引的内存搜索片段及其注入大小控制。 + 已索引的内存搜索片段及注入大小控制。 仅当某个智能体需要不同预算时，才使用对应的按智能体覆盖项： @@ -140,7 +141,7 @@ OpenClaw 有多个高容量提示 / 上下文预算，并且这些预算会按 #### `agents.defaults.startupContext` -控制在空白 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。 +控制在纯 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。 ```json5 { @@ -161,7 +162,7 @@ OpenClaw 有多个高容量提示 / 上下文预算，并且这些预算会按 #### `agents.defaults.contextLimits` -用于有界运行时上下文表面的共享默认值。 +为有界运行时上下文面提供共享默认值。 ```json5 { @@ -181,11 +182,11 @@ OpenClaw 有多个高容量提示 / 上下文预算，并且这些预算会按 - `memoryGetMaxChars`：`memory_get` 摘录在添加截断元数据和续接提示前的默认上限。 - `memoryGetDefaultLines`：当省略 `lines` 时，`memory_get` 的默认行窗口。 - `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。 -- `postCompactionMaxChars`：压缩后刷新注入期间，`AGENTS.md` 摘录的字符上限。 +- `postCompactionMaxChars`：压缩后刷新注入期间使用的 `AGENTS.md` 摘录上限。 #### `agents.list[].contextLimits` -对共享 `contextLimits` 开关提供按智能体覆盖。省略的字段会继承自 `agents.defaults.contextLimits`。 +共享 `contextLimits` 控件的按智能体覆盖项。省略的字段会继承 `agents.defaults.contextLimits`。 ```json5 { @@ -211,7 +212,7 @@ OpenClaw 有多个高容量提示 / 上下文预算，并且这些预算会按 #### `skills.limits.maxSkillsPromptChars` -注入系统提示中的紧凑 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。 +注入系统提示中的精简 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。 ```json5 { @@ -244,11 +245,11 @@ Skills 提示预算的按智能体覆盖项。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，transcript / 工具图像区块中图像最长边的最大像素尺寸。 +在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。 默认值：`1200`。 -较低的值通常会减少视觉 token 使用量以及以截图为主的运行请求负载大小。 -较高的值则会保留更多视觉细节。 +较低的值通常会减少视觉 token 使用量和请求负载大小，适合以截图为主的运行。 +较高的值会保留更多视觉细节。 ```json5 { @@ -325,52 +326,53 @@ Skills 提示预算的按智能体覆盖项。 } ``` -- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 +- `model`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。 - 字符串形式只设置主模型。 - 对象形式设置主模型以及按顺序排列的故障切换模型。 -- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 作为 `image` 工具路径的视觉模型配置使用。 - - 当所选 / 默认模型无法接受图像输入时，也会用作回退路由。 -- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 用于共享图像生成能力，以及任何未来会生成图像的工具 / 插件表面。 +- `imageModel`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。 + - 用作 `image` 工具路径中的视觉模型配置。 + - 当所选/默认模型无法接受图像输入时，也会用作回退路由。 +- `imageGenerationModel`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。 + - 用于共享的图像生成能力，以及未来任何生成图像的工具/插件表面。 - 典型值：`google/gemini-3.1-flash-image-preview` 用于原生 Gemini 图像生成，`fal/fal-ai/flux/dev` 用于 fal，或 `openai/gpt-image-2` 用于 OpenAI Images。 - - 如果你直接选择某个 provider / model，也要配置匹配的提供商凭证（例如，`google/*` 需要 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` 需要 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 需要 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推断出一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的图像生成提供商。 -- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 用于共享音乐生成能力以及内置的 `music_generate` 工具。 + - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证，例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` 使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 使用 `FAL_KEY`。 + - 如果省略，`image_generate` 仍可以推断出一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的图像生成提供商。 +- `musicGenerationModel`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。 + - 用于共享的音乐生成能力和内置的 `music_generate` 工具。 - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 - - 如果省略，`music_generate` 仍可推断出一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的音乐生成提供商。 - - 如果你直接选择某个 provider / model，也要配置匹配的提供商凭证 / API 密钥。 -- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 用于共享视频生成能力以及内置的 `video_generate` 工具。 + - 如果省略，`music_generate` 仍可以推断出一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的音乐生成提供商。 + - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证/API 密钥。 +- `videoGenerationModel`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。 + - 用于共享的视频生成能力和内置的 `video_generate` 工具。 - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 - - 如果省略，`video_generate` 仍可推断出一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的视频生成提供商。 - - 如果你直接选择某个 provider / model，也要配置匹配的提供商凭证 / API 密钥。 + - 如果省略，`video_generate` 仍可以推断出一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的视频生成提供商。 + - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证/API 密钥。 - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 -- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 +- `pdfModel`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。 - 用于 `pdf` 工具的模型路由。 - - 如果省略，PDF 工具会依次回退到 `imageModel`，然后回退到已解析的会话 / 默认模型。 -- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb`，`pdf` 工具使用的默认 PDF 大小限制。 -- `pdfMaxPages`：`pdf` 工具在提取回退模式下默认考虑的最大页数。 + - 如果省略，PDF 工具会先回退到 `imageModel`，再回退到解析后的会话/默认模型。 +- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具使用的默认 PDF 大小限制。 +- `pdfMaxPages`：`pdf` 工具在提取回退模式中考虑的默认最大页数。 - `verboseDefault`：智能体的默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 - `elevatedDefault`：智能体的默认增强输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 -- `model.primary`：格式为 `provider/model`（例如，`openai/gpt-5.4` 用于 API 密钥访问，或 `openai-codex/gpt-5.5` 用于 Codex OAuth）。如果你省略 provider，OpenClaw 会先尝试别名，然后尝试与该精确 model id 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此建议优先使用显式 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider / model，而不是显示一个已过期、已移除提供商的默认值。 -- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`）。 - - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非你传入 `--replace`，否则 `config set` 会拒绝会删除现有允许列表条目的替换操作。 - - 以提供商为作用域的 configure / onboarding 流程会将选定提供商的模型合并到此映射中，并保留已配置的无关提供商。 +- `model.primary`：格式为 `provider/model`（例如，`openai/gpt-5.4` 用于 API 密钥访问，或 `openai-codex/gpt-5.5` 用于 Codex OAuth）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试精确匹配该模型 id 的唯一已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此建议优先使用显式的 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露一个已经失效、来自已移除提供商的默认值。 +- `models`：`/model` 使用的已配置模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`）。 + - 安全编辑方式：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非你传入 `--replace`，否则 `config set` 会拒绝会删除现有允许列表条目的替换操作。 + - 以提供商为作用域的配置/新手引导流程会将所选提供商模型合并到这个映射中，并保留已经配置好的无关提供商。 - 对于直接使用的 OpenAI Responses 模型，会自动启用服务端压缩。使用 `params.responsesServerCompaction: false` 可停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。 -- `params`：应用于所有模型的全局默认提供商参数。设置位置为 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 +- `params`：应用到所有模型的全局默认提供商参数。在 `agents.defaults.params` 中设置（例如 `{ cacheRetention: "long" }`）。 - `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后再由 `agents.list[].params`（匹配的智能体 id）按键覆盖。详见 [提示缓存](/zh-CN/reference/prompt-caching)。 -- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。省略 runtime 时默认使用 OpenClaw Pi。使用 `runtime: "pi"` 可强制使用内置 PI harness，使用 `runtime: "auto"` 可让已注册的插件 harness 接管其支持的模型，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 PI 回退。请将模型引用保持为标准 `provider/model`；通过运行时配置而不是旧式运行时 provider 前缀来选择 Codex、Claude CLI、Gemini CLI 以及其他执行后端。 -- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及 fallback add / remove 命令）会保存为标准对象形式，并尽可能保留现有的回退列表。 -- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍然串行）。默认值：4。 +- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。省略 `runtime` 时默认使用 OpenClaw Pi。使用 `runtime: "pi"` 可强制使用内置 PI harness，使用 `runtime: "auto"` 可让已注册的插件 harness 认领受支持的模型，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动回退到 PI。像 `codex` 这样的显式插件运行时默认采用失败即关闭，除非你在同一覆盖作用域中设置 `fallback: "pi"`。请将模型引用保持为规范形式 `provider/model`；Codex、Claude CLI、Gemini CLI 以及其他执行后端应通过运行时配置来选择，而不是使用旧式运行时提供商前缀。参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，了解它与提供商/模型选择有何不同。 +- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退模型的添加/移除命令）会保存为规范对象形式，并尽可能保留现有回退列表。 +- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话本身仍然串行）。默认值：4。 ### `agents.defaults.embeddedHarness` `embeddedHarness` 控制哪个底层执行器运行嵌入式智能体轮次。 大多数部署应保留默认的 OpenClaw Pi 运行时。 当受信任的插件提供原生 harness 时使用它，例如内置的 -Codex app-server harness。 +Codex 应用服务器 harness。关于其思维模型，请参见 +[Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 ```json5 { @@ -386,12 +388,12 @@ Codex app-server harness。 } ``` -- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置 Codex 插件注册的是 `codex`。 -- `fallback`：`"pi"` 或 `"none"`。在 `runtime: "auto"` 中，省略 `fallback` 时默认是 `"pi"`，这样旧配置在没有插件 harness 接管运行时仍可继续使用 PI。在显式插件运行时模式下，例如 `runtime: "codex"`，省略 `fallback` 时默认是 `"none"`，这样缺失 harness 时会直接失败，而不是静默使用 PI。运行时覆盖不会继承更广作用域中的 fallback；如果你确实想要这种兼容回退，请在显式 runtime 旁边一起设置 `fallback: "pi"`。所选插件 harness 的失败总是会直接暴露出来。 -- 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 会覆盖该进程的 fallback。 -- 对于仅使用 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `embeddedHarness.runtime: "codex"`。你也可以为了可读性显式设置 `embeddedHarness.fallback: "none"`；对于显式插件运行时，这本来就是默认值。 -- 在第一次嵌入式运行之后，harness 选择会按每个 session id 固定。配置 / 环境变量变更只会影响新的或已重置的会话，不会影响现有 transcript。带有 transcript 历史但没有记录固定值的旧会话会被视为固定到 PI。`/status` 会在 `Fast` 旁显示非 PI 的 harness id，例如 `codex`。 -- 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的 provider / model 设置。 +- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置的 Codex 插件会注册 `codex`。 +- `fallback`：`"pi"` 或 `"none"`。在 `runtime: "auto"` 中，省略 `fallback` 时默认值为 `"pi"`，这样旧配置在没有插件 harness 认领运行时仍可继续使用 PI。在显式插件运行时模式下，例如 `runtime: "codex"`，省略 `fallback` 时默认值为 `"none"`，这样缺少 harness 时会失败，而不是静默改用 PI。运行时覆盖项不会从更宽范围继承 `fallback`；当你有意需要这种兼容性回退时，请在显式运行时旁边同时设置 `fallback: "pi"`。所选插件 harness 的失败总是会直接暴露出来。 +- 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 会为该进程覆盖 `fallback`。 +- 对于仅使用 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `embeddedHarness.runtime: "codex"`。你也可以显式设置 `embeddedHarness.fallback: "none"` 以提高可读性；对于显式插件运行时，这就是默认值。 +- 第一次嵌入式运行之后，harness 选择会按会话 id 固定。配置/环境变量变更只影响新的或已重置的会话，不影响现有转录。具有转录历史但没有记录固定值的旧会话会被视为固定到 PI。`/status` 会在 `Fast` 旁显示非 PI 的 harness id，例如 `codex`。 +- 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。 **内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： @@ -399,7 +401,7 @@ Codex app-server harness。 | ------------------- | -------------------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.4` 或已配置 Codex OAuth 的 GPT-5.5 | +| `gpt` | `openai/gpt-5.4` 或已配置的 Codex OAuth GPT-5.5 | | `gpt-mini` | `openai/gpt-5.4-mini` | | `gpt-nano` | `openai/gpt-5.4-nano` | | `gemini` | `google/gemini-3.1-pro-preview` | @@ -408,13 +410,13 @@ Codex app-server harness。 你配置的别名始终优先于默认值。 -Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 以支持工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设置为 `false` 可禁用它。 -Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 `adaptive` thinking。 +Z.AI 的 GLM-4.x 模型会自动启用思考模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/"].params.thinking`。 +Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用它。 +Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `adaptive` 思考。 ### `agents.defaults.cliBackends` -用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，这可作为备份。 +用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，可作为备份。 ```json5 { @@ -443,12 +445,12 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ``` - CLI 后端以文本为主；工具始终被禁用。 -- 当设置了 `sessionArg` 时支持会话。 -- 当 `imageArg` 接受文件路径时，支持图像透传。 +- 设置了 `sessionArg` 时支持会话。 +- 当 `imageArg` 接受文件路径时，支持图像直通。 ### `agents.defaults.systemPromptOverride` -用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认层级（`agents.defaults.systemPromptOverride`）设置，也可按智能体设置（`agents.list[].systemPromptOverride`）。按智能体设置的值优先；空值或仅含空白字符的值会被忽略。这对受控提示实验很有用。 +用一个固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）设置，也可按智能体设置（`agents.list[].systemPromptOverride`）。按智能体的值优先；空值或仅空白字符的值会被忽略。适用于受控的提示实验。 ```json5 { @@ -462,7 +464,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.promptOverlays` -按模型家族应用的、与提供商无关的提示覆盖层。GPT-5 家族模型 id 会在各提供商之间收到共享的行为契约；`personality` 仅控制友好交互风格这一层。 +按模型家族应用、与提供商无关的提示覆盖层。GPT-5 系列模型 id 会在不同提供商之间接收共享行为契约；`personality` 仅控制友好的交互风格层。 ```json5 { @@ -479,12 +481,12 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ``` - `"friendly"`（默认）和 `"on"` 会启用友好交互风格层。 -- `"off"` 只会禁用友好层；带标签的 GPT-5 行为契约仍保持启用。 -- 旧版 `plugins.entries.openai.config.personality` 在此共享设置未设置时仍会被读取。 +- `"off"` 仅禁用友好层；带标签的 GPT-5 行为契约仍保持启用。 +- 旧版 `plugins.entries.openai.config.personality` 在这个共享设置未配置时仍会被读取。 ### `agents.defaults.heartbeat` -周期性 Heartbeat 运行。 +周期性心跳运行。 ```json5 { @@ -496,10 +498,10 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 includeReasoning: false, includeSystemPromptSection: true, // 默认值：true；false 会从系统提示中省略 Heartbeat 部分 lightContext: false, // 默认值：false；true 只保留工作区引导文件中的 HEARTBEAT.md - isolatedSession: false, // 默认值：false；true 会在全新会话中运行每次 heartbeat（无对话历史） + isolatedSession: false, // 默认值：false；true 会让每次心跳在一个全新的会话中运行（无会话历史） session: "main", to: "+15555550123", - directPolicy: "allow", // allow（默认）| block + directPolicy: "allow", // allow（默认） | block target: "none", // 默认值：none | 可选值：last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, @@ -512,14 +514,14 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ``` - `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API 密钥认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 -- `includeSystemPromptSection`：设为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入引导上下文。默认值：`true`。 -- `suppressToolErrorWarnings`：设为 true 时，会在 heartbeat 运行期间抑制工具错误警告负载。 -- `timeoutSeconds`：在 heartbeat 智能体轮次被中止前允许的最长秒数。若不设置，则使用 `agents.defaults.timeoutSeconds`。 -- `directPolicy`：直接 / 私信投递策略。`allow`（默认）允许直接目标投递。`block` 会阻止直接目标投递，并发出 `reason=dm-blocked`。 -- `lightContext`：设为 true 时，heartbeat 运行会使用轻量级引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：设为 true 时，每次 heartbeat 都会在一个没有任何先前对话历史的全新会话中运行。隔离模式与 cron `sessionTarget: "isolated"` 相同。可将每次 heartbeat 的 token 成本从约 100K 降低到约 2–5K token。 -- 按智能体设置：使用 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 heartbeat。 -- Heartbeat 会运行完整的智能体轮次——间隔越短，消耗的 token 越多。 +- `includeSystemPromptSection`：为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入引导上下文。默认值：`true`。 +- `suppressToolErrorWarnings`：为 true 时，会在心跳运行期间抑制工具错误警告负载。 +- `timeoutSeconds`：心跳智能体轮次在被中止前允许的最长秒数。留空则使用 `agents.defaults.timeoutSeconds`。 +- `directPolicy`：直接/私信投递策略。`allow`（默认）允许投递到直接目标。`block` 会阻止投递到直接目标，并发出 `reason=dm-blocked`。 +- `lightContext`：为 true 时，心跳运行使用轻量引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次心跳都会在一个没有先前会话历史的新会话中运行。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次心跳的 token 成本从约 100K 降低到约 2-5K token。 +- 按智能体设置：使用 `agents.list[].heartbeat`。当任何智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。 +- 心跳会运行完整的智能体轮次——间隔越短，消耗的 token 越多。 ### `agents.defaults.compaction` @@ -535,7 +537,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 identifierPolicy: "strict", // strict | off | custom identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用 postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入 - model: "openrouter/anthropic/claude-sonnet-4-6", // 仅用于压缩的可选模型覆盖 + model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于压缩的模型覆盖 notifyUser: true, // 在压缩开始和完成时向用户发送简短通知（默认值：false） memoryFlush: { enabled: true, @@ -549,19 +551,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [压缩](/zh-CN/concepts/compaction)。 -- `provider`：已注册压缩提供商插件的 id。设置后，会调用该提供商的 `summarize()`，而不是内置的 LLM 摘要功能。失败时会回退到内置实现。设置提供商会强制使用 `mode: "safeguard"`。参见 [压缩](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 中止单次压缩操作前允许的最大秒数。默认值：`900`。 +- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见[压缩](/zh-CN/concepts/compaction)。 +- `provider`：已注册压缩提供商插件的 id。设置后，会调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置方式。设置提供商会强制使用 `mode: "safeguard"`。参见[压缩](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：OpenClaw 中止单次压缩操作前允许的最长秒数。默认值：`900`。 - `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要时预先添加内置的不透明标识符保留指引。 -- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 -- `postCompactionSections`：压缩后重新注入的可选 `AGENTS.md` H2 / H3 节名称。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。当未设置或显式设为这对默认值时，也接受旧版的 `Every Session` / `Safety` 标题作为兼容回退。 -- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖。当主会话应继续使用一个模型，而压缩摘要应使用另一个模型时使用此项；未设置时，压缩会使用会话的主模型。 -- `notifyUser`：当为 `true` 时，会在压缩开始和完成时向用户发送简短通知（例如，“正在压缩上下文...” 和 “压缩完成”）。默认禁用，以保持压缩静默。 -- `memoryFlush`：自动压缩前的静默智能体轮次，用于存储持久记忆。当工作区为只读时会跳过。 +- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留说明文本。 +- `postCompactionSections`：压缩后重新注入的可选 `AGENTS.md` H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。未设置时，或显式设置为该默认组合时，也接受旧版 `Every Session`/`Safety` 标题作为兼容回退。 +- `model`：可选的 `provider/model-id` 覆盖项，仅用于压缩摘要。当主会话应继续使用一个模型，而压缩摘要应使用另一个模型时可使用此项；未设置时，压缩会使用会话的主模型。 +- `notifyUser`：为 `true` 时，在压缩开始和完成时向用户发送简短通知（例如“Compacting context...” 和 “Compaction complete”）。默认关闭，以保持压缩静默。 +- `memoryFlush`：在自动压缩前执行静默智能体轮次，以存储持久记忆。当工作区为只读时会跳过。 ### `agents.defaults.contextPruning` -在将上下文发送给 LLM 之前，从内存中的上下文中修剪**旧工具结果**。**不会**修改磁盘上的会话历史。 +在将内容发送给 LLM 之前，从内存上下文中修剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -585,23 +587,23 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 -- `mode: "cache-ttl"` 会启用修剪过程。 -- `ttl` 控制再次允许执行修剪的频率（基于上次缓存触碰之后）。 -- 修剪会先对过大的工具结果执行软裁剪，然后在需要时对更旧的工具结果执行硬清除。 +- `mode: "cache-ttl"` 会启用修剪流程。 +- `ttl` 控制多久之后才能再次运行修剪（从上次缓存触达后开始计算）。 +- 修剪会先对过大的工具结果进行软修剪，如果仍有需要，再对更旧的工具结果执行硬清除。 -**软裁剪**会保留开头和结尾，并在中间插入 `...`。 +**软修剪**会保留开头和结尾，并在中间插入 `...`。 -**硬清除**会用占位文本替换整个工具结果。 +**硬清除**会用占位符替换整个工具结果。 说明： -- 图像区块永远不会被裁剪 / 清除。 -- 比例按字符数计算（近似值），不是精确 token 计数。 -- 如果助手消息少于 `keepLastAssistants` 条，则跳过修剪。 +- 图像块永远不会被修剪/清除。 +- 比例是基于字符的近似值，而不是精确 token 计数。 +- 如果助手消息少于 `keepLastAssistants` 条，则会跳过修剪。 -行为详情请参见 [会话修剪](/zh-CN/concepts/session-pruning)。 +行为细节参见[会话修剪](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -619,13 +621,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。 -- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号的变体）。Signal / Slack / Discord / Google Chat 默认 `minChars: 1500`。 -- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。 +- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 +- 渠道覆盖项：`channels..blockStreamingCoalesce`（以及按账号的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 +- `humanDelay`：分块回复之间的随机停顿。`natural` = 800–2500 毫秒。按智能体覆盖：`agents.list[].humanDelay`。 -行为和分块详情请参见 [流式传输](/zh-CN/concepts/streaming)。 +行为和分块细节参见[流式传输](/zh-CN/concepts/streaming)。 -### 输入状态指示器 +### 输入中指示器 ```json5 { @@ -638,16 +640,16 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 默认值：直接聊天 / 提及时为 `instant`，未被提及的群聊中为 `message`。 +- 默认值：直接聊天/提及时使用 `instant`，未提及的群聊使用 `message`。 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 -参见 [输入状态指示器](/zh-CN/concepts/typing-indicators)。 +参见[输入中指示器](/zh-CN/concepts/typing-indicators)。 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南参见[沙箱隔离](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -747,17 +749,17 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **后端：** - `docker`：本地 Docker 运行时（默认） -- `ssh`：通用的基于 SSH 的远程运行时 +- `ssh`：通用 SSH 远程运行时 - `openshell`：OpenShell 运行时 -当选择 `backend: "openshell"` 时，运行时特定设置会移动到 +当选择 `backend: "openshell"` 时，运行时专属设置会移动到 `plugins.entries.openshell.config`。 **SSH 后端配置：** -- `target`：`user@host[:port]` 形式的 SSH 目标 +- `target`：采用 `user@host[:port]` 形式的 SSH 目标 - `command`：SSH 客户端命令（默认值：`ssh`） -- `workspaceRoot`：用于按作用域划分工作区的远程绝对根路径 +- `workspaceRoot`：供各作用域工作区使用的远程绝对根路径 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 - `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件 - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 @@ -767,12 +769,12 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 基于 SecretRef 的 `*Data` 值会在沙箱会话启动前从当前活动的 secrets 运行时快照中解析 +- 基于 SecretRef 的 `*Data` 值会在沙箱会话开始前，从活动的 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重建后仅为远程工作区执行一次初始化播种 -- 然后保持远程 SSH 工作区为标准副本 +- 在创建或重建后，会先对远程工作区执行一次初始化填充 +- 然后保持远程 SSH 工作区为规范副本 - 通过 SSH 路由 `exec`、文件工具和媒体路径 - 不会自动将远程更改同步回主机 - 不支持沙箱浏览器容器 @@ -802,10 +804,10 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // 可选 - gatewayEndpoint: "https://lab.example", // 可选 - policy: "strict", // 可选的 OpenShell policy id - providers: ["openai"], // 可选 + gateway: "lab", // optional + gatewayEndpoint: "https://lab.example", // optional + policy: "strict", // optional OpenShell policy id + providers: ["openai"], // optional autoProviders: true, timeoutSeconds: 120, }, @@ -817,30 +819,30 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：在执行前从本地向远程播种，执行后再同步回本地；本地工作区保持为标准副本 -- `remote`：在创建沙箱时仅向远程播种一次，之后保持远程工作区为标准副本 +- `mirror`：在执行前将本地内容初始化到远程，执行后再同步回本地；本地工作区保持为规范副本 +- `remote`：在创建沙箱时仅向远程初始化一次，此后保持远程工作区为规范副本 -在 `remote` 模式下，在 OpenClaw 之外于主机本地所做的编辑，在播种步骤之后不会自动同步进沙箱。 +在 `remote` 模式下，在 OpenClaw 之外于主机本地所做的编辑，在初始化步骤之后不会自动同步到沙箱中。 传输方式是通过 SSH 连接到 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统以及 root 用户。 +**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。它需要网络出口、可写根文件系统以及 root 用户。 -**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 -默认会阻止 `"host"`。默认也会阻止 `"container:"`，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（破玻璃紧急开关）。 +**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义桥接网络）。 +`"host"` 会被阻止。默认也会阻止 `"container:"`，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（破窗开关）。 -**入站附件** 会暂存到活动工作区中的 `media/inbound/*`。 +**入站附件** 会被暂存到活动工作区中的 `media/inbound/*`。 -**`docker.binds`** 会挂载其他主机目录；全局和按智能体的 binds 会合并。 +**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的挂载会合并。 -**沙箱浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入到系统提示中。无需在 `openclaw.json` 中启用 `browser.enabled`。 -noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有效的 token URL（而不是在共享 URL 中暴露密码）。 +**沙箱浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入到系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。 +noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出短时有效的 token URL（而不是在共享 URL 中暴露密码）。 -- `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。 -- `network` 默认是 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确需要全局 bridge 连通性时，才设置为 `bridge`。 -- `cdpSourceRange` 可选地将容器边界上的 CDP 入站访问限制到某个 CIDR 范围内（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 只会将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 -- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器宿主机做了调优： +- `allowHostControl: false`（默认）会阻止沙箱会话将主机浏览器作为目标。 +- `network` 默认是 `openclaw-sandbox-browser`（专用桥接网络）。只有在你明确需要全局桥接连通性时，才设置为 `bridge`。 +- `cdpSourceRange` 可选择将容器边缘的 CDP 入站限制为某个 CIDR 范围（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 +- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -859,16 +861,16 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有 - `--metrics-recording-only` - `--disable-extensions`（默认启用） - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` - 默认启用；如果 WebGL / 3D 使用场景需要它们，可通过 + 默认启用；如果 WebGL/3D 使用场景需要它们，可通过 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。 - - 如果你的工作流依赖扩展，可通过 `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` - 重新启用扩展。 + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展，如果你的工作流 + 依赖于它们。 - `--renderer-process-limit=2` 可通过 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设置为 `0` 可使用 Chromium 的 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设置为 `0` 将使用 Chromium 的 默认进程限制。 - - 以及当启用 `noSandbox` 时附加 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 默认值是容器镜像基线；如需更改容器默认值，请使用带有自定义 - entrypoint 的自定义浏览器镜像。 + - 以及当启用 `noSandbox` 时的 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 这些默认值是容器镜像基线；如果要更改容器默认值，请使用带自定义 + 入口点的自定义浏览器镜像。 @@ -893,13 +895,13 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks } - thinkingDefault: "high", // 按智能体覆盖 thinking 级别 - reasoningDefault: "on", // 按智能体覆盖 reasoning 可见性 - fastModeDefault: false, // 按智能体覆盖 fast mode + model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } + thinkingDefault: "high", // per-agent thinking level override + reasoningDefault: "on", // per-agent reasoning visibility override + fastModeDefault: false, // per-agent fast mode override embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params - skills: ["docs-search"], // 设置后会替换 agents.defaults.skills + params: { cacheRetention: "none" }, // overrides matching defaults.models params by key + skills: ["docs-search"], // replaces agents.defaults.skills when set identity: { name: "Samantha", theme: "helpful sloth", @@ -931,26 +933,26 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ``` - `id`：稳定的智能体 id（必填）。 -- `default`：当设置了多个时，第一个生效（会记录警告）。如果一个都没设，列表中的第一个条目就是默认值。 -- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 会禁用全局 fallbacks）。只覆盖 `primary` 的 cron 作业仍会继承默认 fallbacks，除非你设置 `fallbacks: []`。 -- `params`：按智能体的流参数，会合并到 `agents.defaults.models` 中所选模型条目之上。用于智能体特定覆盖，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 -- `skills`：可选的按智能体 Skills 允许列表。如果省略，在设置了 `agents.defaults.skills` 时，该智能体会继承它；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。 -- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置按消息或按会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。所选 provider / model 配置决定了哪些值有效；对于 Google Gemini，`adaptive` 会保留由提供商管理的动态 thinking（Gemini 3 / 3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。 -- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当未设置按消息或按会话的 reasoning 覆盖时生效。 -- `fastModeDefault`：可选的按智能体默认 fast mode（`true | false`）。当未设置按消息或按会话的 fast mode 覆盖时生效。 -- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex" }` 可让某一个智能体仅使用 Codex，而其他智能体仍保留默认的 `auto` 模式 PI 回退。 -- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 并配合 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `default`：当设置了多个时，以第一个为准（会记录警告）。如果都未设置，则列表中的第一个条目为默认值。 +- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 会禁用全局故障切换）。只覆盖 `primary` 的 cron 作业仍会继承默认故障切换，除非你设置 `fallbacks: []`。 +- `params`：按智能体的流参数，会合并覆盖到 `agents.defaults.models` 中选定模型条目之上。可用于为特定智能体覆盖 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 +- `skills`：可选的按智能体 Skills 允许列表。如果省略，则在已设置时该智能体会继承 `agents.defaults.skills`；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。 +- `thinkingDefault`：可选的按智能体默认思考级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置按消息或按会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。所选提供商/模型配置决定哪些值有效；对于 Google Gemini，`adaptive` 会保留由提供商控制的动态思考（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。 +- `reasoningDefault`：可选的按智能体默认推理可见性（`on | off | stream`）。当未设置按消息或按会话的推理覆盖时生效。 +- `fastModeDefault`：可选的按智能体快速模式默认值（`true | false`）。当未设置按消息或按会话的快速模式覆盖时生效。 +- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex" }` 可让某个智能体仅使用 Codex，而其他智能体在 `auto` 模式下继续保留默认的 PI 回退。 +- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 并设置 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 - `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。 -- `identity` 会派生默认值：`ackReaction` 取自 `emoji`，`mentionPatterns` 取自 `name` / `emoji`。 -- `subagents.allowAgents`：用于 `sessions_spawn` 的智能体 id 允许列表（`["*"]` = 任意；默认：仅相同智能体）。 -- 沙箱继承保护：如果请求方会话已处于沙箱隔离中，`sessions_spawn` 会拒绝那些本应在非沙箱隔离环境中运行的目标。 -- `subagents.requireAgentId`：设为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。 +- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。 +- `subagents.allowAgents`：用于 `sessions_spawn` 的智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- 沙箱继承保护：如果请求方会话处于沙箱中，`sessions_spawn` 会拒绝会导致目标在非沙箱中运行的请求。 +- `subagents.requireAgentId`：为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。 --- ## 多智能体路由 -在一个 Gateway 网关中运行多个彼此隔离的智能体。参见 [多智能体](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关中运行多个彼此隔离的智能体。参见[多智能体](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -969,29 +971,29 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 绑定匹配字段 -- `type`（可选）：普通路由使用 `route`（缺失时默认是 route），持久 ACP 对话绑定使用 `acp`。 +- `type`（可选）：普通路由使用 `route`（缺失时默认是 route），持久 ACP 会话绑定使用 `acp` - `match.channel`（必填） - `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） -- `match.guildId` / `match.teamId`（可选；渠道特定） -- `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }` +- `match.guildId` / `match.teamId`（可选；特定于渠道） +- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }` -**确定性的匹配顺序：** +**确定性匹配顺序：** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId`（精确匹配，无 peer / guild / team） +4. `match.accountId`（精确匹配，无 peer/guild/team） 5. `match.accountId: "*"`（整个渠道范围） 6. 默认智能体 -在每个层级内，第一条匹配的 `bindings` 条目胜出。 +在每一层内，第一个匹配的 `bindings` 条目获胜。 -对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份解析（`match.channel` + account + `match.peer.id`），不会使用上述 route 绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 会按精确会话标识（`match.channel` + 账号 + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。 -### 按智能体划分的访问配置 +### 按智能体的访问配置 - + ```json5 { @@ -1038,7 +1040,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - + ```json5 { @@ -1084,7 +1086,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 -关于优先级详情，请参见 [多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 +有关优先级细节，请参阅[多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1110,20 +1112,20 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 高于此 token 数时跳过父线程分叉（0 表示禁用） + parentForkMaxTokens: 100000, // 父线程 token 数超过此值时跳过父线程分叉（0 表示禁用） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // 时长或 false - maxDiskBytes: "500mb", // 可选硬预算 - highWaterBytes: "400mb", // 可选清理目标 + resetArchiveRetention: "30d", // duration or false + maxDiskBytes: "500mb", // optional hard budget + highWaterBytes: "400mb", // optional cleanup target }, threadBindings: { enabled: true, - idleHours: 24, // 默认按小时计算的无活动自动取消聚焦时间（`0` 表示禁用） - maxAgeHours: 0, // 默认按小时计算的硬性最大年龄（`0` 表示禁用） + idleHours: 24, // 默认按不活动时间自动取消聚焦的小时数（`0` 表示禁用） + maxAgeHours: 0, // 默认硬性最长存续小时数（`0` 表示禁用） }, mainKey: "main", // 旧版字段（运行时始终使用 "main"） agentToAgent: { maxPingPongTurns: 5 }, @@ -1137,35 +1139,35 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 -- **`scope`**：群聊上下文的基础会话分组策略。 +- **`scope`**：群聊上下文中的基础会话分组策略。 - `per-sender`（默认）：在某个渠道上下文中，每个发送者都有独立会话。 - - `global`：某个渠道上下文中的所有参与者共享一个会话（仅在明确需要共享上下文时使用）。 + - `global`：某个渠道上下文中的所有参与者共享同一个会话（仅在确实需要共享上下文时使用）。 - **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - `per-peer`：按发送者 id 跨渠道隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将标准 id 映射到带提供商前缀的 peer，以便跨渠道共享会话。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。当两者都配置时，以先到期者为准。 -- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 也可作为 `direct` 的别名使用。 +- **`identityLinks`**：将规范 id 映射到带提供商前缀的 peer，用于跨渠道共享会话。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在空闲 `idleMinutes` 后重置。如果两者都已配置，则先到期者生效。 +- **`resetByType`**：按类型的覆盖项（`direct`、`group`、`thread`）。旧版 `dm` 仍接受，作为 `direct` 的别名。 - **`parentForkMaxTokens`**：创建分叉线程会话时，父会话允许的最大 `totalTokens`（默认 `100000`）。 - - 如果父会话的 `totalTokens` 高于此值，OpenClaw 会启动一个新的线程会话，而不是继承父 transcript 历史。 - - 设置为 `0` 可禁用此保护，并始终允许从父会话分叉。 + - 如果父会话的 `totalTokens` 高于此值，OpenClaw 会启动一个全新的线程会话，而不是继承父转录历史。 + - 设置为 `0` 可禁用此保护，并始终允许父会话分叉。 - **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：在智能体之间交互时，智能体间来回回复的最大轮次（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链式交互。 -- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版别名 `dm` 也可用）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 规则优先。 +- **`agentToAgent.maxPingPongTurns`**：智能体之间来回对话时允许的最大回复轮数（整数，范围：`0`–`5`）。`0` 表示禁用来回链式对话。 +- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 仍可作为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 规则优先。 - **`maintenance`**：会话存储清理 + 保留控制。 - - `mode`：`warn` 只发出警告；`enforce` 会实际执行清理。 - - `pruneAfter`：过期条目的年龄截止时间（默认 `30d`）。 - - `maxEntries`：`sessions.json` 中条目的最大数量（默认 `500`）。 - - `rotateBytes`：当 `sessions.json` 超过此大小时轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` transcript 归档的保留时长。默认继承 `pruneAfter`；设置为 `false` 可禁用。 - - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的制品 / 会话。 + - `mode`：`warn` 仅发出警告；`enforce` 执行清理。 + - `pruneAfter`：陈旧条目的保留截止时间（默认 `30d`）。 + - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 + - `rotateBytes`：当 `sessions.json` 超过该大小时进行轮转（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留时长。默认跟随 `pruneAfter`；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的会话目录磁盘硬预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的产物/会话。 - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - - `enabled`：主默认开关（提供商可以覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认按小时计算的无活动自动取消聚焦时间（`0` 表示禁用；提供商可以覆盖） - - `maxAgeHours`：默认按小时计算的硬性最大年龄（`0` 表示禁用；提供商可以覆盖） + - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） + - `idleHours`：默认按不活动时间自动取消聚焦的小时数（`0` 表示禁用；提供商可覆盖） + - `maxAgeHours`：默认硬性最长存续小时数（`0` 表示禁用；提供商可覆盖） @@ -1203,36 +1205,36 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 响应前缀 -按渠道 / 账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 +按渠道/账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会推导为 `[{identity.name}]`。 +解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止继续回退。`"auto"` 会派生为 `[{identity.name}]`。 **模板变量：** -| 变量 | 说明 | 示例 | -| ----------------- | ------------------ | --------------------------- | -| `{model}` | 简短模型名 | `claude-opus-4-6` | -| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供商名称 | `anthropic` | -| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| 变量 | 说明 | 示例 | +| ----------------- | -------------- | --------------------------- | +| `{model}` | 短模型名 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前思考级别 | `high`、`low`、`off` | +| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 ### 确认反应 -- 默认取当前活动智能体的 `identity.emoji`，否则为 `"👀"`。设置 `""` 可禁用。 +- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设置为 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 - 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退值。 - 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上会在回复后移除确认反应。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除确认反应。 - `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 - 在 Slack 和 Discord 上，未设置时如果确认反应处于启用状态，则状态反应也保持启用。 - 在 Telegram 上，需要显式将它设为 `true` 才会启用生命周期状态反应。 + 在 Slack 和 Discord 上，未设置时如果确认反应处于激活状态，则状态反应保持启用。 + 在 Telegram 上，需显式设为 `true` 才会启用生命周期状态反应。 ### 入站防抖 -将来自同一发送者的快速纯文本消息批量合并为一个智能体轮次。媒体 / 附件会立即刷新。控制命令会绕过防抖。 +将同一发送者的快速连续纯文本消息批处理为单个智能体轮次。媒体/附件会立即触发发送。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -1275,18 +1277,18 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -- `auto` 控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示生效状态。 -- `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。 -- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需显式开启）。 -- API 密钥会回退到 `ELEVENLABS_API_KEY` / `XI_API_KEY` 和 `OPENAI_API_KEY`。 -- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置，然后是 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 -- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型 / 语音校验。 +- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好设置，`/tts status` 会显示实际生效状态。 +- `summaryModel` 会覆盖自动摘要所使用的 `agents.defaults.model.primary`。 +- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认是 `false`（需主动启用）。 +- API 密钥会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 +- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序是配置，然后是 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 +- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽对模型/语音的校验。 --- -## 通话 +## 对话 -Talk 模式的默认值（macOS / iOS / Android）。 +对话模式的默认设置（macOS/iOS/Android）。 ```json5 { @@ -1310,18 +1312,18 @@ Talk 模式的默认值（macOS / iOS / Android）。 } ``` -- `talk.provider` 在配置了多个 Talk 提供商时必须匹配 `talk.providers` 中的某个键。 -- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.`。 -- Voice id 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 +- `talk.provider` 在配置了多个对话提供商时，必须匹配 `talk.providers` 中的某个键。 +- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.`。 +- 语音 id 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 - `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 -- 仅当未配置 Talk API 密钥时，才会使用 `ELEVENLABS_API_KEY` 回退。 -- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 -- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久再发送 transcript。未设置时会保留平台默认的停顿窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）。 +- 只有在未配置对话 API 密钥时，才会应用 `ELEVENLABS_API_KEY` 回退。 +- `providers.*.voiceAliases` 允许对话指令使用友好名称。 +- `silenceTimeoutMs` 控制对话模式在用户停止说话后等待多久才发送转录。未设置时，将保持平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- ## 相关内容 -- [配置参考](/zh-CN/gateway/configuration-reference) — 所有其他配置键 -- [配置](/zh-CN/gateway/configuration) — 常见任务和快速设置 +- [配置参考](/zh-CN/gateway/configuration-reference) —— 所有其他配置键 +- [配置](/zh-CN/gateway/configuration) —— 常见任务和快速设置 - [配置示例](/zh-CN/gateway/configuration-examples) diff --git a/docs/zh-CN/help/testing.md b/docs/zh-CN/help/testing.md index 45b6bfe66..a9f2594db 100644 --- a/docs/zh-CN/help/testing.md +++ b/docs/zh-CN/help/testing.md @@ -3,221 +3,151 @@ read_when: - 在本地或 CI 中运行测试 - 为模型 / 提供商缺陷添加回归测试 - 调试 Gateway 网关 + 智能体行为 -summary: 测试工具包：unit/e2e/live 测试套件、Docker 运行器，以及每项测试覆盖的内容 +summary: 测试工具包：单元 / e2e / 实时测试套件、Docker 运行器，以及每项测试涵盖的内容 title: 测试 x-i18n: - generated_at: "2026-04-25T00:41:26Z" + generated_at: "2026-04-25T01:51:46Z" model: gpt-5.4 provider: openai - source_hash: b3bd1ab654b43a380c6eecb3ba53e74442bad9374be4eea2d9ce368d8b89b7c2 + source_hash: ef5558c1f296c9925227be4f79770346ed10050d555194fef6cdff28d0eb5274 source_path: help/testing.md workflow: 15 --- -OpenClaw 有三个 Vitest 测试套件（unit/integration、e2e、live）以及一小组 -Docker 运行器。本文档是一份“我们如何测试”的指南： +OpenClaw 有三个 Vitest 测试套件（单元 / 集成、e2e、实时），以及一小组 Docker 运行器。本文档是一份“我们如何测试”的指南： -- 每个测试套件覆盖什么（以及它刻意**不**覆盖什么）。 -- 常见工作流应运行哪些命令（本地、推送前、调试）。 -- 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` -- 当你在迭代单个失败用例时，优先先运行定向测试。 +- 现在直接指定文件路径也会路由扩展 / 渠道路径：`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` +- E2E 套件：`pnpm test:e2e` 当你在调试真实提供商 / 模型时（需要真实凭证）： -- live 测试套件（模型 + Gateway 网关 tool/image 探测）：`pnpm test:live` -- 安静地只运行一个 live 文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts` -- 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 模型 - matrix 作业。 - - 若要进行聚焦的 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 调用方中。 +- 实时套件（模型 + Gateway 网关工具 / 图像探测）：`pnpm test:live` +- 安静地只运行一个实时测试文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Docker 实时模型全量扫描：`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` 都会调用可复用的实时 / E2E 工作流，并设置 `include_live_suites: true`，其中包含按提供商分片的独立 Docker 实时模型矩阵任务。 + - 若要有针对性地重跑 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。 -- 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，且助手转录中保存了规范化的 - `usage.cost`。 + - 该命令会针对 Codex app-server 路径运行一条 Docker 实时通道，使用 `/codex bind` 绑定一个合成的 Slack 私信，执行 `/codex fast` 和 `/codex permissions`，然后验证普通回复和图像附件是通过原生插件绑定而不是 ACP 路由的。 +- 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 转录中存储了规范化的 `usage.cost`。 -提示：当你只需要一个失败用例时，优先使用下文描述的允许列表环境变量来缩小 live 测试范围。 +提示：当你只需要一个失败用例时，优先使用下面描述的 allowlist 环境变量来缩小实时测试范围。 ## 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、实时 Matrix 通道以及由 Convex 管理的实时 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` 通道。 + - 直接在宿主机上运行由仓库支持的 QA 场景。 + - 默认会使用隔离的 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 测试套件。 - - 保持与主机上 `qa suite` 相同的场景选择行为。 - - 复用与 `qa suite` 相同的 provider/model 选择标志。 - - live 运行会转发对来宾系统切实可行的受支持 QA 凭证输入： - 基于环境变量的 provider 密钥、QA live provider 配置路径，以及存在时的 `CODEX_HOME`。 - - 输出目录必须位于仓库根目录下，以便来宾可通过 - 挂载的工作区回写。 - - 在 `.artifacts/qa-e2e/...` 下写入常规 QA 报告 + 摘要，以及 Multipass 日志。 + - 在一次性 Multipass Linux VM 中运行同样的 QA 套件。 + - 保持与宿主机上 `qa suite` 相同的场景选择行为。 + - 复用与 `qa suite` 相同的提供商 / 模型选择标志。 + - 实时运行会转发对来宾机实际可行的受支持 QA 认证输入：基于环境变量的提供商密钥、QA 实时提供商配置路径，以及存在时的 `CODEX_HOME`。 + - 输出目录必须保持在仓库根目录下，这样来宾机才能通过挂载的工作区回写内容。 + - 会将常规 QA 报告 + 摘要，以及 Multipass 日志写入 `.artifacts/qa-e2e/...`。 - `pnpm qa:lab:up` - - 启动基于 Docker 的 QA 站点，用于面向操作人员风格的 QA 工作。 + - 启动基于 Docker 的 QA 站点，用于偏操作员风格的 QA 工作。 - `pnpm test:docker:npm-onboard-channel-agent` - - 从当前检出构建一个 npm tarball，在 Docker 中全局安装， - 运行非交互式 OpenAI API 密钥新手引导，默认配置 Telegram， - 验证启用插件会按需安装运行时依赖，运行 doctor， - 并针对一个模拟的 OpenAI 端点运行一次本地智能体回合。 - - 使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 可在同一打包安装 - 通道中改为运行 Discord。 + - 从当前检出构建一个 npm tarball，在 Docker 中全局安装，以非交互方式完成 OpenAI API 密钥新手引导，默认配置 Telegram，验证启用插件会按需安装运行时依赖，运行 doctor，并针对一个被 mock 的 OpenAI 端点运行一次本地智能体轮次。 + - 使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 可用 Discord 运行相同的打包安装通道。 - `pnpm test:docker:npm-telegram-live` - - 在 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 凭证租约。 + - 在 Docker 中安装已发布的 OpenClaw 包，运行已安装包的新手引导，通过已安装的 CLI 配置 Telegram，然后复用实时 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 凭证租约。 - `pnpm test:docker:bundled-channel-deps` - - 在 Docker 中打包并安装当前 OpenClaw 构建，使用已配置的 OpenAI 启动 - Gateway 网关，然后通过配置编辑启用内置 channel/plugins。 - - 验证设置发现阶段会让未配置插件的运行时依赖保持缺失状态， - 第一次配置后的 Gateway 网关或 doctor 运行会按需安装每个内置 - 插件的运行时依赖，并验证第二次重启不会重新安装 - 已经激活的依赖。 - - 还会安装一个已知较旧的 npm 基线版本，在运行 - `openclaw update --tag ` 之前启用 Telegram，并验证候选版本的 - 更新后 doctor 会修复内置渠道运行时依赖，而不需要 - harness 侧的 postinstall 修复。 + - 在 Docker 中打包并安装当前的 OpenClaw 构建，使用已配置的 OpenAI 启动 Gateway 网关，然后通过修改配置启用内置渠道 / 插件。 + - 验证设置发现阶段不会提前安装未配置插件的运行时依赖；第一次配置后的 Gateway 网关或 doctor 运行会按需安装每个内置插件的运行时依赖；第二次重启不会重复安装已经激活的依赖。 + - 还会安装一个已知的较旧 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 网关状态上发生冲突。 - - 更新后证明会运行常规的内置插件表面，因为像 speech、image generation 和 media - understanding 这样的能力 facade 是通过内置运行时 API 加载的，即使智能体回合本身 - 只检查一个简单的文本响应也是如此。 + - 该脚本会将嵌套通道日志写入 `/tmp/openclaw-parallels-npm-update.*` 下。不要在检查 `windows-update.log`、`macos-update.log` 或 `linux-update.log` 之前就假设外层包装器已卡死。 + - Windows 更新在冷启动来宾系统上，可能会花 10 到 15 分钟执行更新后的 doctor / 运行时依赖修复；只要嵌套的 npm 调试日志仍在推进，这就是健康状态。 + - 不要将这个聚合包装器与单独的 Parallels macOS、Windows 或 Linux 冒烟通道并行运行。它们共享 VM 状态，可能会在快照恢复、包服务或来宾 gateway 状态上发生冲突。 + - 更新后的证明会运行常规的内置插件表面，因为像语音、图像生成和媒体理解这样的能力外观层，是通过内置运行时 API 加载的，即使智能体轮次本身只检查简单的文本响应。 - `pnpm openclaw qa aimock` - - 仅启动本地 AIMock provider 服务器，用于直接协议冒烟 - 测试。 + - 仅启动本地 AIMock 提供商服务器，用于直接协议冒烟测试。 - `pnpm openclaw qa matrix` - - 针对一次性的、基于 Docker 的 Tuwunel homeserver 运行 Matrix live QA 通道。 - - 这个 QA 主机目前仅用于仓库 / 开发环境。打包安装的 OpenClaw 不包含 - `qa-lab`，因此不会暴露 `openclaw qa`。 - - 仓库检出会直接加载内置运行器；不需要单独的插件安装 - 步骤。 - - 预配三个临时 Matrix 用户（`driver`、`sut`、`observer`）和一个私有房间，然后以真实 Matrix 插件作为 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`。 + - 针对一次性、基于 Docker 的 Tuwunel homeserver 运行 Matrix 实时 QA 通道。 + - 这个 QA 宿主当前仅用于仓库 / 开发。打包后的 OpenClaw 安装不会附带 `qa-lab`，因此也不会暴露 `openclaw qa`。 + - 仓库检出会直接加载内置运行器；不需要单独安装插件步骤。 + - 会配置三个临时 Matrix 用户（`driver`、`sut`、`observer`）以及一个私有房间，然后启动一个 QA gateway 子进程，并使用真实的 Matrix 插件作为被测传输层。 + - 默认使用固定稳定版 Tuwunel 镜像 `ghcr.io/matrix-construct/tuwunel:v1.5.1`。当你需要测试其他镜像时，可通过 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 覆盖。 + - Matrix 不暴露共享的凭证来源标志，因为该通道会在本地配置一次性用户。 + - 会将 Matrix QA 报告、摘要、observed-events 工件以及合并的 stdout / stderr 输出日志写入 `.artifacts/qa-e2e/...`。 + - 默认输出进度，并通过 `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 通道。 - - 需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`。群组 id 必须是数值型 Telegram chat id。 - - 支持 `--credential-source convex` 以使用共享池化凭证。默认使用 env 模式，或设置 `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。 + - 针对真实私有群组运行 Telegram 实时 QA 通道，使用来自环境变量的 driver 和 SUT 机器人令牌。 + - 需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`。群组 id 必须是 Telegram 聊天的数字 id。 + - 支持 `--credential-source convex` 来使用共享池化凭证。默认使用环境变量模式，或设置 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` 以启用池化租约。 + - 任一场景失败时会以非零状态退出。若你希望保留工件但不让退出码失败，可使用 `--allow-failures`。 + - 需要同一私有群组中的两个不同机器人，并且 SUT 机器人必须公开 Telegram 用户名。 + - 为了稳定地观察 bot 到 bot 通信，请在 `@BotFather` 中为两个机器人启用 Bot-to-Bot Communication Mode，并确保 driver 机器人能够观察群组中的机器人流量。 + - 会将 Telegram QA 报告、摘要和 observed-messages 工件写入 `.artifacts/qa-e2e/...`。回复场景中会包含从 driver 发送请求到观察到 SUT 回复的 RTT。 -live 传输通道共享一个标准契约，以防新传输出现漂移： +实时传输通道共享一个标准契约，这样新传输层就不会发生漂移： -`qa-channel` 仍然是广泛的合成 QA 测试套件，不属于 live -传输覆盖矩阵的一部分。 +`qa-channel` 仍然是广泛的合成 QA 套件，不属于实时传输覆盖矩阵的一部分。 -| 通道 | Canary | 提及门控 | 允许列表阻止 | 顶层回复 | 重启恢复 | 线程后续跟进 | 线程隔离 | 反应观测 | 帮助命令 | -| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | +| 通道 | Canary | 提及门禁 | allowlist 拦截 | 顶层回复 | 重启恢复 | 线程跟进 | 线程隔离 | 反应观察 | 帮助命令 | +| ---- | ------ | -------- | -------------- | -------- | -------- | -------- | -------- | -------- | -------- | | 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 项目脚手架参考： - `qa/convex-credential-broker/` -所需环境变量： +必需环境变量： - `OPENCLAW_QA_CONVEX_SITE_URL`（例如 `https://your-deployment.convex.site`） -- 针对所选角色的一个密钥： - - `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`） 可选环境变量： @@ -226,13 +156,12 @@ Convex 项目脚手架参考： - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS`（默认 `90000`） - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS`（默认 `15000`） - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX`（默认 `/qa-credentials/v1`） -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（可选追踪 id） -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` 允许仅用于本地开发的 loopback `http://` Convex URL。 +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（可选跟踪 id） +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` 允许在仅限本地开发时使用 loopback `http://` Convex URL。 -正常运行时，`OPENCLAW_QA_CONVEX_SITE_URL` 应使用 `https://`。 +在正常运行中，`OPENCLAW_QA_CONVEX_SITE_URL` 应使用 `https://`。 -维护者管理命令（池添加 / 删除 / 列表）要求 -专门使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`。 +维护者管理命令（池添加 / 删除 / 列表）必须显式使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`。 供维护者使用的 CLI 辅助命令： @@ -243,10 +172,7 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -在 live 运行前使用 `doctor`，以检查 Convex 站点 URL、broker 密钥、 -端点前缀、HTTP 超时以及 admin/list 可达性，而不会打印 -密钥值。在脚本和 CI -工具中使用 `--json` 可获得机器可读输出。 +在实时运行前使用 `doctor` 检查 Convex 站点 URL、broker 密钥、端点前缀、HTTP 超时以及管理 / 列表可达性，同时不会打印密钥值。在脚本和 CI 工具中使用 `--json` 获取机器可读输出。 默认端点契约（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）： @@ -260,73 +186,71 @@ pnpm openclaw qa credentials remove --credential-id - `POST /release` - 请求：`{ kind, ownerId, actorRole, credentialId, leaseToken }` - 成功：`{ status: "ok" }`（或空的 `2xx`） -- `POST /admin/add`（仅限 maintainer 密钥） +- `POST /admin/add`（仅维护者密钥） - 请求：`{ kind, actorId, payload, note?, status? }` - 成功：`{ status: "ok", credential }` -- `POST /admin/remove`（仅限 maintainer 密钥） +- `POST /admin/remove`（仅维护者密钥） - 请求：`{ credentialId, actorId }` - 成功：`{ status: "ok", changed, credential }` - 活跃租约保护：`{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list`（仅限 maintainer 密钥） +- `POST /admin/list`（仅维护者密钥） - 请求：`{ kind?, status?, includePayload?, limit? }` - 成功：`{ status: "ok", credentials, count }` -Telegram 类型的负载结构： +Telegram 类型的 payload 结构： - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` 必须是数值型 Telegram chat id 字符串。 -- `admin/add` 会对 `kind: "telegram"` 验证该结构，并拒绝格式错误的负载。 +- `groupId` 必须是 Telegram 聊天的数字 id 字符串。 +- `admin/add` 会对 `kind: "telegram"` 校验此结构，并拒绝格式错误的 payload。 ### 向 QA 添加一个渠道 -向 Markdown QA 系统添加一个渠道只需要两样东西： +向 Markdown QA 系统添加一个渠道只需要严格满足两项要求： -1. 该渠道的传输适配器。 +1. 一个适用于该渠道的传输适配器。 2. 一个用于验证渠道契约的场景包。 -当共享的 `qa-lab` 主机可以负责流程时，不要添加新的顶层 QA 命令根。 +如果共享的 `qa-lab` 宿主可以负责该流程，就不要添加新的顶层 QA 命令根。 -`qa-lab` 负责共享主机机制： +`qa-lab` 负责共享宿主机制： - `openclaw qa` 命令根 -- 测试套件启动和拆除 -- worker 并发 -- 产物写入 +- 套件启动与清理 +- 工作进程并发 +- 工件写入 - 报告生成 - 场景执行 - 对旧版 `qa-channel` 场景的兼容别名 运行器插件负责传输契约： -- `openclaw qa ` 如何挂载到共享的 `qa` 根之下 -- 如何为该传输配置 Gateway 网关 +- 如何将 `openclaw qa ` 挂载到共享 `qa` 根之下 +- 如何为该传输配置 gateway - 如何检查就绪状态 - 如何注入入站事件 -- 如何观测出站消息 -- 如何暴露转录内容和规范化后的传输状态 -- 如何执行由传输支持的操作 -- 如何处理特定于传输的重置或清理 +- 如何观察出站消息 +- 如何暴露转录和规范化的传输状态 +- 如何执行由传输支撑的动作 +- 如何处理传输专属的重置或清理 新渠道的最低接入门槛是： -1. 保持 `qa-lab` 作为共享 `qa` 根的拥有者。 -2. 在共享的 `qa-lab` 主机接缝上实现传输运行器。 -3. 将特定于传输的机制保留在运行器插件或渠道 harness 内部。 -4. 将运行器挂载为 `openclaw qa `，而不是注册一个相互竞争的根命令。 - 运行器插件应在 `openclaw.plugin.json` 中声明 `qaRunners`，并从 `runtime-api.ts` 导出匹配的 `qaRunnerCliRegistrations` 数组。 - 保持 `runtime-api.ts` 轻量；延迟 CLI 和运行器执行应保留在单独的入口点之后。 -5. 在有主题的 `qa/scenarios/` 目录下编写或调整 Markdown 场景。 -6. 为新场景使用通用场景辅助工具。 -7. 除非仓库正在进行有意迁移，否则保持现有兼容别名继续可用。 +1. 保持 `qa-lab` 作为共享 `qa` 根的所有者。 +2. 在共享的 `qa-lab` 宿主接缝上实现传输运行器。 +3. 将传输专属机制保留在运行器插件或渠道 harness 内部。 +4. 将运行器挂载为 `openclaw qa `，而不是注册一个竞争性的根命令。运行器插件应在 `openclaw.plugin.json` 中声明 `qaRunners`，并从 `runtime-api.ts` 导出匹配的 `qaRunnerCliRegistrations` 数组。保持 `runtime-api.ts` 轻量；延迟加载的 CLI 和运行器执行应放在单独的入口点之后。 +5. 在按主题划分的 `qa/scenarios/` 目录下编写或改造 Markdown 场景。 +6. 为新场景使用通用场景辅助函数。 +7. 除非仓库正在进行有意迁移，否则应保持现有兼容别名继续工作。 -决策规则非常严格： +决策规则是严格的： -- 如果某个行为可以在 `qa-lab` 中统一表达一次，就把它放进 `qa-lab`。 -- 如果某个行为依赖某一个渠道传输，就把它保留在该运行器插件或插件 harness 中。 -- 如果某个场景需要一个超过一个渠道都能使用的新能力，请添加一个通用辅助工具，而不是在 `suite.ts` 中增加渠道特定分支。 -- 如果某个行为只对一种传输有意义，就保持该场景是传输特定的，并在场景契约中明确说明。 +- 如果某个行为可以在 `qa-lab` 中统一表达一次，就把它放在 `qa-lab`。 +- 如果某个行为依赖单一渠道传输，就把它保留在对应运行器插件或插件 harness 中。 +- 如果某个场景需要多个渠道都可使用的新能力，应添加通用辅助函数，而不是在 `suite.ts` 中添加渠道专属分支。 +- 如果某个行为只对一种传输有意义，就让该场景保持传输专属，并在场景契约中明确说明。 -新场景优先使用的通用辅助工具名称是： +新场景推荐使用的通用辅助函数名称： - `waitForTransportReady` - `waitForChannelReady` @@ -341,7 +265,7 @@ Telegram 类型的负载结构： - `formatTransportTranscript` - `resetTransport` -现有场景仍可使用兼容别名，包括： +现有场景仍可使用的兼容别名包括： - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -349,22 +273,21 @@ Telegram 类型的负载结构： - `formatConversationTranscript` - `resetBus` -新的渠道工作应使用通用辅助工具名称。 -兼容别名的存在是为了避免一次性强制迁移，而不是作为 -新场景编写的范式。 +新的渠道工作应使用这些通用辅助函数名称。 +兼容别名的存在是为了避免一次性强制迁移，而不是作为新场景编写的范式。 -## 测试套件（什么在什么地方运行） +## 测试套件（各自在哪运行） -可以把这些测试套件理解为“真实性逐步增加”（以及不稳定性 / 成本逐步增加）： +可以把这些套件理解为“真实性逐步提高”（同时不稳定性 / 成本也逐步提高）： -### Unit / integration（默认） +### 单元 / 集成（默认） - 命令：`pnpm test` -- 配置：未定向运行会使用 `vitest.full-*.config.ts` 分片集，并且可能会将多项目分片扩展为按项目拆分的配置，以便并行调度 -- 文件：core/unit 清单位于 `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts`，以及由 `vitest.unit.config.ts` 覆盖的白名单 `ui` node 测试 +- 配置：未指定目标的运行使用 `vitest.full-*.config.ts` 分片集合，并且可能会将多项目分片展开为按项目划分的配置，以便并行调度 +- 文件：核心 / 单元清单位于 `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts`，以及由 `vitest.unit.config.ts` 覆盖的白名单 `ui` 节点测试 - 范围： - 纯单元测试 - - 进程内集成测试（Gateway 网关 auth、路由、tooling、解析、配置） + - 进程内集成测试（gateway 认证、路由、工具、解析、配置） - 针对已知缺陷的确定性回归测试 - 预期： - 在 CI 中运行 @@ -374,224 +297,192 @@ 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`），而不是一个巨大的原生 root-project 进程。这可以降低高负载机器上的峰值 RSS，并避免 auto-reply/extension 工作拖慢无关套件。 - - `pnpm test --watch` 仍然使用原生 root `vitest.config.ts` 项目图，因为多分片的 watch 循环并不现实。 - - `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 会先通过作用域通道路由显式文件 / 目录目标，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 不必承担完整 root 项目启动开销。 - - `pnpm test:changed` 会在差异仅触及可路由的源文件 / 测试文件时，将变更过的 git 路径扩展为相同的作用域通道；配置 / 设置编辑仍会回退为更广泛的 root-project 重跑。 - - `pnpm check:changed` 是窄范围工作时常规的智能本地门禁。它会将差异分类为 core、core tests、extensions、extension tests、apps、docs、release metadata 和 tooling，然后运行匹配的 typecheck/lint/test 通道。公共插件 SDK 和插件契约变更会包含一次 extension 验证通道，因为 extensions 依赖这些 core 契约。仅发布元数据版本号变更会运行定向的 version/config/root-dependency 检查，而不是完整套件，并带有一个守卫，用于拒绝超出顶层 version 字段范围的 package 变更。 - - 来自 agents、commands、plugins、auto-reply helpers、`plugin-sdk` 及类似纯工具区域的轻导入 unit 测试会路由到 `unit-fast` 通道，该通道会跳过 `test/setup-openclaw-runtime.ts`；有状态 / 运行时较重的文件仍保留在现有通道上。 - - 选定的 `plugin-sdk` 和 `commands` helper 源文件也会将 changed 模式运行映射到这些轻量通道中的显式同级测试，因此 helper 编辑可避免为该目录重跑完整的重型套件。 - - `auto-reply` 有三个专用分桶：顶层 core helper、顶层 `reply.*` 集成测试，以及 `src/auto-reply/reply/**` 子树。这让最重的 reply harness 工作不会落到廉价的 status/chunk/token 测试上。 + - 未指定目标的 `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 / 扩展工作拖累无关套件。 + - `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` 可以避免付出完整根项目启动成本。 + - `pnpm test:changed` 会在差异仅涉及可路由的源文件 / 测试文件时，将变更的 git 路径展开到相同的作用域通道；配置 / setup 修改仍会回退到更广泛的根项目重跑。 + - `pnpm check:changed` 是窄范围工作时常规的智能本地门禁。它会将差异分类为核心、核心测试、扩展、扩展测试、应用、文档、发布元数据和工具，然后运行对应的类型检查 / lint / 测试通道。公开的 插件 SDK 和插件契约变更会额外包含一次扩展验证，因为扩展依赖这些核心契约。仅涉及发布元数据版本提升时，会运行有针对性的版本 / 配置 / 根依赖检查，而不是完整套件，并且有防护措施拒绝顶层版本字段之外的包改动。 + - 来自智能体、命令、插件、auto-reply 辅助函数、`plugin-sdk` 以及类似纯工具区域的轻导入单元测试，会路由到 `unit-fast` 通道，该通道会跳过 `test/setup-openclaw-runtime.ts`；有状态 / 运行时负担较重的文件则保留在现有通道。 + - 某些 `plugin-sdk` 和 `commands` 辅助源文件也会在 changed 模式运行时映射到这些轻量通道中的显式同级测试，因此辅助函数修改无需为该目录重跑完整的重型套件。 + - `auto-reply` 有三个专用桶：顶层核心辅助函数、顶层 `reply.*` 集成测试，以及 `src/auto-reply/reply/**` 子树。这样可以让最重的 reply harness 工作不影响廉价的 status / chunk / token 测试。 - - 当你变更消息工具发现输入或压缩运行时 - 上下文时，请同时保持两个层级的覆盖。 - - 为纯路由和规范化 - 边界添加聚焦的 helper 回归测试。 + - 当你修改消息工具发现输入或压缩运行时上下文时，要同时保持两个层级的覆盖。 + - 为纯路由和规范化边界添加聚焦的辅助函数回归测试。 - 保持嵌入式运行器集成套件健康： `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 和压缩行为仍会 - 通过真实的 `run.ts` / `compact.ts` 路径流动；仅有 helper 测试 - 不能充分替代这些集成路径。 + - 这些套件会验证作用域 id 和压缩行为仍然流经真实的 `run.ts` / `compact.ts` 路径；仅有辅助函数测试并不能充分替代这些集成路径。 - + - 基础 Vitest 配置默认使用 `threads`。 - - 共享 Vitest 配置固定 `isolate: false`，并在 - root projects、e2e 和 live 配置中使用非隔离运行器。 - - root UI 通道保留其 `jsdom` 设置和优化器，但也运行在 - 共享的非隔离运行器上。 - - 每个 `pnpm test` 分片都继承了相同的 `threads` + `isolate: false` - 默认值，来源于共享的 Vitest 配置。 - - `scripts/run-vitest.mjs` 默认会为 Vitest 子 Node - 进程添加 `--no-maglev`，以减少大型本地运行期间的 V8 编译抖动。 - 设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1` 可与默认 V8 - 行为进行对比。 + - 共享的 Vitest 配置固定使用 `isolate: false`，并在根项目、e2e 和实时配置中使用非隔离运行器。 + - 根 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` 会显示某个差异触发了哪些架构通道。 - - pre-commit hook 仅执行格式化。它会重新暂存已格式化文件， - 不会运行 lint、typecheck 或测试。 - - 在交接或推送前，当你 - 需要智能本地门禁时，请显式运行 `pnpm check:changed`。公共插件 SDK 和 plugin-contract - 变更会包含一次 extension 验证通道。 - - `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`。 + - `pnpm changed:lanes` 会显示某个差异会触发哪些架构通道。 + - pre-commit 钩子只负责格式化。它会重新暂存已格式化的文件，但不会运行 lint、类型检查或测试。 + - 当你需要智能本地门禁时，在交接或推送前显式运行 `pnpm check:changed`。公开的 插件 SDK 和插件契约变更会包含一次扩展验证通道。 + - `pnpm test:changed` 会在变更路径可以清晰映射到更小测试套件时，通过有作用域的通道进行路由。 + - `pnpm test:max` 和 `pnpm test:changed:max` 保持相同的路由行为，只是提高了工作进程上限。 + - 本地工作进程自动扩缩容刻意保持保守；当宿主机负载平均值已经较高时会自动回退，因此默认情况下多个并发 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` 与该已提交差异对应的原生 root-project 路径进行比较，并打印墙钟时间以及 macOS 最大 RSS。 - - `pnpm test:perf:changed:bench -- --worktree` 会通过 - `scripts/test-projects.mjs` 和 root Vitest 配置， - 对当前脏工作树执行基准测试，并按变更文件列表进行路由。 - - `pnpm test:perf:profile:main` 会为 - Vitest/Vite 启动和 transform 开销写入主线程 CPU profile。 - - `pnpm test:perf:profile:runner` 会在禁用文件级并行的情况下， - 为 unit 套件写入运行器 CPU + heap profile。 + - `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` 与该已提交差异对应的原生根项目路径进行比较，并打印墙钟时间和 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` 会在禁用文件并行的情况下，为单元测试套件写出运行器的 CPU + 堆 profile。 -### 稳定性（Gateway 网关） +### 稳定性（gateway） - 命令：`pnpm test:stability:gateway` -- 配置：`vitest.gateway.config.ts`，强制使用一个 worker +- 配置：`vitest.gateway.config.ts`，强制使用单个工作进程 - 范围： - 启动一个默认启用诊断功能的真实 loopback Gateway 网关 - - 通过诊断事件路径驱动合成的 Gateway 网关消息、内存和大负载抖动 + - 通过诊断事件路径驱动合成的 gateway 消息、memory 和大负载抖动 - 通过 Gateway 网关 WS RPC 查询 `diagnostics.stability` - - 覆盖诊断稳定性 bundle 持久化辅助工具 - - 断言记录器保持有界、合成 RSS 采样保持在压力预算之下，并且每个会话的队列深度会回落到零 + - 覆盖诊断稳定性包持久化辅助函数 + - 断言记录器保持有界、合成 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/` 下的内置插件 E2E 测试 +- 文件：`src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`，以及 `extensions/` 下的内置插件 E2E 测试 - 运行时默认值： - 使用 Vitest `threads`，并设置 `isolate: false`，与仓库其余部分保持一致。 - - 使用自适应 worker（CI：最多 2 个，本地：默认 1 个）。 + - 使用自适应工作进程（CI：最多 2 个，本地默认 1 个）。 - 默认以静默模式运行，以减少控制台 I/O 开销。 -- 有用的覆盖项： - - `OPENCLAW_E2E_WORKERS=` 用于强制指定 worker 数量（上限 16）。 +- 常用覆盖项： + - `OPENCLAW_E2E_WORKERS=` 用于强制指定工作进程数（上限为 16）。 - `OPENCLAW_E2E_VERBOSE=1` 用于重新启用详细控制台输出。 - 范围： - - 多实例 Gateway 网关端到端行为 - - WebSocket/HTTP 表面、节点配对以及更重的网络行为 + - 多实例 gateway 端到端行为 + - WebSocket / HTTP 表面、节点配对以及更重的网络交互 - 预期： - - 在 CI 中运行（当流水线启用时） + - 会在 CI 中运行（当流水线启用时） - 不需要真实密钥 - - 比 unit 测试有更多活动部件（可能更慢） + - 比单元测试涉及更多活动部件（可能更慢） ### E2E：OpenShell 后端冒烟 - 命令：`pnpm test:e2e:openshell` - 文件：`extensions/openshell/src/backend.e2e.test.ts` - 范围： - - 通过 Docker 在主机上启动一个隔离的 OpenShell Gateway 网关 + - 通过 Docker 在宿主机上启动一个隔离的 OpenShell gateway - 从临时本地 Dockerfile 创建一个沙箱 - - 通过真实的 `sandbox ssh-config` + SSH exec 对 OpenClaw 的 OpenShell 后端进行验证 - - 通过沙箱 fs bridge 验证远端规范文件系统行为 + - 通过真实的 `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 二进制文件或包装脚本 + - 仅在选择启用时运行；不属于默认的 `pnpm test:e2e` 执行 + - 需要本地 `openshell` CLI 和可用的 Docker 守护进程 + - 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，随后销毁测试 gateway 和沙箱 +- 常用覆盖项： + - `OPENCLAW_E2E_OPENSHELL=1` 用于在手动运行更广泛的 e2e 套件时启用该测试 + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` 用于指向非默认的 CLI 二进制或包装脚本 -### live（真实提供商 + 真实模型） +### 实时（真实提供商 + 真实模型） - 命令：`pnpm test:live` - 配置：`vitest.live.config.ts` -- 文件：`src/**/*.live.test.ts`、`test/**/*.live.test.ts`，以及位于 `extensions/` 下的内置插件 live 测试 -- 默认值：由 `pnpm test:live` **启用**（设置 `OPENCLAW_LIVE_TEST=1`） +- 文件：`src/**/*.live.test.ts`、`test/**/*.live.test.ts`，以及 `extensions/` 下的内置插件实时测试 +- 默认：由 `pnpm test:live` **启用**（设置 `OPENCLAW_LIVE_TEST=1`） - 范围： - - “这个提供商 / 模型在今天配合真实凭证时是否真的可用？” - - 捕捉提供商格式变化、tool-calling 怪癖、auth 问题以及速率限制行为 + - “这个提供商 / 模型 _今天_ 是否真的能在真实凭证下工作？” + - 捕捉提供商格式变化、工具调用怪癖、认证问题和限流行为 - 预期： - - 按设计并非 CI 稳定（真实网络、真实提供商策略、配额、故障） - - 会花钱 / 消耗速率限制 - - 优先运行缩小范围后的子集，而不是“全部” -- live 运行会读取 `~/.profile`，以获取缺失的 API 密钥。 -- 默认情况下，live 运行仍会隔离 `HOME`，并将配置 / auth 材料复制到一个临时测试 home 中，这样 unit fixture 就无法修改你真实的 `~/.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 的覆盖；测试会在遇到速率限制响应时重试。 + - 按设计不保证在 CI 中稳定（真实网络、真实提供商策略、配额、故障） + - 会花钱 / 消耗限流额度 + - 优先运行缩小范围的子集，而不是“全部都跑” +- 实时运行会读取 `~/.profile`，以获取缺失的 API 密钥。 +- 默认情况下，实时运行仍会隔离 `HOME`，并将配置 / 认证材料复制到临时测试 home 中，这样单元测试夹具就不会修改你的真实 `~/.openclaw`。 +- 仅当你明确需要实时测试使用真实 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 套件现在会将进度行输出到 stderr，因此即使 Vitest 控制台捕获处于安静模式，长时间的提供商调用也能显式显示仍在活动。 - - `vitest.live.config.ts` 会禁用 Vitest 控制台拦截，因此在 live 运行期间，提供商 / Gateway 网关进度行会立即流式输出。 + - 实时套件现在会将进度行输出到 stderr，因此即使 Vitest 控制台捕获较安静，长时间的提供商调用也能明确显示仍在活动。 + - `vitest.live.config.ts` 禁用了 Vitest 控制台拦截，因此在实时运行期间，提供商 / gateway 的进度行会立即流式输出。 - 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整直接模型心跳。 - - 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 Gateway 网关 / 探测心跳。 + - 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 gateway / 探测心跳。 -## 我应该运行哪个测试套件？ +## 我应该运行哪个套件？ -使用这个决策表： +使用这张决策表： -- 编辑逻辑 / 测试：运行 `pnpm test`（如果你改动很多，也运行 `pnpm test:coverage`） -- 涉及 Gateway 网关网络 / WS 协议 / 配对：额外运行 `pnpm test:e2e` -- 调试“我的 bot 挂了” / 提供商特定故障 / tool calling：运行一个缩小范围的 `pnpm test:live` +- 修改逻辑 / 测试：运行 `pnpm test`（如果你改动很多，也运行 `pnpm test:coverage`） +- 涉及 gateway 网络 / WS 协议 / 配对：额外运行 `pnpm test:e2e` +- 调试“我的 bot 挂了” / 提供商专属故障 / 工具调用：运行缩小范围的 `pnpm test:live` -## live（涉及网络）测试 +## 实时（会触网）测试 -关于 live 模型矩阵、CLI 后端冒烟、ACP 冒烟、Codex app-server -harness，以及所有媒体提供商 live 测试（Deepgram、BytePlus（国际版）、ComfyUI、image、 -music、video、media harness）—— 以及 live 运行的凭证处理 —— 请参见 -[测试 — live 套件](/zh-CN/help/testing-live)。 +关于实时模型矩阵、CLI 后端冒烟、ACP 冒烟、Codex app-server +harness，以及所有媒体提供商实时测试（Deepgram、BytePlus（国际版）、ComfyUI、图像、音乐、视频、媒体 harness）——以及实时运行的凭证处理——请参见 +[测试 — 实时套件](/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` 和 `test:docker:live-gateway` 只会在仓库 Docker 镜像中运行与其匹配的 profile-key 实时文件（`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 实时运行器默认使用较小的冒烟上限，这样完整的 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。 -- 容器冒烟运行器：`test:docker:openwebui`、`test:docker:onboard`、`test:docker:npm-onboard-channel-agent`、`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` 会启动一个或多个真实容器，并验证更高层级的集成路径。 + `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` 和 + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。当你明确想进行更大的穷尽扫描时，可覆盖这些环境变量。 +- `test:docker:all` 会先通过 `test:docker:live-build` 构建一次实时 Docker 镜像，然后在后续 Docker 实时通道中复用它。它还会通过 `test:docker:e2e-build` 构建一个共享的 `scripts/e2e/Dockerfile` 镜像，并将其复用于运行已构建应用的 E2E 容器冒烟运行器。这个聚合任务使用带权重的本地调度器：`OPENCLAW_DOCKER_ALL_PARALLELISM` 控制进程槽位，而资源上限会防止重型实时、npm 安装和多服务通道同时全部启动。默认值为 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 auth home（如果运行未缩小范围，则挂载所有受支持的 auth home），然后在运行前将它们复制到容器 home 中，这样外部 CLI OAuth 就能刷新 token，而不会修改主机 auth 存储： +实时模型 Docker 运行器还只会绑定挂载所需的 CLI 认证 home（如果运行未缩小范围，则挂载所有受支持的 home），然后在运行前将它们复制到容器 home 中，这样外部 CLI OAuth 就可以刷新令牌，而不会修改宿主的认证存储： - 直接模型：`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`） - 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 网关 + 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`） -- 新手引导向导（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 会修复已激活插件的运行时依赖，并运行一次模拟的 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` 会返回内置 image 提供商，而不是挂起。使用 `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` 覆盖时，请在本地运行该脚本且不要设置此环境变量。 -- Gateway 网关网络（两个容器，WS auth + 健康检查）：`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 网关运行一个模拟 OpenAI 服务器，验证 `web_search` 会将 `reasoning.effort` 从 `minimal` 提升到 `low`，然后强制 provider schema 拒绝，并检查原始细节是否出现在 Gateway 网关日志中。 -- MCP 渠道路由桥（预置 Gateway 网关 + stdio bridge + 原始 Claude 通知帧冒烟）：`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`） +- Open WebUI 实时冒烟：`pnpm test:docker:openwebui`（脚本：`scripts/e2e/openwebui-docker.sh`） +- 新手引导向导（TTY、完整脚手架）：`pnpm test:docker:onboard`（脚本：`scripts/e2e/onboard-docker.sh`） +- Npm tarball 新手引导 / 渠道 / 智能体冒烟：`pnpm test:docker:npm-onboard-channel-agent` 会在 Docker 中全局安装打包后的 OpenClaw tarball，通过环境变量引用式新手引导配置 OpenAI，并默认配置 Telegram，验证 doctor 会修复已激活插件的运行时依赖，并运行一次被 mock 的 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 镜像。 +- Gateway 网关网络（两个容器、WS 认证 + 健康检查）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`） +- OpenAI Responses `web_search` 最小推理回归：`pnpm test:docker:openai-web-search-minimal`（脚本：`scripts/e2e/openai-web-search-minimal-docker.sh`）会让一个被 mock 的 OpenAI 服务器通过 Gateway 网关运行，验证 `web_search` 会将 `reasoning.effort` 从 `minimal` 提升到 `low`，然后强制提供商 schema 拒绝，并检查原始细节是否出现在 Gateway 网关日志中。 +- MCP 渠道桥接（带种子数据的 Gateway 网关 + stdio bridge + 原始 Claude 通知帧冒烟）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`） +- Pi bundle MCP 工具（真实 stdio MCP 服务器 + 嵌入式 Pi 配置文件 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`） - 插件（安装冒烟 + `/plugin` 别名 + Claude bundle 重启语义）：`pnpm test:docker:plugins`（脚本：`scripts/e2e/plugins-docker.sh`） -- 插件更新未变化冒烟：`pnpm test:docker:plugin-update`（脚本：`scripts/e2e/plugin-update-unchanged-docker.sh`） +- 插件更新无变更冒烟：`pnpm test:docker:plugin-update`（脚本：`scripts/e2e/plugin-update-unchanged-docker.sh`） - 配置热重载元数据冒烟：`pnpm test:docker:config-reload`（脚本：`scripts/e2e/config-reload-source-docker.sh`） -- 内置插件运行时依赖：`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` 缩小渠道 matrix，或使用 `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx` 缩小更新场景。该通道还会验证 `channels..enabled=false` 和 `plugins.entries..enabled=false` 会抑制 doctor/运行时依赖修复。 -- 在迭代时缩小内置插件运行时依赖范围，可以禁用无关场景，例如： +- 内置插件运行时依赖：`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 / 运行时依赖修复。 +- 在迭代时，可通过禁用无关场景来缩小内置插件运行时依赖测试范围，例如： `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 镜像： @@ -601,175 +492,142 @@ 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，因为它们验证的是 package/install 行为，而不是共享的 built-app 运行时。 +诸如 `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` 这样的套件专属镜像覆盖项在设置后仍然优先生效。当 `OPENCLAW_SKIP_DOCKER_BUILD=1` 指向远端共享镜像时，如果本地尚不存在，脚本会先拉取该镜像。二维码和安装器 Docker 测试保留各自的 Dockerfile，因为它们验证的是包 / 安装行为，而不是共享的 built-app 运行时。 -live 模型 Docker 运行器还会以只读方式 bind-mount 当前检出内容， -并将其暂存到容器内的临时工作目录中。这样既能保持运行时 -镜像精简，又能让 Vitest 针对你本地的精确 source/config 运行。 -暂存步骤会跳过大型仅本地缓存和应用构建输出，例如 -`.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 网关容器， -针对该 Gateway 网关启动一个固定版本的 Open WebUI 容器，通过 -Open WebUI 完成登录，验证 `/api/models` 暴露了 `openclaw/default`，然后通过 -Open WebUI 的 `/api/chat/completions` 代理发送一个真实聊天请求。 -首次运行可能会明显更慢，因为 Docker 可能需要拉取 -Open WebUI 镜像，并且 Open WebUI 可能需要完成自身的冷启动设置。 -该通道要求提供一个可用的 live 模型密钥，而 `OPENCLAW_PROFILE_FILE` -（默认 `~/.profile`）是在 Docker 化运行中提供该密钥的主要方式。 -成功运行会打印一小段 JSON 负载，例如 `{ "ok": true, "model": +实时模型 Docker 运行器还会以只读方式绑定挂载当前检出，并将其暂存到容器内的临时工作目录中。这样既能保持运行时镜像精简，又仍然可以针对你本地的精确源码 / 配置运行 Vitest。暂存步骤会跳过大型仅本地缓存和应用构建输出，例如 `.pnpm-store`、`.worktrees`、`__openclaw_vitest__`，以及应用本地 `.build` 或 Gradle 输出目录，因此 Docker 实时运行不会花上数分钟复制与机器相关的工件。 +它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，这样 gateway 实时探测就不会在容器中启动真实的 Telegram / Discord / 等渠道工作进程。 +`test:docker:live-models` 仍然运行 `pnpm test:live`，因此当你需要缩小或排除该 Docker 通道中的 gateway 实时覆盖范围时，也应一并传入 `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 也可能需要完成自身的冷启动设置。 +该通道需要可用的实时模型密钥，而 `OPENCLAW_PROFILE_FILE`（默认 `~/.profile`）是在 Docker 化运行中提供该密钥的主要方式。 +成功运行会打印一个小型 JSON payload，例如 `{ "ok": true, "model": "openclaw/default", ... }`。 -`test:docker:mcp-channels` 是有意设计为确定性的，不需要 -真实的 Telegram、Discord 或 iMessage 账户。它会启动一个预置的 Gateway 网关 -容器，再启动第二个容器来生成 `openclaw mcp serve`，然后 -验证路由后的会话发现、转录读取、附件元数据、 -live 事件队列行为、出站发送路由，以及 Claude 风格的渠道 + -权限通知，这些都通过真实的 stdio MCP bridge 完成。通知检查 -会直接检查原始 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 子进程会在每次运行后退出。 +`test:docker:mcp-channels` 被刻意设计为确定性测试，不需要真实的 Telegram、Discord 或 iMessage 账号。它会启动一个带种子数据的 Gateway 容器，再启动第二个容器并生成 `openclaw mcp serve`，随后通过真实的 stdio MCP bridge 验证路由后的会话发现、转录读取、附件元数据、实时事件队列行为、出站发送路由，以及 Claude 风格的渠道 + 权限通知。通知检查会直接检查原始 stdio MCP 帧，因此该冒烟测试验证的是 bridge 实际发出的内容，而不只是某个特定客户端 SDK 恰好暴露了什么。 +`test:docker:pi-bundle-mcp-tools` 是确定性测试，不需要实时模型密钥。它会构建仓库 Docker 镜像，在容器中启动一个真实的 stdio MCP 探测服务器，通过嵌入式 Pi bundle MCP 运行时实例化该服务器，执行工具，然后验证 `coding` 和 `messaging` 会保留 `bundle-mcp` 工具，而 `minimal` 和 `tools.deny: ["bundle-mcp"]` 会将其过滤掉。 +`test:docker:cron-mcp-cleanup` 是确定性测试，不需要实时模型密钥。它会启动一个带种子数据的 Gateway 网关以及一个真实的 stdio MCP 探测服务器，运行一次隔离的 cron 轮次和一次 `/subagents spawn` 单次子智能体轮次，然后验证 MCP 子进程会在每次运行后退出。 手动 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` 读取的环境变量，使用临时配置 / 工作区目录，且不挂载外部 CLI auth -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（默认：`~/.cache/openclaw/docker-cli-tools`）挂载到 `/home/node/.npm-global`，用于在 Docker 内缓存 CLI 安装 -- `$HOME` 下的外部 CLI auth 目录 / 文件会以只读方式挂载到 `/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_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_REQUIRE_PROFILE_KEYS=1` 用于确保凭证来自 profile 存储（而非环境变量） -- `OPENCLAW_OPENWEBUI_MODEL=...` 用于选择 Gateway 网关向 Open WebUI 冒烟测试暴露的模型 -- `OPENCLAW_OPENWEBUI_PROMPT=...` 用于覆盖 Open WebUI 冒烟测试使用的 nonce 检查提示词 +- `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=...` 用于选择 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 安全） -这些是在没有真实提供商情况下的“真实流水线”回归： +这些是“不依赖真实提供商”的“真实流水线”回归： -- Gateway 网关 tool calling（模拟 OpenAI，真实 gateway + 智能体循环）：`src/gateway/gateway.test.ts`（用例：“runs a mock OpenAI tool call end-to-end via gateway agent loop”） -- Gateway 网关向导（WS `wizard.start`/`wizard.next`，强制写入配置 + auth）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”） +- 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`，会写入配置 + 强制认证）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”） ## 智能体可靠性评估（Skills） -我们已经有一些对 CI 安全的测试，其行为类似“智能体可靠性评估”： +我们已经有少量对 CI 安全的测试，其行为类似于“智能体可靠性评估”： -- 通过真实 Gateway 网关 + 智能体循环进行模拟 tool-calling（`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 时，智能体是否会选择正确的 Skills（或避开无关 Skills）？ +- **遵从性：** 智能体在使用前是否会读取 `SKILL.md`，并遵循必需的步骤 / 参数？ +- **工作流契约：** 断言工具顺序、会话历史延续和沙箱边界的多轮场景。 -未来的评估应优先保持确定性： +未来的评估应首先保持确定性： -- 一个使用模拟提供商的场景运行器，用于断言工具调用 + 顺序、skill 文件读取以及会话接线。 -- 一小组聚焦于 skill 的场景（使用 vs 避免、门控、提示词注入）。 -- 只有在对 CI 安全的套件就位后，才添加可选的 live 评估（按需启用、由环境变量门控）。 +- 使用 mock 提供商的场景运行器，用于断言工具调用 + 顺序、skill 文件读取和会话接线。 +- 一小组面向 Skills 的场景（使用 vs 避免、门禁、提示注入）。 +- 只有在对 CI 安全的套件就位之后，才添加可选的实时评估（选择启用、受环境变量门禁控制）。 ## 契约测试（插件和渠道形状） -契约测试用于验证每个已注册插件和渠道都符合其 -接口契约。它们会遍历所有已发现插件，并运行一组 -形状和行为断言。默认的 `pnpm test` unit 通道会有意 -跳过这些共享接缝和冒烟文件；当你修改共享渠道或 provider 表面时， -请显式运行契约命令。 +契约测试用于验证每个已注册插件和渠道都符合其接口契约。它们会遍历所有已发现的插件，并运行一组关于形状和行为的断言。默认的 `pnpm test` 单元通道会刻意跳过这些共享接缝和冒烟文件；当你修改共享渠道或提供商表面时，请显式运行契约命令。 ### 命令 - 所有契约：`pnpm test:contracts` - 仅渠道契约：`pnpm test:contracts:channels` -- 仅 provider 契约：`pnpm test:contracts:plugins` +- 仅提供商契约：`pnpm test:contracts:plugins` ### 渠道契约 位于 `src/channels/plugins/contracts/*.contract.test.ts`： -- **plugin** - 基础插件形状（id、name、capabilities） +- **plugin** - 基本插件形状（id、name、capabilities） - **setup** - 设置向导契约 - **session-binding** - 会话绑定行为 -- **outbound-payload** - 消息负载结构 +- **outbound-payload** - 消息 payload 结构 - **inbound** - 入站消息处理 -- **actions** - 渠道操作处理器 +- **actions** - 渠道动作处理器 - **threading** - 线程 ID 处理 -- **directory** - Directory/roster API +- **directory** - 目录 / roster API - **group-policy** - 群组策略执行 -### Provider 状态契约 +### 提供商状态契约 位于 `src/plugins/contracts/*.contract.test.ts`。 - **status** - 渠道状态探测 - **registry** - 插件注册表形状 -### Provider 契约 +### 提供商契约 位于 `src/plugins/contracts/*.contract.test.ts`： - **auth** - 认证流程契约 -- **auth-choice** - 认证选项 / 选择 +- **auth-choice** - 认证选择 / 选取 - **catalog** - 模型目录 API - **discovery** - 插件发现 - **loader** - 插件加载 -- **runtime** - provider 运行时 +- **runtime** - 提供商运行时 - **shape** - 插件形状 / 接口 - **wizard** - 设置向导 ### 何时运行 -- 在更改插件 SDK 导出或子路径之后 -- 在添加或修改渠道或 provider 插件之后 -- 在重构插件注册或发现逻辑之后 +- 修改 plugin-sdk 导出或子路径之后 +- 添加或修改渠道或提供商插件之后 +- 重构插件注册或发现逻辑之后 契约测试会在 CI 中运行，且不需要真实 API 密钥。 ## 添加回归测试（指南） -当你修复一个在 live 中发现的 provider/model 问题时： +当你修复了在实时环境中发现的提供商 / 模型问题时： -- 如果可能，添加一个对 CI 安全的回归测试（模拟 / stub provider，或捕获精确的请求形状转换） -- 如果它本质上只能在 live 中复现（速率限制、认证策略），就让 live 测试保持窄范围，并通过环境变量按需启用 -- 优先定位到能捕捉该缺陷的最小层级： - - provider 请求转换 / 重放缺陷 → 直接模型测试 - - Gateway 网关会话 / 历史 / 工具管线缺陷 → Gateway 网关 live 冒烟或对 CI 安全的 Gateway 网关 mock 测试 -- SecretRef 遍历保护栏： - - `src/secrets/exec-secret-ref-id-parity.test.ts` 会从注册表元数据（`listSecretTargetRegistryEntries()`）中为每个 SecretRef 类派生一个采样目标，然后断言会拒绝 traversal-segment exec id。 - - 如果你在 `src/secrets/target-registry-data.ts` 中添加新的 `includeInPlan` SecretRef 目标族，请更新该测试中的 `classifyTargetClass`。该测试会在遇到未分类目标 id 时有意失败，以确保新类别不会被静默跳过。 +- 如果可能，添加一个对 CI 安全的回归测试（mock / stub 提供商，或捕获精确的请求形状转换） +- 如果它本质上只能在实时环境中复现（限流、认证策略），那就让实时测试保持窄范围，并通过环境变量选择启用 +- 优先定位到能捕获该缺陷的最小层级： + - 提供商请求转换 / 回放缺陷 → 直接模型测试 + - gateway 会话 / 历史 / 工具流水线缺陷 → gateway 实时冒烟或对 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 时故意失败，这样新类别就无法被静默跳过。 ## 相关内容 -- [测试 live](/zh-CN/help/testing-live) +- [Testing live](/zh-CN/help/testing-live) - [CI](/zh-CN/ci) diff --git a/docs/zh-CN/plugins/codex-harness.md b/docs/zh-CN/plugins/codex-harness.md index 2eb96faa3..5dd6265e8 100644 --- a/docs/zh-CN/plugins/codex-harness.md +++ b/docs/zh-CN/plugins/codex-harness.md @@ -2,28 +2,25 @@ read_when: - 你想使用内置的 Codex app-server harness - 你需要 Codex harness 配置示例 - - 你希望仅使用 Codex 的部署在失败时直接报错，而不是回退到 PI -summary: 通过内置的 Codex app-server harness 运行 OpenClaw 嵌入式智能体轮次 + - 你希望仅使用 Codex 的部署在无法使用时直接失败，而不是回退到 PI +summary: 通过内置的 Codex app-server harness 运行 OpenClaw 嵌入式智能体回合 title: Codex harness x-i18n: - generated_at: "2026-04-25T00:42:00Z" + generated_at: "2026-04-25T01:51:48Z" model: gpt-5.4 provider: openai - source_hash: 366400f3d4018d6149e80b0b87b49ad7332c6164e8b3b70a0c4359068ee2685f + source_hash: bf0292de4a3e189bb96f02dfeaa42df6e4b1b24cf335cbb83f8821d33585cb5b source_path: plugins/codex-harness.md workflow: 15 --- -内置的 `codex` 插件可让 OpenClaw 通过 -Codex app-server 运行嵌入式智能体轮次，而不是使用内置的 PI harness。 +内置的 `codex` 插件让 OpenClaw 可以通过 Codex app-server 而不是内置的 PI harness 来运行嵌入式智能体回合。 -当你希望由 Codex 接管底层智能体会话时，请使用此方式：模型 -发现、原生线程恢复、原生压缩，以及 app-server 执行。 -OpenClaw 仍负责聊天渠道、会话文件、模型选择、工具、 -审批、媒体投递，以及可见的转录镜像。 +当你希望由 Codex 接管底层智能体会话时，请使用此功能：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体传递，以及可见的转录镜像。 -原生 Codex 轮次将 OpenClaw 插件钩子保留为公共兼容层。 -这些是进程内的 OpenClaw 钩子，而不是 Codex `hooks.json` 命令钩子： +如果你正在了解整体结构，请先从 [Agent Runtimes](/zh-CN/concepts/agent-runtimes) 开始。简要来说：`openai/gpt-5.5` 是模型引用，`codex` 是运行时，而 Telegram、Discord、Slack 或其他渠道仍然是通信界面。 + +原生 Codex 回合会将 OpenClaw 插件钩子保留为公开兼容层。这些是进程内的 OpenClaw 钩子，不是 Codex `hooks.json` 命令钩子： - `before_prompt_build` - `before_compaction`, `after_compaction` @@ -32,59 +29,33 @@ OpenClaw 仍负责聊天渠道、会话文件、模型选择、工具、 - 用于镜像转录记录的 `before_message_write` - `agent_end` -插件还可以注册与运行时无关的工具结果中间件，在 OpenClaw 执行工具之后、将结果返回给 Codex 之前，重写 OpenClaw 动态工具结果。这与公共 -`tool_result_persist` 插件钩子是分开的；后者会转换由 OpenClaw 管理的转录 -工具结果写入。 +插件还可以注册与运行时无关的工具结果中间件，在 OpenClaw 执行工具之后、结果返回给 Codex 之前，重写 OpenClaw 动态工具结果。这与公开的 `tool_result_persist` 插件钩子不同，后者用于转换由 OpenClaw 管理的转录工具结果写入。 -该 harness 默认关闭。新配置应将 OpenAI 模型引用 -保持为规范形式 `openai/gpt-*`，并在需要原生 app-server 执行时显式强制指定 -`embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。旧版 `codex/*` 模型引用仍会出于兼容性自动选择 -该 harness，但由运行时支持的旧版提供商前缀不会显示为普通模型 / 提供商选项。 +该 harness 默认关闭。新配置应保持 OpenAI 模型引用使用规范形式 `openai/gpt-*`，并在需要原生 app-server 执行时显式强制设置 `embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。旧版 `codex/*` 模型引用仍会为了兼容性自动选择该 harness，但由运行时支持的旧版 provider 前缀不会显示为常规模型 / 提供商选项。 ## 选择正确的模型前缀 -OpenAI 系列路由对前缀很敏感。当你希望通过 PI 使用 -Codex OAuth 时，请使用 `openai-codex/*`；当你希望直接访问 OpenAI API，或 -当你强制使用原生 Codex app-server harness 时，请使用 `openai/*`： +OpenAI 系列路由对前缀很敏感。当你想通过 PI 使用 Codex OAuth 时，请使用 `openai-codex/*`；当你想直接使用 OpenAI API，或你正在强制使用原生 Codex app-server harness 时，请使用 `openai/*`： -| 模型引用 | 运行时路径 | 使用场景 | +| Model ref | Runtime path | Use when | | ----------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | -| `openai/gpt-5.4` | 通过 OpenClaw / PI 流程的 OpenAI 提供商 | 你希望使用当前通过 `OPENAI_API_KEY` 访问的直接 OpenAI Platform API。 | -| `openai-codex/gpt-5.5` | 通过 OpenClaw / PI 的 OpenAI Codex OAuth | 你希望通过默认 PI 运行器使用 ChatGPT / Codex 订阅认证。 | -| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex app-server harness | 你希望嵌入式智能体轮次使用原生 Codex app-server 执行。 | +| `openai/gpt-5.4` | 通过 OpenClaw / PI 管道的 OpenAI provider | 你希望使用带有 `OPENAI_API_KEY` 的当前直接 OpenAI Platform API 访问。 | +| `openai-codex/gpt-5.5` | 通过 OpenClaw / PI 的 OpenAI Codex OAuth | 你希望使用默认 PI 运行器的 ChatGPT / Codex 订阅认证。 | +| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex app-server harness | 你希望为嵌入式智能体回合使用原生 Codex app-server 执行。 | -GPT-5.5 目前在 OpenClaw 中仅支持订阅 / OAuth。请使用 -`openai-codex/gpt-5.5` 用于 PI OAuth，或使用带 Codex -app-server harness 的 `openai/gpt-5.5`。 -一旦 OpenAI 在公共 API 上启用 GPT-5.5，即支持对 `openai/gpt-5.5` 的直接 API key 访问。 +GPT-5.5 目前在 OpenClaw 中仅支持订阅 / OAuth。PI OAuth 请使用 `openai-codex/gpt-5.5`，或者将 `openai/gpt-5.5` 与 Codex app-server harness 搭配使用。一旦 OpenAI 在公共 API 上启用 GPT-5.5，就会支持通过 API key 直接访问 `openai/gpt-5.5`。 -旧版 `codex/gpt-*` 引用仍然作为兼容别名被接受。Doctor -兼容性迁移会将旧版主运行时引用重写为规范模型引用，并单独记录运行时策略，而仅作为回退的旧版引用则保持不变，因为运行时是为整个智能体容器配置的。 -新的 PI Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生 -app-server harness 配置应使用 `openai/gpt-*`，并搭配 -`embeddedHarness.runtime: "codex"`。 +旧版 `codex/gpt-*` 引用仍然作为兼容别名被接受。Doctor 兼容性迁移会将旧版主运行时引用重写为规范模型引用，并单独记录运行时策略；而仅作为回退使用的旧版引用会保持不变，因为运行时是为整个智能体容器配置的。新的 PI Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生 app-server harness 配置应使用 `openai/gpt-*`，再加上 `embeddedHarness.runtime: "codex"`。 -`agents.defaults.imageModel` 也遵循相同的前缀划分。请使用 -`openai-codex/gpt-*`，当图像理解应通过 OpenAI -Codex OAuth 提供商路径运行时。请使用 `codex/gpt-*`，当图像理解应通过 -受限的 Codex app-server 轮次运行时。Codex app-server 模型必须 -声明支持图像输入；纯文本 Codex 模型会在媒体轮次开始前失败。 +`agents.defaults.imageModel` 也遵循相同的前缀划分。当图像理解应通过 OpenAI Codex OAuth provider 路径运行时，请使用 `openai-codex/gpt-*`。当图像理解应通过受限的 Codex app-server 回合运行时，请使用 `codex/gpt-*`。Codex app-server 模型必须声明支持图像输入；仅文本的 Codex 模型会在媒体回合开始前失败。 -使用 `/status` 确认当前会话的实际 harness。如果选择结果出乎意料，请为 `agents/harness` 子系统启用调试日志，并检查 Gateway 网关的结构化 `agent harness selected` 记录。它 -包含选中的 harness id、选择原因、运行时 / 回退策略，以及在 -`auto` 模式下每个插件候选项的支持结果。 +使用 `/status` 确认当前会话的实际 harness。如果选择结果出乎意料，请为 `agents/harness` 子系统启用调试日志，并检查 Gateway 网关中的结构化 `agent harness selected` 记录。它包含所选 harness id、选择原因、运行时 / 回退策略，以及在 `auto` 模式下每个插件候选项的支持结果。 -Harness 选择不是实时会话控制。当嵌入式轮次运行时， -OpenClaw 会在该会话上记录所选 harness id，并在同一会话 id 的后续轮次中继续使用它。若你希望未来的会话使用其他 harness，请更改 `embeddedHarness` 配置或 -`OPENCLAW_AGENT_RUNTIME`；在将现有会话从 PI 切换到 Codex 之前，请使用 `/new` 或 `/reset` 启动新会话。 -这样可以避免通过两套不兼容的原生会话系统重放同一份转录。 +Harness 选择不是实时会话控制。当嵌入式回合运行时，OpenClaw 会在该会话上记录所选 harness id，并在同一会话 id 的后续回合中继续使用它。当你希望未来会话改用其他 harness 时，请修改 `embeddedHarness` 配置或 `OPENCLAW_AGENT_RUNTIME`；在现有对话于 PI 和 Codex 之间切换之前，请使用 `/new` 或 `/reset` 启动一个全新会话。这样可以避免同一份转录被两个不兼容的原生会话系统重复回放。 -在 harness 固定机制引入之前创建的旧会话，一旦具有转录历史，就会被视为固定到 PI。更改配置后，如需让该会话切换到 -Codex，请使用 `/new` 或 `/reset`。 +在引入 harness 固定之前创建的旧会话，一旦已有转录历史，就会被视为固定到 PI。更改配置后，请使用 `/new` 或 `/reset`，以便让该对话切换到 Codex。 -`/status` 会显示实际的模型运行时。默认 PI harness 显示为 -`Runtime: OpenClaw Pi Default`，而 Codex app-server harness 显示为 -`Runtime: OpenAI Codex`。 +`/status` 会显示实际的模型运行时。默认的 PI harness 显示为 `Runtime: OpenClaw Pi Default`，而 Codex app-server harness 显示为 `Runtime: OpenAI Codex`。 ## 要求 @@ -92,11 +63,9 @@ Codex，请使用 `/new` 或 `/reset`。 - Codex app-server `0.118.0` 或更高版本。 - app-server 进程可用的 Codex 认证。 -该插件会阻止较旧或无版本信息的 app-server 握手。 -这样可以确保 OpenClaw 使用它已测试过的协议接口。 +该插件会阻止旧版本或未标注版本的 app-server 握手。这可确保 OpenClaw 始终使用它已测试过的协议接口。 -对于 live 和 Docker 冒烟测试，认证通常来自 `OPENAI_API_KEY`，外加可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 -`~/.codex/config.toml`。请使用与你本地 Codex app-server 相同的认证材料。 +对于 live 和 Docker 冒烟测试，认证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 `~/.codex/config.toml`。请使用与你本地 Codex app-server 相同的认证材料。 ## 最小配置 @@ -116,14 +85,13 @@ Codex，请使用 `/new` 或 `/reset`。 model: "openai/gpt-5.5", embeddedHarness: { runtime: "codex", - fallback: "none", }, }, }, } ``` -如果你的配置使用 `plugins.allow`，也请将 `codex` 包含进去： +如果你的配置使用 `plugins.allow`，也请将 `codex` 包含在其中： ```json5 { @@ -134,18 +102,23 @@ Codex，请使用 `/new` 或 `/reset`。 enabled: true, }, }, - }, + } } ``` -将 `agents.defaults.model` 或某个智能体模型设置为 -`codex/` 的旧版配置仍会自动启用内置 `codex` 插件。新配置应 -优先使用 `openai/`，并显式添加上述 `embeddedHarness` 条目。 +旧版配置如果将 `agents.defaults.model` 或某个智能体模型设为 `codex/`，仍会自动启用内置的 `codex` 插件。新配置应优先使用 `openai/`，再加上上面的显式 `embeddedHarness` 条目。 -## 添加 Codex 而不替换其他模型 +## 将 Codex 与其他模型一同使用 -当你希望旧版 `codex/*` 引用选择 Codex，而其他所有情况都使用 -PI 时，请保留 `runtime: "auto"`。对于新配置，建议在应使用该 harness 的智能体上显式指定 `runtime: "codex"`。 +如果同一个智能体需要在 Codex 和非 Codex provider 模型之间自由切换，请不要全局设置 `runtime: "codex"`。强制运行时会作用于该智能体或会话的每一个嵌入式回合。如果你在该运行时被强制时选择了 Anthropic 模型，OpenClaw 仍会尝试使用 Codex harness，并以封闭失败的方式结束，而不是悄悄通过 PI 路由该回合。 + +请改用以下其中一种方式： + +- 为 Codex 使用一个专用智能体，并设置 `embeddedHarness.runtime: "codex"`。 +- 将默认智能体保持为 `runtime: "auto"`，并为正常的混合 provider 使用保留 PI 回退。 +- 仅为兼容性使用旧版 `codex/*` 引用。新配置应优先使用 `openai/*`，再加上显式的 Codex 运行时策略。 + +例如，下面的配置会让默认智能体保持常规自动选择，并新增一个独立的 Codex 智能体： ```json5 { @@ -158,34 +131,39 @@ PI 时，请保留 `runtime: "auto"`。对于新配置，建议在应使用该 h }, agents: { defaults: { - model: { - primary: "openai/gpt-5.5", - fallbacks: ["openai/gpt-5.5", "anthropic/claude-opus-4-6"], - }, - models: { - "openai/gpt-5.5": { alias: "gpt" }, - "anthropic/claude-opus-4-6": { alias: "opus" }, - }, embeddedHarness: { - runtime: "codex", + runtime: "auto", fallback: "pi", }, }, + list: [ + { + id: "main", + default: true, + model: "anthropic/claude-opus-4-6", + }, + { + id: "codex", + name: "Codex", + model: "openai/gpt-5.5", + embeddedHarness: { + runtime: "codex", + }, + }, + ], }, } ``` -在这种配置下： +使用这种形式时： -- `/model gpt` 或 `/model openai/gpt-5.5` 会在此配置中使用 Codex app-server harness。 -- `/model opus` 使用 Anthropic 提供商路径。 -- 如果选择了非 Codex 模型，PI 仍然是兼容性 harness。 +- 默认的 `main` 智能体使用常规 provider 路径和 PI 兼容性回退。 +- `codex` 智能体使用 Codex app-server harness。 +- 如果 `codex` 智能体缺少 Codex 或不受支持，该回合会失败，而不是悄悄改用 PI。 ## 仅 Codex 部署 -当你需要证明每个嵌入式智能体轮次 -都使用 Codex 时，请强制使用 Codex harness。显式插件运行时默认不会回退到 PI，因此 -`fallback: "none"` 是可选的，但通常有助于作为文档说明： +当你需要证明每一个嵌入式智能体回合都使用 Codex 时，请强制使用 Codex harness。显式插件运行时默认不使用 PI 回退，因此 `fallback: "none"` 是可选的，但通常有助于作为文档说明： ```json5 { @@ -201,20 +179,17 @@ PI 时，请保留 `runtime: "auto"`。对于新配置，建议在应使用该 h } ``` -环境变量覆盖： +环境覆盖： ```bash OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -强制使用 Codex 时，如果 Codex 插件被禁用、 -app-server 版本过旧，或 app-server 无法启动，OpenClaw 会尽早失败。仅当你明确希望在缺失 harness 选择时由 PI 处理时，才设置 -`OPENCLAW_AGENT_HARNESS_FALLBACK=pi`。 +强制使用 Codex 后，如果 Codex 插件被禁用、app-server 版本过旧，或 app-server 无法启动，OpenClaw 会尽早失败。仅当你明确希望 PI 处理缺失的 harness 选择时，才设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=pi`。 -## 按智能体使用 Codex +## 按智能体配置 Codex -你可以让某个智能体仅使用 Codex，而默认智能体保持正常的 -自动选择： +你可以让某一个智能体仅使用 Codex，而默认智能体仍保持正常自动选择： ```json5 { @@ -245,21 +220,17 @@ app-server 版本过旧，或 app-server 无法启动，OpenClaw 会尽早失败 } ``` -使用普通会话命令即可切换智能体和模型。`/new` 会创建一个新的 -OpenClaw 会话，而 Codex harness 会根据需要创建或恢复其 sidecar app-server -线程。`/reset` 会清除该线程的 OpenClaw 会话绑定， -并让下一轮再次根据当前配置解析 harness。 +使用常规会话命令来切换智能体和模型。`/new` 会创建一个新的 OpenClaw 会话，而 Codex harness 会按需创建或恢复其 sidecar app-server 线程。`/reset` 会清除该线程的 OpenClaw 会话绑定，并让下一回合再次根据当前配置解析 harness。 ## 模型发现 -默认情况下，Codex 插件会向 app-server 请求可用模型。如果 -发现失败或超时，它会使用内置的回退目录，包括： +默认情况下，`codex` 插件会向 app-server 查询可用模型。如果发现失败或超时，它会使用内置的回退目录，适用于： - GPT-5.5 - GPT-5.4 mini - GPT-5.2 -你可以通过 `plugins.entries.codex.config.discovery` 调整发现设置： +你可以在 `plugins.entries.codex.config.discovery` 下调整发现配置： ```json5 { @@ -279,8 +250,7 @@ OpenClaw 会话，而 Codex harness 会根据需要创建或恢复其 sidecar ap } ``` -当你希望启动时避免探测 Codex 并固定使用 -回退目录时，请禁用发现： +当你希望启动时避免探测 Codex，并固定使用回退目录时，请禁用发现： ```json5 { @@ -301,19 +271,15 @@ OpenClaw 会话，而 Codex harness 会根据需要创建或恢复其 sidecar ap ## App-server 连接与策略 -默认情况下，插件会通过以下命令在本地启动 Codex： +默认情况下，插件会在本地通过以下命令启动 Codex： ```bash codex app-server --listen stdio:// ``` -默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex harness 会话： -`approvalPolicy: "never"`、`approvalsReviewer: "user"`，以及 -`sandbox: "danger-full-access"`。这是受信任的本地操作员姿态，用于 -自主心跳：Codex 可以使用 shell 和网络工具，而无需停下来等待无人应答的原生审批提示。 +默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex harness 会话：`approvalPolicy: "never"`、`approvalsReviewer: "user"`，以及 `sandbox: "danger-full-access"`。这是用于自主心跳的受信任本地操作员姿态：Codex 可以使用 shell 和网络工具，而不会停在无人可回答的原生审批提示上。 -若要选择启用由 Codex guardian 审核的审批，请设置 `appServer.mode: -"guardian"`： +若要选择启用由 Codex Guardian 审核的审批，请设置 `appServer.mode: "guardian"`： ```json5 { @@ -333,9 +299,9 @@ codex app-server --listen stdio:// } ``` -Guardian 是原生 Codex 审批审核者。当 Codex 请求离开沙箱、在工作区外写入，或添加如网络访问之类的权限时，Codex 会将该审批请求路由给审核子智能体，而不是弹出人工提示。审核者会应用 Codex 的风险框架，并批准或拒绝该具体请求。如果你希望比 YOLO 模式有更多防护措施，但仍需要无人值守的智能体持续推进，请使用 Guardian。 +Guardian 是原生的 Codex 审批审查器。当 Codex 请求离开沙箱、在工作区外写入，或添加诸如网络访问之类的权限时，Codex 会将该审批请求路由给一个审查子智能体，而不是向人工发出提示。该审查器会应用 Codex 的风险框架，并批准或拒绝该特定请求。如果你希望比 YOLO 模式有更多防护措施，同时仍需要无人值守的智能体持续推进，请使用 Guardian。 -`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "guardian_subagent"` 和 `sandbox: "workspace-write"`。单独的策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选择混合使用。 +`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "guardian_subagent"` 和 `sandbox: "workspace-write"`。单独的策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选项混合使用。 对于已经在运行的 app-server，请使用 WebSocket 传输： @@ -361,22 +327,22 @@ Guardian 是原生 Codex 审批审核者。当 Codex 请求离开沙箱、在工 支持的 `appServer` 字段： -| 字段 | 默认值 | 含义 | -| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 | -| `command` | `"codex"` | `stdio` 传输使用的可执行文件。 | -| `args` | `["app-server", "--listen", "stdio://"]` | `stdio` 传输的参数。 | -| `url` | unset | WebSocket app-server URL。 | -| `authToken` | unset | WebSocket 传输的 Bearer token。 | -| `headers` | `{}` | 额外的 WebSocket 标头。 | -| `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 | -| `mode` | `"yolo"` | 用于 YOLO 或 guardian 审核执行的预设。 | -| `approvalPolicy` | `"never"` | 发送到线程启动 / 恢复 / 轮次的原生 Codex 审批策略。 | -| `sandbox` | `"danger-full-access"` | 发送到线程启动 / 恢复的原生 Codex 沙箱模式。 | -| `approvalsReviewer` | `"user"` | 使用 `"guardian_subagent"` 可让 Codex Guardian 审核提示。 | -| `serviceTier` | unset | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版值会被忽略。 | +| Field | Default | Meaning | +| ------------------- | ---------------------------------------- | ----------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 | +| `command` | `"codex"` | 用于 stdio 传输的可执行文件。 | +| `args` | `["app-server", "--listen", "stdio://"]` | 用于 stdio 传输的参数。 | +| `url` | unset | WebSocket app-server URL。 | +| `authToken` | unset | 用于 WebSocket 传输的 Bearer token。 | +| `headers` | `{}` | 额外的 WebSocket 请求头。 | +| `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 | +| `mode` | `"yolo"` | 用于 YOLO 或 guardian 审核执行的预设。 | +| `approvalPolicy` | `"never"` | 发送到线程启动 / 恢复 / 回合的原生 Codex 审批策略。 | +| `sandbox` | `"danger-full-access"` | 发送到线程启动 / 恢复的原生 Codex 沙箱模式。 | +| `approvalsReviewer` | `"user"` | 使用 `"guardian_subagent"` 让 Codex Guardian 审核提示。 | +| `serviceTier` | unset | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧值会被忽略。 | -较旧的环境变量在匹配的配置字段未设置时，仍可作为本地测试的回退： +较早的环境变量在对应配置字段未设置时，仍可作为本地测试的回退方式使用： - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -384,14 +350,11 @@ Guardian 是原生 Codex 审批审核者。当 Codex 请求离开沙箱、在工 - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已移除。请改用 -`plugins.entries.codex.config.appServer.mode: "guardian"`，或 -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` 进行一次性本地测试。对于可重复部署， -更推荐使用配置，因为这样可以将插件行为与 Codex harness 其余设置保存在同一个经过审查的文件中。 +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已移除。请改用 `plugins.entries.codex.config.appServer.mode: "guardian"`，或者在一次性本地测试中使用 `OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复的部署，优先使用配置，因为这样可以将插件行为与 Codex harness 其余设置一起保存在同一个经过审查的文件中。 ## 常见配方 -使用默认 `stdio` 传输的本地 Codex： +使用默认 stdio 传输的本地 Codex： ```json5 { @@ -405,12 +368,17 @@ Guardian 是原生 Codex 审批审核者。当 Codex 请求离开沙箱、在工 } ``` -仅 Codex harness 验证，禁用 PI 回退： +仅 Codex harness 验证： ```json5 { - embeddedHarness: { - fallback: "none", + agents: { + defaults: { + model: "openai/gpt-5.5", + embeddedHarness: { + runtime: "codex", + }, + }, }, plugins: { entries: { @@ -444,7 +412,7 @@ Guardian 是原生 Codex 审批审核者。当 Codex 请求离开沙箱、在工 } ``` -带显式标头的远程 app-server： +带显式请求头的远程 app-server： ```json5 { @@ -467,118 +435,110 @@ Guardian 是原生 Codex 审批审核者。当 Codex 请求离开沙箱、在工 } ``` -模型切换仍由 OpenClaw 控制。当 OpenClaw 会话附加到现有 Codex 线程时，下一轮会再次将当前选定的 -OpenAI 模型、提供商、审批策略、沙箱和服务层级发送给 -app-server。从 `openai/gpt-5.5` 切换到 `openai/gpt-5.2` 时会保留 -线程绑定，但会要求 Codex 使用新选定的模型继续。 +模型切换仍由 OpenClaw 控制。当一个 OpenClaw 会话附加到现有的 Codex 线程时，下一回合会再次将当前所选的 OpenAI 模型、provider、审批策略、沙箱和服务层级发送给 app-server。从 `openai/gpt-5.5` 切换到 `openai/gpt-5.2` 会保留线程绑定，但会要求 Codex 继续使用新选择的模型。 ## Codex 命令 -内置插件将 `/codex` 注册为已授权斜杠命令。它是通用的，可在任何支持 OpenClaw 文本命令的渠道上运行。 +内置插件将 `/codex` 注册为一个已授权的斜杠命令。它是通用的，可在任何支持 OpenClaw 文本命令的渠道中使用。 常见形式： -- `/codex status` 显示实时 app-server 连接状态、模型、账户、速率限制、MCP 服务器和 Skills。 +- `/codex status` 显示实时 app-server 连接性、模型、账户、速率限制、MCP 服务器和 Skills。 - `/codex models` 列出实时 Codex app-server 模型。 - `/codex threads [filter]` 列出最近的 Codex 线程。 -- `/codex resume ` 将当前 OpenClaw 会话附加到现有 Codex 线程。 -- `/codex compact` 请求 Codex app-server 压缩已附加线程。 -- `/codex review` 为已附加线程启动 Codex 原生审查。 +- `/codex resume ` 将当前 OpenClaw 会话附加到现有的 Codex 线程。 +- `/codex compact` 请求 Codex app-server 压缩已附加的线程。 +- `/codex review` 启动已附加线程的 Codex 原生审查。 - `/codex account` 显示账户和速率限制状态。 - `/codex mcp` 列出 Codex app-server MCP 服务器状态。 - `/codex skills` 列出 Codex app-server Skills。 -`/codex resume` 会写入与 harness 正常轮次 -使用的同一个 sidecar 绑定文件。在下一条消息时，OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw 模型传入 app-server，并保持扩展历史记录 -处于启用状态。 +`/codex resume` 会写入与 harness 正常回合所使用的相同 sidecar 绑定文件。下一条消息到来时，OpenClaw 会恢复该 Codex 线程，将当前所选的 OpenClaw 模型传入 app-server，并保持扩展历史已启用。 -该命令界面需要 Codex app-server `0.118.0` 或更高版本。如果未来或自定义 app-server 未暴露某个 JSON-RPC 方法， -各个控制方法会报告为 `unsupported by this Codex app-server`。 +该命令界面要求 Codex app-server `0.118.0` 或更高版本。如果未来版本或自定义 app-server 未暴露某个 JSON-RPC 方法，则单个控制方法会显示为 `unsupported by this Codex app-server`。 ## 钩子边界 Codex harness 有三层钩子： -| 层级 | 所有者 | 用途 | -| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| OpenClaw 插件钩子 | OpenClaw | 在 PI 和 Codex harness 之间提供产品 / 插件兼容性。 | -| Codex app-server 扩展中间件 | OpenClaw 内置插件 | 围绕 OpenClaw 动态工具的每轮适配器行为。 | -| Codex 原生钩子 | Codex | 来自 Codex 配置的底层 Codex 生命周期和原生工具策略。 | +| Layer | Owner | Purpose | +| ------------------------------------- | ------------------------ | ------------------------------------------------------------- | +| OpenClaw plugin hooks | OpenClaw | 在 PI 和 Codex harness 之间提供产品 / 插件兼容性。 | +| Codex app-server extension middleware | OpenClaw bundled plugins | 围绕 OpenClaw 动态工具的每回合适配器行为。 | +| Codex native hooks | Codex | 来自 Codex 配置的底层 Codex 生命周期和原生工具策略。 | -OpenClaw 不使用项目级或全局 Codex `hooks.json` 文件来路由 -OpenClaw 插件行为。Codex 原生钩子适用于由 Codex 管理的 -操作，例如 shell 策略、原生工具结果审查、停止处理，以及 -原生压缩 / 模型生命周期，但它们不是 OpenClaw 插件 API。 +OpenClaw 不使用项目级或全局 Codex `hooks.json` 文件来路由 OpenClaw 插件行为。Codex 原生钩子对于由 Codex 管理的操作很有用，例如 shell 策略、原生工具结果审查、停止处理以及原生压缩 / 模型生命周期，但它们不是 OpenClaw 插件 API。 -对于 OpenClaw 动态工具，在 Codex 请求调用之后，OpenClaw 才执行该工具，因此 OpenClaw 会在 -harness 适配器中触发其拥有的插件和中间件行为。对于 Codex 原生工具，Codex 持有规范工具记录。 -OpenClaw 可以镜像选定事件，但除非 Codex 通过 app-server 或原生钩子 -回调暴露该操作，否则它无法重写原生 Codex -线程。 +对于 OpenClaw 动态工具，Codex 发起调用请求后，OpenClaw 会执行该工具，因此 OpenClaw 会在 harness 适配器中触发它所管理的插件和中间件行为。对于 Codex 原生工具，Codex 拥有规范的工具记录。OpenClaw 可以镜像部分事件，但除非 Codex 通过 app-server 或原生钩子回调暴露该操作，否则它无法重写原生 Codex 线程。 -当较新的 Codex app-server 构建暴露原生压缩和模型生命周期 -钩子事件时，OpenClaw 应对该协议支持进行版本门控，并在语义真实的前提下将这些事件映射到现有 OpenClaw 钩子契约中。 -在此之前，OpenClaw 的 `before_compaction`、`after_compaction`、`llm_input` 和 -`llm_output` 事件属于适配器层观察结果，而不是对 Codex 内部请求或压缩负载的逐字节捕获。 +当更新的 Codex app-server 版本暴露出原生压缩和模型生命周期钩子事件时，OpenClaw 应对该协议支持进行版本门控，并在语义真实的前提下，将这些事件映射到现有 OpenClaw 钩子契约中。在此之前，OpenClaw 的 `before_compaction`、`after_compaction`、`llm_input` 和 `llm_output` 事件都属于适配器级观察，而不是对 Codex 内部请求或压缩负载的逐字节捕获。 -Codex 原生 `hook/started` 和 `hook/completed` app-server 通知会被投射为 `codex_app_server.hook` 智能体事件，用于轨迹和调试。 -它们不会调用 OpenClaw 插件钩子。 +Codex 原生 `hook/started` 和 `hook/completed` app-server 通知会被投影为 `codex_app_server.hook` 智能体事件，用于轨迹记录和调试。它们不会调用 OpenClaw 插件钩子。 -## 工具、媒体与压缩 +## V1 支持契约 + +Codex 模式并不是“底层只是换了模型调用的 PI”。Codex 接管了更多原生模型循环，而 OpenClaw 会围绕这一边界适配其插件和会话界面。 + +Codex runtime v1 中支持的内容： + +| Surface | Support | Why | +| --------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| 通过 Codex 的 OpenAI 模型循环 | 支持 | Codex app-server 负责 OpenAI 回合、原生线程恢复和原生工具续接。 | +| OpenClaw 渠道路由与传递 | 支持 | Telegram、Discord、Slack、WhatsApp、iMessage 以及其他渠道仍位于模型运行时之外。 | +| OpenClaw 动态工具 | 支持 | Codex 会请求 OpenClaw 执行这些工具，因此 OpenClaw 仍在执行路径中。 | +| 提示词和上下文插件 | 支持 | OpenClaw 会在启动或恢复线程之前构建提示词覆盖层，并将上下文投射到 Codex 回合中。 | +| 上下文引擎生命周期 | 支持 | 组装、摄取或回合后维护，以及上下文引擎压缩协调，都会在 Codex 回合中运行。 | +| 动态工具钩子 | 支持 | `before_tool_call`、`after_tool_call` 和工具结果中间件会围绕由 OpenClaw 管理的动态工具运行。 | +| 生命周期钩子 | 以适配器观察形式支持 | `llm_input`、`llm_output`、`agent_end`、`before_compaction` 和 `after_compaction` 会以真实的 Codex 模式负载触发。 | +| 原生 shell 和 patch 的阻止或观察 | 通过原生钩子转发支持 | 对受支持的 Codex 原生工具，会转发 Codex `PreToolUse` 和 `PostToolUse`。支持阻止，不支持参数重写。 | +| 原生权限策略 | 通过原生钩子转发支持 | 当运行时暴露该能力时，Codex `PermissionRequest` 可以通过 OpenClaw 策略进行路由。 | +| App-server 轨迹捕获 | 支持 | OpenClaw 会记录它发送给 app-server 的请求，以及它收到的 app-server 通知。 | + +Codex runtime v1 中不支持的内容： + +| Surface | V1 Boundary | Future Path | +| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | +| 原生工具参数修改 | Codex 原生预工具钩子可以阻止执行，但 OpenClaw 不会重写 Codex 原生工具参数。 | 需要 Codex 钩子 / schema 支持替换后的工具输入。 | +| 可编辑的 Codex 原生转录历史 | Codex 拥有规范的原生线程历史。OpenClaw 拥有镜像，并可投射未来上下文，但不应修改不受支持的内部实现。 | 如果需要原生线程手术操作，应添加显式的 Codex app-server API。 | +| 用于 Codex 原生工具记录的 `tool_result_persist` | 该钩子转换的是由 OpenClaw 管理的转录写入，而不是 Codex 原生工具记录。 | 可以镜像转换后的记录，但规范重写需要 Codex 支持。 | +| 丰富的原生压缩元数据 | OpenClaw 可观察到压缩开始和完成，但不会收到稳定的保留 / 丢弃列表、token 增量或摘要负载。 | 需要更丰富的 Codex 压缩事件。 | +| 压缩干预 | 当前 OpenClaw 的压缩钩子在 Codex 模式下属于通知级别。 | 如果插件需要否决或重写原生压缩，应添加 Codex 压缩前 / 后钩子。 | +| 停止或最终答案门控 | Codex 具有原生停止钩子，但 OpenClaw 未将最终答案门控公开为 v1 插件契约。 | 未来可提供带循环和超时保护的可选启用原语。 | +| 原生 MCP 钩子一致性 | Codex 拥有 MCP 执行，而完整的前 / 后钩子负载一致性取决于 Codex MCP 处理器支持。 | 添加 Codex MCP 钩子负载，然后通过相同的原生钩子路径转发它们。 | +| 逐字节模型 API 请求捕获 | OpenClaw 可以捕获 app-server 请求和通知，但最终的 OpenAI API 请求由 Codex 核心在内部构建。 | 需要 Codex 模型请求跟踪事件或调试 API。 | + +## 工具、媒体和压缩 Codex harness 只改变底层嵌入式智能体执行器。 -OpenClaw 仍会构建工具列表，并从 harness 接收动态工具结果。文本、图像、视频、音乐、TTS、审批和消息工具输出 -仍通过常规 OpenClaw 投递路径处理。 +OpenClaw 仍然构建工具列表，并从 harness 接收动态工具结果。文本、图像、视频、音乐、TTS、审批以及消息工具输出，都会继续通过正常的 OpenClaw 传递路径处理。 -当 Codex 将 `_meta.codex_approval_kind` 标记为 -`"mcp_tool_call"` 时，Codex MCP 工具审批征询会通过 OpenClaw 的插件 -审批流进行路由。Codex `request_user_input` 提示会发回原始聊天， -而下一条排队的后续消息会响应该原生 -服务器请求，而不是被作为额外上下文引导。其他 MCP 征询请求仍然会默认拒绝。 +当 Codex 将 `_meta.codex_approval_kind` 标记为 `"mcp_tool_call"` 时，Codex MCP 工具审批征求会通过 OpenClaw 的插件审批流程进行路由。Codex `request_user_input` 提示会被发送回发起的聊天，而下一个排队的后续消息会用于回答该原生服务器请求，而不是作为额外上下文被引导。其他 MCP 征求请求仍然会以封闭失败的方式处理。 -当选中的模型使用 Codex harness 时，原生线程压缩会委托给 Codex app-server。OpenClaw 会保留一个转录镜像，用于渠道历史、搜索、`/new`、`/reset` 以及未来的模型或 harness 切换。该镜像 -包含用户提示、最终助手文本，以及在 app-server 发出时的轻量级 Codex -推理或计划记录。目前，OpenClaw 仅记录原生压缩开始和完成信号。它尚未公开 -人类可读的压缩摘要，也未提供 Codex 在压缩后保留了哪些条目的可审计列表。 +当所选模型使用 Codex harness 时，原生线程压缩会委托给 Codex app-server。OpenClaw 会保留一个转录镜像，用于渠道历史、搜索、`/new`、`/reset` 以及未来的模型或 harness 切换。该镜像包括用户提示、最终助手文本，以及当 app-server 发出这些记录时的轻量级 Codex 推理或计划记录。目前，OpenClaw 仅记录原生压缩开始和完成信号。它尚未公开人类可读的压缩摘要，也未提供 Codex 在压缩后保留了哪些条目的可审计列表。 -由于 Codex 持有规范原生线程，`tool_result_persist` 当前不会 -重写 Codex 原生工具结果记录。它仅在 -OpenClaw 写入由 OpenClaw 管理的会话转录工具结果时生效。 +由于 Codex 拥有规范的原生线程，`tool_result_persist` 当前不会重写 Codex 原生工具结果记录。它仅在 OpenClaw 写入由 OpenClaw 管理的会话转录工具结果时生效。 -媒体生成不需要 PI。图像、视频、音乐、PDF、TTS 和媒体 -理解仍继续使用匹配的提供商 / 模型设置，例如 -`agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 -`messages.tts`。 +媒体生成不需要 PI。图像、视频、音乐、PDF、TTS 和媒体理解会继续使用相应的 provider / 模型设置，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。 ## 故障排除 -**`/model` 中没有出现 Codex：** 启用 `plugins.entries.codex.enabled`， -选择带有 `embeddedHarness.runtime: "codex"` 的 `openai/gpt-*` 模型（或 -旧版 `codex/*` 引用），并检查 `plugins.allow` 是否排除了 `codex`。 +**`/model` 中未出现 Codex：** 启用 `plugins.entries.codex.enabled`，选择带有 `embeddedHarness.runtime: "codex"` 的 `openai/gpt-*` 模型（或旧版 `codex/*` 引用），并检查 `plugins.allow` 是否排除了 `codex`。 -**OpenClaw 使用了 PI 而不是 Codex：** `runtime: "auto"` 在没有 Codex harness 认领该运行时， -仍可能使用 PI 作为兼容性后端。测试时请设置 -`embeddedHarness.runtime: "codex"` 以强制选择 Codex。现在，强制使用 Codex 运行时会直接失败，而不是回退到 PI，除非你 -显式设置 `embeddedHarness.fallback: "pi"`。一旦选中了 Codex app-server， -其失败会直接暴露出来，而不会有额外的回退配置。 +**OpenClaw 使用的是 PI 而不是 Codex：** 当没有 Codex harness 声明该运行时，`runtime: "auto"` 仍可能使用 PI 作为兼容性后端。测试时请设置 `embeddedHarness.runtime: "codex"` 以强制选择 Codex。强制的 Codex 运行时现在会直接失败，而不是回退到 PI，除非你显式设置 `embeddedHarness.fallback: "pi"`。一旦选择了 Codex app-server，其失败会直接暴露出来，而不会有额外的回退配置。 -**app-server 被拒绝：** 升级 Codex，使 app-server 握手 -报告版本 `0.118.0` 或更高。 +**app-server 被拒绝：** 升级 Codex，使 app-server 握手报告版本 `0.118.0` 或更高。 -**模型发现很慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs` -或禁用发现。 +**模型发现过慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs` 或禁用发现。 -**WebSocket 传输立即失败：** 检查 `appServer.url`、`authToken`， -以及远程 app-server 是否使用相同的 Codex app-server 协议版本。 +**WebSocket 传输立即失败：** 检查 `appServer.url`、`authToken`，并确认远程 app-server 使用相同版本的 Codex app-server 协议。 -**非 Codex 模型使用了 PI：** 这是预期行为，除非你强制设置了 -`embeddedHarness.runtime: "codex"`（或选择了旧版 `codex/*` 引用）。普通 -`openai/gpt-*` 和其他提供商引用会保留在它们正常的提供商路径上。 +**非 Codex 模型使用了 PI：** 这是预期行为，除非你为该智能体强制设置了 `embeddedHarness.runtime: "codex"`，或选择了旧版 `codex/*` 引用。普通的 `openai/gpt-*` 和其他 provider 引用在 `auto` 模式下会保持其正常的 provider 路径。如果你强制设置 `runtime: "codex"`，则该智能体的每一个嵌入式回合都必须是受 Codex 支持的 OpenAI 模型。 ## 相关内容 -- [智能体 Harness 插件](/zh-CN/plugins/sdk-agent-harness) -- [模型提供商](/zh-CN/concepts/model-providers) -- [配置参考](/zh-CN/gateway/configuration-reference) +- [Agent harness plugins](/zh-CN/plugins/sdk-agent-harness) +- [Agent Runtimes](/zh-CN/concepts/agent-runtimes) +- [Model Providers](/zh-CN/concepts/model-providers) +- [Configuration Reference](/zh-CN/gateway/configuration-reference) - [测试](/zh-CN/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/zh-CN/plugins/sdk-agent-harness.md b/docs/zh-CN/plugins/sdk-agent-harness.md index a73879068..dc660399c 100644 --- a/docs/zh-CN/plugins/sdk-agent-harness.md +++ b/docs/zh-CN/plugins/sdk-agent-harness.md @@ -1,51 +1,58 @@ --- read_when: - - 你正在更改内嵌智能体运行时或 Harness 注册表 - - 你正在从内置或受信任的插件注册一个智能体 Harness + - 你正在更改嵌入式智能体运行时或 harness 注册表 + - 你正在从内置或受信任插件注册一个智能体 harness - 你需要了解 Codex 插件与模型提供商之间的关系 sidebarTitle: Agent Harness -summary: 供替换底层内嵌智能体执行器的插件使用的实验性 SDK 接口 -title: 智能体 Harness 插件 +summary: 面向替换底层嵌入式智能体执行器的插件的实验性 SDK 接口 +title: Agent harness plugins x-i18n: - generated_at: "2026-04-25T01:27:31Z" + generated_at: "2026-04-25T01:51:47Z" model: gpt-5.4 provider: openai - source_hash: 6a451995a18bce70b02eea88e2ac52561e21208c40cf93b88fc921aad49dffec + source_hash: bceb0ccf51431918aec2dfca047af6ed916aa1a8a7c34ca38cb64a14655e4d50 source_path: plugins/sdk-agent-harness.md workflow: 15 --- -**智能体 Harness** 是为单个已准备好的 OpenClaw 智能体轮次提供的底层执行器。它不是模型提供商，不是渠道，也不是工具注册表。 +**智能体 harness** 是为一个已准备好的 OpenClaw 智能体轮次提供底层执行的组件。它不是模型提供商，不是渠道，也不是工具注册表。 +关于面向用户的心智模型，请参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 -仅将此接口用于内置或受信任的原生插件。该契约仍然是实验性的，因为参数类型有意映射当前的内嵌运行器。 +仅将此接口用于内置或受信任的原生插件。该契约 +仍然是实验性的，因为其参数类型有意映射当前的 +嵌入式运行器。 -## 何时使用 Harness +## 何时使用 harness -当某个模型家族拥有自己的原生会话运行时，而常规的 OpenClaw 提供商传输层并不是合适抽象时，请注册一个智能体 Harness。 +当某个模型家族拥有自己的原生会话 +运行时，而常规的 OpenClaw 提供商传输层是错误抽象时，请注册一个智能体 harness。 示例： - 拥有线程和压缩能力的原生编码智能体服务器 - 必须流式传输原生计划 / 推理 / 工具事件的本地 CLI 或守护进程 -- 除 OpenClaw 会话转录记录之外，还需要自己的恢复 id 的模型运行时 +- 除 OpenClaw + 会话转录之外，还需要自己恢复 id 的模型运行时 -**不要** 只是为了添加一个新的 LLM API 就注册 Harness。对于普通的 HTTP 或 WebSocket 模型 API，请构建一个[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。 +不要只是为了添加一个新的 LLM API 而注册 harness。对于普通的 HTTP 或 +WebSocket 模型 API，请构建一个[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。 -## 核心仍然负责的内容 +## 核心仍然负责什么 -在选择 Harness 之前，OpenClaw 已经解析了： +在选择 harness 之前，OpenClaw 已经解析了： - 提供商和模型 -- 运行时凭证状态 +- 运行时认证状态 - 思考级别和上下文预算 -- OpenClaw 转录记录 / 会话文件 +- OpenClaw 转录 / 会话文件 - 工作区、沙箱和工具策略 - 渠道回复回调和流式传输回调 - 模型回退和实时模型切换策略 -这种划分是有意设计的。Harness 运行的是一个已准备好的尝试；它不会选择提供商、替换渠道投递，或静默切换模型。 +这种划分是有意为之。harness 负责执行一个已准备好的尝试；它不会选择 +提供商、替换渠道投递，或静默切换模型。 -## 注册 Harness +## 注册 harness **导入：** `openclaw/plugin-sdk/agent-harness` @@ -83,58 +90,104 @@ export default definePluginEntry({ ## 选择策略 -OpenClaw 会在提供商 / 模型解析完成后选择一个 Harness： +OpenClaw 会在提供商 / 模型解析之后选择一个 harness： -1. 现有会话中记录的 Harness id 优先，因此配置 / 环境变量变更不会将该转录记录热切换到另一个运行时。 -2. `OPENCLAW_AGENT_RUNTIME=` 会为尚未固定的会话强制使用具有该 id 的已注册 Harness。 -3. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置的 PI Harness。 -4. `OPENCLAW_AGENT_RUNTIME=auto` 会询问已注册的 Harness 是否支持已解析的提供商 / 模型。 -5. 如果没有匹配的已注册 Harness，除非 PI 回退已被禁用，否则 OpenClaw 会使用 PI。 +1. 现有会话中记录的 harness id 优先，因此配置 / 环境变化不会 + 将该转录热切换到另一个运行时。 +2. `OPENCLAW_AGENT_RUNTIME=` 会为 + 尚未被固定的会话强制使用具有该 id 的已注册 harness。 +3. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置的 PI harness。 +4. `OPENCLAW_AGENT_RUNTIME=auto` 会询问已注册的 harness，它们是否支持已解析的 + 提供商 / 模型。 +5. 如果没有匹配的已注册 harness，OpenClaw 会使用 PI，除非禁用了 PI 回退。 -插件 Harness 失败会表现为运行失败。在 `auto` 模式下，仅当没有任何已注册的插件 Harness 支持已解析的提供商 / 模型时，才会使用 PI 回退。一旦某个插件 Harness 已接管一次运行，OpenClaw 不会再通过 PI 重放同一个轮次，因为那可能改变凭证 / 运行时语义或导致副作用重复。 +插件 harness 故障会表现为运行失败。在 `auto` 模式下，只有当没有已注册的插件 harness 支持已解析的 +提供商 / 模型时，才会使用 PI 回退。一旦某个插件 harness 已经接管了一次运行，OpenClaw 就不会通过 PI 重新执行同一轮次，因为这可能改变认证 / 运行时语义 +或导致副作用重复。 -选中的 Harness id 会在一次内嵌运行后与会话 id 一起持久化。在 Harness 固定机制出现之前创建的旧会话，只要已有转录历史，就会被视为已固定到 PI。在 PI 与原生插件 Harness 之间切换时，请使用新的 / 重置后的会话。`/status` 会在 `Fast` 旁显示诸如 `codex` 之类的非默认 Harness id；PI 因为是默认兼容路径而保持隐藏。如果选中的 Harness 出乎你的预期，请启用 `agents/harness` 调试日志，并检查 Gateway 网关的结构化 `agent harness selected` 记录。它包含选中的 Harness id、选择原因、运行时 / 回退策略，以及在 `auto` 模式下每个插件候选项的支持结果。 +在一次嵌入式运行之后，所选的 harness id 会与会话 id 一起持久化。 +在 harness 固定机制出现之前创建的旧会话，只要已有转录历史，就会被视为已固定到 PI。 +在 PI 和原生插件 harness 之间切换时，请使用新的 / 已重置的会话。`/status` 会在 `Fast` 旁边显示诸如 `codex` +这样的非默认 harness id；PI 因为是默认兼容路径而保持隐藏。 +如果所选 harness 让你感到意外，请启用 `agents/harness` 调试日志，并检查 Gateway 网关 的结构化 `agent harness selected` 记录。它包含 +所选 harness id、选择原因、运行时 / 回退策略，以及在 `auto` 模式下每个插件候选项的支持结果。 -内置的 Codex 插件将 `codex` 注册为它的 Harness id。核心将其视为普通的插件 Harness id；Codex 专用别名应放在插件或操作员配置中，而不是共享运行时选择器中。 +内置的 Codex 插件会将 `codex` 注册为其 harness id。核心将其视为普通的插件 harness id；Codex 专用别名应放在插件 +或操作员配置中，而不是放在共享的运行时选择器中。 -## 提供商与 Harness 配对 +## 提供商与 harness 的配对 -大多数 Harness 也应注册一个提供商。提供商会让模型引用、凭证状态、模型元数据和 `/model` 选择对 OpenClaw 的其余部分可见。然后 Harness 在 `supports(...)` 中声明该提供商。 +大多数 harness 也应该注册一个提供商。提供商使模型引用、 +认证状态、模型元数据以及 `/model` 选择对 OpenClaw 的其余部分可见。 +然后，harness 在 `supports(...)` 中声明支持该提供商。 -内置的 Codex 插件遵循这一模式： +内置的 Codex 插件遵循此模式： -- provider id：`codex` -- 用户模型引用：`openai/gpt-5.5` 加上 `embeddedHarness.runtime: "codex"`；旧版 `codex/gpt-*` 引用仍然出于兼容性而被接受 +- 首选的用户模型引用：`openai/gpt-5.5` 加上 + `embeddedHarness.runtime: "codex"` +- 兼容性引用：旧版 `codex/gpt-*` 引用仍然被接受，但新的 + 配置不应将其用作普通提供商 / 模型引用 - harness id：`codex` -- auth：合成的提供商可用性，因为 Codex Harness 拥有原生 Codex 登录 / 会话 -- app-server 请求：OpenClaw 将裸模型 id 发送给 Codex，并让 Harness 与原生 app-server 协议通信 +- 认证：合成的提供商可用性，因为 Codex harness 拥有 + 原生 Codex 登录 / 会话 +- app-server 请求：OpenClaw 向 Codex 发送裸模型 id，并让 + harness 与原生 app-server 协议通信 -Codex 插件是增量式的。普通的 `openai/gpt-*` 引用会继续使用常规 OpenClaw 提供商路径，除非你通过 `embeddedHarness.runtime: "codex"` 强制使用 Codex Harness。较旧的 `codex/gpt-*` 引用仍会出于兼容性而选择 Codex 提供商和 Harness。 +Codex 插件是增量式的。普通的 `openai/gpt-*` 引用仍会使用 +常规 OpenClaw 提供商路径，除非你通过 +`embeddedHarness.runtime: "codex"` 强制使用 Codex harness。较旧的 `codex/gpt-*` 引用 +出于兼容性考虑仍会选择 Codex 提供商和 harness。 -关于操作员设置、模型前缀示例和仅限 Codex 的配置，请参见 [Codex Harness](/zh-CN/plugins/codex-harness)。 +关于操作员设置、模型前缀示例和仅 Codex 配置，请参见 +[Codex harness](/zh-CN/plugins/codex-harness)。 -OpenClaw 要求 Codex app-server 为 `0.118.0` 或更高版本。Codex 插件会检查 app-server 初始化握手，并阻止更旧或未带版本号的服务器，以确保 OpenClaw 仅在它已测试过的协议接口上运行。 +OpenClaw 要求 Codex app-server 为 `0.118.0` 或更高版本。Codex 插件会检查 +app-server 初始化握手，并阻止较旧或未标明版本的服务器，以便 +OpenClaw 仅针对其已测试过的协议接口运行。 ### 工具结果中间件 -当内置插件的清单在 `contracts.agentToolResultMiddleware` 中声明了目标运行时 id 时，它们可以通过 `api.registerAgentToolResultMiddleware(...)` 附加运行时无关的工具结果中间件。这个受信任接口用于异步工具结果转换，这些转换必须在 PI 或 Codex 将工具输出反馈给模型之前运行。 +内置插件可以通过 +`api.registerAgentToolResultMiddleware(...)` 附加运行时无关的工具结果中间件，前提是 +其清单在 `contracts.agentToolResultMiddleware` 中声明了目标运行时 id。这个受信任的接口 +用于必须在 PI 或 Codex 将 +工具输出送回模型之前运行的异步工具结果转换。 -旧版内置插件仍可使用 `api.registerCodexAppServerExtensionFactory(...)` 来实现仅适用于 Codex app-server 的中间件，但新的结果转换应使用运行时无关 API。 -仅限 Pi 的 `api.registerEmbeddedExtensionFactory(...)` 钩子已被移除；Pi 工具结果转换必须使用运行时无关中间件。 +旧版内置插件仍然可以使用 +`api.registerCodexAppServerExtensionFactory(...)` 来实现仅适用于 Codex app-server 的 +中间件，但新的结果转换应使用运行时无关 API。 +仅适用于 Pi 的 `api.registerEmbeddedExtensionFactory(...)` 钩子已被移除； +Pi 工具结果转换必须使用运行时无关中间件。 -### 原生 Codex Harness 模式 +### 原生 Codex harness 模式 -内置的 `codex` Harness 是内嵌 OpenClaw 智能体轮次的原生 Codex 模式。请先启用内置的 `codex` 插件；如果你的配置使用了限制性 allowlist，还需要在 `plugins.allow` 中包含 `codex`。原生 app-server 配置应使用 `openai/gpt-*` 并设置 `embeddedHarness.runtime: "codex"`。若要通过 PI 使用 Codex OAuth，请改用 `openai-codex/*`。旧版 `codex/*` 模型引用仍保留为原生 Harness 的兼容别名。 +内置的 `codex` harness 是嵌入式 OpenClaw +智能体轮次的原生 Codex 模式。请先启用内置的 `codex` 插件，并在 +你的配置使用限制性 allowlist 时，将 `codex` 包含在 +`plugins.allow` 中。原生 app-server 配置应使用 `openai/gpt-*`，并设置 `embeddedHarness.runtime: "codex"`。 +如果要通过 PI 使用 Codex OAuth，请改用 `openai-codex/*`。旧版 `codex/*` +模型引用仍然保留为原生 harness 的兼容性别名。 -当该模式运行时，Codex 负责原生线程 id、恢复行为、压缩和 app-server 执行。OpenClaw 仍然负责聊天渠道、可见转录镜像、工具策略、审批、媒体投递和会话选择。当你需要证明只有 Codex app-server 路径可以接管运行时，请使用 `embeddedHarness.runtime: "codex"` 并配合 `embeddedHarness.fallback: "none"`。该配置只是一个选择保护措施：Codex app-server 失败本来就会直接失败，而不是通过 PI 重试。 +当此模式运行时，Codex 负责原生线程 id、恢复行为、 +压缩以及 app-server 执行。OpenClaw 仍然负责聊天渠道、 +可见转录镜像、工具策略、批准、媒体投递和会话选择。 +当你需要证明只有 Codex app-server 路径能够接管该运行时，请使用 `embeddedHarness.runtime: "codex"`，且不要设置 `fallback` 覆盖。 +显式插件运行时默认已经是失败即关闭。只有在你明确希望缺失的 harness 选择由 PI 处理时，才设置 `fallback: "pi"`。 +Codex app-server 故障本来就会直接失败，而不会通过 PI 重试。 ## 禁用 PI 回退 -默认情况下，OpenClaw 运行内嵌智能体时，`agents.defaults.embeddedHarness` 设置为 `{ runtime: "auto", fallback: "pi" }`。在 `auto` 模式下，已注册的插件 Harness 可以接管某个提供商 / 模型对。如果没有匹配项，OpenClaw 会回退到 PI。 +默认情况下，OpenClaw 会以 `agents.defaults.embeddedHarness` +设置为 `{ runtime: "auto", fallback: "pi" }` 的方式运行嵌入式智能体。在 `auto` 模式下，已注册的插件 +harness 可以声明接管某个提供商 / 模型对。如果没有匹配项，OpenClaw 会回退到 PI。 -当你需要在缺少插件 Harness 选择时直接失败，而不是使用 PI 时，请设置 `fallback: "none"`。已选中的插件 Harness 失败本来就会硬失败。这不会阻止显式的 `runtime: "pi"` 或 `OPENCLAW_AGENT_RUNTIME=pi`。 +在 `auto` 模式下，当你需要在缺失插件 harness +选择时直接失败而不是使用 PI，请设置 `fallback: "none"`。显式插件运行时，例如 +`runtime: "codex"`，默认已经是失败即关闭，除非在同一配置或环境覆盖作用域中设置了 `fallback: "pi"`。 +所选插件 harness 的故障始终会硬失败。这不会阻止显式的 `runtime: "pi"` 或 +`OPENCLAW_AGENT_RUNTIME=pi`。 -对于仅限 Codex 的内嵌运行： +对于仅 Codex 的嵌入式运行： ```json { @@ -142,15 +195,15 @@ OpenClaw 要求 Codex app-server 为 `0.118.0` 或更高版本。Codex 插件会 "defaults": { "model": "openai/gpt-5.5", "embeddedHarness": { - "runtime": "codex", - "fallback": "none" + "runtime": "codex" } } } } ``` -如果你希望任何已注册的插件 Harness 都可以接管匹配的模型，但绝不希望 OpenClaw 静默回退到 PI，请保持 `runtime: "auto"` 并禁用回退： +如果你希望任何已注册的插件 harness 都可以接管匹配的模型，但又绝不希望 OpenClaw 静默回退到 PI，请保持 `runtime: "auto"` 并禁用 +回退： ```json { @@ -165,7 +218,7 @@ OpenClaw 要求 Codex app-server 为 `0.118.0` 或更高版本。Codex 插件会 } ``` -按智能体覆盖使用相同的结构： +每个智能体的覆盖使用相同的结构： ```json { @@ -190,7 +243,9 @@ OpenClaw 要求 Codex app-server 为 `0.118.0` 或更高版本。Codex 插件会 } ``` -`OPENCLAW_AGENT_RUNTIME` 仍会覆盖已配置的运行时。使用 `OPENCLAW_AGENT_HARNESS_FALLBACK=none` 可通过环境变量禁用 PI 回退。 +`OPENCLAW_AGENT_RUNTIME` 仍然会覆盖已配置的运行时。使用 +`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 可通过 +环境变量禁用 PI 回退。 ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -198,39 +253,50 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -在禁用回退的情况下，如果请求的 Harness 未注册、不支持已解析的提供商 / 模型，或在产生轮次副作用之前失败，会话会尽早失败。这是 Codex 专用部署以及必须证明 Codex app-server 路径确实在使用中的实时测试所期望的行为。 +在禁用回退后，如果请求的 harness 未注册、 +不支持已解析的提供商 / 模型，或在产生轮次副作用之前失败，会话就会提前失败。这对于仅 Codex 的部署以及必须证明 +Codex app-server 路径确实在使用中的在线测试来说，是有意设计的行为。 -此设置仅控制内嵌智能体 Harness。它不会禁用图像、视频、音乐、TTS、PDF 或其他特定提供商的模型路由。 +此设置只控制嵌入式智能体 harness。它不会禁用 +图像、视频、音乐、TTS、PDF 或其他提供商特定的模型路由。 -## 原生会话与转录镜像 +## 原生会话和转录镜像 -Harness 可以保留原生会话 id、线程 id 或守护进程侧恢复令牌。请将这种绑定显式地与 OpenClaw 会话关联，并持续将用户可见的助手 / 工具输出镜像到 OpenClaw 转录记录中。 +harness 可以保留原生会话 id、线程 id 或守护进程侧恢复令牌。 +请让这种绑定明确关联到 OpenClaw 会话，并继续将用户可见的助手 / 工具输出镜像到 OpenClaw 转录中。 -OpenClaw 转录记录仍然是以下内容的兼容层： +OpenClaw 转录仍然是以下场景的兼容层： - 渠道可见的会话历史 -- 转录记录搜索与索引 -- 在后续轮次切换回内置 PI Harness +- 转录搜索和索引 +- 在后续轮次切换回内置 PI harness - 通用的 `/new`、`/reset` 和会话删除行为 -如果你的 Harness 存储了一个 sidecar 绑定，请实现 `reset(...)`，以便 OpenClaw 在所属 OpenClaw 会话被重置时清除它。 +如果你的 harness 存储了 sidecar 绑定，请实现 `reset(...)`，以便 OpenClaw 能够在所属 OpenClaw 会话被重置时 +清除它。 ## 工具和媒体结果 -核心会构造 OpenClaw 工具列表并将其传入已准备好的尝试中。当 Harness 执行动态工具调用时，请通过 Harness 结果结构返回工具结果，而不是自行发送渠道媒体。 +核心会构造 OpenClaw 工具列表，并将其传入已准备好的尝试中。 +当 harness 执行动态工具调用时，请通过 +harness 结果结构返回工具结果，而不是自己发送渠道媒体。 -这样可以让文本、图像、视频、音乐、TTS、审批以及消息工具输出与基于 PI 的运行共享同一条投递路径。 +这样可以让文本、图像、视频、音乐、TTS、批准以及消息工具输出 +与基于 PI 的运行使用相同的投递路径。 ## 当前限制 -- 公共导入路径是通用的，但某些 attempt / result 类型别名仍然保留 `Pi` 命名以维持兼容性。 -- 第三方 Harness 安装仍是实验性的。在你确实需要原生会话运行时之前，请优先使用提供商插件。 -- 支持跨轮次切换 Harness。不要在一个轮次中途、在原生工具、审批、助手文本或消息发送已经开始后切换 Harness。 +- 公共导入路径是通用的，但一些 attempt / result 类型别名 + 出于兼容性考虑仍然带有 `Pi` 名称。 +- 第三方 harness 安装仍处于实验阶段。在你确实需要原生会话运行时之前， + 优先使用提供商插件。 +- 支持跨轮次切换 harness。不要在一个轮次进行到一半时切换 harness， + 特别是在原生工具、批准、助手文本或消息发送已经开始之后。 ## 相关内容 - [SDK 概览](/zh-CN/plugins/sdk-overview) - [运行时辅助工具](/zh-CN/plugins/sdk-runtime) - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) -- [Codex Harness](/zh-CN/plugins/codex-harness) +- [Codex harness](/zh-CN/plugins/codex-harness) - [模型提供商](/zh-CN/concepts/model-providers) diff --git a/docs/zh-CN/plugins/sdk-migration.md b/docs/zh-CN/plugins/sdk-migration.md index c82548956..0220865c5 100644 --- a/docs/zh-CN/plugins/sdk-migration.md +++ b/docs/zh-CN/plugins/sdk-migration.md @@ -2,57 +2,64 @@ read_when: - 你看到了 `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` 警告 - 你看到了 `OPENCLAW_EXTENSION_API_DEPRECATED` 警告 - - 你在 OpenClaw 2026.4.24 之前使用了 `api.registerEmbeddedExtensionFactory` - - 你正在将插件更新为现代插件架构 - - 你维护一个外部 OpenClaw 插件 + - 你在 OpenClaw 2026.4.24 之前使用过 `api.registerEmbeddedExtensionFactory` + - 你正在将插件更新到现代插件架构 + - 你在维护一个外部 OpenClaw 插件 sidebarTitle: Migrate to SDK summary: 从旧版向后兼容层迁移到现代插件 SDK title: 插件 SDK 迁移 x-i18n: - generated_at: "2026-04-25T01:27:32Z" + generated_at: "2026-04-25T01:51:59Z" model: gpt-5.4 provider: openai - source_hash: 109261bd1358dab30dc521b5103201e6f8b06800650497bcb86bb4e423694eff + source_hash: 7072e690b1f23fd80d4de9a00bc0352f0c635d1ed89d4b530bfbb1f9f6eab483 source_path: plugins/sdk-migration.md workflow: 15 --- -OpenClaw 已经从宽泛的向后兼容层迁移到现代插件架构，采用聚焦、文档化的导入方式。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。 +OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供更聚焦、文档完善的导入路径。如果你的插件是在新架构之前构建的，本指南可帮助你完成迁移。 ## 正在发生什么变化 -旧版插件系统提供了两个开放范围很大的接口，使插件可以从单一入口点导入所需的任何内容： +旧插件系统提供了两个开放范围很大的接口面，使插件能够从单一入口点导入所需的任何内容： -- **`openclaw/plugin-sdk/compat`** — 一个会重新导出几十个辅助函数的单一导入入口。它的引入是为了在构建新插件架构期间，让较旧的基于钩子的插件继续正常工作。 -- **`openclaw/extension-api`** — 一个桥接层，让插件能够直接访问宿主端的辅助功能，例如嵌入式智能体运行器。 -- **`api.registerEmbeddedExtensionFactory(...)`** — 一个已移除的、仅限 Pi 的内置扩展钩子，可以观察诸如 `tool_result` 之类的嵌入式运行器事件。 +- **`openclaw/plugin-sdk/compat`** — 一个单一导入路径，会重新导出数十个辅助函数。它最初是为了在构建新插件架构期间，让较旧的基于钩子的插件继续工作。 +- **`openclaw/extension-api`** — 一个桥接层，使插件能够直接访问宿主端辅助函数，例如嵌入式智能体运行器。 +- **`api.registerEmbeddedExtensionFactory(...)`** — 一个已移除的、仅限 Pi 的内置扩展钩子，可观察嵌入式运行器事件，例如 `tool_result`。 -这些宽泛的导入接口现已**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主要版本移除它们之前完成迁移。仅限 Pi 的嵌入式扩展工厂注册 API 已被移除；请改用工具结果中间件。 +这些宽泛的导入接口面现已**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主要版本移除它们之前完成迁移。仅限 Pi 的嵌入式扩展工厂注册 API 已被移除；请改用工具结果中间件。 -OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释已文档化的插件行为。破坏契约的变更必须先经过兼容适配器、诊断、文档以及弃用窗口。这一规则适用于 SDK 导入、清单字段、设置 API、钩子以及运行时注册行为。 +OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释已文档化的插件行为。破坏性契约变更必须先经过兼容适配器、诊断、文档和弃用窗口。这适用于 SDK 导入、清单字段、设置 API、钩子和运行时注册行为。 - 向后兼容层将在未来的主要版本中移除。 - 到那时，仍从这些接口导入的插件将会中断。 - 仅限 Pi 的嵌入式扩展工厂注册已经不再加载。 + 向后兼容层将在未来的一个主要版本中移除。 + 仍然从这些接口面导入的插件届时将会失效。 + 仅限 Pi 的嵌入式扩展工厂注册现在已经不会再加载。 -## 为什么会有这个变化 +## 为什么会有这项变更 -旧方法会导致一些问题： +旧方法会带来一些问题： -- **启动缓慢** — 导入一个辅助函数会加载几十个无关模块 -- **循环依赖** — 宽泛的重新导出使创建导入循环变得很容易 -- **API 接口不清晰** — 无法分辨哪些导出是稳定的，哪些是内部实现 +- **启动缓慢** — 导入一个辅助函数会加载数十个无关模块 +- **循环依赖** — 宽泛的重新导出很容易造成导入循环 +- **API 接口面不清晰** — 无法判断哪些导出是稳定的，哪些属于内部实现 -现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含模块，具有明确用途和文档化契约。 +现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含的模块，具有明确用途和已文档化的契约。 -面向内置渠道的旧版提供商便捷接口也已经移除。诸如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、带渠道品牌的辅助接口以及 `openclaw/plugin-sdk/telegram-core` 之类的导入，都是私有单体仓库快捷方式，而不是稳定的插件契约。请改用更窄的通用 SDK 子路径。在内置插件工作区内部，请将提供商自有辅助函数保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 +面向内置渠道的旧版提供商便捷接口也已移除。类似 +`openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、 +`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、 +带有渠道品牌的辅助接口，以及 +`openclaw/plugin-sdk/telegram-core` +这样的导入路径，都是私有 monorepo 快捷方式，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区内部，应将提供商自有的辅助函数保留在该插件自己的 +`api.ts` 或 `runtime-api.ts` 中。 当前内置提供商示例： -- Anthropic 将 Claude 专用的流式辅助函数保留在其自己的 `api.ts` / `contract-api.ts` 接口中 -- OpenAI 将提供商构建器、默认模型辅助函数以及实时提供商构建器保留在其自己的 `api.ts` 中 +- Anthropic 将 Claude 专用的流式传输辅助函数保留在其自己的 `api.ts` / + `contract-api.ts` 接口中 +- OpenAI 将提供商构建器、默认模型辅助函数和实时提供商构建器保留在其自己的 `api.ts` 中 - OpenRouter 将提供商构建器以及新手引导 / 配置辅助函数保留在其自己的 `api.ts` 中 ## 兼容性策略 @@ -60,13 +67,13 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 对于外部插件，兼容性工作遵循以下顺序： 1. 添加新契约 -2. 通过兼容适配器保持旧行为继续接通 +2. 通过兼容适配器保持旧行为继续可用 3. 发出诊断或警告，明确指出旧路径及其替代方案 4. 在测试中覆盖两条路径 5. 记录弃用信息和迁移路径 -6. 仅在宣布的迁移窗口结束后移除，通常是在主要版本中 +6. 仅在已宣布的迁移窗口结束后移除，通常是在主要版本中 -如果某个清单字段仍被接受，插件作者就可以继续使用它，直到文档和诊断另有说明。新代码应优先使用文档化的替代方案，但现有插件不应在普通的小版本发布中被破坏。 +如果某个清单字段仍然被接受，插件作者就可以继续使用它，直到文档和诊断另有说明。新代码应优先使用已文档化的替代方案，但现有插件不应在普通次要版本中失效。 ## 如何迁移 @@ -95,40 +102,39 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 } ``` - 外部插件不能注册工具结果中间件，因为它可以在模型看到高信任度工具输出之前重写这些输出。 + 外部插件不能注册工具结果中间件，因为它可以在模型看到之前重写高信任级别的工具输出。 - 具备审批能力的渠道插件现在通过 - `approvalCapability.nativeRuntime` 加上共享运行时上下文注册表来公开原生审批行为。 + 支持审批的渠道插件现在通过 + `approvalCapability.nativeRuntime` 加上共享运行时上下文注册表来暴露原生审批行为。 关键变化： - 将 `approvalCapability.handler.loadRuntime(...)` 替换为 `approvalCapability.nativeRuntime` - 将审批专用的认证 / 投递逻辑从旧版 `plugin.auth` / - `plugin.approvals` 接线迁移到 `approvalCapability` - - `ChannelPlugin.approvals` 已从公共渠道插件契约中移除； + `plugin.approvals` 线路迁移到 `approvalCapability` + - `ChannelPlugin.approvals` 已从公开的渠道插件契约中移除； 请将 delivery / native / render 字段迁移到 `approvalCapability` - - `plugin.auth` 仅保留给渠道登录 / 登出流程使用；其中的审批认证 - 钩子不再被核心读取 + - `plugin.auth` 仅保留用于渠道登录 / 登出流程；其中的审批认证 + 钩子不再由核心读取 - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道自有的运行时对象，例如客户端、令牌或 Bolt 应用 - - 不要从原生审批处理器发送插件自有的改道路由通知； - 核心现在会根据实际投递结果统一负责“已路由到其他位置”的通知 - - 当把 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供一个 + - 不要从原生审批处理器发送插件自有的重路由通知； + 核心现在会根据实际投递结果统一处理“已路由到其他地方”的通知 + - 将 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供一个 真实的 `createPluginRuntime().channel` 接口。部分桩实现将被拒绝。 - 请参阅 `/plugins/sdk-channel-plugins`，了解当前的审批能力布局。 + 有关当前审批能力布局，请参见 `/plugins/sdk-channel-plugins`。 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`， - 那么未解析的 Windows `.cmd`/`.bat` 包装器现在会默认失败关闭， - 除非你显式传入 `allowShellFallback: true`。 + 那么当 Windows `.cmd` / `.bat` 包装器无法解析时，现在会默认失败关闭，除非你显式传入 `allowShellFallback: true`。 ```typescript // Before @@ -149,7 +155,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - 在你的插件中搜索来自以下任一已弃用接口的导入： + 在你的插件中搜索来自这两个已弃用接口面的导入： ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -159,7 +165,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - 旧接口中的每个导出都映射到一个特定的现代导入路径： + 旧接口面中的每个导出都映射到一个特定的现代导入路径： ```typescript // Before (deprecated backwards-compatibility layer) @@ -186,9 +192,9 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - 同样的模式也适用于其他旧版桥接辅助函数： + 相同模式也适用于其他旧版桥接辅助函数： - | 旧导入 | 现代等价方式 | + | 旧导入 | 现代等价项 | | --- | --- | | `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` | | `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` | @@ -196,7 +202,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | 会话存储辅助函数 | `api.runtime.agent.session.*` | + | session store helpers | `api.runtime.agent.session.*` | @@ -210,42 +216,42 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 ## 导入路径参考 - + | 导入路径 | 用途 | 关键导出 | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | 规范插件入口辅助函数 | `definePluginEntry` | - | `plugin-sdk/core` | 用于渠道入口定义 / 构建器的旧版伞式重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/plugin-entry` | 规范的插件入口辅助函数 | `definePluginEntry` | + | `plugin-sdk/core` | 用于渠道入口定义 / 构建器的旧版聚合重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` | | `plugin-sdk/provider-entry` | 单提供商入口辅助函数 | `defineSingleProviderPluginEntry` | | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | 共享设置向导辅助函数 | Allowlist 提示、设置状态构建器 | - | `plugin-sdk/setup-runtime` | 设置时运行时辅助函数 | 导入安全的设置补丁适配器、lookup-note 辅助函数、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 | + | `plugin-sdk/setup` | 共享的设置向导辅助函数 | Allowlist 提示、设置状态构建器 | + | `plugin-sdk/setup-runtime` | 设置时运行时辅助函数 | 可安全导入的设置补丁适配器、查找说明辅助函数、`promptResolvedAllowFrom`、`splitSetupEntries`、委派设置代理 | | `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助函数 | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | 设置工具辅助函数 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户辅助函数 | 账户列表 / 配置 / action-gate 辅助函数 | + | `plugin-sdk/account-core` | 多账户辅助函数 | 账户列表 / 配置 / 操作门控辅助函数 | | `plugin-sdk/account-id` | account-id 辅助函数 | `DEFAULT_ACCOUNT_ID`、account-id 规范化 | | `plugin-sdk/account-resolution` | 账户查找辅助函数 | 账户查找 + 默认回退辅助函数 | | `plugin-sdk/account-helpers` | 窄范围账户辅助函数 | 账户列表 / 账户操作辅助函数 | - | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/channel-pairing` | 私信 配对原语 | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 正在输入接线 | `createChannelReplyPipeline` | + | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` | + | `plugin-sdk/channel-pairing` | 私信配对原语 | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 输入中状态线路 | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 共享渠道配置 schema 原语；带内置渠道名称的 schema 导出仅用于旧版兼容性 | - | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助函数 | 命令名称规范化、描述裁剪、重复 / 冲突校验 | - | `plugin-sdk/channel-policy` | 群组 / 私信 策略解析 | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | 账户状态和草稿流生命周期辅助函数 | `createAccountStatusSink`、草稿预览完成辅助函数 | - | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助函数 | 共享 route + envelope 构建辅助函数 | - | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助函数 | 共享 record-and-dispatch 辅助函数 | + | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 共享渠道配置 schema 原语；以内置渠道命名的 schema 导出仅用于旧版兼容性 | + | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助函数 | 命令名规范化、描述裁剪、重复 / 冲突校验 | + | `plugin-sdk/channel-policy` | 群组 / 私信策略解析 | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-lifecycle` | 账户状态和草稿流生命周期辅助函数 | `createAccountStatusSink`、草稿预览收尾辅助函数 | + | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助函数 | 共享路由 + envelope 构建器辅助函数 | + | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助函数 | 共享记录并分发辅助函数 | | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析 / 匹配辅助函数 | | `plugin-sdk/outbound-media` | 出站媒体辅助函数 | 共享出站媒体加载 | - | `plugin-sdk/outbound-runtime` | 出站运行时辅助函数 | 出站身份 / 发送委托和负载规划辅助函数 | + | `plugin-sdk/outbound-runtime` | 出站运行时辅助函数 | 出站身份 / 发送委派和载荷规划辅助函数 | | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助函数 | 线程绑定生命周期和适配器辅助函数 | - | `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助函数 | 用于旧版字段布局的智能体媒体负载构建器 | - | `plugin-sdk/channel-runtime` | 已弃用的兼容性垫片 | 仅限旧版渠道运行时工具 | + | `plugin-sdk/agent-media-payload` | 旧版媒体载荷辅助函数 | 面向旧字段布局的智能体媒体载荷构建器 | + | `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅保留旧版渠道运行时工具 | | `plugin-sdk/channel-send-result` | 发送结果类型 | 回复结果类型 | | `plugin-sdk/runtime-store` | 持久化插件存储 | `createPluginRuntimeStore` | | `plugin-sdk/runtime` | 宽范围运行时辅助函数 | 运行时 / 日志 / 备份 / 插件安装辅助函数 | - | `plugin-sdk/runtime-env` | 窄范围运行时环境辅助函数 | Logger / 运行时环境、超时、重试和退避辅助函数 | + | `plugin-sdk/runtime-env` | 窄范围运行时环境辅助函数 | 日志器 / 运行时环境、超时、重试和退避辅助函数 | | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助函数 | 插件命令 / 钩子 / http / 交互式辅助函数 | | `plugin-sdk/hook-runtime` | 钩子流水线辅助函数 | 共享 webhook / 内部钩子流水线辅助函数 | | `plugin-sdk/lazy-runtime` | 惰性运行时辅助函数 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | @@ -253,105 +259,105 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | `plugin-sdk/cli-runtime` | CLI 运行时辅助函数 | 命令格式化、等待、版本辅助函数 | | `plugin-sdk/gateway-runtime` | Gateway 网关辅助函数 | Gateway 网关客户端和渠道状态补丁辅助函数 | | `plugin-sdk/config-runtime` | 配置辅助函数 | 配置加载 / 写入辅助函数 | - | `plugin-sdk/telegram-command-config` | Telegram 命令辅助函数 | 当内置 Telegram 契约接口不可用时，提供回退稳定的 Telegram 命令校验辅助函数 | - | `plugin-sdk/approval-runtime` | 审批提示辅助函数 | exec / 插件审批负载、approval capability / profile 辅助函数、原生审批路由 / 运行时辅助函数 | - | `plugin-sdk/approval-auth-runtime` | 审批认证辅助函数 | approver 解析、同聊天操作认证 | - | `plugin-sdk/approval-client-runtime` | 审批客户端辅助函数 | 原生 exec 审批 profile / filter 辅助函数 | - | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助函数 | 原生 approval capability / delivery 适配器 | + | `plugin-sdk/telegram-command-config` | Telegram 命令辅助函数 | 当内置 Telegram 契约接口不可用时，提供具备稳定回退行为的 Telegram 命令校验辅助函数 | + | `plugin-sdk/approval-runtime` | 审批提示辅助函数 | exec / 插件审批载荷、审批能力 / 配置文件辅助函数、原生审批路由 / 运行时辅助函数，以及结构化审批显示路径格式化 | + | `plugin-sdk/approval-auth-runtime` | 审批认证辅助函数 | 审批人解析、同聊天操作认证 | + | `plugin-sdk/approval-client-runtime` | 审批客户端辅助函数 | 原生 exec 审批配置文件 / 过滤器辅助函数 | + | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助函数 | 原生审批能力 / 投递适配器 | | `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关辅助函数 | 共享审批 Gateway 网关解析辅助函数 | - | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助函数 | 用于热渠道入口点的轻量级原生审批适配器加载辅助函数 | - | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助函数 | 范围更广的审批处理器运行时辅助函数；如果更窄的 adapter / gateway 接口已足够，优先使用它们 | + | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助函数 | 用于高频渠道入口点的轻量级原生审批适配器加载辅助函数 | + | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助函数 | 范围更广的审批处理器运行时辅助函数；如果较窄的 adapter / gateway 接口已足够，则优先使用后者 | | `plugin-sdk/approval-native-runtime` | 审批目标辅助函数 | 原生审批目标 / 账户绑定辅助函数 | - | `plugin-sdk/approval-reply-runtime` | 审批回复辅助函数 | exec / 插件审批回复负载辅助函数 | + | `plugin-sdk/approval-reply-runtime` | 审批回复辅助函数 | exec / 插件审批回复载荷辅助函数 | | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助函数 | 通用渠道运行时上下文 register / get / watch 辅助函数 | - | `plugin-sdk/security-runtime` | 安全辅助函数 | 共享信任、私信 门控、外部内容和密钥收集辅助函数 | + | `plugin-sdk/security-runtime` | 安全辅助函数 | 共享信任、私信门控、外部内容和密钥收集辅助函数 | | `plugin-sdk/ssrf-policy` | SSRF 策略辅助函数 | 主机 allowlist 和私有网络策略辅助函数 | - | `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助函数 | pinned-dispatcher、guarded fetch、SSRF 策略辅助函数 | + | `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助函数 | 固定 dispatcher、受保护 fetch、SSRF 策略辅助函数 | | `plugin-sdk/collection-runtime` | 有界缓存辅助函数 | `pruneMapToMaxSize` | | `plugin-sdk/diagnostic-runtime` | 诊断门控辅助函数 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | | `plugin-sdk/error-runtime` | 错误格式化辅助函数 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助函数 | - | `plugin-sdk/fetch-runtime` | 封装 fetch / proxy 辅助函数 | `resolveFetch`、proxy 辅助函数 | + | `plugin-sdk/fetch-runtime` | 包装后的 fetch / 代理辅助函数 | `resolveFetch`、代理辅助函数 | | `plugin-sdk/host-runtime` | 主机规范化辅助函数 | `normalizeHostname`, `normalizeScpRemoteHost` | | `plugin-sdk/retry-runtime` | 重试辅助函数 | `RetryConfig`, `retryAsync`、策略运行器 | - | `plugin-sdk/allow-from` | allowlist 格式化 | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | allowlist 输入映射 | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | 命令门控和命令接口辅助函数 | `resolveControlCommandGate`、发送方授权辅助函数、命令注册表辅助函数 | + | `plugin-sdk/allow-from` | Allowlist 格式化 | `formatAllowFromLowercase` | + | `plugin-sdk/allowlist-resolution` | Allowlist 输入映射 | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | 命令门控和命令接口辅助函数 | `resolveControlCommandGate`、发送者授权辅助函数、命令注册表辅助函数 | | `plugin-sdk/command-status` | 命令状态 / 帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | | `plugin-sdk/secret-input` | 密钥输入解析 | 密钥输入辅助函数 | - | `plugin-sdk/webhook-ingress` | webhook 请求辅助函数 | webhook 目标工具 | - | `plugin-sdk/webhook-request-guards` | webhook 请求体守卫辅助函数 | 请求体读取 / 限制辅助函数 | + | `plugin-sdk/webhook-ingress` | Webhook 请求辅助函数 | Webhook 目标工具函数 | + | `plugin-sdk/webhook-request-guards` | Webhook 请求体保护辅助函数 | 请求体读取 / 限制辅助函数 | | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 | - | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助函数 | 完成、提供商分发和会话标签辅助函数 | + | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助函数 | 收尾、提供商分发和会话标签辅助函数 | | `plugin-sdk/reply-history` | 回复历史辅助函数 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | 回复引用规划 | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 回复分块辅助函数 | 文本 / markdown 分块辅助函数 | + | `plugin-sdk/reply-chunking` | 回复分块辅助函数 | 文本 / Markdown 分块辅助函数 | | `plugin-sdk/session-store-runtime` | 会话存储辅助函数 | 存储路径 + updated-at 辅助函数 | - | `plugin-sdk/state-paths` | 状态路径辅助函数 | 状态和 OAuth 目录辅助函数 | + | `plugin-sdk/state-paths` | 状态路径辅助函数 | 状态目录和 OAuth 目录辅助函数 | | `plugin-sdk/routing` | 路由 / session-key 辅助函数 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、session-key 规范化辅助函数 | | `plugin-sdk/status-helpers` | 渠道状态辅助函数 | 渠道 / 账户状态摘要构建器、运行时状态默认值、问题元数据辅助函数 | | `plugin-sdk/target-resolver-runtime` | 目标解析器辅助函数 | 共享目标解析器辅助函数 | | `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助函数 | slug / 字符串规范化辅助函数 | - | `plugin-sdk/request-url` | 请求 URL 辅助函数 | 从类请求输入中提取字符串 URL | + | `plugin-sdk/request-url` | 请求 URL 辅助函数 | 从类似请求的输入中提取字符串 URL | | `plugin-sdk/run-command` | 定时命令辅助函数 | 带标准化 stdout / stderr 的定时命令运行器 | | `plugin-sdk/param-readers` | 参数读取器 | 通用工具 / CLI 参数读取器 | - | `plugin-sdk/tool-payload` | 工具负载提取 | 从工具结果对象中提取标准化负载 | - | `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范发送目标字段 | + | `plugin-sdk/tool-payload` | 工具载荷提取 | 从工具结果对象中提取标准化载荷 | + | `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范的发送目标字段 | | `plugin-sdk/temp-path` | 临时路径辅助函数 | 共享临时下载路径辅助函数 | - | `plugin-sdk/logging-core` | 日志辅助函数 | 子系统 logger 和脱敏辅助函数 | + | `plugin-sdk/logging-core` | 日志辅助函数 | 子系统日志器和脱敏辅助函数 | | `plugin-sdk/markdown-table-runtime` | Markdown 表格辅助函数 | Markdown 表格模式辅助函数 | - | `plugin-sdk/reply-payload` | 消息回复类型 | 回复负载类型 | - | `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助函数 | 自托管提供商发现 / 配置辅助函数 | - | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管提供商设置辅助函数 | 相同的自托管提供商发现 / 配置辅助函数 | + | `plugin-sdk/reply-payload` | 消息回复类型 | 回复载荷类型 | + | `plugin-sdk/provider-setup` | 面向本地 / 自托管提供商的精选设置辅助函数 | 自托管提供商发现 / 配置辅助函数 | + | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管提供商设置辅助函数 | 同一组自托管提供商发现 / 配置辅助函数 | | `plugin-sdk/provider-auth-runtime` | 提供商运行时认证辅助函数 | 运行时 API key 解析辅助函数 | - | `plugin-sdk/provider-auth-api-key` | 提供商 API key 设置辅助函数 | API key 新手引导 / profile 写入辅助函数 | - | `plugin-sdk/provider-auth-result` | 提供商 auth-result 辅助函数 | 标准 OAuth auth-result 构建器 | + | `plugin-sdk/provider-auth-api-key` | 提供商 API key 设置辅助函数 | API key 新手引导 / 配置文件写入辅助函数 | + | `plugin-sdk/provider-auth-result` | 提供商认证结果辅助函数 | 标准 OAuth 认证结果构建器 | | `plugin-sdk/provider-auth-login` | 提供商交互式登录辅助函数 | 共享交互式登录辅助函数 | | `plugin-sdk/provider-selection-runtime` | 提供商选择辅助函数 | 已配置或自动提供商选择，以及原始提供商配置合并 | | `plugin-sdk/provider-env-vars` | 提供商环境变量辅助函数 | 提供商认证环境变量查找辅助函数 | - | `plugin-sdk/provider-model-shared` | 共享提供商模型 / 重放辅助函数 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助函数以及 model-id 规范化辅助函数 | + | `plugin-sdk/provider-model-shared` | 共享提供商模型 / 重放辅助函数 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略构建器、提供商端点辅助函数，以及 model-id 规范化辅助函数 | | `plugin-sdk/provider-catalog-shared` | 共享提供商目录辅助函数 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | | `plugin-sdk/provider-onboard` | 提供商新手引导补丁 | 新手引导配置辅助函数 | - | `plugin-sdk/provider-http` | 提供商 HTTP 辅助函数 | 通用提供商 HTTP / endpoint capability 辅助函数，包括音频转录 multipart form 辅助函数 | + | `plugin-sdk/provider-http` | 提供商 HTTP 辅助函数 | 通用提供商 HTTP / 端点能力辅助函数，包括音频转录 multipart 表单辅助函数 | | `plugin-sdk/provider-web-fetch` | 提供商 web-fetch 辅助函数 | web-fetch 提供商注册 / 缓存辅助函数 | - | `plugin-sdk/provider-web-search-config-contract` | 提供商 web-search 配置辅助函数 | 面向不需要插件启用接线的提供商的窄范围 web-search 配置 / 凭证辅助函数 | - | `plugin-sdk/provider-web-search-contract` | 提供商 web-search 契约辅助函数 | 窄范围 web-search 配置 / 凭证契约辅助函数，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` 以及作用域凭证 setter / getter | + | `plugin-sdk/provider-web-search-config-contract` | 提供商 web-search 配置辅助函数 | 面向无需插件启用线路的提供商的窄范围 web-search 配置 / 凭证辅助函数 | + | `plugin-sdk/provider-web-search-contract` | 提供商 web-search 契约辅助函数 | 窄范围 web-search 配置 / 凭证契约辅助函数，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig`，以及作用域化凭证 setter / getter | | `plugin-sdk/provider-web-search` | 提供商 web-search 辅助函数 | web-search 提供商注册 / 缓存 / 运行时辅助函数 | - | `plugin-sdk/provider-tools` | 提供商工具 / schema 兼容性辅助函数 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-tools` | 提供商工具 / schema 兼容辅助函数 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 xAI 兼容辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | 提供商用量辅助函数 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` 以及其他提供商用量辅助函数 | - | `plugin-sdk/provider-stream` | 提供商流包装辅助函数 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装类型，以及共享 Anthropic / Bedrock / Google / Kilocode / Moonshot AI / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装辅助函数 | - | `plugin-sdk/provider-transport-runtime` | 提供商传输辅助函数 | 原生提供商传输辅助函数，例如 guarded fetch、传输消息转换以及可写传输事件流 | + | `plugin-sdk/provider-stream` | 提供商流包装辅助函数 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装辅助函数 | + | `plugin-sdk/provider-transport-runtime` | 提供商传输辅助函数 | 原生提供商传输辅助函数，例如受保护 fetch、传输消息转换和可写传输事件流 | | `plugin-sdk/keyed-async-queue` | 有序异步队列 | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | 共享媒体辅助函数 | 媒体获取 / 转换 / 存储辅助函数，以及媒体负载构建器 | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助函数 | 图像 / 视频 / 音乐生成的共享故障转移辅助函数、候选项选择以及缺失模型消息 | - | `plugin-sdk/media-understanding` | 媒体理解辅助函数 | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助导出 | - | `plugin-sdk/text-runtime` | 共享文本辅助函数 | 对助手可见文本的剥离、markdown 渲染 / 分块 / 表格辅助函数、脱敏辅助函数、directive-tag 辅助函数、安全文本工具以及相关文本 / 日志辅助函数 | + | `plugin-sdk/media-runtime` | 共享媒体辅助函数 | 媒体获取 / 转换 / 存储辅助函数，以及媒体载荷构建器 | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助函数 | 共享故障转移辅助函数、候选项选择，以及用于图像 / 视频 / 音乐生成的缺失模型提示 | + | `plugin-sdk/media-understanding` | 媒体理解辅助函数 | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助函数导出 | + | `plugin-sdk/text-runtime` | 共享文本辅助函数 | 面向助手可见文本剥离、Markdown 渲染 / 分块 / 表格辅助函数、脱敏辅助函数、指令标签辅助函数、安全文本工具，以及相关文本 / 日志辅助函数 | | `plugin-sdk/text-chunking` | 文本分块辅助函数 | 出站文本分块辅助函数 | - | `plugin-sdk/speech` | 语音辅助函数 | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助函数 | - | `plugin-sdk/speech-core` | 共享语音核心 | 语音提供商类型、注册表、directives、规范化 | - | `plugin-sdk/realtime-transcription` | 实时转录辅助函数 | 提供商类型、注册表辅助函数以及共享 WebSocket 会话辅助函数 | - | `plugin-sdk/realtime-voice` | 实时语音辅助函数 | 提供商类型、注册表 / 解析辅助函数以及桥接会话辅助函数 | + | `plugin-sdk/speech` | 语音辅助函数 | 语音提供商类型，以及面向提供商的指令、注册表和校验辅助函数 | + | `plugin-sdk/speech-core` | 共享语音核心 | 语音提供商类型、注册表、指令、规范化 | + | `plugin-sdk/realtime-transcription` | 实时转录辅助函数 | 提供商类型、注册表辅助函数和共享 WebSocket 会话辅助函数 | + | `plugin-sdk/realtime-voice` | 实时语音辅助函数 | 提供商类型、注册表 / 解析辅助函数和桥接会话辅助函数 | | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、认证和注册表辅助函数 | | `plugin-sdk/music-generation` | 音乐生成辅助函数 | 音乐生成提供商 / 请求 / 结果类型 | | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 | | `plugin-sdk/video-generation` | 视频生成辅助函数 | 视频生成提供商 / 请求 / 结果类型 | | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 | - | `plugin-sdk/interactive-runtime` | 交互式回复辅助函数 | 交互式回复负载规范化 / 归约 | + | `plugin-sdk/interactive-runtime` | 交互式回复辅助函数 | 交互式回复载荷规范化 / 缩减 | | `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄范围渠道 config-schema 原语 | - | `plugin-sdk/channel-config-writes` | 渠道 config-write 辅助函数 | 渠道 config-write 授权辅助函数 | + | `plugin-sdk/channel-config-writes` | 渠道配置写入辅助函数 | 渠道配置写入授权辅助函数 | | `plugin-sdk/channel-plugin-common` | 共享渠道前导模块 | 共享渠道插件前导导出 | | `plugin-sdk/channel-status` | 渠道状态辅助函数 | 共享渠道状态快照 / 摘要辅助函数 | - | `plugin-sdk/allowlist-config-edit` | allowlist 配置辅助函数 | allowlist 配置编辑 / 读取辅助函数 | + | `plugin-sdk/allowlist-config-edit` | Allowlist 配置辅助函数 | Allowlist 配置编辑 / 读取辅助函数 | | `plugin-sdk/group-access` | 群组访问辅助函数 | 共享群组访问决策辅助函数 | - | `plugin-sdk/direct-dm` | 直接私信辅助函数 | 共享直接私信 认证 / 守卫辅助函数 | + | `plugin-sdk/direct-dm` | 直接私信辅助函数 | 共享直接私信认证 / 保护辅助函数 | | `plugin-sdk/extension-shared` | 共享扩展辅助函数 | 被动渠道 / 状态和环境代理辅助原语 | - | `plugin-sdk/webhook-targets` | webhook 目标辅助函数 | webhook 目标注册表和 route-install 辅助函数 | - | `plugin-sdk/webhook-path` | webhook 路径辅助函数 | webhook 路径规范化辅助函数 | - | `plugin-sdk/web-media` | 共享 Web 媒体辅助函数 | 远程 / 本地媒体加载辅助函数 | - | `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用方重新导出的 `zod` | - | `plugin-sdk/memory-core` | 内置 memory-core 辅助函数 | Memory 核心管理器 / 配置 / 文件 / CLI 辅助接口 | - | `plugin-sdk/memory-core-engine-runtime` | Memory 引擎运行时外观 | Memory 索引 / 搜索运行时外观 | + | `plugin-sdk/webhook-targets` | Webhook 目标辅助函数 | Webhook 目标注册表和路由安装辅助函数 | + | `plugin-sdk/webhook-path` | Webhook 路径辅助函数 | Webhook 路径规范化辅助函数 | + | `plugin-sdk/web-media` | 共享 web 媒体辅助函数 | 远程 / 本地媒体加载辅助函数 | + | `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用者重新导出的 `zod` | + | `plugin-sdk/memory-core` | 内置 memory-core 辅助函数 | Memory 管理器 / 配置 / 文件 / CLI 辅助接口 | + | `plugin-sdk/memory-core-engine-runtime` | Memory 引擎运行时门面 | Memory 索引 / 搜索运行时门面 | | `plugin-sdk/memory-core-host-engine-foundation` | Memory 宿主基础引擎 | Memory 宿主基础引擎导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 宿主嵌入引擎 | Memory 嵌入契约、注册表访问、本地提供商以及通用批处理 / 远程辅助函数；具体远程提供商位于其所属插件中 | + | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 宿主嵌入引擎 | Memory 嵌入契约、注册表访问、本地提供商和通用批处理 / 远程辅助函数；具体远程提供商位于其所属插件中 | | `plugin-sdk/memory-core-host-engine-qmd` | Memory 宿主 QMD 引擎 | Memory 宿主 QMD 引擎导出 | | `plugin-sdk/memory-core-host-engine-storage` | Memory 宿主存储引擎 | Memory 宿主存储引擎导出 | | `plugin-sdk/memory-core-host-multimodal` | Memory 宿主多模态辅助函数 | Memory 宿主多模态辅助函数 | @@ -362,60 +368,62 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | `plugin-sdk/memory-core-host-runtime-cli` | Memory 宿主 CLI 运行时 | Memory 宿主 CLI 运行时辅助函数 | | `plugin-sdk/memory-core-host-runtime-core` | Memory 宿主核心运行时 | Memory 宿主核心运行时辅助函数 | | `plugin-sdk/memory-core-host-runtime-files` | Memory 宿主文件 / 运行时辅助函数 | Memory 宿主文件 / 运行时辅助函数 | - | `plugin-sdk/memory-host-core` | Memory 宿主核心运行时别名 | 面向供应商中立的 Memory 宿主核心运行时辅助函数别名 | - | `plugin-sdk/memory-host-events` | Memory 宿主事件日志别名 | 面向供应商中立的 Memory 宿主事件日志辅助函数别名 | - | `plugin-sdk/memory-host-files` | Memory 宿主文件 / 运行时别名 | 面向供应商中立的 Memory 宿主文件 / 运行时辅助函数别名 | - | `plugin-sdk/memory-host-markdown` | 托管 markdown 辅助函数 | 面向与 Memory 邻接插件的共享托管 markdown 辅助函数 | - | `plugin-sdk/memory-host-search` | 活跃 Memory 搜索外观 | 惰性活跃 Memory search-manager 运行时外观 | - | `plugin-sdk/memory-host-status` | Memory 宿主状态别名 | 面向供应商中立的 Memory 宿主状态辅助函数别名 | + | `plugin-sdk/memory-host-core` | Memory 宿主核心运行时别名 | 面向厂商中立的 Memory 宿主核心运行时辅助函数别名 | + | `plugin-sdk/memory-host-events` | Memory 宿主事件日志别名 | 面向厂商中立的 Memory 宿主事件日志辅助函数别名 | + | `plugin-sdk/memory-host-files` | Memory 宿主文件 / 运行时别名 | 面向厂商中立的 Memory 宿主文件 / 运行时辅助函数别名 | + | `plugin-sdk/memory-host-markdown` | 托管 Markdown 辅助函数 | 面向 Memory 相邻插件的共享托管 Markdown 辅助函数 | + | `plugin-sdk/memory-host-search` | 活动 Memory 搜索门面 | 惰性活动 Memory 搜索管理器运行时门面 | + | `plugin-sdk/memory-host-status` | Memory 宿主状态别名 | 面向厂商中立的 Memory 宿主状态辅助函数别名 | | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助函数 | Memory-lancedb 辅助接口 | | `plugin-sdk/testing` | 测试工具 | 测试辅助函数和 mocks | 这个表刻意只包含常见迁移子集，而不是完整的 SDK -接口。完整的 200+ 个入口点列表位于 +接口面。完整的 200+ 个入口点列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 该列表仍然包含一些内置插件辅助接口，例如 -`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些接口仍会继续导出， -用于内置插件维护和兼容性，但它们被有意省略在常见迁移表之外，也不是 -新插件代码推荐使用的目标。 +`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、 +`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些导出仍会保留， +用于内置插件维护和兼容性，但它们被有意排除在常见迁移表之外， +也不是新插件代码的推荐目标。 -同样的规则也适用于其他内置辅助函数家族，例如： +同样的规则也适用于其他内置辅助接口族，例如： -- 浏览器支持辅助函数：`plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` +- 浏览器支持辅助函数：`plugin-sdk/browser-cdp`、`plugin-sdk/browser-config-runtime`、`plugin-sdk/browser-config-support`、`plugin-sdk/browser-control-auth`、`plugin-sdk/browser-node-runtime`、`plugin-sdk/browser-profiles`、`plugin-sdk/browser-security-runtime`、`plugin-sdk/browser-setup-tools`、`plugin-sdk/browser-support` - Matrix：`plugin-sdk/matrix*` - LINE：`plugin-sdk/line*` - IRC：`plugin-sdk/irc*` -- 内置辅助函数 / 插件接口，例如 `plugin-sdk/googlechat`, - `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, - `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, - `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, - `plugin-sdk/twitch`, - `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, - `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, +- 内置辅助函数 / 插件接口，例如 `plugin-sdk/googlechat`、 + `plugin-sdk/zalouser`、`plugin-sdk/bluebubbles*`、 + `plugin-sdk/mattermost*`、`plugin-sdk/msteams`、 + `plugin-sdk/nextcloud-talk`、`plugin-sdk/nostr`、`plugin-sdk/tlon`、 + `plugin-sdk/twitch`、 + `plugin-sdk/github-copilot-login`、`plugin-sdk/github-copilot-token`、 + `plugin-sdk/diagnostics-otel`、`plugin-sdk/diffs`、`plugin-sdk/llm-task`、 `plugin-sdk/thread-ownership` 和 `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` 当前暴露了窄范围的令牌辅助接口 -`DEFAULT_COPILOT_API_BASE_URL`, +`plugin-sdk/github-copilot-token` 当前公开的是窄范围 token 辅助接口 +`DEFAULT_COPILOT_API_BASE_URL`、 `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。 -请使用与任务最匹配的最窄导入路径。如果你找不到某个导出， -请检查 `src/plugin-sdk/` 中的源码，或在 Discord 中提问。 +请使用最符合当前任务的最窄导入路径。如果你找不到某个导出， +请查看 `src/plugin-sdk/` 中的源码，或在 Discord 中提问。 ## 当前弃用项 -以下是横跨插件 SDK、提供商契约、运行时接口和清单的更窄范围弃用项。它们目前仍然可用，但将在未来的主要版本中移除。每个条目下方都给出了旧 API 到其规范替代方案的映射。 +这些更窄范围的弃用项适用于整个插件 SDK、提供商契约、 +运行时接口和清单。它们目前仍然可用，但将在未来的主要版本中移除。 +每个条目下方都给出了旧 API 与其规范替代方案的映射。 - - **旧版（`openclaw/plugin-sdk/command-auth`）**：`buildCommandsMessage`, - `buildCommandsMessagePaginated`, `buildHelpMessage`。 + + **旧版（`openclaw/plugin-sdk/command-auth`）**：`buildCommandsMessage`、 + `buildCommandsMessagePaginated`、`buildHelpMessage`。 - **新版（`openclaw/plugin-sdk/command-status`）**：签名相同，导出相同—— - 只是从更窄的子路径导入。`command-auth` - 将它们重新导出为兼容性桩。 + **新版（`openclaw/plugin-sdk/command-status`）**：签名相同，导出也相同—— + 只是改为从更窄的子路径导入。`command-auth` + 会将它们作为兼容性 stub 重新导出。 ```typescript // Before @@ -427,95 +435,93 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - + **旧版**：`resolveInboundMentionRequirement({ facts, policy })` 和 `shouldDropInboundForMention(...)`，来自 `openclaw/plugin-sdk/channel-inbound` 或 `openclaw/plugin-sdk/channel-mention-gating`。 - **新版**：`resolveInboundMentionDecision({ facts, policy })` —— 返回一个 + **新版**：`resolveInboundMentionDecision({ facts, policy })` —— 它返回一个 单一决策对象，而不是拆分为两个调用。 - 下游渠道插件（Slack、Discord、Matrix、Microsoft Teams）已经完成切换。 + 下游渠道插件（Slack、Discord、Matrix、MS Teams）已全部完成切换。 - - `openclaw/plugin-sdk/channel-runtime` 是为较旧 - 渠道插件提供的兼容性垫片。新代码不要导入它；请使用 + + `openclaw/plugin-sdk/channel-runtime` 是面向旧渠道插件的兼容性 shim。 + 新代码不要导入它；请改用 `openclaw/plugin-sdk/channel-runtime-context` 来注册运行时 对象。 - `openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` 辅助函数 - 已与原始 “actions” 渠道导出一起弃用。请改为通过语义化的 - `presentation` 接口暴露能力——渠道插件声明它们能渲染什么 - （cards、buttons、selects），而不是声明它们接受哪些原始 - action 名称。 + `openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` + 辅助函数也已随原始 “actions” 渠道导出一同弃用。请改为通过语义化的 + `presentation` 接口暴露能力——渠道插件应声明它们能渲染什么 + （卡片、按钮、选择器），而不是声明它们接受哪些原始操作名称。 - + **旧版**：来自 `openclaw/plugin-sdk/provider-web-search` 的 `tool()` - 工厂。 + 工厂函数。 **新版**：直接在提供商插件上实现 `createTool(...)`。 - OpenClaw 不再需要 SDK 辅助函数来注册工具包装器。 + OpenClaw 不再需要 SDK 辅助函数来注册该工具包装器。 - + **旧版**：`formatInboundEnvelope(...)`（以及 `ChannelMessageForAgent.channelEnvelope`），用于从入站渠道消息构建 - 扁平纯文本提示 envelope。 + 扁平的纯文本提示 envelope。 - **新版**：`BodyForAgent` 加结构化用户上下文块。渠道 - 插件会将路由元数据（thread、topic、reply-to、reactions）作为 - 类型化字段附加，而不是把它们拼接进提示字符串中。 - `formatAgentEnvelope(...)` 辅助函数仍然支持用于合成的、 - 面向助手的 envelope，但入站纯文本 envelope 正在被逐步淘汰。 + **新版**：`BodyForAgent` 加上结构化用户上下文块。 + 渠道插件会将路由元数据（线程、主题、reply-to、reactions）作为 + 类型化字段附加，而不是将它们拼接到提示字符串中。 + `formatAgentEnvelope(...)` 辅助函数仍支持用于合成面向助手的 + envelope，但入站纯文本 envelope 正在逐步淘汰。 - 受影响区域：`inbound_claim`、`message_received`，以及任何对 - `channelEnvelope` 文本做后处理的自定义渠道插件。 + 受影响区域：`inbound_claim`、`message_received`，以及任何会对 + `channelEnvelope` 文本进行后处理的自定义渠道插件。 - - 四个 discovery 类型别名现在只是对 - catalog 时代类型的轻量封装： + + 四个发现类型别名现在只是目录时代类型的薄包装： | 旧别名 | 新类型 | | ------------------------- | ------------------------- | - | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` | - | `ProviderDiscoveryContext`| `ProviderCatalogContext` | - | `ProviderDiscoveryResult` | `ProviderCatalogResult` | - | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | + | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` | + | `ProviderDiscoveryContext`| `ProviderCatalogContext` | + | `ProviderDiscoveryResult` | `ProviderCatalogResult` | + | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | - 以及旧版的 `ProviderCapabilities` 静态集合——提供商插件 + 另外，旧版的 `ProviderCapabilities` 静态集合也已不再推荐——提供商插件 应通过提供商运行时契约附加能力事实，而不是使用静态对象。 - - **旧版**（`ProviderThinkingPolicy` 上三个独立钩子）： + + **旧版**（`ProviderThinkingPolicy` 上分散的三个钩子）： `isBinaryThinking(ctx)`、`supportsXHighThinking(ctx)` 和 `resolveDefaultThinkingLevel(ctx)`。 - **新版**：单个 `resolveThinkingProfile(ctx)`，返回一个 - `ProviderThinkingProfile`，包含规范 `id`、可选 `label` 以及 - 按级别排序的列表。OpenClaw 会按 profile 排名自动降级过期的已存储值。 + **新版**：单个 `resolveThinkingProfile(ctx)`，它返回一个 + `ProviderThinkingProfile`，其中包含规范的 `id`、可选的 `label` 以及 + 已排序的级别列表。OpenClaw 会按 profile 排名自动降级过时的已存储值。 - 只需实现一个钩子，而不是三个。旧版钩子在弃用窗口期间仍可使用， - 但不会与 profile 结果进行组合。 + 现在只需实现一个钩子，而不是三个。旧版钩子在弃用窗口期间仍可继续使用， + 但不会与 profile 结果组合。 - - **旧版**：在插件清单中未声明提供商的情况下，实现 - `resolveExternalOAuthProfiles(...)`。 + + **旧版**：实现 `resolveExternalOAuthProfiles(...)`， + 但不在插件清单中声明该提供商。 **新版**：在插件清单中声明 `contracts.externalAuthProviders` - **并且**实现 `resolveExternalAuthProfiles(...)`。旧的 “auth - fallback” 路径会在运行时发出警告，并将在后续移除。 + **并且**实现 `resolveExternalAuthProfiles(...)`。旧版 “auth + fallback” 路径会在运行时发出警告，并将在之后被移除。 ```json { @@ -527,19 +533,19 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - - **旧版**清单字段：`providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`。 + + **旧版** 清单字段：`providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`。 - **新版**：将相同的环境变量查找镜像到清单中的 `setup.providers[].envVars` - 中。这样可以把设置 / 状态环境变量元数据整合到一个位置， - 并避免仅仅为了回答环境变量查找而启动插件运行时。 + **新版**：将相同的环境变量查找镜像到清单中的 `setup.providers[].envVars`。 + 这样可以将设置 / 状态环境变量元数据统一到一个位置， + 并避免仅为回答环境变量查找而启动插件运行时。 - `providerAuthEnvVars` 仍然通过兼容适配器支持， + `providerAuthEnvVars` 会通过兼容适配器继续受支持， 直到弃用窗口结束。 - + **旧版**：三个独立调用—— `api.registerMemoryPromptSection(...)`、 `api.registerMemoryFlushPlan(...)`、 @@ -548,22 +554,22 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 **新版**：在 memory-state API 上使用一个调用—— `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`。 - 相同插槽，单次注册调用。附加型 Memory 辅助函数 - （`registerMemoryPromptSupplement`, `registerMemoryCorpusSupplement`, + 插槽相同，但统一为单次注册调用。增量式 Memory 辅助函数 + （`registerMemoryPromptSupplement`、`registerMemoryCorpusSupplement`、 `registerMemoryEmbeddingProvider`）不受影响。 - - 仍从 `src/plugins/runtime/types.ts` 导出的两个旧版类型别名： + + 仍然从 `src/plugins/runtime/types.ts` 导出的两个旧类型别名： | 旧版 | 新版 | | ----------------------------- | ------------------------------- | - | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | - | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | + | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | + | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | - 运行时方法 `readSession` 已弃用，改用 - `getSessionMessages`。签名相同；旧方法会直接调用 + 运行时方法 `readSession` 已弃用，推荐改用 + `getSessionMessages`。签名相同；旧方法会转调到 新方法。 @@ -572,7 +578,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 **旧版**：`runtime.tasks.flow`（单数）返回一个实时 task-flow 访问器。 **新版**：`runtime.tasks.flows`（复数）返回基于 DTO 的 TaskFlow 访问， - 它具备导入安全性，且不需要加载完整任务运行时。 + 这种方式可安全导入，且不需要加载完整任务运行时。 ```typescript // Before @@ -583,18 +589,18 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - - 上文“如何迁移 → 将 Pi 工具结果扩展迁移到中间件”中已涵盖。这里列出 - 仅为完整性考虑：已移除的、仅限 Pi 的 - `api.registerEmbeddedExtensionFactory(...)` 路径现由 - `api.registerAgentToolResultMiddleware(...)` 替代，并在 - `contracts.agentToolResultMiddleware` 中提供显式运行时 + + 上文 “如何迁移 → 将 Pi 工具结果扩展迁移到中间件” 已对此进行说明。 + 这里为了完整性再次列出：已移除的、仅限 Pi 的 + `api.registerEmbeddedExtensionFactory(...)` 路径，现替换为 + `api.registerAgentToolResultMiddleware(...)`，并在 + `contracts.agentToolResultMiddleware` 中显式声明运行时 列表。 - - 从 `openclaw/plugin-sdk` 重新导出的 `OpenClawSchemaType` 现在是 - `OpenClawConfig` 的一行别名。请优先使用规范名称。 + + 从 `openclaw/plugin-sdk` 重新导出的 `OpenClawSchemaType` 现在只是 + `OpenClawConfig` 的单行别名。请优先使用规范名称。 ```typescript // Before @@ -609,32 +615,32 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 扩展级弃用项（位于 `extensions/` 下的内置渠道 / 提供商插件内部） 会在它们各自的 `api.ts` 和 `runtime-api.ts` -barrel 中跟踪。它们不会影响第三方插件契约，因此未在此列出。如果你直接 -使用某个内置插件的本地 barrel，请在升级前先阅读该 -barrel 中的弃用注释。 +barrel 中跟踪。它们不会影响第三方插件契约，因此这里不列出。 +如果你直接使用某个内置插件的本地 barrel，请在升级前先阅读 +该 barrel 中的弃用注释。 ## 移除时间线 -| 时间 | 会发生什么 | +| 时间 | 将发生的事情 | | ---------------------- | ----------------------------------------------------------------------- | -| **现在** | 已弃用接口会发出运行时警告 | -| **下一个主要版本** | 已弃用接口将被移除；仍在使用它们的插件将会失败 | +| **现在** | 已弃用接口面会发出运行时警告 | +| **下一个主要版本** | 已弃用接口面将被移除；仍在使用它们的插件将会失效 | -所有核心插件都已经完成迁移。外部插件应在下一个主要版本之前完成迁移。 +所有核心插件都已完成迁移。外部插件应在下一个主要版本之前完成迁移。 ## 临时抑制警告 -在你进行迁移期间，设置这些环境变量： +在迁移期间工作时，可以设置以下环境变量： ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -这只是临时逃生舱口，不是永久解决方案。 +这只是临时的应急出口，不是永久解决方案。 -## 相关内容 +## 相关 - [入门指南](/zh-CN/plugins/building-plugins) — 构建你的第一个插件 - [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考 diff --git a/docs/zh-CN/plugins/sdk-subpaths.md b/docs/zh-CN/plugins/sdk-subpaths.md index f151176fb..9161c4571 100644 --- a/docs/zh-CN/plugins/sdk-subpaths.md +++ b/docs/zh-CN/plugins/sdk-subpaths.md @@ -1,22 +1,23 @@ --- read_when: - - 为插件导入选择合适的 plugin-sdk 子路径 - - 审查 bundled-plugin 子路径和辅助接口 -summary: 插件 SDK 子路径目录：按领域分组，说明各导入路径分别位于何处 + - 为插件导入选择正确的 plugin-sdk 子路径 + - 审查内置插件子路径和辅助接口 +summary: 插件 SDK 子路径目录：按领域分组说明各导入项所在位置 title: 插件 SDK 子路径 x-i18n: - generated_at: "2026-04-24T18:37:19Z" + generated_at: "2026-04-25T01:52:11Z" model: gpt-5.4 provider: openai - source_hash: 502fe07a2e1c8c6d70c5750d7a229e0262ecb94d4e535516a9cb939a8fa3e28c + source_hash: f24d5add576ec0985d8d4335fb244ffcc1b9fc4643b87f4d72d42ec44b138520 source_path: plugins/sdk-subpaths.md workflow: 15 --- - 插件 SDK 通过 `openclaw/plugin-sdk/` 下的一组精简子路径对外暴露。 - 本页按用途对常用子路径进行归类说明。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`；其中也会出现为 bundled-plugin 预留的辅助子路径，但除非文档页面明确将其作为公开能力介绍，否则它们都属于实现细节。 + 插件 SDK 以 `openclaw/plugin-sdk/` 下的一组精细子路径形式公开。 + 本页按用途分组，汇总了常用子路径。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`； + 其中也包含为内置插件保留的辅助子路径，但除非某个文档页面明确将其列为公开能力，否则它们都属于实现细节。 - 关于插件编写指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 + 关于插件编写指南，请参见 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 ## 插件入口 @@ -34,181 +35,182 @@ x-i18n: | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | 根级 `openclaw.json` Zod schema 导出（`OpenClawSchema`） | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | 共享的设置向导辅助函数、allowlist 提示、设置状态构建器 | + | `plugin-sdk/setup` | 共享的设置向导辅助工具、allowlist 提示和设置状态构建器 | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户配置 / action-gate 辅助函数，以及默认账户回退辅助函数 | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助函数 | - | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助函数 | - | `plugin-sdk/account-helpers` | 精简的账户列表 / 账户操作辅助函数 | + | `plugin-sdk/account-core` | 多账户配置 / 操作门控辅助工具，以及默认账户回退辅助工具 | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、账户 id 规范化辅助工具 | + | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助工具 | + | `plugin-sdk/account-helpers` | 精细的账户列表 / 账户操作辅助工具 | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 | - | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化 / 校验辅助函数，带 bundled-contract 回退 | - | `plugin-sdk/command-gating` | 精简的命令授权 gate 辅助函数 | + | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化 / 校验辅助工具，带内置契约回退 | + | `plugin-sdk/command-gating` | 精细的命令授权门控辅助工具 | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 完成辅助函数 | - | `plugin-sdk/inbound-envelope` | 共享的入站路由 + envelope 构建辅助函数 | - | `plugin-sdk/inbound-reply-dispatch` | 共享的入站记录与分发辅助函数 | - | `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助函数 | - | `plugin-sdk/outbound-media` | 共享的出站媒体加载辅助函数 | - | `plugin-sdk/outbound-runtime` | 出站身份、发送委托和负载规划辅助函数 | - | `plugin-sdk/poll-runtime` | 精简的投票规范化辅助函数 | - | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助函数 | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 完成辅助工具 | + | `plugin-sdk/inbound-envelope` | 共享的入站路由 + envelope 构建辅助工具 | + | `plugin-sdk/inbound-reply-dispatch` | 共享的入站记录与分发辅助工具 | + | `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助工具 | + | `plugin-sdk/outbound-media` | 共享的出站媒体加载辅助工具 | + | `plugin-sdk/outbound-runtime` | 出站身份、发送委托和负载规划辅助工具 | + | `plugin-sdk/poll-runtime` | 精细的投票规范化辅助工具 | + | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期与适配器辅助工具 | | `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 | - | `plugin-sdk/conversation-runtime` | 会话 / 线程绑定、配对和已配置绑定辅助函数 | - | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助函数 | - | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助函数 | - | `plugin-sdk/channel-status` | 共享的渠道状态快照 / 摘要辅助函数 | - | `plugin-sdk/channel-config-primitives` | 精简的渠道配置 schema 基元 | - | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助函数 | + | `plugin-sdk/conversation-runtime` | 对话 / 线程绑定、配对和已配置绑定辅助工具 | + | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 | + | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 | + | `plugin-sdk/channel-status` | 共享的渠道状态快照 / 摘要辅助工具 | + | `plugin-sdk/channel-config-primitives` | 精细的渠道配置 schema 基元 | + | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 | | `plugin-sdk/channel-plugin-common` | 共享的渠道插件前导导出 | - | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助函数 | - | `plugin-sdk/group-access` | 共享的群组访问决策辅助函数 | - | `plugin-sdk/direct-dm` | 共享的直接私信认证 / 守卫辅助函数 | - | `plugin-sdk/interactive-runtime` | 语义消息展示、投递以及旧版交互式回复辅助函数。参阅 [消息展示](/zh-CN/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | 兼容性 barrel，包含入站去抖、提及匹配、提及策略辅助函数以及 envelope 辅助函数 | - | `plugin-sdk/channel-inbound-debounce` | 精简的入站去抖辅助函数 | - | `plugin-sdk/channel-mention-gating` | 精简的提及策略和提及文本辅助函数，不包含更广泛的入站运行时接口 | - | `plugin-sdk/channel-envelope` | 精简的入站 envelope 格式化辅助函数 | - | `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助函数 | - | `plugin-sdk/channel-logging` | 用于入站丢弃以及 typing / ack 失败的渠道日志辅助函数 | + | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助工具 | + | `plugin-sdk/group-access` | 共享的群组访问决策辅助工具 | + | `plugin-sdk/direct-dm` | 共享的直接私信认证 / 守卫辅助工具 | + | `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递以及旧版交互式回复辅助工具。参见 [消息呈现](/zh-CN/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | 入站防抖、提及匹配、提及策略辅助工具以及 envelope 辅助工具的兼容性 barrel | + | `plugin-sdk/channel-inbound-debounce` | 精细的入站防抖辅助工具 | + | `plugin-sdk/channel-mention-gating` | 不包含更广泛入站运行时接口的精细提及策略与提及文本辅助工具 | + | `plugin-sdk/channel-envelope` | 精细的入站 envelope 格式化辅助工具 | + | `plugin-sdk/channel-location` | 渠道位置上下文与格式化辅助工具 | + | `plugin-sdk/channel-logging` | 用于入站丢弃和 typing / ack 失败的渠道日志辅助工具 | | `plugin-sdk/channel-send-result` | 回复结果类型 | - | `plugin-sdk/channel-actions` | 渠道消息动作辅助函数，以及为插件兼容性保留的已弃用原生 schema 辅助函数 | - | `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助函数 | + | `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为插件兼容性保留的已弃用原生 schema 辅助工具 | + | `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助工具 | | `plugin-sdk/channel-contract` | 渠道契约类型 | - | `plugin-sdk/channel-feedback` | 反馈 / reaction 连接逻辑 | - | `plugin-sdk/channel-secret-runtime` | 精简的 secret-contract 辅助函数，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及 secret target 类型 | + | `plugin-sdk/channel-feedback` | 反馈 / reaction 连接 | + | `plugin-sdk/channel-secret-runtime` | 精细的 secret 契约辅助工具，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及 secret target 类型 | | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | 精选的本地 / 自托管 provider 设置辅助函数 | - | `plugin-sdk/self-hosted-provider-setup` | 专注于 OpenAI 兼容自托管 provider 的设置辅助函数 | + | `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助工具 | + | `plugin-sdk/self-hosted-provider-setup` | 聚焦 OpenAI 兼容自托管提供商的设置辅助工具 | | `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 | - | `plugin-sdk/provider-auth-runtime` | 面向 provider 插件的运行时 API key 解析辅助函数 | - | `plugin-sdk/provider-auth-api-key` | API key 新手引导 / profile 写入辅助函数，例如 `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-runtime` | 面向提供商插件的运行时 API key 解析辅助工具 | + | `plugin-sdk/provider-auth-api-key` | API key 新手引导 / profile 写入辅助工具，例如 `upsertApiKeyProfile` | | `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 | - | `plugin-sdk/provider-auth-login` | 面向 provider 插件的共享交互式登录辅助函数 | - | `plugin-sdk/provider-env-vars` | provider 认证环境变量查找辅助函数 | + | `plugin-sdk/provider-auth-login` | 面向提供商插件的共享交互式登录辅助工具 | + | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider endpoint 辅助函数，以及 `normalizeNativeXaiModelId` 等 model-id 规范化辅助函数 | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具，以及模型 id 规范化辅助工具，如 `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | 通用 provider HTTP / endpoint 能力辅助函数、provider HTTP 错误，以及音频转录 multipart form 辅助函数 | - | `plugin-sdk/provider-web-fetch-contract` | 精简的 web-fetch 配置 / 选择契约辅助函数，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | web-fetch provider 注册 / 缓存辅助函数 | - | `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用连接逻辑的 provider 的精简 web-search 配置 / 凭证辅助函数 | - | `plugin-sdk/provider-web-search-contract` | 精简的 web-search 配置 / 凭证契约辅助函数，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及作用域化凭证 setter / getter | - | `plugin-sdk/provider-web-search` | web-search provider 注册 / 缓存 / 运行时辅助函数 | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 xAI 兼容辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似导出 | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装器辅助函数 | - | `plugin-sdk/provider-transport-runtime` | 原生 provider 传输辅助函数，例如受保护的 fetch、传输消息转换以及可写传输事件流 | - | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助函数 | - | `plugin-sdk/global-singleton` | 进程本地 singleton / map / cache 辅助函数 | - | `plugin-sdk/group-activation` | 精简的群组激活模式和命令解析辅助函数 | + | `plugin-sdk/provider-http` | 通用提供商 HTTP / endpoint 能力辅助工具、提供商 HTTP 错误，以及音频转录 multipart form 辅助工具 | + | `plugin-sdk/provider-web-fetch-contract` | 精细的 web-fetch 配置 / 选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册 / 缓存辅助工具 | + | `plugin-sdk/provider-web-search-config-contract` | 适用于不需要插件启用连接逻辑的提供商的精细 web-search 配置 / 凭证辅助工具 | + | `plugin-sdk/provider-web-search-contract` | 精细的 web-search 配置 / 凭证契约辅助工具，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及作用域化凭证设置 / 获取器 | + | `plugin-sdk/provider-web-search` | web-search 提供商注册 / 缓存 / 运行时辅助工具 | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助工具，如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似项 | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装器辅助工具 | + | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受保护的 fetch、传输消息转换以及可写传输事件流 | + | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 | + | `plugin-sdk/global-singleton` | 进程本地 singleton / map / cache 辅助工具 | + | `plugin-sdk/group-activation` | 精细的群组激活模式与命令解析辅助工具 | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数、发送者授权辅助函数 | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送者授权辅助工具 | | `plugin-sdk/command-status` | 命令 / 帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | 审批人解析以及同一聊天内 action-auth 辅助函数 | - | `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile / filter 辅助函数 | - | `plugin-sdk/approval-delivery-runtime` | 原生审批能力 / 传递适配器 | - | `plugin-sdk/approval-gateway-runtime` | 共享的审批 Gateway 网关解析辅助函数 | - | `plugin-sdk/approval-handler-adapter-runtime` | 面向高频渠道入口点的轻量级原生审批适配器加载辅助函数 | - | `plugin-sdk/approval-handler-runtime` | 范围更广的审批处理器运行时辅助函数；如果更精简的 adapter / gateway 接口已经足够，优先使用它们 | - | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助函数 | - | `plugin-sdk/approval-reply-runtime` | exec / 插件审批回复负载辅助函数 | - | `plugin-sdk/reply-dedupe` | 精简的入站回复去重重置辅助函数 | - | `plugin-sdk/channel-contract-testing` | 精简的渠道契约测试辅助函数，不包含宽泛的测试 barrel | - | `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助函数 | - | `plugin-sdk/command-detection` | 共享的命令检测辅助函数 | - | `plugin-sdk/command-primitives-runtime` | 面向高频渠道路径的轻量级命令文本谓词 | - | `plugin-sdk/command-surface` | 命令主体规范化和命令表面辅助函数 | + | `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天操作认证辅助工具 | + | `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile / filter 辅助工具 | + | `plugin-sdk/approval-delivery-runtime` | 原生审批能力 / 投递适配器 | + | `plugin-sdk/approval-gateway-runtime` | 共享的审批 Gateway 网关解析辅助工具 | + | `plugin-sdk/approval-handler-adapter-runtime` | 适用于热渠道入口点的轻量级原生审批适配器加载辅助工具 | + | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；当更精细的 adapter / gateway 接口已足够时，应优先使用它们 | + | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 | + | `plugin-sdk/approval-reply-runtime` | exec / 插件审批回复负载辅助工具 | + | `plugin-sdk/approval-runtime` | exec / 插件审批负载辅助工具、原生审批路由 / 运行时辅助工具，以及结构化审批显示辅助工具，例如 `formatApprovalDisplayPath` | + | `plugin-sdk/reply-dedupe` | 精细的入站回复去重重置辅助工具 | + | `plugin-sdk/channel-contract-testing` | 不包含广泛 testing barrel 的精细渠道契约测试辅助工具 | + | `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助工具 | + | `plugin-sdk/command-detection` | 共享的命令检测辅助工具 | + | `plugin-sdk/command-primitives-runtime` | 适用于热渠道路径的轻量级命令文本谓词 | + | `plugin-sdk/command-surface` | 命令主体规范化和命令接口辅助工具 | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret surface 的精简 secret-contract 收集辅助函数 | - | `plugin-sdk/secret-ref-runtime` | 面向 secret-contract / 配置解析的精简 `coerceSecretRef` 和 SecretRef 类型辅助函数 | - | `plugin-sdk/security-runtime` | 共享的信任、私信 gate、外部内容和 secret 收集辅助函数 | - | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助函数 | - | `plugin-sdk/ssrf-dispatcher` | 精简的 pinned-dispatcher 辅助函数，不包含宽泛的基础设施运行时接口 | - | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch，以及 SSRF 策略辅助函数 | - | `plugin-sdk/secret-input` | secret 输入解析辅助函数 | - | `plugin-sdk/webhook-ingress` | webhook 请求 / 目标辅助函数 | - | `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助函数 | + | `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret 接口的精细 secret 契约收集辅助工具 | + | `plugin-sdk/secret-ref-runtime` | 面向 secret 契约 / 配置解析的精细 `coerceSecretRef` 和 `SecretRef` 类型辅助工具 | + | `plugin-sdk/security-runtime` | 共享的信任、私信门控、外部内容和 secret 收集辅助工具 | + | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 | + | `plugin-sdk/ssrf-dispatcher` | 不包含广泛基础设施运行时接口的精细 pinned-dispatcher 辅助工具 | + | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch，以及 SSRF 策略辅助工具 | + | `plugin-sdk/secret-input` | secret 输入解析辅助工具 | + | `plugin-sdk/webhook-ingress` | webhook 请求 / 目标辅助工具 | + | `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助工具 | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/runtime` | 范围广泛的运行时 / 日志 / 备份 / 插件安装辅助函数 | - | `plugin-sdk/runtime-env` | 精简的运行时环境、logger、timeout、retry 和 backoff 辅助函数 | - | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助函数 | + | `plugin-sdk/runtime` | 广泛的运行时 / 日志 / 备份 / 插件安装辅助工具 | + | `plugin-sdk/runtime-env` | 精细的运行时环境、logger、超时、重试和退避辅助工具 | + | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助工具 | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | 共享的插件命令 / hook / http / 交互式辅助函数 | - | `plugin-sdk/hook-runtime` | 共享的 webhook / 内部 hook 管道辅助函数 | - | `plugin-sdk/lazy-runtime` | 惰性运行时导入 / 绑定辅助函数，例如 `createLazyRuntimeModule`, `createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | 进程 exec 辅助函数 | - | `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助函数 | - | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助函数 | - | `plugin-sdk/config-runtime` | 配置加载 / 写入辅助函数，以及插件配置查找辅助函数 | - | `plugin-sdk/telegram-command-config` | Telegram 命令名称 / 描述规范化，以及重复 / 冲突检查，即使 bundled Telegram 契约接口不可用时也可使用 | - | `plugin-sdk/text-autolink-runtime` | 文件引用自动链接检测，不包含宽泛的 text-runtime barrel | - | `plugin-sdk/approval-runtime` | exec / 插件审批辅助函数、审批能力构建器、认证 / profile 辅助函数、原生路由 / 运行时辅助函数 | - | `plugin-sdk/reply-runtime` | 共享的入站 / 回复运行时辅助函数、分块、分发、心跳、回复规划器 | - | `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发 / 完成，以及会话标签辅助函数 | - | `plugin-sdk/reply-history` | 共享的短时间窗口回复历史辅助函数，例如 `buildHistoryContext`, `recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/plugin-runtime` | 共享的插件命令 / 钩子 / HTTP / 交互式辅助工具 | + | `plugin-sdk/hook-runtime` | 共享的 webhook / 内部钩子流水线辅助工具 | + | `plugin-sdk/lazy-runtime` | 延迟运行时导入 / 绑定辅助工具，例如 `createLazyRuntimeModule`, `createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | 进程 exec 辅助工具 | + | `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助工具 | + | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助工具 | + | `plugin-sdk/config-runtime` | 配置加载 / 写入辅助工具，以及插件配置查找辅助工具 | + | `plugin-sdk/telegram-command-config` | Telegram 命令名称 / 描述规范化以及重复 / 冲突检查，即使内置的 Telegram 契约接口不可用时也可使用 | + | `plugin-sdk/text-autolink-runtime` | 不包含广泛 text-runtime barrel 的文件引用自动链接检测 | + | `plugin-sdk/approval-runtime` | exec / 插件审批辅助工具、审批能力构建器、认证 / profile 辅助工具、原生路由 / 运行时辅助工具，以及结构化审批显示路径格式化 | + | `plugin-sdk/reply-runtime` | 共享的入站 / 回复运行时辅助工具、分块、分发、心跳、回复规划器 | + | `plugin-sdk/reply-dispatch-runtime` | 精细的回复分发 / 完成，以及对话标签辅助工具 | + | `plugin-sdk/reply-history` | 共享的短窗口回复历史辅助工具，例如 `buildHistoryContext`, `recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 精简的文本 / Markdown 分块辅助函数 | - | `plugin-sdk/session-store-runtime` | 会话存储路径 + `updated-at` 辅助函数 | - | `plugin-sdk/state-paths` | 状态 / OAuth 目录路径辅助函数 | - | `plugin-sdk/routing` | 路由 / 会话键 / 账户绑定辅助函数，例如 `resolveAgentRoute`, `buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | 共享的渠道 / 账户状态摘要辅助函数、运行时状态默认值以及问题元数据辅助函数 | - | `plugin-sdk/target-resolver-runtime` | 共享的目标解析器辅助函数 | - | `plugin-sdk/string-normalization-runtime` | slug / 字符串规范化辅助函数 | + | `plugin-sdk/reply-chunking` | 精细的文本 / Markdown 分块辅助工具 | + | `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助工具 | + | `plugin-sdk/state-paths` | 状态 / OAuth 目录路径辅助工具 | + | `plugin-sdk/routing` | 路由 / 会话键 / 账户绑定辅助工具，例如 `resolveAgentRoute`, `buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | 共享的渠道 / 账户状态摘要辅助工具、运行时状态默认值和问题元数据辅助工具 | + | `plugin-sdk/target-resolver-runtime` | 共享的目标解析器辅助工具 | + | `plugin-sdk/string-normalization-runtime` | slug / 字符串规范化辅助工具 | | `plugin-sdk/request-url` | 从 fetch / request 类输入中提取字符串 URL | - | `plugin-sdk/run-command` | 带超时控制的命令执行器，返回规范化的 stdout / stderr 结果 | + | `plugin-sdk/run-command` | 带超时控制的命令运行器，并返回规范化的 stdout / stderr 结果 | | `plugin-sdk/param-readers` | 通用工具 / CLI 参数读取器 | | `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化负载 | - | `plugin-sdk/tool-send` | 从工具参数中提取规范的发送目标字段 | - | `plugin-sdk/temp-path` | 共享的临时下载路径辅助函数 | - | `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助函数 | - | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助函数 | - | `plugin-sdk/json-store` | 小型 JSON 状态读写辅助函数 | - | `plugin-sdk/file-lock` | 可重入文件锁辅助函数 | - | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助函数 | - | `plugin-sdk/acp-runtime` | ACP 运行时 / 会话和回复分发辅助函数 | - | `plugin-sdk/acp-binding-resolve-runtime` | 只读 ACP 绑定解析，不引入生命周期启动相关导入 | - | `plugin-sdk/agent-config-primitives` | 精简的智能体运行时配置 schema 基元 | + | `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 | + | `plugin-sdk/temp-path` | 共享的临时下载路径辅助工具 | + | `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助工具 | + | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助工具 | + | `plugin-sdk/json-store` | 小型 JSON 状态读取 / 写入辅助工具 | + | `plugin-sdk/file-lock` | 可重入文件锁辅助工具 | + | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 | + | `plugin-sdk/acp-runtime` | ACP 运行时 / 会话和回复分发辅助工具 | + | `plugin-sdk/acp-binding-resolve-runtime` | 不包含生命周期启动导入的只读 ACP 绑定解析 | + | `plugin-sdk/agent-config-primitives` | 精细的智能体运行时配置 schema 基元 | | `plugin-sdk/boolean-param` | 宽松布尔参数读取器 | - | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 | - | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助函数 | + | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 | + | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 | | `plugin-sdk/extension-shared` | 共享的被动渠道、状态和环境代理辅助基元 | - | `plugin-sdk/models-provider-runtime` | `/models` 命令 / provider 回复辅助函数 | - | `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助函数 | - | `plugin-sdk/native-command-registry` | 原生命令注册表 / 构建 / 序列化辅助函数 | - | `plugin-sdk/agent-harness` | 面向受信任插件的实验性低层智能体 harness 接口：harness 类型、活动运行 steer / abort 辅助函数、OpenClaw 工具桥接辅助函数、工具进度格式化 / 详情辅助函数，以及尝试结果工具函数 | - | `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助函数 | - | `plugin-sdk/infra-runtime` | 系统事件 / 心跳辅助函数 | - | `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 | - | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助函数 | - | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数，以及 `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和 pinned lookup 辅助函数 | - | `plugin-sdk/runtime-fetch` | 感知 dispatcher 的运行时 fetch，不引入 proxy / guarded-fetch 导入 | - | `plugin-sdk/response-limit-runtime` | 有界响应体读取器，不包含宽泛的媒体运行时接口 | - | `plugin-sdk/session-binding-runtime` | 当前会话绑定状态，不包含已配置绑定路由或配对存储 | - | `plugin-sdk/session-store-runtime` | 会话存储读取辅助函数，不引入宽泛的配置写入 / 维护导入 | - | `plugin-sdk/context-visibility-runtime` | 上下文可见性解析和补充上下文过滤，不引入宽泛的配置 / 安全导入 | - | `plugin-sdk/string-coerce-runtime` | 精简的基础类型记录 / 字符串强制转换和规范化辅助函数，不引入 Markdown / 日志导入 | - | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助函数 | - | `plugin-sdk/retry-runtime` | 重试配置和重试执行器辅助函数 | - | `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助函数 | + | `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助工具 | + | `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助工具 | + | `plugin-sdk/native-command-registry` | 原生命令注册表 / 构建 / 序列化辅助工具 | + | `plugin-sdk/agent-harness` | 面向底层智能体 harness 的实验性可信插件接口：harness 类型、活动运行 steer / abort 辅助工具、OpenClaw 工具桥接辅助工具、工具进度格式化 / 详情辅助工具，以及 attempt 结果工具 | + | `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助工具 | + | `plugin-sdk/infra-runtime` | 系统事件 / 心跳辅助工具 | + | `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 | + | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助工具 | + | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具，`isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | 包装的 fetch、代理和固定查找辅助工具 | + | `plugin-sdk/runtime-fetch` | 感知 dispatcher 的运行时 fetch，不包含 proxy / guarded-fetch 导入 | + | `plugin-sdk/response-limit-runtime` | 不包含广泛媒体运行时接口的有界响应体读取器 | + | `plugin-sdk/session-binding-runtime` | 当前对话绑定状态，不包含已配置绑定路由或配对存储 | + | `plugin-sdk/session-store-runtime` | 不包含广泛配置写入 / 维护导入的会话存储读取辅助工具 | + | `plugin-sdk/context-visibility-runtime` | 不包含广泛配置 / 安全导入的上下文可见性解析和补充上下文过滤 | + | `plugin-sdk/string-coerce-runtime` | 不包含 Markdown / 日志导入的精细基元记录 / 字符串强制转换与规范化辅助工具 | + | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 | + | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 | + | `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助工具 | | `plugin-sdk/directory-runtime` | 基于配置的目录查询 / 去重 | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | @@ -216,64 +218,64 @@ x-i18n: | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/media-runtime` | 共享的媒体获取 / 转换 / 存储辅助函数，以及媒体负载构建器 | - | `plugin-sdk/media-store` | 精简的媒体存储辅助函数，例如 `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | 共享的媒体生成故障转移辅助函数、候选选择和缺失模型提示 | - | `plugin-sdk/media-understanding` | 媒体理解 provider 类型，以及面向 provider 的图像 / 音频辅助导出 | - | `plugin-sdk/text-runtime` | 共享的文本 / Markdown / 日志辅助函数，例如对 assistant 可见文本的剥离、Markdown 渲染 / 分块 / 表格辅助函数、脱敏辅助函数、directive-tag 辅助函数以及安全文本工具函数 | - | `plugin-sdk/text-chunking` | 出站文本分块辅助函数 | - | `plugin-sdk/speech` | 语音 provider 类型，以及面向 provider 的 directive、注册表、校验和语音辅助导出 | - | `plugin-sdk/speech-core` | 共享的语音 provider 类型、注册表、directive、规范化和语音辅助导出 | - | `plugin-sdk/realtime-transcription` | 实时转录 provider 类型、注册表辅助函数和共享 WebSocket 会话辅助函数 | - | `plugin-sdk/realtime-voice` | 实时语音 provider 类型和注册表辅助函数 | - | `plugin-sdk/image-generation` | 图像生成 provider 类型 | - | `plugin-sdk/image-generation-core` | 共享的图像生成类型、故障转移、认证和注册表辅助函数 | - | `plugin-sdk/music-generation` | 音乐生成 provider / 请求 / 结果类型 | - | `plugin-sdk/music-generation-core` | 共享的音乐生成类型、故障转移辅助函数、provider 查找和 model-ref 解析 | - | `plugin-sdk/video-generation` | 视频生成 provider / 请求 / 结果类型 | - | `plugin-sdk/video-generation-core` | 共享的视频生成类型、故障转移辅助函数、provider 查找和 model-ref 解析 | - | `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助函数 | - | `plugin-sdk/webhook-path` | webhook 路径规范化辅助函数 | - | `plugin-sdk/web-media` | 共享的远程 / 本地媒体加载辅助函数 | - | `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` | + | `plugin-sdk/media-runtime` | 共享的媒体获取 / 转换 / 存储辅助工具，以及媒体负载构建器 | + | `plugin-sdk/media-store` | 精细的媒体存储辅助工具，例如 `saveMediaBuffer` | + | `plugin-sdk/media-generation-runtime` | 共享的媒体生成故障切换辅助工具、候选项选择和缺失模型消息 | + | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助导出 | + | `plugin-sdk/text-runtime` | 共享的文本 / Markdown / 日志辅助工具，例如面向助手可见文本剥离、Markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本工具 | + | `plugin-sdk/text-chunking` | 出站文本分块辅助工具 | + | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表、校验和语音辅助导出 | + | `plugin-sdk/speech-core` | 共享的语音提供商类型、注册表、directive、规范化和语音辅助导出 | + | `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助工具和共享 WebSocket 会话辅助工具 | + | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 | + | `plugin-sdk/image-generation` | 图像生成提供商类型 | + | `plugin-sdk/image-generation-core` | 共享的图像生成类型、故障切换、认证和注册表辅助工具 | + | `plugin-sdk/music-generation` | 音乐生成提供商 / 请求 / 结果类型 | + | `plugin-sdk/music-generation-core` | 共享的音乐生成类型、故障切换辅助工具、提供商查找和 model-ref 解析 | + | `plugin-sdk/video-generation` | 视频生成提供商 / 请求 / 结果类型 | + | `plugin-sdk/video-generation-core` | 共享的视频生成类型、故障切换辅助工具、提供商查找和 model-ref 解析 | + | `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助工具 | + | `plugin-sdk/webhook-path` | webhook 路径规范化辅助工具 | + | `plugin-sdk/web-media` | 共享的远程 / 本地媒体加载辅助工具 | + | `plugin-sdk/zod` | 为插件 SDK 使用方重新导出的 `zod` | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/memory-core` | bundled memory-core 辅助接口，包含 manager / config / file / CLI 辅助函数 | - | `plugin-sdk/memory-core-engine-runtime` | Memory 索引 / 搜索运行时门面 | + | `plugin-sdk/memory-core` | 内置的 memory-core 辅助接口，用于 manager / config / file / CLI 辅助工具 | + | `plugin-sdk/memory-core-engine-runtime` | Memory 索引 / 搜索运行时 facade | | `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地 provider 以及通用批处理 / 远程辅助函数 | + | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商以及通用批处理 / 远程辅助工具 | | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine 导出 | - | `plugin-sdk/memory-core-host-engine-storage` | Memory host 存储 engine 导出 | - | `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助函数 | - | `plugin-sdk/memory-core-host-query` | Memory host 查询辅助函数 | - | `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助函数 | - | `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助函数 | - | `plugin-sdk/memory-core-host-status` | Memory host 状态辅助函数 | - | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助函数 | - | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助函数 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件 / 运行时辅助函数 | - | `plugin-sdk/memory-host-core` | 面向供应商中立的别名，对应 memory host 核心运行时辅助函数 | - | `plugin-sdk/memory-host-events` | 面向供应商中立的别名，对应 memory host 事件日志辅助函数 | - | `plugin-sdk/memory-host-files` | 面向供应商中立的别名，对应 memory host 文件 / 运行时辅助函数 | - | `plugin-sdk/memory-host-markdown` | 面向 memory 相邻插件的共享托管 Markdown 辅助函数 | - | `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活动 Memory 运行时门面 | - | `plugin-sdk/memory-host-status` | 面向供应商中立的别名，对应 memory host 状态辅助函数 | - | `plugin-sdk/memory-lancedb` | bundled memory-lancedb 辅助接口 | + | `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine 导出 | + | `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助工具 | + | `plugin-sdk/memory-core-host-query` | Memory host 查询辅助工具 | + | `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助工具 | + | `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助工具 | + | `plugin-sdk/memory-core-host-status` | Memory host 状态辅助工具 | + | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件 / 运行时辅助工具 | + | `plugin-sdk/memory-host-core` | 面向供应商中立的 memory host 核心运行时辅助工具别名 | + | `plugin-sdk/memory-host-events` | 面向供应商中立的 memory host 事件日志辅助工具别名 | + | `plugin-sdk/memory-host-files` | 面向供应商中立的 memory host 文件 / 运行时辅助工具别名 | + | `plugin-sdk/memory-host-markdown` | 面向 memory 相邻插件的共享托管 Markdown 辅助工具 | + | `plugin-sdk/memory-host-search` | 用于 search-manager 访问的活动 Memory 运行时 facade | + | `plugin-sdk/memory-host-status` | 面向供应商中立的 memory host 状态辅助工具别名 | + | `plugin-sdk/memory-lancedb` | 内置的 memory-lancedb 辅助接口 | - - | 家族 | 当前子路径 | 预期用途 | + + | 系列 | 当前子路径 | 预期用途 | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | bundled browser 插件支持辅助函数（`browser-support` 仍然是兼容性 barrel） | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | bundled Matrix 辅助 / 运行时接口 | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | bundled LINE 辅助 / 运行时接口 | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | bundled IRC 辅助接口 | - | 渠道专用辅助函数 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | bundled 渠道兼容性 / 辅助接口 | - | 认证 / 插件专用辅助函数 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | bundled 功能 / 插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置 Browser 插件支持辅助工具（`browser-support` 仍然是兼容性 barrel） | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助 / 运行时接口 | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助 / 运行时接口 | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助接口 | + | 渠道专用辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性 / 辅助接口 | + | 认证 / 插件专用辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能 / 插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |