From 35e026cccd48d124797e7c050a2b0459343d0ff2 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 27 Apr 2026 23:54:42 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/ci.md | 181 +++++----- docs/zh-CN/plugins/codex-harness.md | 522 +++++++++++++++++++--------- docs/zh-CN/providers/openai.md | 343 +++++++++--------- 3 files changed, 631 insertions(+), 415 deletions(-) diff --git a/docs/zh-CN/ci.md b/docs/zh-CN/ci.md index 743cae0c1..f0bf9543e 100644 --- a/docs/zh-CN/ci.md +++ b/docs/zh-CN/ci.md @@ -1,59 +1,59 @@ --- read_when: - - 你需要了解某个 CI 作业为什么运行了或没有运行。 - - 你正在调试失败的 GitHub Actions 检查。 -summary: CI 作业图、作用域门控，以及本地对应命令 + - 你需要了解某个 CI 作业为什么运行了或没有运行 + - 你正在调试失败的 GitHub Actions 检查 +summary: CI 作业图、作用域门禁和本地等效命令 title: CI 流水线 x-i18n: - generated_at: "2026-04-27T23:11:43Z" + generated_at: "2026-04-27T23:52:41Z" model: gpt-5.4 provider: openai - source_hash: 0f9181fe819550b195068ded66076722323e055e5a9f1e46bff61ba205ae5f8c + source_hash: 4d9fabbc0980661076f4b0187dda4ac682b2361943266c7ec85a8cf38796299a source_path: ci.md workflow: 15 --- -CI 会在每次推送到 `main` 以及每个拉取请求上运行。它使用智能作用域划分，在只有无关区域发生变更时跳过开销较大的作业。手动触发的 `workflow_dispatch` 运行会有意绕过智能作用域划分，并展开完整的常规 CI 作业图，用于发布候选版本或大范围验证。 +CI 会在每次推送到 `main` 以及每个拉取请求时运行。它使用智能作用域判定，在仅更改了无关区域时跳过高成本作业。手动 `workflow_dispatch` 运行会有意绕过智能作用域，并展开完整的常规 CI 作业图，用于发布候选版本或大范围验证。 -`Full Release Validation` 是用于“发布前运行所有检查”的手动总控工作流。它接受分支、标签或完整提交 SHA，使用该目标触发手动 `CI` 工作流，并触发 `OpenClaw Release Checks`，用于安装冒烟测试、包验收、Docker 发布路径测试套件、live/E2E、OpenWebUI、QA Lab 一致性、Matrix 和 Telegram 通道。提供已发布的软件包规范时，它还可以运行发布后的 `NPM Telegram Beta E2E` 工作流。这个总控工作流会记录已触发的子运行 id，而最终的 `Verify full validation` 作业会重新检查当前子运行的结论。如果某个子工作流被重新运行并转为绿色，只需重新运行父级验证器作业即可刷新总控结果。 +`Full Release Validation` 是用于“发布前运行所有内容”的手动总控工作流。它接受分支、标签或完整提交 SHA，使用该目标触发手动 `CI` 工作流，并触发 `OpenClaw Release Checks` 来运行安装冒烟测试、包验收、Docker 发布路径测试套件、live/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram 通道。提供已发布的包规格时，它还可以运行发布后的 `NPM Telegram Beta E2E` 工作流。这个总控工作流会记录触发的子运行 ID，最终的 `Verify full validation` 作业会重新检查当前子运行的结论。如果某个子工作流被重新运行并变为绿色，只需重新运行父级验证作业即可刷新总控结果。 -为了便于恢复，`Full Release Validation` 和 `OpenClaw Release Checks` 都接受 `rerun_group`。发布候选版本使用 `all`；仅重新运行常规完整 CI 子工作流使用 `ci`；重新运行所有发布子检查使用 `release-checks`；也可以使用更窄的发布分组：总控工作流支持 `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。这样可以在有针对性的修复之后，把失败的发布测试环境重跑范围控制在较小范围内。 +为便于恢复，`Full Release Validation` 和 `OpenClaw Release Checks` 都接受 `rerun_group`。发布候选版本使用 `all`，仅运行常规完整 CI 子流程使用 `ci`，所有发布子流程使用 `release-checks`，或者使用更窄的发布分组：在总控工作流上可选 `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。这样在针对性修复后，可以把失败的发布环境重跑范围控制在较小边界内。 -发布版 live/E2E 子工作流仍然保留广泛的原生 `pnpm test:live` 覆盖，但它不是作为单个串行作业运行，而是通过 `scripts/test-live-shard.mjs` 以具名分片运行：`native-live-src-agents`、`native-live-src-gateway-core`、`native-live-src-gateway-backends`、`native-live-test`、`native-live-extensions-a-k`、`native-live-extensions-l-n`、`native-live-extensions-openai`、`native-live-extensions-o-z` 和 `native-live-extensions-media`。这样在保持相同文件覆盖范围的同时，也让慢速 live provider 故障更容易重跑和诊断。 +发布 live/E2E 子流程保留了广泛的原生 `pnpm test:live` 覆盖，但它不再作为单个串行作业运行，而是通过 `scripts/test-live-shard.mjs` 按具名分片执行：`native-live-src-agents`、`native-live-src-gateway-core`、按 provider 过滤的 `native-live-src-gateway-profiles` 作业、`native-live-src-gateway-backends`、`native-live-test`、`native-live-extensions-a-k`、`native-live-extensions-l-n`、`native-live-extensions-openai`、`native-live-extensions-o-z-other`、`native-live-extensions-xai`，以及拆分后的媒体音频/音乐/视频分片。这样既保持了相同的文件覆盖范围，也更便于重跑和诊断缓慢的 live provider 故障。聚合分片名 `native-live-extensions-o-z` 和 `native-live-extensions-media` 仍然可用于手动一次性重跑。 -`Package Acceptance` 是用于验证软件包产物的旁路工作流，不会阻塞发布工作流。它可以从已发布的 npm 规范、使用所选 `workflow_ref` harness 构建的可信 `package_ref`、带有 SHA-256 的 HTTPS tarball URL，或来自其他 GitHub Actions 运行的 tarball artifact 中解析出一个候选包，将其上传为 `package-under-test`，然后复用 Docker 发布/E2E 调度器，针对该 tarball 运行，而不是重新打包工作流检出的代码。它支持 smoke、package、product、full 以及自定义 Docker 通道选择等配置。`package` 配置使用离线插件覆盖，因此已发布软件包的验证不会被 live ClawHub 可用性所阻塞。可选的 Telegram 通道会在 `NPM Telegram Beta E2E` 工作流中复用 `package-under-test` artifact，而已发布 npm 规范路径则保留给独立触发场景。 +`Package Acceptance` 是一个旁路工作流，用于验证某个包产物，而不会阻塞发布工作流。它会从已发布的 npm 规格、使用所选 `workflow_ref` harness 构建的可信 `package_ref`、带有 SHA-256 的 HTTPS tarball URL，或另一个 GitHub Actions 运行中的 tarball artifact 中解析出一个候选包，将其作为 `package-under-test` 上传，然后复用 Docker 发布/E2E 调度器，以该 tarball 代替对工作流检出的内容重新打包。配置档覆盖 smoke、package、product、full，以及自定义 Docker 测试通道选择。`package` 配置档使用离线插件覆盖，因此已发布包验证不受 live ClawHub 可用性影响。可选的 Telegram 通道会在 `NPM Telegram Beta E2E` 工作流中复用 `package-under-test` artifact，而已发布 npm 规格路径则保留给独立触发使用。 ## 包验收 -当问题是“这个可安装的 OpenClaw 软件包作为产品是否可用”时，使用 `Package Acceptance`。它不同于常规 CI：常规 CI 验证的是源码树，而包验收验证的是单个 tarball，并通过用户在安装或更新后实际使用的同一套 Docker E2E harness 来运行。 +当问题是“这个可安装的 OpenClaw 软件包作为一个产品是否可用？”时，使用 `Package Acceptance`。它与常规 CI 不同：常规 CI 验证源码树，而包验收则通过用户在安装或更新后实际经历的同一套 Docker E2E harness，对单个 tarball 进行验证。 -该工作流有四个作业： +该工作流包含四个作业： -1. `resolve_package` 会检出 `workflow_ref`，解析一个软件包候选项，写入 `.artifacts/docker-e2e-package/openclaw-current.tgz`，写入 `.artifacts/docker-e2e-package/package-candidate.json`，将两者作为 `package-under-test` artifact 上传，并在 GitHub 步骤摘要中打印来源、workflow ref、package ref、版本、SHA-256 和配置。 -2. `docker_acceptance` 会使用 `ref=workflow_ref` 和 `package_artifact_name=package-under-test` 调用 `openclaw-live-and-e2e-checks-reusable.yml`。这个可复用工作流会下载该 artifact，验证 tarball 清单，按需准备基于 package digest 的 Docker 镜像，并针对该软件包运行所选的 Docker 通道，而不是打包当前工作流检出的代码。当某个配置选择了多个定向 `docker_lanes` 时，这个可复用工作流会先准备一次软件包和共享镜像，然后将这些通道展开为并行的定向 Docker 作业，并生成各自独立的 artifact。 -3. `package_telegram` 可选地调用 `NPM Telegram Beta E2E`。当 `telegram_mode` 不是 `none` 时运行；如果 `Package Acceptance` 已解析出一个软件包，它会安装同一个 `package-under-test` artifact；独立触发的 Telegram 运行仍然可以安装已发布的 npm 规范。 -4. `summary` 会在软件包解析、Docker 验收或可选的 Telegram 通道失败时让整个工作流失败。 +1. `resolve_package` 检出 `workflow_ref`，解析一个包候选项，写入 `.artifacts/docker-e2e-package/openclaw-current.tgz`，写入 `.artifacts/docker-e2e-package/package-candidate.json`，将两者作为 `package-under-test` artifact 上传，并在 GitHub 步骤摘要中输出其来源、workflow ref、package ref、版本、SHA-256 和 profile。 +2. `docker_acceptance` 调用 `openclaw-live-and-e2e-checks-reusable.yml`，并传入 `ref=workflow_ref` 与 `package_artifact_name=package-under-test`。该可复用工作流会下载该 artifact，验证 tarball 清单，按需准备 package-digest Docker 镜像，并针对该包而不是工作流检出内容打包结果来运行所选 Docker 通道。当某个配置档选择了多个定向 `docker_lanes` 时，该可复用工作流会只准备一次包和共享镜像，然后以带唯一 artifact 的并行定向 Docker 作业展开这些通道。 +3. `package_telegram` 会按需调用 `NPM Telegram Beta E2E`。当 `telegram_mode` 不为 `none` 时它会运行；如果 Package Acceptance 已解析出一个包，它会安装同一个 `package-under-test` artifact；独立的 Telegram 触发仍然可以安装已发布的 npm 规格。 +4. `summary` 会在包解析、Docker 验收或可选 Telegram 通道失败时使整个工作流失败。 候选来源： -- `source=npm`：仅接受 `openclaw@beta`、`openclaw@latest`，或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。用于已发布 beta/stable 版本的验收。 -- `source=ref`：打包一个可信的 `package_ref` 分支、标签或完整提交 SHA。解析器会抓取 OpenClaw 分支/标签，验证所选提交是否可从仓库分支历史或发布标签到达，在分离工作树中安装依赖，并使用 `scripts/package-openclaw-for-docker.mjs` 进行打包。 +- `source=npm`：仅接受 `openclaw@beta`、`openclaw@latest` 或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。用于已发布 beta/stable 包的验收。 +- `source=ref`：打包一个可信的 `package_ref` 分支、标签或完整提交 SHA。解析器会抓取 OpenClaw 分支/标签，验证所选提交可从仓库分支历史或发布标签到达，在分离工作树中安装依赖，并使用 `scripts/package-openclaw-for-docker.mjs` 进行打包。 - `source=url`：下载一个 HTTPS `.tgz`；必须提供 `package_sha256`。 -- `source=artifact`：从 `artifact_run_id` 和 `artifact_name` 下载一个 `.tgz`；`package_sha256` 是可选的，但对于外部共享的 artifact 应当提供。 +- `source=artifact`：从 `artifact_run_id` 和 `artifact_name` 下载一个 `.tgz`；`package_sha256` 是可选的，但对于外部分发的 artifact 应当提供。 -请将 `workflow_ref` 和 `package_ref` 分开。`workflow_ref` 是运行测试时所用的可信工作流/harness 代码。`package_ref` 是在 `source=ref` 时会被打包的源码提交。这样，当前测试 harness 就可以在不运行旧工作流逻辑的前提下，验证较早的可信源码提交。 +请将 `workflow_ref` 与 `package_ref` 分开。`workflow_ref` 是运行测试的可信工作流/harness 代码。`package_ref` 是在 `source=ref` 时会被打包的源提交。这样，当前测试 harness 就可以验证较早的可信源提交，而无需运行旧的工作流逻辑。 -配置与 Docker 覆盖的映射： +配置档与 Docker 覆盖范围的映射： - `smoke`：`npm-onboard-channel-agent`、`gateway-network`、`config-reload` - `package`：`npm-onboard-channel-agent`、`doctor-switch`、`update-channel-switch`、`bundled-channel-deps-compat`、`plugins-offline`、`plugin-update` -- `product`：`package` 外加 `mcp-channels`、`cron-mcp-cleanup`、`openai-web-search-minimal`、`openwebui` +- `product`：在 `package` 基础上增加 `mcp-channels`、`cron-mcp-cleanup`、`openai-web-search-minimal`、`openwebui` - `full`：包含 OpenWebUI 的完整 Docker 发布路径分块 -- `custom`：精确指定 `docker_lanes`；当 `suite_profile=custom` 时必须提供 +- `custom`：精确的 `docker_lanes`；当 `suite_profile=custom` 时为必填 -发布检查会以 `source=ref`、`package_ref=`、`workflow_ref=`、`suite_profile=custom`、`docker_lanes='bundled-channel-deps-compat plugins-offline'` 和 `telegram_mode=mock-openai` 调用 `Package Acceptance`。发布路径 Docker 分块会覆盖重叠的软件包/更新/插件通道，而 `Package Acceptance` 则针对同一个已解析的软件包 tarball，保留基于产物原生运行的 bundled-channel 兼容性、离线插件以及 Telegram 证明。跨操作系统发布检查仍然覆盖特定操作系统的新手引导、安装器和平台行为；而软件包/更新的产品级验证应从 `Package Acceptance` 开始。Windows 打包版和安装器全新安装通道还会验证：已安装的软件包能否从原始绝对 Windows 路径导入 browser-control override。 +发布检查会以 `source=ref`、`package_ref=`、`workflow_ref=`、`suite_profile=custom`、`docker_lanes='bundled-channel-deps-compat plugins-offline'` 和 `telegram_mode=mock-openai` 调用 Package Acceptance。发布路径 Docker 分块会覆盖重叠的 package/update/plugin 通道，而 Package Acceptance 则针对同一个已解析的 package tarball 保留原生 artifact 的 bundled-channel 兼容性、离线插件以及 Telegram 验证。跨操作系统发布检查仍会覆盖特定于操作系统的新手引导、安装器和平台行为；包/更新产品验证应从 Package Acceptance 开始。Windows 打包版和安装器全新安装通道还会验证已安装包能否从原始绝对 Windows 路径导入浏览器控制覆盖项。 -`Package Acceptance` 对已发布的软件包提供一个有界的旧兼容窗口，适用于 `2026.4.25` 及之前的版本，包括 `2026.4.25-beta.*`。这些放宽规则记录在这里，是为了避免它们变成永久的静默跳过：如果 tarball 省略了这些文件，`dist/postinstall-inventory.json` 中已知的私有 QA 条目可能会发出警告；如果软件包未暴露该标志，`doctor-switch` 可能会跳过 `gateway install --wrapper` 持久化子场景；`update-channel-switch` 可能会从由 tarball 派生的伪 git fixture 中裁剪缺失的 `pnpm.patchedDependencies`，并可能记录缺失的持久化 `update.channel`；插件冒烟测试可能会读取旧版安装记录位置，或接受缺失的 marketplace 安装记录持久化；而 `plugin-update` 可能允许配置元数据迁移，但仍要求安装记录和不重新安装行为保持不变。`2026.4.25` 之后的软件包必须满足现代契约；相同条件将直接失败，而不是警告或跳过。 +对于已发布的软件包，Package Acceptance 为截至 `2026.4.25`（包括 `2026.4.25-beta.*`）的版本保留了一个有界的旧兼容窗口。这些例外在此记录，以防它们变成永久性的静默跳过：`dist/postinstall-inventory.json` 中已知的私有 QA 条目在 tarball 省略这些文件时可能只发出警告；当软件包未暴露该标志时，`doctor-switch` 可能跳过 `gateway install --wrapper` 持久化子用例；`update-channel-switch` 可能会从基于 tarball 的伪 git fixture 中剪除缺失的 `pnpm.patchedDependencies`，并可能记录缺失的已持久化 `update.channel`；插件冒烟测试可能读取旧版安装记录位置，或接受缺失的 marketplace 安装记录持久化；而 `plugin-update` 可能允许配置元数据迁移，同时仍要求安装记录和不重新安装行为保持不变。`2026.4.25` 之后的软件包必须满足现代契约；同样的条件将失败，而不是警告或跳过。 示例： @@ -96,17 +96,17 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -调试失败的包验收运行时，先查看 `resolve_package` 摘要，确认软件包来源、版本和 SHA-256。然后检查 `docker_acceptance` 子运行及其 Docker artifact：`.artifacts/docker-tests/**/summary.json`、`failures.json`、通道日志、阶段耗时以及重跑命令。优先重跑失败的包验收配置或精确的 Docker 通道，而不是重新运行整个完整发布验证。 +调试失败的包验收运行时，请先查看 `resolve_package` 摘要，以确认包来源、版本和 SHA-256。然后检查 `docker_acceptance` 子运行及其 Docker artifacts：`.artifacts/docker-tests/**/summary.json`、`failures.json`、通道日志、阶段耗时和重跑命令。优先重跑失败的包配置档或精确的 Docker 通道，而不是重跑完整发布验证。 -QA Lab 在主智能作用域工作流之外有专门的 CI 通道。`Parity gate` 工作流会在匹配的 PR 变更和手动触发时运行；它会构建私有 QA 运行时，并比较 mock GPT-5.5 和 Opus 4.6 agentic packs。`QA-Lab - All Lanes` 工作流会在 `main` 上每夜运行，并支持手动触发；它会把 mock parity gate、live Matrix 通道，以及 live Telegram 和 Discord 通道展开为并行作业。live 作业使用 `qa-live-shared` 环境，Telegram/Discord 使用 Convex leases。Matrix 在计划任务和发布门控中使用 `--profile fast`，并且仅在检出的 CLI 支持时才添加 `--fail-fast`。CLI 默认值和手动工作流输入仍然是 `all`；手动触发 `matrix_profile=all` 时，总是会将完整 Matrix 覆盖分片为 `transport`、`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 作业。`OpenClaw Release Checks` 也会在发布批准前运行发布关键的 QA Lab 通道；它的 QA parity gate 会把候选包和基线包作为并行通道作业运行，然后把两个 artifact 下载到一个小型报告作业中，以进行最终的一致性比较。 +QA Lab 在主智能作用域工作流之外有专门的 CI 通道。`Parity gate` 工作流会在匹配的 PR 更改和手动触发时运行；它会构建私有 QA 运行时，并比较 mock GPT-5.5 和 Opus 4.6 agentic 包。`QA-Lab - All Lanes` 工作流会在 `main` 上每晚运行，也可手动触发；它会将 mock parity gate、live Matrix 通道，以及 live Telegram 和 Discord 通道作为并行作业展开。live 作业使用 `qa-live-shared` 环境，而 Telegram/Discord 使用 Convex 租约。Matrix 在定时和发布门禁中使用 `--profile fast`，仅当检出的 CLI 支持时才添加 `--fail-fast`。CLI 默认值和手动工作流输入仍为 `all`；手动 `matrix_profile=all` 触发始终会将完整 Matrix 覆盖拆分为 `transport`、`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 作业。`OpenClaw Release Checks` 也会在发布批准前运行发布关键的 QA Lab 通道；其 QA parity gate 会将候选包和基线包作为并行通道作业运行，然后在一个小型报告作业中下载两者的 artifact，以进行最终 parity 比较。 -`Duplicate PRs After Merge` 工作流是一个供维护者使用的手动工作流，用于合并后的重复 PR 清理。它默认以 dry-run 方式运行，只有在 `apply=true` 时才会关闭明确列出的 PR。在修改 GitHub 之前，它会验证已落地的 PR 已经合并，并且每个重复项都具有共享的引用 issue 或重叠的变更 hunk。 +`Duplicate PRs After Merge` 工作流是一个供维护者在合并后进行重复 PR 清理的手动工作流。它默认使用 dry-run，只有在 `apply=true` 时才会关闭显式列出的 PR。在修改 GitHub 之前，它会验证已合并的 PR 确实已被合并，并且每个重复 PR 都具有关联的共享 issue 引用或重叠的变更 hunk。 -`CodeQL` 工作流有意设计为一个范围较窄的首轮扫描器，而不是对整个仓库进行完整扫描。每日运行和手动运行会扫描 Actions 工作流代码，以及风险最高的 JavaScript/TypeScript 凭证、密钥、沙箱、cron 和 Gateway 网关相关模块。关键安全通道会针对这个较窄的 JavaScript/TypeScript 范围运行高精度安全查询，而单独的关键质量通道则只运行严重级别为 error 的非安全查询。Swift、Android、Python、UI 和内置插件的 CodeQL 扩展应仅在这个窄范围配置的运行时间和信噪比稳定之后，作为有作用域限制或分片的后续工作再逐步加回。 +`CodeQL` 工作流有意作为一个范围较窄的第一阶段扫描器，而不是对整个仓库进行完整扫描。每日运行和手动运行会扫描 Actions 工作流代码，以及最高风险的 JavaScript/TypeScript 凭证、密钥、沙箱、cron 和 Gateway 网关表面。关键安全通道会对同一小范围 JavaScript/TypeScript 表面运行高精度安全查询，而单独的关键质量通道则仅运行严重级别为 error 的非安全查询。Swift、Android、Python、UI 和内置插件的 CodeQL 扩展，应仅在这个窄范围配置的运行时间和信噪比稳定之后，作为有作用域限制或分片的后续工作重新加入。 -`Docs Agent` 工作流是一个事件驱动的 Codex 维护通道，用于让现有文档与最近已合并的变更保持一致。它没有纯定时调度：在 `main` 上一次成功的、非机器人触发的 push CI 运行可以触发它，也可以通过手动触发直接运行。对于 workflow-run 调用，如果 `main` 已经继续前进，或者过去一小时内已经创建了另一次未跳过的 Docs Agent 运行，则会跳过。实际运行时，它会审查从上一次未跳过的 Docs Agent 源 SHA 到当前 `main` 的提交范围，因此每小时一次的运行就可以覆盖自上次文档处理以来积累到 `main` 的所有变更。 +`Docs Agent` 工作流是一个事件驱动的 Codex 维护通道，用于让现有文档与最近已合并的更改保持一致。它没有纯定时调度：当 `main` 上一次成功的非机器人 push CI 运行完成后，可以触发它；也可以通过手动触发直接运行。工作流运行触发会在 `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 日期内已有另一个由工作流运行触发的实例已经运行过或正在运行，它就会跳过。手动触发会绕过这一每日活动门禁。该通道会构建完整测试套件分组的 Vitest 性能报告，让 Codex 仅进行小幅、保持覆盖率不变的测试性能修复，而不是进行大范围重构，然后重新运行完整测试套件报告，并拒绝任何会降低通过基线测试数量的更改。如果基线中已有失败测试，Codex 只能修复明显的问题，并且 agent 运行后的完整测试套件报告必须全部通过，之后才会提交任何内容。当 `main` 在 bot push 落地前继续前进时，该通道会对已验证的补丁执行 rebase，重新运行 `pnpm check:changed`，并重试推送；存在冲突的陈旧补丁会被跳过。它使用 GitHub 托管的 Ubuntu，这样 Codex action 就能与 docs agent 保持相同的 drop-sudo 安全策略。 ```bash gh workflow run duplicate-after-merge.yml \ @@ -119,29 +119,29 @@ gh workflow run duplicate-after-merge.yml \ | 作业 | 用途 | 运行时机 | | -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | 检测是否仅有文档变更、变更作用域、变更的扩展，并构建 CI 清单 | 总是在非草稿 push 和 PR 上运行 | -| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 总是在非草稿 push 和 PR 上运行 | -| `security-dependency-audit` | 针对 npm 安全公告执行无依赖的生产 lockfile 审计 | 总是在非草稿 push 和 PR 上运行 | -| `security-fast` | 快速安全作业的必需聚合作业 | 总是在非草稿 push 和 PR 上运行 | -| `build-artifacts` | 构建 `dist/`、Control UI、已构建产物检查以及可复用的下游 artifact | 与 Node 相关的变更 | -| `checks-fast-core` | 快速 Linux 正确性通道，例如 bundled/plugin-contract/protocol 检查 | 与 Node 相关的变更 | -| `checks-fast-contracts-channels` | 分片的渠道契约检查，并提供稳定的聚合检查结果 | 与 Node 相关的变更 | -| `checks-node-extensions` | 对整个扩展套件执行完整的内置插件测试分片 | 与 Node 相关的变更 | -| `checks-node-core-test` | Core Node 测试分片，不包含渠道、内置、契约和扩展通道 | 与 Node 相关的变更 | -| `check` | 与主本地门控等效的分片作业：生产类型、lint、防护、测试类型和严格冒烟测试 | 与 Node 相关的变更 | -| `check-additional` | 架构、边界、扩展表面防护、包边界和 gateway-watch 分片 | 与 Node 相关的变更 | -| `build-smoke` | 已构建 CLI 冒烟测试和启动内存冒烟测试 | 与 Node 相关的变更 | -| `checks` | 已构建产物渠道测试的验证器 | 与 Node 相关的变更 | -| `checks-node-compat-node22` | Node 22 兼容性构建和冒烟通道 | 用于发布的手动 CI 触发 | -| `check-docs` | 文档格式化、lint 和断链检查 | 文档发生变更时 | -| `skills-python` | 面向 Python 支持的 Skills 运行 Ruff + pytest | 与 Python Skills 相关的变更 | -| `checks-windows` | Windows 特有的进程/路径测试，以及共享运行时导入说明符回归检查 | 与 Windows 相关的变更 | -| `macos-node` | 使用共享已构建产物的 macOS TypeScript 测试通道 | 与 macOS 相关的变更 | -| `macos-swift` | macOS 应用的 Swift lint、构建和测试 | 与 macOS 相关的变更 | -| `android` | 两个 flavor 的 Android 单元测试，以及一个 debug APK 构建 | 与 Android 相关的变更 | -| `test-performance-agent` | 在可信活动之后按日运行的 Codex 慢测试优化 | 在 main CI 成功后或手动触发 | +| `preflight` | 检测仅文档更改、更改的作用域、更改的扩展，并构建 CI 清单 | 始终在非草稿 push 和 PR 上运行 | +| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 始终在非草稿 push 和 PR 上运行 | +| `security-dependency-audit` | 针对 npm 公告进行无依赖的生产 lockfile 审计 | 始终在非草稿 push 和 PR 上运行 | +| `security-fast` | 快速安全作业的必需聚合项 | 始终在非草稿 push 和 PR 上运行 | +| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查，以及可复用的下游 artifacts | 与 Node 相关的更改 | +| `checks-fast-core` | 快速 Linux 正确性通道，例如 bundled/plugin-contract/protocol 检查 | 与 Node 相关的更改 | +| `checks-fast-contracts-channels` | 分片的渠道契约检查，带有稳定的聚合检查结果 | 与 Node 相关的更改 | +| `checks-node-extensions` | 扩展套件中的完整内置插件测试分片 | 与 Node 相关的更改 | +| `checks-node-core-test` | 核心 Node 测试分片，不含渠道、内置、契约和扩展通道 | 与 Node 相关的更改 | +| `check` | 分片的主本地门禁等效项：生产类型、lint、防护、测试类型和严格 smoke | 与 Node 相关的更改 | +| `check-additional` | 架构、边界、扩展表面防护、包边界以及 gateway-watch 分片 | 与 Node 相关的更改 | +| `build-smoke` | 已构建 CLI 冒烟测试和启动内存冒烟测试 | 与 Node 相关的更改 | +| `checks` | 已构建产物渠道测试的验证器 | 与 Node 相关的更改 | +| `checks-node-compat-node22` | Node 22 兼容性构建和 smoke 通道 | 用于发布的手动 CI 触发 | +| `check-docs` | 文档格式、lint 和失效链接检查 | 文档有更改时 | +| `skills-python` | 面向 Python 支持的 Skills 的 Ruff + pytest | 与 Python Skills 相关的更改 | +| `checks-windows` | Windows 特定的进程/路径测试，以及共享运行时导入说明符回归检查 | 与 Windows 相关的更改 | +| `macos-node` | 使用共享构建 artifacts 的 macOS TypeScript 测试通道 | 与 macOS 相关的更改 | +| `macos-swift` | macOS 应用的 Swift lint、构建和测试 | 与 macOS 相关的更改 | +| `android` | 两种 flavor 的 Android 单元测试，以及一个 debug APK 构建 | 与 Android 相关的更改 | +| `test-performance-agent` | 在可信活动之后每日运行的 Codex 慢测试优化 | `main` CI 成功后或手动触发 | -手动触发的 CI 会运行与常规 CI 相同的作业图，但会强制开启所有带作用域限制的通道：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、build smoke、文档检查、Python Skills、Windows、macOS、Android 以及 Control UI i18n。手动运行使用唯一的并发组，因此发布候选版本的完整测试套件不会因为同一 ref 上的另一条 push 或 PR 运行而被取消。可选的 `target_ref` 输入允许可信调用方在使用所选触发 ref 对应工作流文件的同时，针对某个分支、标签或完整提交 SHA 运行这张作业图。 +手动 CI 触发会运行与常规 CI 相同的作业图，但会强制开启所有按作用域控制的通道：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建 smoke、文档检查、Python Skills、Windows、macOS、Android，以及 Control UI i18n。手动运行使用唯一的并发组，因此发布候选版本的完整测试套件不会被同一 ref 上的另一次 push 或 PR 运行取消。可选的 `target_ref` 输入允许可信调用方在使用所选触发 ref 的工作流文件的同时，针对某个分支、标签或完整提交 SHA 运行这张作业图。 ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -151,82 +151,67 @@ gh workflow run full-release-validation.yml --ref main -f ref= ## 快速失败顺序 -作业的排序方式是让便宜的检查先失败，再决定是否运行昂贵作业： +作业的排序方式使得低成本检查会先于高成本作业失败： -1. `preflight` 决定哪些通道实际存在。`docs-scope` 和 `changed-scope` 逻辑是这个作业中的步骤，而不是独立作业。 -2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，而无需等待更重的产物和平台矩阵作业。 -3. `build-artifacts` 会与快速 Linux 通道并行运行，这样下游消费者可以在共享构建准备好后立刻开始。 +1. `preflight` 决定哪些通道实际存在。`docs-scope` 和 `changed-scope` 逻辑是该作业内部的步骤，而不是独立作业。 +2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，而无需等待较重的构建产物和平台矩阵作业。 +3. `build-artifacts` 会与快速 Linux 通道并行运行，这样下游消费者就能在共享构建准备好后立即开始。 4. 更重的平台和运行时通道随后展开：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-extensions`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 -作用域逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。手动触发会跳过变更作用域检测，并让 preflight 清单表现得像所有带作用域限制的区域都发生了变更。CI 工作流编辑会验证 Node CI 作业图以及工作流 lint，但不会仅因这些编辑就强制运行 Windows、Android 或 macOS 原生构建；这些平台通道仍然仅由平台源码变更触发。 +作用域逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。 +手动触发会跳过 changed-scope 检测，并让 preflight 清单表现得如同所有按作用域控制的区域都发生了更改。 +CI 工作流编辑会验证 Node CI 作业图以及工作流 lint，但不会仅因这些编辑就强制运行 Windows、Android 或 macOS 原生构建；这些平台通道仍然只受平台源码更改控制。 +仅涉及 CI 路由的编辑、选定的低成本 core-test fixture 编辑，以及狭窄范围的插件契约辅助工具/测试路由编辑，会使用快速 Node-only 清单路径：preflight、安全检查，以及单个 `checks-fast-core` 任务。当前更改文件仅限于快速任务可直接覆盖的路由或辅助表面时，该路径会避免构建 artifacts、Node 22 兼容性、渠道契约、完整核心分片、内置插件分片，以及额外的防护矩阵。 +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/package 表面、内置插件 package/manifest 更改，以及 Docker smoke 作业会覆盖到的核心插件/渠道/Gateway 网关/插件 SDK 表面，会运行快速路径。仅源码的内置插件更改、仅测试编辑和仅文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete shared-workspace CLI smoke，运行容器化 gateway-network e2e，验证内置扩展 build arg，并在 240 秒总命令超时限制下运行有界的内置插件 Docker profile，同时每个场景的 Docker 运行各自有独立上限。完整路径会保留 QR package 安装和安装器 Docker/update 覆盖，用于夜间定时运行、手动触发、workflow-call 发布检查，以及真正触及安装器/package/Docker 表面的拉取请求。推送到 `main`，包括 merge commit，不会强制完整路径；当 changed-scope 逻辑在 push 上会请求完整覆盖时，工作流仍只保留快速 Docker smoke，而将完整 install smoke 留给夜间运行或发布验证。较慢的 Bun 全局安装 image-provider smoke 由 `run_bun_global_install_smoke` 单独控制；它会在夜间计划任务和发布检查工作流中运行，手动 `install-smoke` 触发也可以选择加入，但拉取请求和 `main` 推送不会运行它。QR 和安装器 Docker 测试保留各自以安装为中心的 Dockerfile。本地 `test:docker:all` 会预构建一个共享的 live-test 镜像，将 OpenClaw 作为 npm tarball 打包一次，并构建两个共享的 `scripts/e2e/Dockerfile` 镜像：一个是不安装包的 Node/Git 运行器，用于安装器/update/插件依赖通道；另一个是功能镜像，会将同一个 tarball 安装到 `/app` 中，用于常规功能通道。Docker 通道定义位于 `scripts/lib/docker-e2e-scenarios.mjs`，规划逻辑位于 `scripts/lib/docker-e2e-plan.mjs`，运行器只执行所选计划。调度器会通过 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 为每个通道选择镜像，然后在 `OPENCLAW_SKIP_DOCKER_BUILD=1` 下运行这些通道；默认主池槽位数为 10，可通过 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整；对 provider 敏感的尾池槽位数也默认为 10，可通过 `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` 调整。重型通道上限默认是 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `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 通道使用更严格的单通道上限。`OPENCLAW_DOCKER_ALL_LANES=` 会运行精确的调度器通道，包括仅发布时使用的通道，例如 `install-e2e`，以及拆分后的内置更新通道，例如 `bundled-channel-update-acpx`，同时跳过 cleanup smoke，以便智能体复现某个失败通道。可复用的 live/E2E 工作流会调用 `scripts/test-docker-all.mjs --plan-json` 来确定需要哪种 package、镜像类型、live 镜像、通道和凭证覆盖，然后由 `scripts/docker-e2e.mjs` 将该计划转换为 GitHub outputs 和摘要。它会通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw，或下载当前运行的 package artifact，或从 `package_artifact_run_id` 下载 package artifact；验证 tarball 清单；当计划需要已安装 package 的通道时，通过 Blacksmith 的 Docker layer cache 构建并推送以 package-digest 标记的 bare/functional GHCR Docker E2E 镜像；并在有提供 `docker_e2e_bare_image`/`docker_e2e_functional_image` 输入或已有 package-digest 镜像时复用它们，而不是重新构建。`Package Acceptance` 工作流是高层级的包门禁：它会从 npm、可信 `package_ref`、带 SHA-256 的 HTTPS tarball，或先前工作流 artifact 中解析一个候选包，然后将这个单一的 `package-under-test` artifact 传入可复用的 Docker E2E 工作流。它将 `workflow_ref` 与 `package_ref` 分离，这样当前的验收逻辑就可以验证较旧的可信提交，而无需检出旧的工作流代码。发布检查会针对目标 ref 运行自定义的 Package Acceptance 增量：bundled-channel 兼容性、离线插件 fixtures，以及针对已解析 tarball 的 Telegram package QA。发布路径 Docker 测试套件会以更小的分块作业运行，并设置 `OPENCLAW_SKIP_DOCKER_BUILD=1`，这样每个分块只拉取所需的镜像类型，并通过同一个加权调度器运行多个通道（`OPENCLAW_DOCKER_ALL_PROFILE=release-path`、`OPENCLAW_DOCKER_ALL_CHUNK=core|package-update-openai|package-update-anthropic|package-update-core|plugins-runtime-core|plugins-runtime-install-a|plugins-runtime-install-b|bundled-channels`）。当完整发布路径覆盖请求 OpenWebUI 时，它会并入 `plugins-runtime-core`，只有在仅针对 OpenWebUI 的触发中才保留独立的 `openwebui` 分块。旧的聚合分块名称 `package-update`、`plugins-runtime` 和 `plugins-integrations` 仍可用于手动重跑，但发布工作流使用拆分后的分块，这样安装器 E2E 和内置插件安装/卸载扫描就不会主导关键路径。`install-e2e` 通道别名仍是两个 provider 安装器通道的聚合手动重跑别名。`bundled-channels` 分块运行拆分后的 `bundled-channel-*` 和 `bundled-channel-update-*` 通道，而不是串行的一体化 `bundled-channel-deps` 通道。每个分块都会上传 `.artifacts/docker-tests/`，其中包含通道日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON、慢通道表，以及每个通道的重跑命令。工作流 `docker_lanes` 输入会针对已准备好的镜像运行选定通道，而不是使用分块作业，这样失败通道的调试就能控制在单个定向 Docker 作业内，并会为该次运行准备、下载或复用 package artifact；如果选定通道是 live Docker 通道，则该定向作业会在本地构建 live-test 镜像用于重跑。生成的每通道 GitHub 重跑命令会在这些值存在时包含 `package_artifact_run_id`、`package_artifact_name` 和已准备好的镜像输入，因此失败通道可以复用失败运行中的精确 package 和镜像。使用 `pnpm test:docker:rerun ` 可从某次 GitHub 运行下载 Docker artifacts，并输出组合/逐通道的定向重跑命令；使用 `pnpm test:docker:timings ` 可查看慢通道和阶段关键路径摘要。计划中的 live/E2E 工作流会每日运行完整的发布路径 Docker 测试套件。内置更新矩阵按更新目标拆分，以便重复的 npm update 和 doctor 修复过程可以与其他内置检查并行分片运行。 -仅涉及 CI 路由的编辑、部分低成本 core-test fixture 编辑，以及狭窄范围的插件契约辅助工具/测试路由编辑，会走一个快速的仅 Node 清单路径：preflight、安全检查，以及单个 `checks-fast-core` 任务。当变更文件仅限于该快速任务可直接覆盖的路由或辅助工具表面时，这一路径会避免运行构建 artifact、Node 22 兼容性、渠道契约、完整 core 分片、内置插件分片，以及额外的防护矩阵。 +当前发布 Docker 分块为 `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-core`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-b` 和 `bundled-channels-contracts`。聚合的 `bundled-channels` 分块仍可用于手动一次性重跑，但发布工作流使用拆分后的分块，以便渠道 smoke、更新目标以及设置/运行时契约检查可以并行运行。定向 `docker_lanes` 触发也会在一次共享 package/镜像准备步骤之后，将多个选定通道拆分为并行作业；而内置渠道更新通道会针对瞬时 npm 网络故障重试一次。 -Windows Node 检查的作用域仅限于 Windows 特定的进程/路径包装器、npm/pnpm/UI 运行器辅助工具、包管理器配置，以及执行该通道的 CI 工作流表面；不相关的源码、插件、install-smoke 和仅测试类变更仍然停留在 Linux Node 通道上，这样就不会为了已由常规测试分片覆盖的内容占用 16-vCPU 的 Windows worker。 +本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，由 `scripts/check-changed.mjs` 执行。这个本地检查门禁在架构边界上比宽泛的 CI 平台作用域更严格：核心生产更改会运行 core prod 和 core test 类型检查，以及 core lint/guards；核心仅测试更改只运行 core test 类型检查以及 core lint；扩展生产更改会运行 extension prod 和 extension test 类型检查，以及 extension lint；扩展仅测试更改会运行 extension test 类型检查以及 extension lint。公开的插件 SDK 或 plugin-contract 更改会扩展到 extension 类型检查，因为扩展依赖这些核心契约，但 Vitest 扩展扫描属于显式测试工作。仅发布元数据的版本升级会运行定向 version/config/root-dependency 检查。未知的根目录/配置更改会以安全优先的方式退回到全部检查通道。 -独立的 `install-smoke` 工作流会通过它自己的 `preflight` 作业复用同一个作用域脚本。它将冒烟覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。对于 PR，Docker/软件包表面、内置插件 package/manifest 变更，以及 Docker 冒烟作业所覆盖的 core 插件/渠道/Gateway 网关/插件 SDK 表面，会运行快速路径。仅源码的内置插件变更、仅测试编辑以及仅文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete shared-workspace CLI 冒烟，运行容器内的 gateway-network e2e，验证一个内置扩展 build arg，并在 240 秒的总命令超时内运行有边界的内置插件 Docker 配置，同时对每个场景的 Docker run 单独设置上限。 +手动 CI 触发会运行 `checks-node-compat-node22` 作为发布候选版本兼容性覆盖。常规拉取请求和 `main` 推送会跳过该通道，并将矩阵聚焦于 Node 24 测试/渠道通道。 -完整路径则保留 QR 软件包安装以及安装器 Docker/更新覆盖，用于每夜定时运行、手动触发、workflow-call 发布检查，以及确实触及安装器/软件包/Docker 表面的 PR。推送到 `main`，包括 merge commit，不会强制完整路径；当变更作用域逻辑在 push 上本会请求完整覆盖时，该工作流仍然只保留快速 Docker 冒烟，并将完整 install smoke 留给夜间运行或发布验证。较慢的 Bun 全局安装 image-provider 冒烟由单独的 `run_bun_global_install_smoke` 门控；它在夜间计划任务和发布检查工作流中运行，手动触发 `install-smoke` 时也可以选择启用，但 PR 和 `main` push 不会运行它。QR 和安装器 Docker 测试保留各自以安装为中心的 Dockerfile。 +最慢的 Node 测试族会被拆分或做负载平衡，以便每个作业都保持较小规模，同时避免过度预留 runner：渠道契约会拆成三个加权分片，内置插件测试会在六个扩展 worker 之间做均衡，小型核心单元通道会成对组合，auto-reply 会以四个平衡 worker 运行，并将 reply 子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片，而 agentic Gateway 网关/插件配置则分布到现有的仅源码 agentic Node 作业中，而不是等待已构建 artifacts。范围较广的浏览器、QA、媒体和杂项插件测试会使用各自专用的 Vitest 配置，而不是共享的插件兜底配置。扩展分片作业一次最多运行两个插件配置组，每组使用一个 Vitest worker，并配更大的 Node 堆，这样导入开销较大的插件批次就不会额外生成更多 CI 作业。宽范围的 agents 通道使用共享的 Vitest 文件级并行调度器，因为它主要受导入/调度影响，而不是被某个单独的慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享运行时分片拖尾。基于 include-pattern 的分片会使用 CI 分片名称记录耗时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分完整配置和过滤后的分片。`check-additional` 会将 package-boundary 的 compile/canary 工作保持在一起，并将运行时拓扑架构与 gateway watch 覆盖分离；边界防护分片会在一个作业内并发运行其小型独立防护项。Gateway watch、渠道测试以及核心 support-boundary 分片会在 `build-artifacts` 内部于 `dist/` 和 `dist-runtime/` 已构建完成后并发运行，保留它们原有的检查名称作为轻量验证作业，同时避免额外占用两个 Blacksmith worker 和第二条 artifact 消费队列。 -本地 `test:docker:all` 会预构建一个共享的 live-test 镜像，将 OpenClaw 一次性打包为 npm tarball，并构建两个共享的 `scripts/e2e/Dockerfile` 镜像：一个是用于安装器/更新/插件依赖通道的纯 Node/Git 运行器，另一个是将同一 tarball 安装到 `/app` 中、用于常规功能通道的功能型镜像。Docker 通道定义位于 `scripts/lib/docker-e2e-scenarios.mjs`，规划逻辑位于 `scripts/lib/docker-e2e-plan.mjs`，运行器只执行所选计划。调度器通过 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 为每个通道选择镜像，然后在设置 `OPENCLAW_SKIP_DOCKER_BUILD=1` 的情况下运行这些通道；可用 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整主池默认 10 个槽位，用 `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` 调整 provider 敏感的尾池默认 10 个槽位。较重通道的默认上限为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`，这样 npm install 和多服务通道就不会让 Docker 过度超载，同时较轻通道仍然可以填满可用槽位。单个比有效上限更重的通道仍然可以从空池启动，然后独占运行，直到释放容量。 +Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的源码集或 manifest；它的单元测试通道仍会使用 SMS/通话日志 BuildConfig 标志编译该 flavor，同时避免在每次与 Android 相关的推送上重复执行 debug APK 打包作业。 -默认情况下，通道启动会错开 2 秒，以避免本地 Docker daemon 出现 create storm；可通过 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` 或其他毫秒值覆盖。本地聚合运行会预检 Docker，移除过期的 OpenClaw E2E 容器，输出活跃通道状态，持久化通道耗时以支持“最长优先”排序，并支持 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 以检查调度器行为。默认在首次失败后停止调度新的池化通道，并且每个通道都有 120 分钟的兜底超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；部分 live/tail 通道使用更严格的单通道上限。`OPENCLAW_DOCKER_ALL_LANES=` 会运行精确的调度器通道，包括仅用于发布的通道，如 `install-e2e`，以及拆分的内置更新通道，如 `bundled-channel-update-acpx`，同时跳过清理冒烟，这样智能体就能复现某个失败通道。 +当同一 PR 或 `main` ref 上有更新的推送到达时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一 ref 的最新运行也失败，否则应将其视为 CI 噪音。聚合作业分片检查使用 `!cancelled() && always()`，这样它们仍会正常报告分片失败，但不会在整个工作流已被取代后继续排队。 -可复用的 live/E2E 工作流会通过 `scripts/test-docker-all.mjs --plan-json` 查询所需的软件包、镜像类型、live 镜像、通道和凭证覆盖，然后由 `scripts/docker-e2e.mjs` 将该计划转换为 GitHub outputs 和摘要。它会通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw，或下载当前运行的软件包 artifact，或从 `package_artifact_run_id` 下载软件包 artifact；验证 tarball 清单；当计划需要安装了软件包的通道时，通过 Blacksmith 的 Docker layer cache 构建并推送带 package digest 标签的 bare/functional GHCR Docker E2E 镜像；并且在已有可用时，复用提供的 `docker_e2e_bare_image`/`docker_e2e_functional_image` 输入或现有的 package-digest 镜像，而不是重新构建。 - -`Package Acceptance` 工作流是高层的软件包门控：它从 npm、可信 `package_ref`、附带 SHA-256 的 HTTPS tarball，或先前工作流 artifact 中解析出一个候选包，然后将这个单独的 `package-under-test` artifact 传递给可复用的 Docker E2E 工作流。它将 `workflow_ref` 与 `package_ref` 分离，使当前的验收逻辑可以在不检出旧工作流代码的情况下验证较早的可信提交。发布检查会针对目标 ref 运行一个自定义的 Package Acceptance 差量集：内置渠道兼容性、离线插件 fixture，以及针对已解析 tarball 的 Telegram 软件包 QA。 - -发布路径 Docker 套件会运行更小、已分块的作业，并设置 `OPENCLAW_SKIP_DOCKER_BUILD=1`，这样每个分块只拉取自己需要的镜像类型，并通过同一个加权调度器执行多个通道（`OPENCLAW_DOCKER_ALL_PROFILE=release-path`，`OPENCLAW_DOCKER_ALL_CHUNK=core|package-update-openai|package-update-anthropic|package-update-core|plugins-runtime-core|plugins-runtime-install-a|plugins-runtime-install-b|bundled-channels`）。在请求完整发布路径覆盖时，OpenWebUI 会并入 `plugins-runtime-core`，只有在仅针对 OpenWebUI 的触发中才保留独立的 `openwebui` 分块。旧的聚合分块名称 `package-update`、`plugins-runtime` 和 `plugins-integrations` 仍然可用于手动重跑，但发布工作流使用拆分后的分块，这样安装器 E2E 和内置插件安装/卸载全量扫描就不会主导关键路径。`install-e2e` 通道别名仍然是两个 provider 安装器通道的聚合手动重跑别名。`bundled-channels` 分块运行拆分后的 `bundled-channel-*` 和 `bundled-channel-update-*` 通道，而不是串行的一体化 `bundled-channel-deps` 通道。每个分块都会上传 `.artifacts/docker-tests/`，其中包含通道日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON、慢通道表以及每通道重跑命令。 - -工作流的 `docker_lanes` 输入会让所选通道针对准备好的镜像运行，而不是运行整块作业，这样失败通道的调试范围就能限制在一个定向 Docker 作业内，并为该次运行准备、下载或复用软件包 artifact；如果所选通道是 live Docker 通道，定向作业会为该次重跑在本地构建 live-test 镜像。生成的逐通道 GitHub 重跑命令会在这些值存在时包含 `package_artifact_run_id`、`package_artifact_name` 以及准备好的镜像输入，因此失败通道可以复用失败运行中的精确软件包和镜像。使用 `pnpm test:docker:rerun ` 可从某次 GitHub 运行下载 Docker artifact，并打印组合式/逐通道的定向重跑命令；使用 `pnpm test:docker:timings ` 可获取慢通道和阶段关键路径摘要。计划中的 live/E2E 工作流每天运行完整的发布路径 Docker 套件。内置更新矩阵按更新目标拆分，这样重复的 npm update 和 doctor 修复流程就可以与其他内置检查并行分片运行。 - -当前发布 Docker 分块包括 `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-core`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-b` 和 `bundled-channels-contracts`。聚合的 `bundled-channels` 分块仍然可用于手动一次性重跑，但发布工作流使用拆分后的分块，这样渠道冒烟、更新目标以及设置/运行时契约检查就能并行运行。定向 `docker_lanes` 触发也会在共享的软件包/镜像准备步骤之后，将多个所选通道拆分为并行作业；并且内置渠道更新通道会针对临时性的 npm 网络失败重试一次。 - -本地变更通道逻辑位于 `scripts/changed-lanes.mjs`，由 `scripts/check-changed.mjs` 执行。这个本地检查门控在架构边界上比宽泛的 CI 平台作用域更严格：core 生产变更会运行 core 生产和 core 测试 typecheck，以及 core lint/guards；core 仅测试变更只运行 core 测试 typecheck 和 core lint；扩展生产变更会运行扩展生产和扩展测试 typecheck，以及扩展 lint；扩展仅测试变更会运行扩展测试 typecheck 和扩展 lint。公开的插件 SDK 或插件契约变更会扩展到扩展 typecheck，因为扩展依赖这些 core 契约，但 Vitest 扩展全量运行仍然属于显式测试工作。仅发布元数据的版本号变更会运行定向的版本/配置/根依赖检查。未知的根目录/配置变更会以保守方式落入所有检查通道。 - -手动触发的 CI 会运行 `checks-node-compat-node22`，作为发布候选的兼容性覆盖。常规 PR 和 `main` push 会跳过这个通道，并让矩阵聚焦于 Node 24 测试/渠道通道。 - -最慢的 Node 测试家族会被拆分或重新平衡，使每个作业都保持较小规模，同时避免过度预留 runner：渠道契约以三个加权分片运行，内置插件测试在六个扩展 worker 之间平衡分配，小型 core 单元测试通道会成对组合，auto-reply 作为四个平衡 worker 运行，并将 reply 子树拆分为 agent-runner、dispatch 以及 commands/state-routing 分片，而 agentic Gateway 网关/插件配置则分散到现有的仅源码 agentic Node 作业中，而不是等待已构建 artifact。广义的 browser、QA、media 以及杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件兜底配置。扩展分片作业一次最多运行两个插件配置组，每组使用一个 Vitest worker，并提供更大的 Node heap，这样导入开销较大的插件批次就不会产生额外的 CI 作业。广义的 agents 通道使用共享的 Vitest 文件级并行调度器，因为它主要受导入/调度限制，而不是由某个单独的慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享 runtime 分片成为尾部瓶颈。基于 include pattern 的分片会使用 CI 分片名称记录耗时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分整个配置与过滤后的分片。`check-additional` 将 package-boundary 的 compile/canary 工作保留在一起，并将 runtime topology 架构与 gateway watch 覆盖拆开；boundary guard 分片会在一个作业内并发运行其小型独立 guard。Gateway watch、渠道测试和 core support-boundary 分片会在 `dist/` 和 `dist-runtime/` 已构建完成后，在 `build-artifacts` 内部并发运行，保留它们原有的检查名称作为轻量验证作业，同时避免额外占用两个 Blacksmith worker 和第二条 artifact 消费队列。 - -Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的源码集或 manifest；它的单元测试通道仍然会在启用 SMS/通话记录 BuildConfig 标志的情况下编译该 flavor，同时避免在每次与 Android 相关的 push 上重复进行一次 debug APK 打包作业。 - -当同一个 PR 或 `main` ref 上有更新的 push 到达时，GitHub 可能会将被替代的作业标记为 `cancelled`。除非同一 ref 的最新运行也失败，否则应将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会正常报告分片失败，但不会在整个工作流已经被替代后继续排队。 - -自动 CI 并发键带有版本号（`CI-v7-*`），这样 GitHub 侧旧队列组中的僵尸任务就不会无限期阻塞较新的 `main` 运行。手动完整测试套件运行使用 `CI-manual-v1-*`，并且不会取消正在进行中的运行。 +自动 CI 并发键是带版本号的（`CI-v7-*`），这样 GitHub 端旧队列组中的僵尸任务就不会无限期阻塞新的 main 运行。手动完整测试套件运行使用 `CI-manual-v1-*`，且不会取消正在进行中的运行。 ## Runner | Runner | 作业 | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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 矩阵可以更早开始排队 | +| `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` | `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 的本地变更通道分类器 -pnpm check:changed # 智能本地检查门控：按边界通道运行变更后的 typecheck/lint/guards -pnpm check # 快速本地门控：生产 tsgo + 分片 lint + 并行快速 guards +pnpm changed:lanes # 检查 origin/main...HEAD 的本地 changed-lane 分类器 +pnpm check:changed # 智能本地检查门禁：按边界通道运行 changed typecheck/lint/guards +pnpm check # 快速本地门禁：生产 tsgo + 分片 lint + 并行快速 guards pnpm check:test-types -pnpm check:timed # 同一门控，并输出各阶段耗时 +pnpm check:timed # 相同门禁，但带每阶段耗时 pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression -pnpm test # Vitest 测试 -pnpm test:changed # 低成本的智能变更 Vitest 目标 +pnpm test # vitest 测试 +pnpm test:changed # 低成本智能 changed Vitest 目标 pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # 文档格式化 + lint + 断链检查 +pnpm check:docs # 文档格式 + lint + 失效链接 pnpm build # 当 CI artifact/build-smoke 通道相关时构建 dist pnpm ci:timings # 汇总最近一次 origin/main push CI 运行 -pnpm ci:timings:recent # 对比最近成功的 main CI 运行 +pnpm ci:timings:recent # 比较最近成功的 main CI 运行 node scripts/ci-run-timings.mjs # 汇总总耗时、排队时间和最慢作业 -node scripts/ci-run-timings.mjs --latest-main # 忽略 issue/comment 噪声，并选择 origin/main push CI -node scripts/ci-run-timings.mjs --recent 10 # 对比最近成功的 main CI 运行 +node scripts/ci-run-timings.mjs --latest-main # 忽略 issue/comment 噪音并选择 origin/main push CI +node scripts/ci-run-timings.mjs --recent 10 # 比较最近成功的 main CI 运行 pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json ``` diff --git a/docs/zh-CN/plugins/codex-harness.md b/docs/zh-CN/plugins/codex-harness.md index b256676c6..e1e830c83 100644 --- a/docs/zh-CN/plugins/codex-harness.md +++ b/docs/zh-CN/plugins/codex-harness.md @@ -2,63 +2,77 @@ 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-27T23:44:15Z" + generated_at: "2026-04-27T23:52:41Z" model: gpt-5.4 provider: openai - source_hash: ef9654bdc6a2cb44726a53002f2735d823119d2e0379adc68907d8a0980ba4c2 + source_hash: c048ff928fb0b601b6a75631f9e33bbf23d08d1c21ad762b22ac3fb182d862ff 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 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体投递，以及可见的转录镜像。 -如果你正在熟悉相关概念，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。简而言之：`openai/gpt-5.5` 是模型引用，`codex` 是运行时，而 Telegram、Discord、Slack 或其他渠道仍然是通信界面。 +如果你正在熟悉这一部分，请先从 [Agent Runtimes](/zh-CN/concepts/agent-runtimes) 开始。简而言之： +`openai/gpt-5.5` 是模型引用，`codex` 是运行时，而 Telegram、 +Discord、Slack 或其他渠道仍然是通信界面。 ## 此插件会改变什么 -内置的 `codex` 插件提供了几项彼此独立的能力： +内置的 `codex` 插件提供若干彼此独立的能力： -| 能力 | 使用方式 | 作用 | +| 能力 | 你的使用方式 | 它的作用 | | --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | -| 原生嵌入式运行时 | `agentRuntime.id: "codex"` | 通过 Codex app-server 运行 OpenClaw 嵌入式智能体回合。 | +| 原生嵌入式运行时 | `agentRuntime.id: "codex"` | 通过 Codex app-server 运行 OpenClaw 嵌入式智能体轮次。 | | 原生聊天控制命令 | `/codex bind`, `/codex resume`, `/codex steer`, ... | 在消息会话中绑定并控制 Codex app-server 线程。 | -| Codex app-server 提供商/目录 | `codex` 内部机制，通过 harness 暴露 | 让运行时发现并校验 app-server 模型。 | -| Codex 媒体理解路径 | `codex/*` 图像模型兼容路径 | 为支持的图像理解模型运行受限的 Codex app-server 回合。 | -| 原生钩子中继 | 围绕 Codex 原生事件的插件钩子 | 让 OpenClaw 观察/阻止受支持的 Codex 原生工具/终结事件。 | +| Codex app-server 提供商/目录 | `codex` 内部机制，通过 harness 暴露 | 让运行时发现并验证 app-server 模型。 | +| Codex 媒体理解路径 | `codex/*` 图像模型兼容路径 | 为受支持的图像理解模型运行受限的 Codex app-server 轮次。 | +| 原生 hook 转发 | 围绕 Codex 原生事件的插件钩子 | 让 OpenClaw 观察/拦截受支持的 Codex 原生工具/终结事件。 | -启用该插件会让这些能力可用。它**不会**： +启用该插件会使这些能力可用。它**不会**： -- 为每个 OpenAI 模型都开始使用 Codex +- 开始对每个 OpenAI 模型都使用 Codex - 将 `openai-codex/*` 模型引用转换为原生运行时 - 让 ACP/acpx 成为默认的 Codex 路径 -- 热切换已经记录为 PI 运行时的现有会话 +- 热切换已经记录为 Pi 运行时的现有会话 - 替换 OpenClaw 的渠道投递、会话文件、auth-profile 存储或消息路由 -同一个插件也负责原生 `/codex` 聊天控制命令界面。如果插件已启用，且用户希望从聊天中绑定、恢复、引导、停止或检查 Codex 线程，智能体应优先使用 `/codex ...`，而不是 ACP。只有当用户明确要求 ACP/acpx，或正在测试 ACP Codex 适配器时，ACP 才是显式后备方案。 +同一个插件也负责原生 `/codex` 聊天控制命令界面。如果 +插件已启用，并且用户要求从聊天中绑定、恢复、引导、停止或检查 +Codex 线程，智能体应优先使用 `/codex ...` 而不是 ACP。只有当用户明确要求 ACP/acpx，或正在测试 ACP +Codex 适配器时，ACP 才是显式回退路径。 -原生 Codex 回合将 OpenClaw 插件钩子保留为公开兼容层。这些是进程内的 OpenClaw 钩子，而不是 Codex `hooks.json` 命令钩子： +原生 Codex 轮次仍将 OpenClaw 插件钩子作为公共兼容层。 +这些是进程内的 OpenClaw 钩子，不是 Codex `hooks.json` 命令钩子： - `before_prompt_build` - `before_compaction`, `after_compaction` - `llm_input`, `llm_output` - `before_tool_call`, `after_tool_call` - 用于镜像转录记录的 `before_message_write` -- 通过 Codex `Stop` 中继的 `before_agent_finalize` +- 通过 Codex `Stop` 转发的 `before_agent_finalize` - `agent_end` -插件还可以注册运行时无关的工具结果中间件，在 OpenClaw 执行工具之后、结果返回给 Codex 之前，重写 OpenClaw 动态工具结果。这与公开的 `tool_result_persist` 插件钩子不同，后者用于转换由 OpenClaw 拥有的转录工具结果写入。 +插件还可以注册运行时无关的工具结果中间件，在 OpenClaw 执行工具之后、并在结果返回给 Codex 之前，重写 OpenClaw 动态工具结果。这与公共 +`tool_result_persist` 插件钩子不同，后者会转换由 OpenClaw 拥有的转录工具结果写入。 -关于插件钩子语义本身，请参阅 [Plugin hooks](/zh-CN/plugins/hooks) 和 [Plugin guard behavior](/zh-CN/tools/plugin)。 +关于插件钩子语义本身，请参见 [Plugin hooks](/zh-CN/plugins/hooks) +和 [Plugin guard behavior](/zh-CN/tools/plugin)。 -默认情况下，harness 处于关闭状态。新的配置应保持 OpenAI 模型引用为规范形式 `openai/gpt-*`，并在需要原生 app-server 执行时显式强制设置 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。出于兼容性考虑，旧版 `codex/*` 模型引用仍会自动选择该 harness，但由运行时支持的旧版提供商前缀不会显示为普通的模型/提供商选项。 +该 harness 默认关闭。新配置应保持 OpenAI 模型引用 +规范为 `openai/gpt-*`，并在希望使用原生 app-server 执行时显式强制 +`agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。 +旧版 `codex/*` 模型引用仍会自动选择该 harness 以保持兼容，但由运行时支持的旧版提供商前缀不会显示为普通模型/提供商选项。 -如果启用了 `codex` 插件，但主模型仍然是 `openai-codex/*`，`openclaw doctor` 会发出警告，而不是更改路由。这是有意为之：`openai-codex/*` 仍然是 PI Codex OAuth/订阅路径，而原生 app-server 执行始终是一个显式运行时选择。 +如果启用了 `codex` 插件，但主模型仍然是 +`openai-codex/*`，`openclaw doctor` 会给出警告，而不是更改路由。这是 +有意为之：`openai-codex/*` 仍然是 Pi Codex OAuth/订阅路径，而 +原生 app-server 执行仍然是一个显式的运行时选择。 ## 路由映射 @@ -67,65 +81,97 @@ x-i18n: | 期望行为 | 模型引用 | 运行时配置 | 插件要求 | 预期 Status 标签 | | ------------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ | | 通过普通 OpenClaw 运行器使用 OpenAI API | `openai/gpt-*` | 省略或 `runtime: "pi"` | OpenAI provider | `Runtime: OpenClaw Pi Default` | -| 通过 PI 使用 Codex OAuth/订阅 | `openai-codex/gpt-*` | 省略或 `runtime: "pi"` | OpenAI Codex OAuth provider | `Runtime: OpenClaw Pi Default` | -| 原生 Codex app-server 嵌入式回合 | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` 插件 | `Runtime: OpenAI Codex` | -| 使用保守自动模式的混合提供商 | provider-specific refs | `agentRuntime.id: "auto"` | 可选插件运行时 | 取决于所选运行时 | -| 显式 Codex ACP 适配器会话 | ACP prompt/model dependent | `sessions_spawn` 搭配 `runtime: "acp"` | 正常工作的 `acpx` 后端 | ACP 任务/会话状态 | +| 通过 Pi 使用 Codex OAuth/订阅 | `openai-codex/gpt-*` | 省略或 `runtime: "pi"` | OpenAI Codex OAuth provider | `Runtime: OpenClaw Pi Default` | +| 原生 Codex app-server 嵌入式轮次 | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` 插件 | `Runtime: OpenAI Codex` | +| 启用保守自动模式的混合提供商 | 提供商特定引用 | `agentRuntime.id: "auto"` | 可选插件运行时 | 取决于所选运行时 | +| 显式 Codex ACP 适配器会话 | 取决于 ACP prompt/model | `sessions_spawn` 搭配 `runtime: "acp"` | 健康的 `acpx` 后端 | ACP 任务/会话状态 | -关键区别在于提供商与运行时： +这里最重要的区分是提供商与运行时： -- `openai-codex/*` 回答的是“PI 应该使用哪条提供商/认证路由？” -- `agentRuntime.id: "codex"` 回答的是“哪个循环应执行这个嵌入式回合？” -- `/codex ...` 回答的是“这个聊天应绑定或控制哪个原生 Codex 会话？” +- `openai-codex/*` 回答的是“Pi 应该使用哪条提供商/认证路径？” +- `agentRuntime.id: "codex"` 回答的是“哪个 loop 应该执行这次 + 嵌入式轮次？” +- `/codex ...` 回答的是“此聊天应绑定或控制哪个原生 Codex 会话？” - ACP 回答的是“acpx 应启动哪个外部 harness 进程？” ## 选择正确的模型前缀 -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/*`： | 模型引用 | 运行时路径 | 使用场景 | | --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | -| `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` + `agentRuntime.id: "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` + `agentRuntime.id: "codex"` | Codex app-server harness | 你希望为嵌入式智能体轮次使用原生 Codex app-server 执行。 | -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，就会支持对 `openai/gpt-5.5` 的直接 API 密钥访问。 +GPT-5.5 目前在 OpenClaw 中仅支持订阅/OAuth。请使用 +`openai-codex/gpt-5.5` 进行 Pi OAuth，或使用 `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-*` 加上 `agentRuntime.id: "codex"`。 +旧版 `codex/gpt-*` 引用仍然接受为兼容性别名。Doctor +兼容迁移会将旧版主运行时引用重写为规范模型引用，并单独记录运行时策略；而仅用于回退的旧版引用则保持不变，因为运行时是针对整个智能体容器配置的。 +新的 Pi Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生 +app-server harness 配置应使用 `openai/gpt-*`，并加上 +`agentRuntime.id: "codex"`。 -`agents.defaults.imageModel` 也遵循同样的前缀拆分。当图像理解应通过 OpenAI Codex OAuth provider 路径运行时，使用 `openai-codex/gpt-*`。当图像理解应通过受限的 Codex app-server 回合运行时，使用 `codex/gpt-*`。Codex app-server 模型必须声明支持图像输入；纯文本 Codex 模型会在媒体回合开始前失败。 +`agents.defaults.imageModel` 也遵循相同的前缀区分。如果你希望图像理解通过 OpenAI +Codex OAuth 提供商路径运行，请使用 `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` 模式下，每个插件候选项的支持结果。 ### doctor 警告意味着什么 -当以下条件全部成立时，`openclaw doctor` 会发出警告： +当以下条件全部满足时，`openclaw doctor` 会发出警告： -- 内置 `codex` 插件已启用或被允许 +- 内置的 `codex` 插件已启用或被允许 - 某个智能体的主模型是 `openai-codex/*` - 该智能体的实际运行时不是 `codex` -之所以有这个警告，是因为用户常常会认为“启用了 Codex 插件”就意味着“使用原生 Codex app-server 运行时”。OpenClaw 不会自动做出这个跳转。这个警告表示： +之所以有这个警告，是因为用户经常认为“已启用 Codex 插件”就意味着 +“使用原生 Codex app-server 运行时”。OpenClaw 不会自动做出这种推断。这个警告表示： -- 如果你本来就是要通过 PI 使用 ChatGPT/Codex OAuth，**则无需更改**。 -- 如果你想使用原生 app-server 执行，请将模型改为 `openai/`，并设置 `agentRuntime.id: "codex"`。 -- 现有会话在运行时变更后仍需要执行 `/new` 或 `/reset`，因为会话运行时固定是粘性的。 +- 如果你本来就打算通过 Pi 使用 ChatGPT/Codex OAuth，**则无需更改**。 +- 如果你想使用原生 app-server + 执行，请将模型改为 `openai/`，并设置 + `agentRuntime.id: "codex"`。 +- 现有会话在运行时更改后仍需要 `/new` 或 `/reset`， + 因为会话运行时固定是粘性的。 -Harness 选择不是实时会话控制。当一个嵌入式回合运行时，OpenClaw 会在该会话上记录所选 harness id，并在后续同一会话 id 的回合中继续使用它。当你希望未来会话使用另一种 harness 时，请更改 `agentRuntime` 配置或 `OPENCLAW_AGENT_RUNTIME`；在现有会话于 PI 和 Codex 之间切换之前，请先使用 `/new` 或 `/reset` 启动一个新会话。这可以避免将同一份转录通过两套不兼容的原生会话系统重放。 +Harness 选择不是实时会话控制。当嵌入式轮次运行时， +OpenClaw 会在该会话上记录所选的 harness id，并在同一会话 id 的后续轮次中继续使用它。当你希望未来的会话使用另一个 harness 时，请更改 `agentRuntime` 配置或 +`OPENCLAW_AGENT_RUNTIME`；在现有会话于 Pi 和 Codex 之间切换之前，请使用 `/new` 或 `/reset` 启动新会话。 +这样可以避免通过两个不兼容的原生会话系统来重放同一份转录。 -在引入 harness 固定机制之前创建的旧会话，只要已有转录历史，就会被视为固定到 PI。更改配置后，如需让该会话改用 Codex，请使用 `/new` 或 `/reset`。 +在 harness 固定机制引入之前创建的旧会话，只要它们已有转录历史， +就会被视为固定到 Pi。更改配置后，如需让该会话改用 +Codex，请使用 `/new` 或 `/reset`。 -`/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`。 ## 要求 -- OpenClaw，并且可用内置的 `codex` 插件。 -- Codex app-server `0.125.0` 或更高版本。内置插件默认会管理一个兼容的 Codex app-server 二进制文件，因此 `PATH` 上的本地 `codex` 命令不会影响正常的 harness 启动。 -- app-server 进程可用的 Codex 认证信息。 +- OpenClaw，且内置 `codex` 插件可用。 +- Codex app-server `0.125.0` 或更高版本。内置插件默认会管理兼容的 + Codex app-server 二进制文件，因此 `PATH` 上本地的 `codex` 命令 + 不会影响正常的 harness 启动。 +- app-server 进程或 OpenClaw 的 Codex auth + bridge 可用的 Codex 认证。 -该插件会阻止较旧或没有版本信息的 app-server 握手，以确保 OpenClaw 始终运行在其已测试过的协议接口上。 +该插件会阻止较旧或未带版本的 app-server 握手。这能让 +OpenClaw 保持在它已测试过的协议接口上。 -对于实时和 Docker 冒烟测试，认证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 `~/.codex/config.toml`。请使用与你本地 Codex app-server 相同的认证材料。 +对于 live 和 Docker 冒烟测试，认证通常来自 Codex CLI 账户 +或 OpenClaw `openai-codex` auth profile。本地 stdio app-server 启动 +在没有账户时，也可以回退到 `CODEX_API_KEY` / `OPENAI_API_KEY`。 ## 最小配置 @@ -151,7 +197,7 @@ Harness 选择不是实时会话控制。当一个嵌入式回合运行时，Ope } ``` -如果你的配置使用 `plugins.allow`，也要在其中包含 `codex`： +如果你的配置使用 `plugins.allow`，也请将 `codex` 包含进去： ```json5 { @@ -166,19 +212,27 @@ Harness 选择不是实时会话控制。当一个嵌入式回合运行时，Ope } ``` -将 `agents.defaults.model` 或某个智能体模型设置为 `codex/` 的旧配置，仍会自动启用内置 `codex` 插件。新的配置应优先使用 `openai/`，再加上上面显式的 `agentRuntime` 条目。 +旧配置如果将 `agents.defaults.model` 或某个智能体模型设置为 +`codex/`，仍会自动启用内置 `codex` 插件。新配置应优先 +使用 `openai/`，并配合上面的显式 `agentRuntime` 条目。 ## 将 Codex 与其他模型一起使用 -如果同一个智能体需要在 Codex 与非 Codex 提供商模型之间自由切换，请不要全局设置 `agentRuntime.id: "codex"`。强制运行时会应用到该智能体或会话的每个嵌入式回合。如果你在强制该运行时的情况下选择了 Anthropic 模型，OpenClaw 仍会尝试使用 Codex harness，并以失败关闭，而不是悄悄地通过 PI 路由该回合。 +如果同一个智能体应该在 Codex 和非 Codex 提供商模型之间自由切换，请不要全局设置 `agentRuntime.id: "codex"`。 +强制运行时会应用到该智能体或会话的每一次 +嵌入式轮次。如果你在强制该运行时的情况下选择了 Anthropic 模型， +OpenClaw 仍会尝试使用 Codex harness，并且会以失败关闭的方式报错，而不是静默地通过 Pi 路由该轮次。 -请改用以下几种配置形式之一： +请改用以下其中一种方式： -- 将 Codex 放在一个专用智能体上，并设置 `agentRuntime.id: "codex"`。 -- 将默认智能体保留为 `agentRuntime.id: "auto"`，并为普通混合提供商用法保留 PI 后备。 -- 仅将旧版 `codex/*` 引用用于兼容性。新配置应优先使用 `openai/*`，并配合显式的 Codex 运行时策略。 +- 将 Codex 放到一个专用智能体上，并设置 `agentRuntime.id: "codex"`。 +- 将默认智能体保持为 `agentRuntime.id: "auto"`，并为常规混合 + 提供商使用保留 Pi 回退。 +- 仅将旧版 `codex/*` 引用用于兼容性。新配置应优先使用 + `openai/*`，再加上显式的 Codex 运行时策略。 -例如，下面的配置会让默认智能体保持正常的自动选择，并额外添加一个单独的 Codex 智能体： +例如，下面的配置会让默认智能体保持正常的自动选择， +并额外添加一个独立的 Codex 智能体： ```json5 { @@ -215,31 +269,37 @@ Harness 选择不是实时会话控制。当一个嵌入式回合运行时，Ope } ``` -采用这种形式时： +采用这种方式： -- 默认的 `main` 智能体使用普通提供商路径和 PI 兼容后备。 +- 默认的 `main` 智能体使用常规提供商路径和 Pi 兼容性回退。 - `codex` 智能体使用 Codex app-server harness。 -- 如果 `codex` 智能体缺少 Codex 或不受支持，该回合会直接失败，而不是悄悄使用 PI。 +- 如果 `codex` 智能体缺少 Codex，或 Codex 对其不受支持，该轮次会直接失败， + 而不是悄悄改为使用 Pi。 ## 智能体命令路由 -智能体应根据用户意图路由请求，而不是仅凭 “Codex” 这个词： +智能体应根据用户意图来路由请求，而不只是看到 “Codex” 这个词： -| 用户请求的是…… | 智能体应使用…… | +| 用户要求的是... | 智能体应使用... | | -------------------------------------------------------- | ------------------------------------------------ | -| “将这个聊天绑定到 Codex” | `/codex bind` | +| “将此聊天绑定到 Codex” | `/codex bind` | | “在这里恢复 Codex 线程 ``” | `/codex resume ` | | “显示 Codex 线程” | `/codex threads` | -| “将 Codex 用作这个智能体的运行时” | 将 `agentRuntime.id` 改为相应配置 | -| “使用我的 ChatGPT/Codex 订阅并搭配普通 OpenClaw” | `openai-codex/*` 模型引用 | +| “将 Codex 用作此智能体的运行时” | 将配置改为 `agentRuntime.id` | +| “用我的 ChatGPT/Codex 订阅配合普通 OpenClaw” | `openai-codex/*` 模型引用 | | “通过 ACP/acpx 运行 Codex” | ACP `sessions_spawn({ runtime: "acp", ... })` | | “在线程中启动 Claude Code/Gemini/OpenCode/Cursor” | ACP/acpx，而不是 `/codex`，也不是原生子智能体 | -只有在 ACP 已启用、可分发并由已加载的运行时后端支持时，OpenClaw 才会向智能体公开 ACP 启动指导。如果 ACP 不可用，系统提示和插件 Skills 不应向智能体传授 ACP 路由方式。 +只有在 ACP 已启用、可分发，并且由已加载的运行时后端支持时， +OpenClaw 才会向智能体公开 ACP 启动指引。如果 ACP 不可用， +系统提示和插件 Skills 不应向智能体传授 ACP +路由方式。 -## 仅 Codex 的部署 +## 仅使用 Codex 的部署 -当你需要证明每个嵌入式智能体回合都使用 Codex 时，请强制使用 Codex harness。显式插件运行时默认不使用 PI 后备，因此 `fallback: "none"` 是可选的，但通常作为文档说明很有用： +当你需要证明每个嵌入式智能体轮次 +都使用 Codex 时，请强制使用 Codex harness。显式插件运行时默认不会回退到 Pi，因此 +`fallback: "none"` 是可选的，但通常有助于作为文档说明： ```json5 { @@ -261,11 +321,15 @@ Harness 选择不是实时会话控制。当一个嵌入式回合运行时，Ope OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -在强制使用 Codex 的情况下，如果 Codex 插件被禁用、app-server 版本过旧，或者 app-server 无法启动，OpenClaw 会尽早失败。只有在你明确希望 PI 接管缺失的 harness 选择时，才设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=pi`。 +强制使用 Codex 后，如果 Codex 插件被禁用、app-server +版本过旧，或 app-server 无法启动，OpenClaw 会尽早失败。只有在你确实希望 Pi 处理 +缺失的 harness 选择时，才设置 +`OPENCLAW_AGENT_HARNESS_FALLBACK=pi`。 -## 按智能体使用 Codex +## 按智能体配置 Codex -你可以让某一个智能体仅使用 Codex，而默认智能体继续保留正常的自动选择： +你可以让某一个智能体仅使用 Codex，同时让默认智能体保持正常的 +自动选择： ```json5 { @@ -296,11 +360,15 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -使用普通会话命令即可切换智能体和模型。`/new` 会创建一个新的 OpenClaw 会话，Codex harness 会根据需要创建或恢复其 sidecar app-server 线程。`/reset` 会清除此线程的 OpenClaw 会话绑定，并让下一个回合再次根据当前配置解析 harness。 +使用普通会话命令即可切换智能体和模型。`/new` 会创建一个全新的 +OpenClaw 会话，而 Codex harness 会根据需要创建或恢复其附属 app-server +线程。`/reset` 会清除该线程的 OpenClaw 会话绑定， +并让下一轮再次根据当前配置解析 harness。 ## 模型发现 -默认情况下，Codex 插件会向 app-server 请求可用模型。如果发现失败或超时，它会使用内置的后备目录，包含： +默认情况下，Codex 插件会向 app-server 请求可用模型。如果 +发现失败或超时，它会使用内置的回退目录，包含： - GPT-5.5 - GPT-5.4 mini @@ -326,7 +394,8 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -如果你希望启动时避免探测 Codex，而是固定使用后备目录，请禁用发现： +如果你希望启动时避免探测 Codex，并固定使用 +回退目录，请禁用发现： ```json5 { @@ -345,19 +414,27 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -## App-server 连接和策略 +## App-server 连接与策略 -默认情况下，插件会在本地使用以下命令启动由 OpenClaw 管理的 Codex 二进制文件： +默认情况下，插件会在本地使用以下命令启动 OpenClaw 管理的 Codex 二进制文件： ```bash codex app-server --listen stdio:// ``` -该托管二进制文件被声明为内置插件运行时依赖项，并与 `codex` 插件的其余依赖项一起准备就绪。这可以让 app-server 版本绑定到内置插件，而不是绑定到本地碰巧安装的某个独立 Codex CLI。只有在你明确想运行不同可执行文件时，才设置 `appServer.command`。 +该受管二进制文件被声明为内置插件运行时依赖，并与 +`codex` 插件的其他依赖一起暂存。 +这样可以将 app-server 版本绑定到内置插件，而不是绑定到本地碰巧安装的独立 Codex CLI。 +只有在你明确希望运行其他可执行文件时，才设置 `appServer.command`。 -默认情况下，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 { @@ -377,11 +454,20 @@ codex app-server --listen stdio:// } ``` -Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求离开沙箱、在工作区之外写入，或添加网络访问等权限时，Codex 会将该审批请求路由给原生审核器，而不是人工提示。审核器会套用 Codex 的风险框架，并批准或拒绝该具体请求。如果你希望比 YOLO 模式有更多护栏，但仍需要无人值守的智能体持续推进，请使用 Guardian。 +Guardian 模式使用 Codex 原生自动审核审批路径。当 Codex 请求 +离开沙箱、在工作区外写入，或添加网络访问等权限时， +Codex 会将该审批请求路由给原生审核者，而不是向人类发出提示。 +审核者会应用 Codex 的风险框架，并批准或拒绝该具体请求。当你希望有比 YOLO 模式更多的防护， +但仍需要无人值守的智能体持续推进工作时，请使用 Guardian。 -`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "auto_review"` 和 `sandbox: "workspace-write"`。单独的策略字段仍然会覆盖 `mode`，因此高级部署可以将该预设与显式选择混合使用。旧的 `guardian_subagent` reviewer 值仍然作为兼容别名被接受，但新配置应使用 `auto_review`。 +`guardian` 预设会展开为 `approvalPolicy: "on-request"`、 +`approvalsReviewer: "auto_review"` 和 `sandbox: "workspace-write"`。 +各个策略字段仍然可以覆盖 `mode`，因此高级部署可以将 +该预设与显式选择混用。较旧的 `guardian_subagent` 审核者值 +仍接受为兼容性别名，但新配置应使用 +`auto_review`。 -对于已经在运行的 app-server，请使用 WebSocket 传输： +对于已在运行的 app-server，请使用 WebSocket 传输： ```json5 { @@ -403,22 +489,62 @@ Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求 } ``` +默认情况下，stdio app-server 启动会继承 OpenClaw 的进程环境， +但 OpenClaw 负责 Codex app-server 账户 bridge。认证按以下顺序选择： + +1. 智能体的显式 OpenClaw Codex auth profile。 +2. app-server 现有的账户，例如本地 Codex CLI ChatGPT 登录。 +3. 仅对本地 stdio app-server 启动，当不存在 app-server 账户且仍需要 OpenAI 认证时，依次使用 `CODEX_API_KEY`，然后 + `OPENAI_API_KEY`。 + +当 OpenClaw 识别到 ChatGPT 订阅风格的 Codex auth profile 时，它会从已启动的 Codex 子进程中移除 +`CODEX_API_KEY` 和 `OPENAI_API_KEY`。 +这样既能保留 Gateway 网关级别的 API key 供 embeddings 或直接 OpenAI 模型使用， +又能避免原生 Codex app-server 轮次意外通过 API 计费。 +显式的 Codex API-key profile 和本地 stdio 环境变量 key 回退会使用 +app-server 登录，而不是继承子进程环境。WebSocket app-server 连接 +不会接收 Gateway 网关环境变量 API key 回退；请使用显式 auth profile，或使用远程 +app-server 自身的账户。 + +如果某个部署需要额外的环境隔离，请将这些变量添加到 +`appServer.clearEnv`： + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + appServer: { + clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"], + }, + }, + }, + }, + }, +} +``` + +`appServer.clearEnv` 只会影响已启动的 Codex app-server 子进程。 + 支持的 `appServer` 字段： | 字段 | 默认值 | 含义 | -| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| ------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 | -| `command` | 托管的 Codex 二进制文件 | 用于 stdio 传输的可执行文件。留空时使用托管二进制文件；仅在明确覆盖时设置。 | -| `args` | `["app-server", "--listen", "stdio://"]` | stdio 传输的参数。 | +| `command` | 受管 Codex 二进制文件 | 用于 stdio 传输的可执行文件。保持未设置即可使用受管二进制文件；仅在明确覆盖时设置。 | +| `args` | `["app-server", "--listen", "stdio://"]` | 用于 stdio 传输的参数。 | | `url` | 未设置 | WebSocket app-server URL。 | -| `authToken` | 未设置 | WebSocket 传输的 Bearer token。 | -| `headers` | `{}` | 额外的 WebSocket 标头。 | +| `authToken` | 未设置 | 用于 WebSocket 传输的 Bearer token。 | +| `headers` | `{}` | 额外的 WebSocket headers。 | +| `clearEnv` | `[]` | 在 OpenClaw 构建完继承环境后，从已启动的 stdio app-server 进程中额外移除的环境变量名。 | | `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 | -| `mode` | `"yolo"` | YOLO 或 guardian 审核执行的预设。 | -| `approvalPolicy` | `"never"` | 发送到线程启动/恢复/回合的原生 Codex 审批策略。 | +| `mode` | `"yolo"` | 用于 YOLO 或 guardian 审核执行的预设。 | +| `approvalPolicy` | `"never"` | 发送到线程启动/恢复/轮次的原生 Codex 审批策略。 | | `sandbox` | `"danger-full-access"` | 发送到线程启动/恢复的原生 Codex 沙箱模式。 | | `approvalsReviewer` | `"user"` | 使用 `"auto_review"` 可让 Codex 审核原生审批提示。`guardian_subagent` 仍是旧版别名。 | -| `serviceTier` | 未设置 | 可选的 Codex app-server service tier：`"fast"`、`"flex"` 或 `null`。无效的旧值会被忽略。 | +| `serviceTier` | 未设置 | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧值会被忽略。 | 环境变量覆盖仍可用于本地测试： @@ -428,16 +554,22 @@ Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求 - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -当 `appServer.command` 未设置时，`OPENCLAW_CODEX_APP_SERVER_BIN` 会绕过托管二进制文件。 +当 `appServer.command` 未设置时，`OPENCLAW_CODEX_APP_SERVER_BIN` 会绕过受管二进制文件。 -`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 设置的其余部分保存在同一个经审查的文件中。 ## Computer Use -Computer Use 有单独的设置指南： +Computer Use 在其单独的设置指南中说明： [Codex Computer Use](/zh-CN/plugins/codex-computer-use)。 -简而言之：OpenClaw 不会内置桌面控制应用，也不会自行执行桌面操作。它会准备 Codex app-server，验证 `computer-use` MCP 服务器是否可用，然后让 Codex 在 Codex 模式回合中处理原生 MCP 工具调用。 +简而言之：OpenClaw 不会内置桌面控制应用，也不会自行执行 +桌面操作。它会准备 Codex app-server，验证 +`computer-use` MCP 服务器是否可用，然后在 Codex 模式轮次期间让 Codex 处理原生 +MCP 工具调用。 最小配置： @@ -474,11 +606,18 @@ Computer Use 有单独的设置指南： - `/codex computer-use install --source ` - `/codex computer-use install --marketplace-path ` -Computer Use 仅适用于 macOS，在 Codex MCP 服务器控制应用之前，可能需要本地操作系统权限。如果 `computerUse.enabled` 为 true 且 MCP 服务器不可用，Codex 模式回合会在线程启动前失败，而不是悄悄在没有原生 Computer Use 工具的情况下运行。有关 marketplace 选择、远程目录限制、状态原因和故障排除，请参阅 [Codex Computer Use](/zh-CN/plugins/codex-computer-use)。 +Computer Use 仅适用于 macOS，并且在 Codex MCP +服务器能够控制应用之前，可能需要本地操作系统权限。如果 `computerUse.enabled` 为 true，而 MCP +服务器不可用，则 Codex 模式轮次会在线程启动前失败，而不是在没有原生 Computer Use 工具的情况下静默运行。有关 +marketplace 选择、远程目录限制、状态原因和故障排除，请参见 +[Codex Computer Use](/zh-CN/plugins/codex-computer-use)。 -当 `computerUse.autoInstall` 为 true 时，如果 Codex 尚未发现本地 marketplace，OpenClaw 可以从 `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` 注册标准内置的 Codex Desktop marketplace。更改运行时或 Computer Use 配置后，请使用 `/new` 或 `/reset`，这样现有会话就不会继续保留旧的 PI 或 Codex 线程绑定。 +当 `computerUse.autoInstall` 为 true 时，如果 Codex 尚未发现本地 marketplace， +OpenClaw 可以从 +`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` 注册标准的内置 Codex Desktop marketplace。更改运行时或 Computer Use 配置后，请使用 `/new` 或 `/reset`， +以免现有会话继续保留旧的 Pi 或 Codex 线程绑定。 -## 常用配方 +## 常见配方 使用默认 stdio 传输的本地 Codex： @@ -494,7 +633,7 @@ Computer Use 仅适用于 macOS，在 Codex MCP 服务器控制应用之前， } ``` -仅 Codex 的 harness 验证： +仅使用 Codex 的 harness 验证： ```json5 { @@ -538,7 +677,7 @@ Computer Use 仅适用于 macOS，在 Codex MCP 服务器控制应用之前， } ``` -带显式标头的远程 app-server： +带显式 headers 的远程 app-server： ```json5 { @@ -561,15 +700,20 @@ Computer Use 仅适用于 macOS，在 Codex MCP 服务器控制应用之前， } ``` -模型切换仍由 OpenClaw 控制。当一个 OpenClaw 会话附加到现有的 Codex 线程时，下一个回合会再次将当前选定的 OpenAI 模型、提供商、审批策略、沙箱和 service tier 发送给 app-server。从 `openai/gpt-5.5` 切换到 `openai/gpt-5.2` 会保留线程绑定，但会要求 Codex 使用新选择的模型继续运行。 +模型切换仍由 OpenClaw 控制。当一个 OpenClaw 会话附加到现有的 Codex 线程时， +下一轮会再次将当前选定的 +OpenAI 模型、提供商、审批策略、沙箱和服务层级发送给 +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 线程。 @@ -581,100 +725,164 @@ Computer Use 仅适用于 macOS，在 Codex MCP 服务器控制应用之前， - `/codex mcp` 列出 Codex app-server MCP 服务器状态。 - `/codex skills` 列出 Codex app-server Skills。 -`/codex resume` 会写入与 harness 在普通回合中使用的相同 sidecar 绑定文件。在下一条消息时，OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw 模型传递给 app-server，并继续启用扩展历史记录。 +`/codex resume` 会写入与 harness 在 +正常轮次中使用的同一个附属绑定文件。在下一条消息中，OpenClaw 会恢复该 Codex 线程，向 +app-server 传入当前选定的 OpenClaw 模型，并保持启用扩展历史记录。 -该命令界面要求 Codex app-server `0.125.0` 或更高版本。如果未来版本或自定义 app-server 未暴露某个 JSON-RPC 方法，单个控制方法会被报告为 `unsupported by this Codex app-server`。 +该命令界面要求使用 Codex app-server `0.125.0` 或更高版本。如果未来或自定义的 app-server 未暴露相应的 JSON-RPC 方法， +各个控制方法会显示为 `unsupported by this Codex app-server`。 -## 钩子边界 +## Hook 边界 -Codex harness 有三层钩子： +Codex harness 有三层 hook： -| 层级 | 所有者 | 用途 | +| 层级 | 所有者 | 目的 | | ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| OpenClaw 插件钩子 | OpenClaw | 在 PI 和 Codex harness 之间提供产品/插件兼容性。 | -| Codex app-server 扩展中间件 | OpenClaw 内置插件 | 围绕 OpenClaw 动态工具的逐回合适配器行为。 | -| Codex 原生钩子 | Codex | 来自 Codex 配置的底层 Codex 生命周期和原生工具策略。 | +| OpenClaw 插件钩子 | OpenClaw | 提供跨 Pi 和 Codex harness 的产品/插件兼容性。 | +| Codex app-server 扩展中间件 | OpenClaw 内置插件 | 围绕 OpenClaw 动态工具的逐轮适配器行为。 | +| Codex 原生 hooks | Codex | 来自 Codex 配置的底层 Codex 生命周期和原生工具策略。 | -OpenClaw 不会使用项目级或全局 Codex `hooks.json` 文件来路由 OpenClaw 插件行为。对于受支持的原生工具和权限桥接，OpenClaw 会为每个线程注入 Codex 配置，用于 `PreToolUse`、`PostToolUse`、`PermissionRequest` 和 `Stop`。其他 Codex 钩子，例如 `SessionStart` 和 `UserPromptSubmit`，仍然是 Codex 级控制；在 v1 合约中，它们不会作为 OpenClaw 插件钩子暴露。 +OpenClaw 不会使用项目级或全局 Codex `hooks.json` 文件来路由 +OpenClaw 插件行为。对于受支持的原生工具和权限桥接， +OpenClaw 会为 `PreToolUse`、`PostToolUse`、 +`PermissionRequest` 和 `Stop` 注入逐线程 Codex 配置。其他 Codex hooks，如 `SessionStart` 和 +`UserPromptSubmit`，仍然是 Codex 级控制；在 v1 合约中，它们不会作为 +OpenClaw 插件钩子暴露。 -对于 OpenClaw 动态工具，Codex 发起调用请求后，OpenClaw 才会执行工具，因此 OpenClaw 会在 harness 适配器中触发其拥有的插件和中间件行为。对于 Codex 原生工具，Codex 拥有规范工具记录。OpenClaw 可以镜像部分事件，但除非 Codex 通过 app-server 或原生钩子回调公开该操作，否则它无法重写原生 Codex 线程。 +对于 OpenClaw 动态工具，在 Codex 请求调用后，OpenClaw 才会执行该工具，因此 +OpenClaw 会在 +harness 适配器中触发其所拥有的插件和中间件行为。对于 Codex 原生工具，Codex 拥有规范的工具记录。 +OpenClaw 可以镜像选定事件，但除非 Codex 通过 app-server 或原生 hook +回调暴露该操作，否则它无法改写原生 Codex +线程。 -压缩和 LLM 生命周期投影来自 Codex app-server 通知以及 OpenClaw 适配器状态，而不是来自原生 Codex 钩子命令。OpenClaw 的 `before_compaction`、`after_compaction`、`llm_input` 和 `llm_output` 事件是适配器级观察结果，而不是对 Codex 内部请求或压缩载荷的逐字节捕获。 +压缩和 LLM 生命周期投影来自 Codex app-server +通知以及 OpenClaw 适配器状态，而不是原生 Codex hook 命令。 +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 模式并不是仅仅在底层换了模型调用的 Pi。Codex 接管了更多 +原生模型 loop，而 OpenClaw 会围绕这一边界来适配其插件和会话界面。 -Codex 运行时 v1 中支持的内容： +Codex runtime v1 中支持的内容： | 界面 | 支持情况 | 原因 | | --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 通过 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 模式载荷触发。 | -| 最终答案修订门控 | 通过原生钩子中继支持 | Codex `Stop` 会中继到 `before_agent_finalize`；`revise` 会在最终完成前请求 Codex 再进行一次模型推理。 | -| 原生 shell、patch 和 MCP 阻止或观察 | 通过原生钩子中继支持 | Codex `PreToolUse` 和 `PostToolUse` 会针对已承诺的原生工具界面进行中继，包括 Codex app-server `0.125.0` 或更高版本上的 MCP 载荷。支持阻止，不支持参数重写。 | -| 原生权限策略 | 通过原生钩子中继支持 | 当运行时暴露该能力时，Codex `PermissionRequest` 可以通过 OpenClaw 策略进行路由。如果 OpenClaw 不返回决策，Codex 会继续沿用其正常的 guardian 或用户审批路径。 | -| app-server 轨迹捕获 | 支持 | OpenClaw 会记录其发送给 app-server 的请求，以及从 app-server 收到的通知。 | +| 通过 Codex 的 OpenAI 模型 loop | 支持 | Codex app-server 负责 OpenAI 轮次、原生线程恢复和原生工具续接。 | +| OpenClaw 渠道路由与投递 | 支持 | Telegram、Discord、Slack、WhatsApp、iMessage 及其他渠道保持在模型运行时之外。 | +| OpenClaw 动态工具 | 支持 | Codex 会请求 OpenClaw 执行这些工具，因此 OpenClaw 仍在执行路径中。 | +| Prompt 和上下文插件 | 支持 | OpenClaw 会在启动或恢复线程前构建 prompt 覆盖层，并将上下文投射到 Codex 轮次中。 | +| 上下文引擎生命周期 | 支持 | Codex 轮次会运行 assemble、ingest 或轮次后维护，以及上下文引擎压缩协调。 | +| 动态工具 hooks | 支持 | `before_tool_call`、`after_tool_call` 和工具结果中间件会围绕 OpenClaw 拥有的动态工具运行。 | +| 生命周期 hooks | 作为适配器观察结果受支持 | `llm_input`、`llm_output`、`agent_end`、`before_compaction` 和 `after_compaction` 会以真实的 Codex 模式负载触发。 | +| 最终答案修订门控 | 通过原生 hook 转发支持 | Codex `Stop` 会转发到 `before_agent_finalize`；`revise` 会在最终完成前请求 Codex 再进行一次模型轮次。 | +| 原生 shell、patch 和 MCP 的拦截或观察 | 通过原生 hook 转发支持 | Codex `PreToolUse` 和 `PostToolUse` 会为已提交的原生工具界面进行转发，包括 Codex app-server `0.125.0` 或更高版本中的 MCP 负载。支持拦截；不支持参数改写。 | +| 原生权限策略 | 通过原生 hook 转发支持 | 当运行时暴露该能力时，Codex `PermissionRequest` 可以通过 OpenClaw 策略路由。如果 OpenClaw 不返回决定，Codex 会继续走其正常的 guardian 或用户审批路径。 | +| App-server 轨迹捕获 | 支持 | OpenClaw 会记录其发送给 app-server 的请求，以及从 app-server 接收到的通知。 | -Codex 运行时 v1 中不支持的内容： +Codex runtime v1 中不支持的内容： | 界面 | V1 边界 | 未来路径 | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -| 原生工具参数变更 | Codex 原生 pre-tool 钩子可以阻止，但 OpenClaw 不会重写 Codex 原生工具参数。 | 需要 Codex 钩子/模式支持替换工具输入。 | -| 可编辑的 Codex 原生转录历史 | Codex 拥有规范的原生线程历史。OpenClaw 拥有一个镜像，并可以投影未来上下文，但不应修改不受支持的内部结构。 | 如果需要原生线程手术操作，则添加显式 Codex app-server API。 | -| 用于 Codex 原生工具记录的 `tool_result_persist` | 该钩子转换的是 OpenClaw 拥有的转录写入，而不是 Codex 原生工具记录。 | 可以镜像转换后的记录，但规范重写需要 Codex 支持。 | -| 丰富的原生压缩元数据 | OpenClaw 可以观察压缩开始和完成，但不会收到稳定的保留/丢弃列表、token 变化量或摘要载荷。 | 需要更丰富的 Codex 压缩事件。 | -| 压缩干预 | 当前 OpenClaw 压缩钩子在 Codex 模式下仅限通知级别。 | 如果插件需要否决或重写原生压缩，则添加 Codex 前/后压缩钩子。 | -| 逐字节的模型 API 请求捕获 | OpenClaw 可以捕获 app-server 请求和通知，但 Codex core 会在内部构建最终的 OpenAI API 请求。 | 需要 Codex 模型请求追踪事件或调试 API。 | +| 原生工具参数变更 | Codex 原生 pre-tool hooks 可以拦截，但 OpenClaw 不会改写 Codex 原生工具参数。 | 需要 Codex hook/schema 支持替换工具输入。 | +| 可编辑的 Codex 原生转录历史 | Codex 拥有规范的原生线程历史。OpenClaw 拥有一个镜像，并可以投射未来上下文，但不应修改不受支持的内部结构。 | 如果需要原生线程手术能力，应添加显式的 Codex app-server API。 | +| 用于 Codex 原生工具记录的 `tool_result_persist` | 该 hook 转换的是由 OpenClaw 拥有的转录写入，而不是 Codex 原生工具记录。 | 可以镜像转换后的记录，但规范改写需要 Codex 支持。 | +| 丰富的原生压缩元数据 | OpenClaw 可以观察到压缩开始和完成，但不会收到稳定的保留/丢弃列表、token 差值或摘要负载。 | 需要更丰富的 Codex 压缩事件。 | +| 压缩干预 | 当前 OpenClaw 的压缩 hooks 在 Codex 模式下仅为通知级。 | 如果插件需要否决或改写原生压缩，则需要添加 Codex pre/post compaction hooks。 | +| 逐字节的模型 API 请求捕获 | OpenClaw 可以捕获 app-server 请求和通知，但最终的 OpenAI API 请求由 Codex 核心在内部构建。 | 需要 Codex 模型请求追踪事件或调试 API。 | -## 工具、媒体和压缩 +## 工具、媒体与压缩 -Codex harness 只会改变底层的嵌入式智能体执行器。 +Codex harness 只改变底层的嵌入式智能体执行器。 -OpenClaw 仍然会构建工具列表，并从 harness 接收动态工具结果。文本、图像、视频、音乐、TTS、审批以及消息工具输出，都会继续通过正常的 OpenClaw 投递路径处理。 +OpenClaw 仍然会构建工具列表，并从 +harness 接收动态工具结果。文本、图像、视频、音乐、TTS、审批和消息工具输出 +仍然通过正常的 OpenClaw 投递路径继续处理。 -原生钩子中继有意保持通用，但 v1 支持合约仅限于 OpenClaw 已测试的 Codex 原生工具和权限路径。在 Codex 运行时中，这包括 shell、patch 和 MCP 的 `PreToolUse`、`PostToolUse` 以及 `PermissionRequest` 载荷。在运行时合约明确命名前，不要假设未来每个 Codex 钩子事件都会成为 OpenClaw 插件界面。 +原生 hook 转发被有意设计为通用机制，但 v1 支持合约仅限于 OpenClaw 已测试的 Codex 原生工具和权限路径。在 +Codex runtime 中，这包括 shell、patch 和 MCP 的 `PreToolUse`、 +`PostToolUse` 以及 `PermissionRequest` 负载。不要假设未来每个 +Codex hook 事件都会成为 OpenClaw 插件界面，除非运行时合约明确命名了它。 -对于 `PermissionRequest`，只有在策略做出决定时，OpenClaw 才会返回显式的允许或拒绝决策。无决策结果并不等于允许。Codex 会将其视为没有钩子决策，并回退到它自己的 guardian 或用户审批路径。 +对于 `PermissionRequest`，只有在策略做出决定时，OpenClaw 才会返回明确的允许或拒绝决定。 +无决定结果并不等于允许。Codex 会将其视为没有 +hook 决定，并回退到其自身的 guardian 或用户审批路径。 -当 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 切换。该 +镜像包括用户 prompt、最终助手文本，以及当 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 和媒体理解 +仍然继续使用匹配的提供商/模型设置，例如 +`agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 +`messages.tts`。 ## 故障排除 -**Codex 没有作为普通 `/model` provider 出现：** 这对新配置来说是预期行为。请选择 `openai/gpt-*` 模型，并设置 `agentRuntime.id: "codex"`（或使用旧版 `codex/*` 引用），启用 `plugins.entries.codex.enabled`，并检查 `plugins.allow` 是否排除了 `codex`。 +**Codex 没有显示为普通的 `/model` 提供商：** 这对于 +新配置是预期行为。请选择一个 `openai/gpt-*` 模型，并设置 +`agentRuntime.id: "codex"`（或使用旧版 `codex/*` 引用），启用 +`plugins.entries.codex.enabled`，并检查 `plugins.allow` 是否排除了 +`codex`。 -**OpenClaw 使用的是 PI 而不是 Codex：** `agentRuntime.id: "auto"` 在没有 Codex harness 接管该运行时，仍可能使用 PI 作为兼容后端。测试时请设置 `agentRuntime.id: "codex"` 以强制选择 Codex。强制使用 Codex 运行时现在会直接失败，而不是回退到 PI，除非你显式设置 `agentRuntime.fallback: "pi"`。一旦选择了 Codex app-server，它的失败会直接暴露出来，不需要额外的后备配置。 +**OpenClaw 使用的是 Pi 而不是 Codex：** 当没有 Codex harness 认领该运行时，`agentRuntime.id: "auto"` 仍可能使用 Pi 作为 +兼容性后端。测试时请设置 +`agentRuntime.id: "codex"` 以强制选择 Codex。现在，强制的 Codex +运行时会直接失败，而不是回退到 Pi，除非你 +显式设置 `agentRuntime.fallback: "pi"`。一旦选择了 Codex app-server， +其失败会直接暴露出来，而不需要额外的回退配置。 -**app-server 被拒绝：** 请升级 Codex，使 app-server 握手报告版本为 `0.125.0` 或更新版本。相同版本号的预发布版本或带构建后缀的版本，例如 `0.125.0-alpha.2` 或 `0.125.0+custom`，都会被拒绝，因为 OpenClaw 测试所依据的协议下限是稳定版 `0.125.0`。 +**app-server 被拒绝：** 升级 Codex，使 app-server 握手 +报告版本 `0.125.0` 或更高。相同版本号的预发布版或带构建后缀的 +版本，如 `0.125.0-alpha.2` 或 `0.125.0+custom`，都会被拒绝，因为 +OpenClaw 测试的是稳定版 `0.125.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：** 这是预期行为，除非你为该智能体强制设置了 `agentRuntime.id: "codex"`，或者选择了旧版 `codex/*` 引用。普通的 `openai/gpt-*` 和其他提供商引用在 `auto` 模式下会保留其正常的提供商路径。如果你强制设置了 `agentRuntime.id: "codex"`，则该智能体的每个嵌入式回合都必须是 Codex 支持的 OpenAI 模型。 +**非 Codex 模型使用了 Pi：** 这是预期行为，除非你为该智能体强制设置了 +`agentRuntime.id: "codex"`，或者选择了旧版 +`codex/*` 引用。普通的 `openai/gpt-*` 和其他提供商引用在 `auto` 模式下仍会走其正常 +提供商路径。如果你强制设置了 `agentRuntime.id: "codex"`，那么该智能体的每一次嵌入式 +轮次都必须是 Codex 支持的 OpenAI 模型。 -**Computer Use 已安装，但工具无法运行：** 请在一个新会话中检查 `/codex computer-use status`。如果某个工具报告 `Native hook relay unavailable`，请使用 `/new` 或 `/reset`；如果问题仍然存在，请重启 Gateway 网关以清除过时的原生钩子注册。如果 `computer-use.list_apps` 超时，请重启 Codex Computer Use 或 Codex Desktop，然后重试。 +**Computer Use 已安装，但工具无法运行：** 请在新会话中检查 +`/codex computer-use status`。如果某个工具报告 +`Native hook relay unavailable`，请使用 `/new` 或 `/reset`；如果仍然存在，请重启 +Gateway 网关以清除过期的原生 hook 注册。如果 `computer-use.list_apps` +超时，请重启 Codex Computer Use 或 Codex Desktop 后重试。 ## 相关内容 - [Agent harness plugins](/zh-CN/plugins/sdk-agent-harness) - [Agent Runtimes](/zh-CN/concepts/agent-runtimes) -- [模型提供商](/zh-CN/concepts/model-providers) +- [Model providers](/zh-CN/concepts/model-providers) - [OpenAI provider](/zh-CN/providers/openai) - [Status](/zh-CN/cli/status) -- [插件钩子](/zh-CN/plugins/hooks) -- [配置参考](/zh-CN/gateway/configuration-reference) +- [Plugin hooks](/zh-CN/plugins/hooks) +- [Configuration reference](/zh-CN/gateway/configuration-reference) - [测试](/zh-CN/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/zh-CN/providers/openai.md b/docs/zh-CN/providers/openai.md index e004ca6ab..9f9b52784 100644 --- a/docs/zh-CN/providers/openai.md +++ b/docs/zh-CN/providers/openai.md @@ -6,34 +6,34 @@ read_when: summary: 在 OpenClaw 中使用 OpenAI 的 API 密钥或 Codex 订阅 title: OpenAI x-i18n: - generated_at: "2026-04-27T13:31:48Z" + generated_at: "2026-04-27T23:52:39Z" model: gpt-5.4 provider: openai - source_hash: f6a33485bb8372dca81d91d35a4fddca315613336adf601efa7ef9a418bf8480 + source_hash: b9cce8535a4ed5991fc931783daa8908fd2ba1e6e183ea5bcbbcffcfad9f76bd source_path: providers/openai.md workflow: 15 --- -OpenAI 为 GPT 模型提供开发者 API，而 Codex 也可通过 OpenAI 的 Codex 客户端，作为 ChatGPT 计划中的编码智能体使用。OpenClaw 将这些能力面分开处理，以便让配置保持可预测。 +OpenAI 为 GPT 模型提供开发者 API，而 Codex 也可通过 OpenAI 的 Codex 客户端作为 ChatGPT 计划中的编程智能体使用。OpenClaw 将这些能力面分开处理，以便让配置保持可预测。 -OpenClaw 支持三种 OpenAI 家族路由。模型前缀用于选择提供商 / 认证路由；另一个单独的运行时设置用于选择由谁执行嵌入式 Agent loop： +OpenClaw 支持三种 OpenAI 家族路由。模型前缀会选择提供商 / 认证路由；单独的运行时设置会选择由谁执行嵌入式 Agent loop： - **API 密钥** — 通过直接 OpenAI Platform 访问并按用量计费（`openai/*` 模型） -- **通过 PI 的 Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型） +- **通过 PI 使用 Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型） - **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型，加上 `agents.defaults.agentRuntime.id: "codex"`） -OpenAI 明确支持在像 OpenClaw 这样的外部工具和工作流中使用订阅 OAuth。 +OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。 -提供商、模型、运行时和渠道是彼此独立的层。如果你把这些标签混在一起了，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，再修改配置。 +提供商、模型、运行时和渠道是彼此独立的层。如果你把这些标签混在了一起，请在修改配置前先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 ## 快速选择 | 目标 | 使用方式 | 说明 | | --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- | -| 直接 API 密钥计费 | `openai/gpt-5.5` | 设置 `OPENAI_API_KEY`，或运行 OpenAI API 密钥新手引导。 | -| 使用 ChatGPT/Codex 订阅认证的 GPT-5.5 | `openai-codex/gpt-5.5` | Codex OAuth 的默认 PI 路由。对于订阅配置，这是最佳首选。 | -| 使用原生 Codex app-server 行为的 GPT-5.5 | `openai/gpt-5.5` 加 `agentRuntime.id: "codex"` | 为该模型引用强制使用 Codex app-server harness。 | -| 图像生成或编辑 | `openai/gpt-image-2` | 可与 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 搭配使用。 | +| 直接使用 API 密钥计费 | `openai/gpt-5.5` | 设置 `OPENAI_API_KEY` 或运行 OpenAI API 密钥新手引导。 | +| 使用 ChatGPT/Codex 订阅认证的 GPT-5.5 | `openai-codex/gpt-5.5` | 适用于 Codex OAuth 的默认 PI 路由。是订阅配置的首选。 | +| 使用原生 Codex app-server 行为的 GPT-5.5 | `openai/gpt-5.5` 加上 `agentRuntime.id: "codex"` | 为该模型引用强制使用 Codex app-server harness。 | +| 图像生成或编辑 | `openai/gpt-image-2` | 可配合 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 使用。 | | 透明背景图像 | `openai/gpt-image-1.5` | 使用 `outputFormat=png` 或 `webp`，并设置 `openai.background=transparent`。 | ## 命名映射 @@ -43,21 +43,21 @@ OpenAI 明确支持在像 OpenClaw 这样的外部工具和工作流中使用订 | 你看到的名称 | 层级 | 含义 | | ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- | | `openai` | 提供商前缀 | 直接 OpenAI Platform API 路由。 | -| `openai-codex` | 提供商前缀 | 通过常规 OpenClaw PI runner 使用 OpenAI Codex OAuth / 订阅路由。 | +| `openai-codex` | 提供商前缀 | 通过标准 OpenClaw PI 运行器使用 OpenAI Codex OAuth / 订阅的路由。 | | `codex` plugin | 插件 | OpenClaw 内置插件，提供原生 Codex app-server 运行时和 `/codex` 聊天控制。 | | `agentRuntime.id: codex` | Agent 运行时 | 为嵌入式轮次强制使用原生 Codex app-server harness。 | | `/codex ...` | 聊天命令集 | 在对话中绑定 / 控制 Codex app-server 线程。 | | `runtime: "acp", agentId: "codex"` | ACP 会话路由 | 通过 ACP/acpx 运行 Codex 的显式回退路径。 | -这意味着，一个配置中可以有意同时包含 `openai-codex/*` 和 `codex` plugin。当你希望通过 PI 使用 Codex OAuth，同时又希望可使用原生 `/codex` 聊天控制时，这样做是有效的。`openclaw doctor` 会对这种组合发出警告，以便你确认这是有意为之；它不会重写该配置。 +这意味着一个配置中可以有意同时包含 `openai-codex/*` 和 `codex` plugin。当你希望通过 PI 使用 Codex OAuth，同时也希望原生 `/codex` 聊天控制可用时，这是有效的。`openclaw doctor` 会对这种组合发出警告，以便你确认这是有意为之；它不会重写该配置。 -GPT-5.5 同时支持通过直接 OpenAI Platform API 密钥访问，以及订阅 / OAuth 路由访问。对直接 `OPENAI_API_KEY` 流量，请使用 `openai/gpt-5.5`；对通过 PI 的 Codex OAuth，请使用 `openai-codex/gpt-5.5`；若要使用原生 Codex app-server harness，请使用 `openai/gpt-5.5` 并配合 `agentRuntime.id: "codex"`。 +GPT-5.5 同时支持直接 OpenAI Platform API 密钥访问和订阅 / OAuth 路由。对直接 `OPENAI_API_KEY` 流量使用 `openai/gpt-5.5`，对通过 PI 使用 Codex OAuth 使用 `openai-codex/gpt-5.5`，或者将 `openai/gpt-5.5` 与 `agentRuntime.id: "codex"` 一起使用以启用原生 Codex app-server harness。 -启用 OpenAI plugin，或选择 `openai-codex/*` 模型，并不会启用内置的 Codex app-server plugin。只有在你明确通过 `agentRuntime.id: "codex"` 选择原生 Codex harness，或使用旧版 `codex/*` 模型引用时，OpenClaw 才会启用该插件。 -如果内置 `codex` plugin 已启用，但 `openai-codex/*` 仍通过 PI 解析，`openclaw doctor` 会发出警告，并保持该路由不变。 +启用 OpenAI plugin，或选择 `openai-codex/*` 模型，并不会启用内置的 Codex app-server plugin。只有当你显式选择原生 Codex harness（使用 `agentRuntime.id: "codex"`）或使用旧版 `codex/*` 模型引用时，OpenClaw 才会启用该插件。 +如果内置的 `codex` plugin 已启用，但 `openai-codex/*` 仍然通过 PI 解析，`openclaw doctor` 会发出警告并保持该路由不变。 ## OpenClaw 功能覆盖范围 @@ -65,20 +65,20 @@ GPT-5.5 同时支持通过直接 OpenAI Platform API 密钥访问，以及订阅 | OpenAI 能力 | OpenClaw 能力面 | Status | | ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ | | 聊天 / Responses | `openai/` 模型提供商 | 是 | -| Codex 订阅模型 | 带有 `openai-codex` OAuth 的 `openai-codex/` | 是 | -| Codex app-server harness | 带有 `agentRuntime.id: codex` 的 `openai/` | 是 | -| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定提供商时 | +| Codex 订阅模型 | 带 `openai-codex` OAuth 的 `openai-codex/` | 是 | +| Codex app-server harness | 带 `agentRuntime.id: codex` 的 `openai/` | 是 | +| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，启用 Web 搜索且未固定提供商时可用 | | 图像 | `image_generate` | 是 | | 视频 | `video_generate` | 是 | | 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 | | 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 | -| 流式语音转文本 | 语音通话 `streaming.provider: "openai"` | 是 | -| 实时语音 | 语音通话 `realtime.provider: "openai"` / Control UI Talk | 是 | -| Embeddings | memory embedding provider | 是 | +| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 | +| 实时语音 | Voice Call `realtime.provider: "openai"` / Control UI Talk | 是 | +| Embeddings | Memory Wiki 嵌入提供商 | 是 | ## Memory embeddings -OpenClaw 可以为 `memory_search` 索引和查询嵌入使用 OpenAI，或兼容 OpenAI 的嵌入端点： +OpenClaw 可以将 OpenAI 或与 OpenAI 兼容的嵌入端点用于 `memory_search` 的索引和查询嵌入： ```json5 { @@ -93,15 +93,15 @@ OpenClaw 可以为 `memory_search` 索引和查询嵌入使用 OpenAI，或兼 } ``` -对于需要非对称嵌入标签的 OpenAI 兼容端点，请在 `memorySearch` 下设置 `queryInputType` 和 `documentInputType`。OpenClaw 会将它们作为提供商特定的 `input_type` 请求字段转发：查询嵌入使用 `queryInputType`；已索引的记忆分块和批量索引使用 `documentInputType`。完整示例请参阅 [Memory configuration reference](/zh-CN/reference/memory-config#provider-specific-config)。 +对于需要非对称嵌入标签的 OpenAI 兼容端点，请在 `memorySearch` 下设置 `queryInputType` 和 `documentInputType`。OpenClaw 会将它们作为提供商特定的 `input_type` 请求字段转发：查询嵌入使用 `queryInputType`；索引后的内存分块和批量索引使用 `documentInputType`。完整示例请参阅 [Memory 配置参考](/zh-CN/reference/memory-config#provider-specific-config)。 ## 入门指南 -选择你偏好的认证方式，并按照设置步骤操作。 +选择你偏好的认证方式，并按步骤完成设置。 - **最适合：** 直接 API 访问和按量计费。 + **最适合：** 直接 API 访问和按用量计费。 @@ -129,12 +129,12 @@ OpenClaw 可以为 `memory_search` 索引和查询嵌入使用 OpenAI，或兼 | 模型引用 | 运行时配置 | 路由 | 认证 | | ---------------------- | -------------------------- | --------------------------- | ---------------- | - | `openai/gpt-5.5` | omitted / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | - | `openai/gpt-5.4-mini` | omitted / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | + | `openai/gpt-5.5` | 省略 / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | + | `openai/gpt-5.4-mini` | 省略 / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server | - `openai/*` 是直接 OpenAI API 密钥路由，除非你显式强制使用 Codex app-server harness。对于通过默认 PI runner 的 Codex OAuth，请使用 `openai-codex/*`；若要使用原生 Codex app-server 执行，请使用 `openai/gpt-5.5` 并配合 `agentRuntime.id: "codex"`。 + `openai/*` 默认是直接 OpenAI API 密钥路由，除非你显式强制使用 Codex app-server harness。通过默认 PI 运行器使用 Codex OAuth 时，请使用 `openai-codex/*`；若要原生 Codex app-server 执行，则使用 `openai/gpt-5.5` 并设置 `agentRuntime.id: "codex"`。 ### 配置示例 @@ -147,7 +147,7 @@ OpenClaw 可以为 `memory_search` 索引和查询嵌入使用 OpenAI，或兼 ``` - OpenClaw **不**公开提供 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，而当前 Codex 目录也未公开它。 + OpenClaw **不**提供 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，当前 Codex 目录也未提供它。 @@ -167,7 +167,7 @@ OpenClaw 可以为 `memory_search` 索引和查询嵌入使用 OpenAI，或兼 openclaw models auth login --provider openai-codex ``` - 对于无头环境或不适合回调的设置，可添加 `--device-code`，通过 ChatGPT device-code 流程登录，而不是使用 localhost 浏览器回调： + 对于无头环境或不适合回调的环境，可以添加 `--device-code`，通过 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调： ```bash openclaw models auth login --provider openai-codex --device-code @@ -189,12 +189,12 @@ OpenClaw 可以为 `memory_search` 索引和查询嵌入使用 OpenAI，或兼 | 模型引用 | 运行时配置 | 路由 | 认证 | |-----------|----------------|-------|------| - | `openai-codex/gpt-5.5` | omitted / `runtime: "pi"` | 通过 PI 的 ChatGPT/Codex OAuth | Codex 登录 | - | `openai-codex/gpt-5.5` | `runtime: "auto"` | 仍为 PI，除非某个插件显式声明 `openai-codex` | Codex 登录 | - | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server auth | + | `openai-codex/gpt-5.5` | 省略 / `runtime: "pi"` | 通过 PI 使用 ChatGPT/Codex OAuth | Codex 登录 | + | `openai-codex/gpt-5.5` | `runtime: "auto"` | 仍然是 PI，除非某个插件显式接管 `openai-codex` | Codex 登录 | + | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server 认证 | - 对于认证 / 配置文件命令，请继续使用 `openai-codex` provider id。`openai-codex/*` 模型前缀也是通过 PI 的 Codex OAuth 的显式路由。 + 认证 / 配置文件命令仍应使用 `openai-codex` 提供商 id。`openai-codex/*` 模型前缀也是通过 PI 使用 Codex OAuth 的显式路由。 它不会选择或自动启用内置的 Codex app-server harness。 @@ -207,55 +207,75 @@ OpenClaw 可以为 `memory_search` 索引和查询嵌入使用 OpenAI，或兼 ``` - 新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的 device-code 流程登录 —— OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。 + 新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上述设备码流程登录——OpenClaw 会在它自己的智能体认证存储中管理生成的凭据。 ### Status 指示器 - 聊天中的 `/status` 会显示当前会话启用了哪个模型运行时。默认的 PI harness 显示为 `Runtime: OpenClaw Pi Default`。选择内置 Codex app-server harness 时，`/status` 会显示 `Runtime: OpenAI Codex`。现有会话会保留其已记录的 harness id，因此如果你在更改 `agentRuntime` 后希望 `/status` 反映新的 PI / Codex 选择，请使用 `/new` 或 `/reset`。 + 聊天中的 `/status` 会显示当前会话正在使用的模型运行时。 + 默认的 PI harness 会显示为 `Runtime: OpenClaw Pi Default`。选择内置 Codex app-server harness 时，`/status` 会显示 + `Runtime: OpenAI Codex`。现有会话会保留其记录的 harness id，因此如果你在更改 `agentRuntime` 后希望 `/status` 反映新的 PI / Codex 选择，请使用 + `/new` 或 `/reset`。 ### Doctor 警告 - 如果在选择此标签页中的 `openai-codex/*` 路由时，内置的 `codex` plugin 也已启用，`openclaw doctor` 会警告该模型仍然通过 PI 解析。如果这是你预期的订阅认证路由，请保持配置不变。只有当你想要原生 Codex app-server 执行时，才切换到 `openai/` 加 `agentRuntime.id: "codex"`。 + 如果启用了内置 `codex` plugin，同时本标签页中选择了 + `openai-codex/*` 路由，`openclaw doctor` 会警告该模型 + 仍然通过 PI 解析。如果这正是你想要的订阅认证路由，请保持配置不变。只有当你想要原生 Codex + app-server 执行时，才切换为 `openai/` 加上 + `agentRuntime.id: "codex"`。 -### 上下文窗口上限 + ### 上下文窗口上限 -OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。 + OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。 -对于通过 Codex OAuth 的 `openai-codex/gpt-5.5`： + 对于通过 Codex OAuth 使用的 `openai-codex/gpt-5.5`： -- 原生 `contextWindow`：`1000000` -- 默认运行时 `contextTokens` 上限：`272000` + - 原生 `contextWindow`：`1000000` + - 默认运行时 `contextTokens` 上限：`272000` -在实践中，较小的默认上限通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它： + 在实际使用中，较小的默认上限通常具有更好的延迟和质量表现。你可以使用 `contextTokens` 覆盖它： -```json5 -{ - models: { - providers: { - "openai-codex": { - models: [{ id: "gpt-5.5", contextTokens: 160000 }], + ```json5 + { + models: { + providers: { + "openai-codex": { + models: [{ id: "gpt-5.5", contextTokens: 160000 }], + }, + }, }, - }, - }, -} -``` + } + ``` - -使用 `contextWindow` 声明模型的原生元数据。使用 `contextTokens` 限制运行时上下文预算。 - + + 使用 `contextWindow` 来声明模型的原生元数据。使用 `contextTokens` 来限制运行时上下文预算。 + -### 目录恢复 + ### 目录恢复 -当上游 Codex 目录元数据中存在 `gpt-5.5` 时，OpenClaw 会使用它。如果实时 Codex 发现未返回 `openai-codex/gpt-5.5` 这一行，但账户已完成认证，OpenClaw 会合成这一 OAuth 模型行，以避免 cron、子智能体和已配置的默认模型运行因 `Unknown model` 而失败。 + 当存在时，OpenClaw 会对 `gpt-5.5` 使用上游 Codex 目录元数据。如果实时 Codex 发现结果中缺少 `openai-codex/gpt-5.5` 这一行，而账户又已完成认证，OpenClaw 会合成这一 OAuth 模型条目，以避免 cron、子智能体和已配置默认模型的运行因 `Unknown model` 而失败。 +## 原生 Codex app-server 认证 + +原生 Codex app-server harness 使用 `openai/*` 模型引用加上 +`agentRuntime.id: "codex"`，但其认证仍然基于账户。OpenClaw +按以下顺序选择认证方式： + +1. 绑定到该智能体的显式 OpenClaw `openai-codex` 认证配置文件。 +2. app-server 的现有账户，例如本地 Codex CLI 的 ChatGPT 登录。 +3. 仅对于本地 stdio app-server 启动，若 app-server 报告没有账户且仍需要 OpenAI 认证，则依次使用 `CODEX_API_KEY`，然后是 + `OPENAI_API_KEY`。 + +这意味着，本地 ChatGPT/Codex 订阅登录不会仅仅因为 Gateway 网关进程也为直接 OpenAI 模型或嵌入配置了 `OPENAI_API_KEY` 而被替换。环境变量 API 密钥回退仅适用于本地 stdio 无账户路径；它不会发送到 WebSocket app-server 连接。当选择订阅式 Codex 配置文件时，OpenClaw 还会将 `CODEX_API_KEY` 和 `OPENAI_API_KEY` 排除在生成的 stdio app-server 子进程之外，并通过 app-server 登录 RPC 发送所选凭据。 + ## 图像生成 -内置的 `openai` plugin 通过 `image_generate` 工具注册图像生成功能。 -它支持使用同一个 `openai/gpt-image-2` 模型引用，通过 OpenAI API 密钥进行图像生成，以及通过 Codex OAuth 进行图像生成。 +内置的 `openai` plugin 通过 `image_generate` 工具注册图像生成。 +它同时支持使用 OpenAI API 密钥进行图像生成，以及通过同一个 `openai/gpt-image-2` 模型引用进行 Codex OAuth 图像生成。 | 能力 | OpenAI API 密钥 | Codex OAuth | | ------------------------- | ---------------------------------- | ------------------------------------ | @@ -263,9 +283,9 @@ OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值 | 认证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 | | 传输 | OpenAI Images API | Codex Responses 后端 | | 每次请求的最大图像数 | 4 | 4 | -| 编辑模式 | 已启用（最多 5 张参考图像） | 已启用（最多 5 张参考图像） | +| 编辑模式 | 已启用（最多 5 张参考图） | 已启用（最多 5 张参考图） | | 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 | -| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全情况下映射为受支持的尺寸 | +| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全情况下映射到受支持的尺寸 | ```json5 { @@ -278,12 +298,16 @@ OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值 ``` -有关共享工具参数、提供商选择和故障转移行为，请参阅 [Image Generation](/zh-CN/tools/image-generation)。 +有关共享工具参数、提供商选择和故障转移行为，请参阅 [图像生成](/zh-CN/tools/image-generation)。 -`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认模型。`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可作为显式模型覆盖使用。对于透明背景的 PNG/WebP 输出，请使用 `openai/gpt-image-1.5`；当前的 `gpt-image-2` API 会拒绝 `background: "transparent"`。 +`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认模型。`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可作为显式模型覆盖使用。对于透明背景的 PNG/WebP 输出，请使用 `openai/gpt-image-1.5`；当前 `gpt-image-2` API 会拒绝 +`background: "transparent"`。 -对于透明背景请求，智能体应调用 `image_generate`，并设置 `model: "openai/gpt-image-1.5"`、`outputFormat: "png"` 或 `"webp"`，以及 `background: "transparent"`；旧的 `openai.background` 提供商选项仍然被接受。OpenClaw 还会通过将默认 `openai/gpt-image-2` 的透明背景请求重写为 `gpt-image-1.5`，来保护公共 OpenAI 和 OpenAI Codex OAuth 路由；Azure 和自定义 OpenAI 兼容端点则保留它们已配置的部署 / 模型名称。 +对于透明背景请求，智能体应调用 `image_generate`，并使用 +`model: "openai/gpt-image-1.5"`、`outputFormat: "png"` 或 `"webp"`，以及 +`background: "transparent"`；较旧的 `openai.background` 提供商选项仍然受支持。OpenClaw 还会通过将默认的 `openai/gpt-image-2` 透明请求重写为 `gpt-image-1.5` 来保护公共 OpenAI 和 +OpenAI Codex OAuth 路由；Azure 和自定义 OpenAI 兼容端点会保留其已配置的部署 / 模型名称。 相同设置也适用于无头 CLI 运行： @@ -296,11 +320,13 @@ openclaw infer image generate \ --json ``` -当从输入文件开始时，对 `openclaw infer image edit` 使用相同的 `--output-format` 和 `--background` 标志。 +从输入文件开始时，对 `openclaw infer image edit` 也使用相同的 `--output-format` 和 `--background` 标志。 `--openai-background` 仍可作为 OpenAI 专用别名使用。 -对于 Codex OAuth 安装，请继续使用相同的 `openai/gpt-image-2` 引用。当配置了 `openai-codex` OAuth 配置文件时，OpenClaw 会解析该已存储的 OAuth 访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试 `OPENAI_API_KEY`，也不会在该请求中静默回退到 API 密钥。如果你想改用直接 OpenAI Images API 路由，请显式配置 `models.providers.openai`，并提供 API 密钥、自定义 base URL 或 Azure 端点。 -如果该自定义图像端点位于受信任的 LAN / 私有地址上，还要设置 `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；若没有这一显式启用项，OpenClaw 会继续阻止私有 / 内部的 OpenAI 兼容图像端点。 +对于 Codex OAuth 安装，继续使用相同的 `openai/gpt-image-2` 引用。当配置了 +`openai-codex` OAuth 配置文件时，OpenClaw 会解析已存储的 OAuth 访问令牌，并通过 Codex Responses 后端发送图像请求。对于该请求，它不会先尝试 `OPENAI_API_KEY`，也不会静默回退到 API 密钥。如果你希望改为直接 OpenAI Images API 路由，请使用 API 密钥、自定义 base URL 或 Azure 端点显式配置 `models.providers.openai`。 +如果该自定义图像端点位于受信任的局域网 / 私有地址上，还需设置 +`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；若没有此显式启用项，OpenClaw 会继续阻止私有 / 内部的 OpenAI 兼容图像端点。 生成： @@ -322,15 +348,15 @@ openclaw infer image generate \ ## 视频生成 -内置的 `openai` plugin 通过 `video_generate` 工具注册视频生成功能。 +内置的 `openai` plugin 通过 `video_generate` 工具注册视频生成。 | 能力 | 值 | | ---------------- | --------------------------------------------------------------------------------- | | 默认模型 | `openai/sora-2` | -| 模式 | 文生视频、图生视频、单视频编辑 | +| 模式 | 文本生成视频、图像生成视频、单视频编辑 | | 参考输入 | 1 张图像或 1 个视频 | | 尺寸覆盖 | 支持 | -| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并产生工具警告 | +| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并附带工具警告 | ```json5 { @@ -343,16 +369,16 @@ openclaw infer image generate \ ``` -有关共享工具参数、提供商选择和故障转移行为，请参阅 [Video Generation](/zh-CN/tools/video-generation)。 +有关共享工具参数、提供商选择和故障转移行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。 -## GPT-5 提示词贡献 +## GPT-5 提示贡献 -OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提示词贡献。它按模型 id 生效，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会接收相同的覆盖层。较旧的 GPT-4.x 模型则不会。 +OpenClaw 会为跨提供商的 GPT-5 家族运行添加一个共享的 GPT-5 提示贡献。它按模型 id 应用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会获得相同的叠加层。较旧的 GPT-4.x 模型则不会。 -内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳覆盖层，因此，强制通过 `agentRuntime.id: "codex"` 的 `openai/gpt-5.x` 会话，即使其余 harness 提示词由 Codex 控制，也会保留相同的跟进行为和主动心跳指导。 +内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳叠加层，因此即使 Codex 接管了其余的 harness 提示，被强制通过 `agentRuntime.id: "codex"` 运行的 `openai/gpt-5.x` 会话仍会保留相同的后续执行和主动心跳指引。 -GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持续性、执行安全、工具纪律、输出形态、完成检查和验证。渠道特定的回复行为和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。对于匹配的模型，GPT-5 指导始终启用。友好交互风格层是独立且可配置的。 +GPT-5 提示贡献为人格持续性、执行安全、工具纪律、输出形状、完成检查和验证添加了带标签的行为契约。渠道特定的回复和静默消息行为则保留在共享的 OpenClaw 系统提示和出站传递策略中。GPT-5 指引始终对匹配模型启用。友好交互风格层是独立的，并且可配置。 | 值 | 效果 | | ---------------------- | ------------------------------------------- | @@ -382,14 +408,14 @@ GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持 -运行时对值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。 +这些值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。 -当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 时，旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退被读取。 +当共享设置 `agents.defaults.promptOverlays.gpt5.personality` 未设置时，旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退被读取。 -## 语音与语音处理 +## 语音与语音识别 @@ -398,14 +424,14 @@ GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | - | 语音 | `messages.tts.providers.openai.voice` | `coral` | + | 音色 | `messages.tts.providers.openai.voice` | `coral` | | 速度 | `messages.tts.providers.openai.speed` | （未设置） | | 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） | | 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺为 `opus`，文件为 `mp3` | | API 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` | | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | - 可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用语音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。 + 可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用音色：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。 ```json5 { @@ -426,14 +452,16 @@ GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持 - 内置的 `openai` plugin 通过 OpenClaw 的媒体理解转录能力面注册了批量语音转文本功能。 + 内置的 `openai` plugin 通过 + OpenClaw 的媒体理解转录能力面注册了批量语音转文本。 - 默认模型：`gpt-4o-transcribe` - 端点：OpenAI REST `/v1/audio/transcriptions` - 输入路径：multipart 音频文件上传 - - 在 OpenClaw 中，凡是入站音频转录使用 `tools.media.audio` 的地方都支持，包括 Discord 语音频道片段和渠道音频附件 + - 在 OpenClaw 中，凡是入站音频转录使用 + `tools.media.audio` 的地方都受支持，包括 Discord 语音频道片段和渠道音频附件 - 若要为入站音频转录强制使用 OpenAI： + 如需为入站音频转录强制使用 OpenAI： ```json5 { @@ -453,36 +481,36 @@ GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持 } ``` - 当共享音频媒体配置或按调用的转录请求提供了语言和提示词提示时，OpenClaw 会将它们转发给 OpenAI。 + 当通过共享音频媒体配置或按次转录请求提供语言和提示时，OpenAI 会接收并使用这些提示信息。 - 内置的 `openai` plugin 为 Voice Call 插件注册了实时转录功能。 + 内置的 `openai` plugin 为 Voice Call plugin 注册了实时转录功能。 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` | | 语言 | `...openai.language` | （未设置） | - | 提示词 | `...openai.prompt` | （未设置） | + | 提示 | `...openai.prompt` | （未设置） | | 静音时长 | `...openai.silenceDurationMs` | `800` | | VAD 阈值 | `...openai.vadThreshold` | `0.5` | | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` | - 使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这个流式提供商用于 Voice Call 的实时转录路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。 + 使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。此流式提供商用于 Voice Call 的实时转录路径；Discord 语音当前则会录制短片段，并改用批量 `tools.media.audio` 转录路径。 - 内置的 `openai` plugin 为 Voice Call 插件注册了实时语音功能。 + 内置的 `openai` plugin 为 Voice Call plugin 注册了实时语音功能。 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` | - | 语音 | `...openai.voice` | `alloy` | - | Temperature | `...openai.temperature` | `0.8` | + | 音色 | `...openai.voice` | `alloy` | + | 温度 | `...openai.temperature` | `0.8` | | VAD 阈值 | `...openai.vadThreshold` | `0.5` | | 静音时长 | `...openai.silenceDurationMs` | `500` | | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` | @@ -492,9 +520,9 @@ GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持 - Control UI Talk 使用 OpenAI 浏览器实时会话、由 Gateway 网关签发的临时客户端密钥，以及针对 OpenAI Realtime API 的浏览器直连 WebRTC SDP 交换。 - 维护者可使用 `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 进行实时验证； - OpenAI 这一段会在 Node 中签发客户端密钥，使用伪造的麦克风媒体生成浏览器 SDP offer，将其提交给 OpenAI，并在不记录密钥的情况下应用 SDP answer。 + Control UI Talk 使用 OpenAI 浏览器实时会话、由 Gateway 网关签发的临时客户端密钥，以及直接面向 OpenAI Realtime API 的浏览器 WebRTC SDP 交换。维护者可使用 + `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` + 进行实时验证；其中 OpenAI 这一侧会在 Node 中签发客户端密钥，使用伪造的麦克风媒体生成浏览器 SDP offer，将其发送给 OpenAI，并在不记录密钥的情况下应用 SDP answer。 @@ -502,15 +530,14 @@ GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持 ## Azure OpenAI 端点 -内置的 `openai` provider 可以通过覆盖 base URL，将图像生成请求定向到 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换为 Azure 的请求格式。 +内置的 `openai` 提供商可以通过覆盖 base URL，将图像生成请求定向到 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 中的 Azure 主机名，并自动切换到 Azure 的请求格式。 实时语音使用单独的配置路径 -（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`）， -不受 `models.providers.openai.baseUrl` 影响。有关其 Azure 设置，请参阅 [语音与语音处理](#voice-and-speech) 下的 **实时语音** 折叠项。 +（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），不受 `models.providers.openai.baseUrl` 影响。其 Azure 设置请参阅 [语音与语音识别](#voice-and-speech) 下的 **实时语音** 折叠项。 -在以下情况下使用 Azure OpenAI： +在以下情况下可使用 Azure OpenAI： - 你已经拥有 Azure OpenAI 订阅、配额或企业协议 - 你需要 Azure 提供的区域数据驻留或合规控制 @@ -518,9 +545,9 @@ GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持 ### 配置 -若要通过内置的 `openai` provider 使用 Azure 进行图像生成，请将 +若要通过内置 `openai` 提供商使用 Azure 进行图像生成，请将 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 -Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）： +Azure OpenAI 密钥（而非 OpenAI Platform 密钥）： ```json5 { @@ -535,33 +562,33 @@ Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）： } ``` -OpenClaw 会识别以下 Azure 主机后缀，以启用 Azure 图像生成路由： +OpenClaw 会识别以下 Azure 主机后缀，并将其用于 Azure 图像生成路由： - `*.openai.azure.com` - `*.services.ai.azure.com` - `*.cognitiveservices.azure.com` -对于发往已识别 Azure 主机的图像生成请求，OpenClaw 会： +对于发送到已识别 Azure 主机的图像生成请求，OpenClaw 会： -- 发送 `api-key` 头，而不是 `Authorization: Bearer` -- 使用以部署为作用域的路径（`/openai/deployments/{deployment}/...`） -- 为每个请求追加 `?api-version=...` +- 发送 `api-key` 请求头，而不是 `Authorization: Bearer` +- 使用按部署作用域划分的路径（`/openai/deployments/{deployment}/...`） +- 为每个请求附加 `?api-version=...` - 对 Azure 图像生成调用使用默认 600 秒请求超时。 - 每次调用的 `timeoutMs` 值仍会覆盖此默认值。 + 按次调用的 `timeoutMs` 值仍会覆盖此默认值。 其他 base URL（公共 OpenAI、OpenAI 兼容代理）会继续使用标准的 OpenAI 图像请求格式。 -`openai` provider 的 Azure 图像生成路由需要 +`openai` 提供商图像生成路径的 Azure 路由要求 OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义 -`openai.baseUrl` 视为公共 OpenAI 端点，从而在 Azure 图像部署上失败。 +`openai.baseUrl` 按公共 OpenAI 端点处理，因此无法用于 Azure +图像部署。 ### API 版本 -设置 `AZURE_OPENAI_API_VERSION` 可为 Azure 图像生成路径固定特定的 -Azure 预览版或正式版版本： +设置 `AZURE_OPENAI_API_VERSION` 可为 Azure 图像生成路径固定某个 Azure 预览版或 GA 版本： ```bash export AZURE_OPENAI_API_VERSION="2024-12-01-preview" @@ -571,58 +598,54 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview" ### 模型名称就是部署名称 -Azure OpenAI 将模型绑定到部署。对于通过内置 `openai` provider 路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure 部署名称**，而不是公共 OpenAI 模型 id。 +Azure OpenAI 会将模型绑定到部署。对于通过内置 `openai` 提供商路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure 部署名称**，而不是公共 OpenAI 模型 id。 -如果你创建了一个名为 `gpt-image-2-prod` 的部署来提供 `gpt-image-2`： +如果你创建了一个名为 `gpt-image-2-prod` 的部署，用于提供 `gpt-image-2`： ``` /tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1 ``` -同样的部署名称规则也适用于通过内置 `openai` provider 路由的图像生成调用。 +同样的部署名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。 ### 区域可用性 -Azure 图像生成目前仅在部分区域可用 +Azure 图像生成当前仅在部分区域可用 （例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、 -`uaenorth`）。创建部署前，请先查看 Microsoft 最新的区域列表，并确认你的区域中提供该特定模型。 +`uaenorth`）。在创建部署前，请先查看 Microsoft 当前的区域列表，并确认你的区域提供所需的具体模型。 ### 参数差异 -Azure OpenAI 和公共 OpenAI 并不总是接受相同的图像参数。 -Azure 可能会拒绝公共 OpenAI 允许的某些选项（例如 -`gpt-image-2` 上的某些 `background` 值），或者仅在特定模型版本上提供这些选项。这些差异来自 Azure 和底层模型，而不是 -OpenClaw。如果 Azure 请求因验证错误而失败，请在 -Azure 门户中检查你的具体部署和 API 版本所支持的参数集。 +Azure OpenAI 与公共 OpenAI 并不总是接受相同的图像参数。 +Azure 可能会拒绝公共 OpenAI 允许的某些选项（例如在 `gpt-image-2` 上的某些 +`background` 值），或者仅在特定模型版本上提供这些选项。这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 +Azure 门户中检查你的具体部署和 API 版本所支持的参数集合。 Azure OpenAI 使用原生传输和兼容行为，但不会接收 -OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configuration) 下的 **原生 vs OpenAI-compatible routes** 折叠项。 +OpenClaw 的隐藏归因请求头——请参阅 [高级配置](#advanced-configuration) 下 **原生与 OpenAI 兼容路由** 折叠项。 -对于 Azure 上的聊天或 Responses 流量（除图像生成之外），请使用 -新手引导流程或专用的 Azure provider 配置 —— 仅设置 -`openai.baseUrl` 不会启用 Azure API / 认证格式。另有一个独立的 -`azure-openai-responses/*` provider；请参阅下方的 -服务端压缩折叠项。 +若要在 Azure 上使用聊天或 Responses 流量（除图像生成外），请使用新手引导流程或专用的 Azure 提供商配置——仅设置 `openai.baseUrl` 并不会自动采用 Azure 的 API / 认证格式。另有单独的 +`azure-openai-responses/*` 提供商；请参阅下方的服务端压缩折叠项。 ## 高级配置 - - OpenClaw 对 `openai/*` 和 `openai-codex/*` 都使用 WebSocket 优先、SSE 回退（`"auto"`）。 + + 对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都采用 WebSocket 优先并带 SSE 回退（`"auto"`）的方式。 在 `"auto"` 模式下，OpenClaw 会： - - 在回退到 SSE 之前重试一次早期 WebSocket 失败 - - 失败后将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE - - 为重试和重连附加稳定的会话与轮次身份头 - - 统一不同传输变体下的用量计数器（`input_tokens` / `prompt_tokens`） + - 在回退到 SSE 之前，对一次早期 WebSocket 失败进行重试 + - 在发生失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE + - 为重试和重连附加稳定的会话与轮次身份请求头 + - 在不同传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`） | 值 | 行为 | |-------|----------| | `"auto"`（默认） | WebSocket 优先，SSE 回退 | - | `"sse"` | 强制仅使用 SSE | - | `"websocket"` | 强制仅使用 WebSocket | + | `"sse"` | 仅强制使用 SSE | + | `"websocket"` | 仅强制使用 WebSocket | ```json5 { @@ -668,12 +691,12 @@ OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configurat - OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供了共享的快速模式开关： + OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供共享的快速模式开关： - **聊天 / UI：** `/fast status|on|off` - **配置：** `agents.defaults.models["/"].params.fastMode` - 启用后，OpenClaw 会将快速模式映射到 OpenAI 的优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。 + 启用后，OpenClaw 会将快速模式映射为 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。 ```json5 { @@ -694,7 +717,7 @@ OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configurat - OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置它： + OpenAI 的 API 通过 `service_tier` 提供优先处理能力。在 OpenClaw 中可按模型设置： ```json5 { @@ -711,7 +734,7 @@ OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configurat 支持的值：`auto`、`default`、`flex`、`priority`。 - `serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一 provider，OpenClaw 会保持 `service_tier` 原样不变。 + `serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保留 `service_tier` 原样，不做处理。 @@ -719,11 +742,11 @@ OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configurat 对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI plugin 的 Pi harness 流包装器会自动启用服务端压缩： - - 强制设置 `store: true`（除非模型兼容性设置 `supportsStore: false`） + - 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`） - 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]` - - 默认 `compact_threshold`：`contextWindow` 的 70%（若不可用则为 `80000`） + - 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`） - 这适用于内置 Pi harness 路径，也适用于嵌入式运行使用的 OpenAI provider 钩子。原生 Codex app-server harness 通过 Codex 自行管理上下文，并通过 `agents.defaults.agentRuntime.id` 单独配置。 + 这适用于内置 Pi harness 路径，也适用于嵌入式运行所使用的 OpenAI 提供商钩子。原生 Codex app-server harness 则通过 Codex 管理自己的上下文，并通过 `agents.defaults.agentRuntime.id` 单独配置。 @@ -779,13 +802,13 @@ OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configurat - `responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性配置将 `supportsStore` 设为 `false`。 + `responsesServerCompaction` 仅控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性配置将 `supportsStore` 设为 `false`。 - 对于 `openai/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行契约： + 对于 `openai/*` 上的 GPT-5 家族运行，OpenClaw 可以使用更严格的嵌入式执行契约： ```json5 { @@ -797,36 +820,36 @@ OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configurat } ``` - 使用 `strict-agentic` 时，OpenClaw 会： - - 当有可用工具操作时，不再将仅计划轮次视为成功进展 - - 通过“立即行动”的引导重试该轮次 - - 对于实质性工作，自动启用 `update_plan` - - 如果模型持续规划但不执行，则显式显示阻塞状态 + 在 `strict-agentic` 模式下，OpenClaw 会： + - 当工具操作可用时，不再将仅有计划的轮次视为成功进展 + - 使用“立即行动”的引导重试该轮次 + - 对于实质性工作自动启用 `update_plan` + - 如果模型持续只做计划而不执行操作，则显示明确的阻塞状态 - 仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他 provider 和较旧的模型家族保持默认行为。 + 仅适用于 OpenAI 和 Codex 的 GPT-5 家族运行。其他提供商和较旧的模型家族会保留默认行为。 - - OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，以及通用的 OpenAI-compatible `/v1` 代理： + + OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，以及通用的 OpenAI 兼容 `/v1` 代理： **原生路由**（`openai/*`、Azure OpenAI）： - 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }` - 对会拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用的 reasoning - 默认将工具 schema 设为严格模式 - - 仅在已验证的原生主机上附加隐藏归因头 - - 保留 OpenAI 专用请求格式（`service_tier`、`store`、reasoning 兼容性、prompt-cache 提示） + - 仅在已验证的原生主机上附加隐藏归因请求头 + - 保留 OpenAI 专用请求整形（`service_tier`、`store`、reasoning 兼容性、提示缓存提示） **代理 / 兼容路由：** - 使用更宽松的兼容行为 - - 从非原生 `openai-completions` 负载中剥离 Completions `store` - - 为 OpenAI-compatible Completions 代理接受高级 `params.extra_body` / `params.extraBody` 透传 JSON - - 为 OpenAI-compatible Completions 代理（如 vLLM）接受 `params.chat_template_kwargs` - - 不会强制使用严格工具 schema 或原生专用头 + - 从非原生 `openai-completions` 负载中移除 Completions `store` + - 接受面向 OpenAI 兼容 Completions 代理的高级 `params.extra_body` / `params.extraBody` 透传 JSON + - 接受面向 OpenAI 兼容 Completions 代理（如 vLLM）的 `params.chat_template_kwargs` + - 不强制使用严格工具 schema 或原生专用请求头 - Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因头。 + Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因请求头。 @@ -844,6 +867,6 @@ OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configurat 共享视频工具参数和提供商选择。 - 认证细节和凭证复用规则。 + 认证细节和凭据复用规则。