From d8f583ec90b192100a0e7c0c40af480695d78ef4 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 23 Apr 2026 22:16:19 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/ci.md | 124 +++-- docs/zh-CN/concepts/memory-qmd.md | 119 ++--- docs/zh-CN/gateway/cli-backends.md | 178 ++++--- docs/zh-CN/providers/cloudflare-ai-gateway.md | 46 +- docs/zh-CN/providers/openai.md | 323 ++++++------ docs/zh-CN/reference/test.md | 88 ++-- docs/zh-CN/tools/exec-approvals.md | 485 ++++++++---------- docs/zh-CN/tools/image-generation.md | 96 ++-- 8 files changed, 700 insertions(+), 759 deletions(-) diff --git a/docs/zh-CN/ci.md b/docs/zh-CN/ci.md index 4d5d0eb7f..e1102a6f2 100644 --- a/docs/zh-CN/ci.md +++ b/docs/zh-CN/ci.md @@ -1,29 +1,25 @@ --- read_when: - - 你需要了解某个 CI 作业为什么会运行或不会运行 + - 你需要了解某个 CI 作业为什么运行或没有运行 - 你正在调试失败的 GitHub Actions 检查 -summary: CI 作业图、范围门禁以及对应的本地命令 +summary: CI 作业图、范围门禁，以及本地等效命令 title: CI 流水线 x-i18n: - generated_at: "2026-04-23T20:42:40Z" + generated_at: "2026-04-23T22:14:40Z" model: gpt-5.4 provider: openai - source_hash: f06d3bec8a44402afb3aeec252105d3e3c985307deb3fcc0859c2d1df50f2612 + source_hash: d2aa581f173b7171373a9292cef3da20621b845d81a8550bd8b4c8e743d27a4b source_path: ci.md workflow: 15 --- -CI 会在每次推送到 `main` 以及每个 pull request 上运行。它使用智能范围划分，在仅更改了无关区域时跳过高开销作业。 +CI 会在每次推送到 `main` 和每个拉取请求时运行。它使用智能范围界定，在只改动了无关区域时跳过昂贵的作业。 -QA Lab 在主智能范围工作流之外有专用的 CI 通道。 -`Parity gate` 工作流会在匹配的 PR 变更和手动派发时运行；它会构建私有 QA 运行时，并比较模拟的 GPT-5.4 和 Opus 4.6 agentic pack。 -`QA-Lab - All Lanes` 工作流会在 `main` 上每晚运行，也可通过手动派发运行；它会将模拟 parity gate、实时 Matrix 通道和实时 Telegram 通道作为并行作业扇出。 -实时作业使用 `qa-live-shared` 环境，而 Telegram 通道使用 Convex lease。 -`OpenClaw Release Checks` 也会在发布批准前运行同样的 QA Lab 通道。 +QA Lab 在主智能范围工作流之外有专门的 CI 通道。`Parity gate` 工作流会在匹配的 PR 变更和手动触发时运行；它会构建私有 QA 运行时，并比较模拟的 GPT-5.4 和 Opus 4.6 智能体包。`QA-Lab - All Lanes` 工作流会在 `main` 上每晚运行，也可手动触发；它会将模拟 parity gate、实时 Matrix 通道和实时 Telegram 通道并行展开为多个作业。实时作业使用 `qa-live-shared` 环境，而 Telegram 通道使用 Convex 租约。`OpenClaw Release Checks` 也会在发布批准前运行同样的 QA Lab 通道。 -`Duplicate PRs After Merge` 工作流是一个供维护者使用的手动工作流，用于在落地后清理重复 PR。它默认采用 dry-run，只有在 `apply=true` 时才会关闭明确列出的 PR。在修改 GitHub 之前，它会验证已落地的 PR 确实已合并，并且每个重复 PR 都有共享的引用 issue 或重叠的变更 hunk。 +`Duplicate PRs After Merge` 工作流是一个供维护者在合并后清理重复 PR 的手动工作流。它默认是 dry-run，只有在 `apply=true` 时才会关闭明确列出的 PR。在修改 GitHub 之前，它会验证已合并的 PR 确实已经合并，并确认每个重复 PR 要么共享一个被引用的问题，要么具有重叠的修改 hunk。 -`Test Performance Agent` 工作流是一个事件驱动的 Codex 维护通道，用于处理慢测试。它没有纯定时调度：当 `main` 上一次成功的非机器人 push CI 运行完成后，可以触发它；但如果当天 UTC 内另一个 workflow-run 调用已经运行过或正在运行，它就会跳过。手动派发会绕过这个每日活动门禁。该通道会构建完整测试套件的分组 Vitest 性能报告，让 Codex 仅进行小范围且保持覆盖率的测试性能修复，然后重新运行完整测试套件报告，并拒绝任何会降低通过基线测试数量的更改。如果基线本身有失败测试，Codex 只能修复明显失败的问题，并且在提交任何内容之前，智能体执行后的完整测试套件报告必须通过。它使用 GitHub 托管的 Ubuntu，以便 Codex action 可以保持与 docs agent 相同的 drop-sudo 安全策略。 +`Test Performance Agent` 工作流是一个面向慢测试的事件驱动 Codex 维护通道。它没有单纯的定时调度：`main` 上一次成功的、非机器人触发的 push CI 运行可以触发它，但如果当天 UTC 已经有另一个由 workflow-run 触发的实例运行过或正在运行，它就会跳过。手动触发会绕过这个按天活动门禁。该通道会构建一个全量测试套件的分组 Vitest 性能报告，让 Codex 只进行小范围、保持覆盖率不变的测试性能修复，而不是做大范围重构，然后重新运行全量测试套件报告，并拒绝任何会降低通过基线测试数量的改动。如果基线中存在失败测试，Codex 只能修复明显的失败项，而且在提交任何内容之前，智能体处理后的全量测试套件报告必须通过。当 `main` 在机器人 push 落地之前继续前进时，该通道会对已验证的补丁执行 rebase，重新运行 `pnpm check:changed`，并重试 push；有冲突的过时补丁会被跳过。它使用 GitHub 托管的 Ubuntu，这样 Codex action 就能与文档智能体保持相同的 drop-sudo 安全策略。 ```bash gh workflow run duplicate-after-merge.yml \ @@ -34,87 +30,87 @@ gh workflow run duplicate-after-merge.yml \ ## 作业概览 -| 作业 | 用途 | 运行时机 | -| ---- | ---- | -------- | -| `preflight` | 检测仅文档变更、变更范围、已变更的 extensions，并构建 CI 清单 | 所有非草稿 push 和 PR | -| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 所有非草稿 push 和 PR | -| `security-dependency-audit` | 针对 npm advisory 执行无依赖的生产 lockfile 审计 | 所有非草稿 push 和 PR | -| `security-fast` | 快速安全作业的必需聚合作业 | 所有非草稿 push 和 PR | -| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查，以及可复用的下游产物 | Node 相关变更 | -| `checks-fast-core` | 快速 Linux 正确性通道，例如 bundled/plugin-contract/protocol 检查 | Node 相关变更 | -| `checks-fast-contracts-channels` | 分片的渠道契约检查，并带有稳定的聚合检查结果 | Node 相关变更 | -| `checks-node-extensions` | 覆盖整个 extension 套件的完整内置插件测试分片 | Node 相关变更 | -| `checks-node-core-test` | Core Node 测试分片，不包括渠道、内置、契约和 extension 通道 | Node 相关变更 | -| `extension-fast` | 仅针对已变更内置插件的聚焦测试 | 带有 extension 变更的 pull request | -| `check` | 分片的主本地门禁等价项：生产类型、lint、守卫、测试类型和严格冒烟 | Node 相关变更 | -| `check-additional` | 架构、边界、extension-surface 守卫、package-boundary 和 gateway-watch 分片 | Node 相关变更 | -| `build-smoke` | 已构建 CLI 冒烟测试和启动内存冒烟 | Node 相关变更 | -| `checks` | 已构建产物渠道测试的验证器，以及仅 push 时运行的 Node 22 兼容性检查 | Node 相关变更 | -| `check-docs` | 文档格式、lint 和断链检查 | 文档有变更时 | -| `skills-python` | 面向 Python 支持 Skills 的 Ruff + pytest | 与 Python Skills 相关的变更 | -| `checks-windows` | Windows 特定测试通道 | 与 Windows 相关的变更 | -| `macos-node` | 使用共享构建产物的 macOS TypeScript 测试通道 | 与 macOS 相关的变更 | -| `macos-swift` | macOS app 的 Swift lint、构建和测试 | 与 macOS 相关的变更 | -| `android` | 两种 flavor 的 Android 单元测试，以及一个 debug APK 构建 | 与 Android 相关的变更 | -| `test-performance-agent` | 在可信活动后每日进行一次 Codex 慢测试优化 | Main CI 成功后或手动派发 | +| Job | 目的 | 运行时机 | +| -------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------- | +| `preflight` | 检测是否仅为文档改动、改动范围、改动的扩展，并构建 CI 清单 | 始终在非 draft 的 push 和 PR 上运行 | +| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 始终在非 draft 的 push 和 PR 上运行 | +| `security-dependency-audit` | 针对 npm 安全公告执行无依赖的生产 lockfile 审计 | 始终在非 draft 的 push 和 PR 上运行 | +| `security-fast` | 快速安全作业的必需聚合作业 | 始终在非 draft 的 push 和 PR 上运行 | +| `build-artifacts` | 构建 `dist/`、Control UI、已构建产物检查，以及可复用的下游产物 | 与 Node 相关的变更 | +| `checks-fast-core` | 快速 Linux 正确性通道，例如内置/插件契约/协议检查 | 与 Node 相关的变更 | +| `checks-fast-contracts-channels` | 分片的渠道契约检查，并提供稳定的聚合检查结果 | 与 Node 相关的变更 | +| `checks-node-extensions` | 覆盖整个扩展套件的完整内置插件测试分片 | 与 Node 相关的变更 | +| `checks-node-core-test` | 核心 Node 测试分片，不包括渠道、内置、契约和扩展通道 | 与 Node 相关的变更 | +| `extension-fast` | 仅针对已改动的内置插件运行聚焦测试 | 具有扩展改动的拉取请求 | +| `check` | 分片后的主本地门禁等效项：生产类型、lint、守卫、测试类型和严格 smoke | 与 Node 相关的变更 | +| `check-additional` | 架构、边界、扩展表面守卫、包边界和 gateway-watch 分片 | 与 Node 相关的变更 | +| `build-smoke` | 已构建 CLI 的 smoke 测试和启动内存 smoke | 与 Node 相关的变更 | +| `checks` | 针对已构建产物的渠道测试验证器，以及仅 push 触发的 Node 22 兼容性检查 | 与 Node 相关的变更 | +| `check-docs` | 文档格式、lint 和断链检查 | 文档发生改动 | +| `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 成功后或手动触发 | ## 快速失败顺序 -作业的排序方式确保廉价检查会先失败，而不会让高开销作业先运行： +作业的排序方式是让便宜的检查先失败，再决定是否运行昂贵作业： -1. `preflight` 决定究竟存在哪些通道。`docs-scope` 和 `changed-scope` 逻辑是该作业中的步骤，而不是独立作业。 -2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，而无需等待更重的产物和平台矩阵作业。 -3. `build-artifacts` 会与快速 Linux 通道重叠运行，这样下游使用方可以在共享构建就绪后立即开始。 -4. 更重的平台和运行时通道随后扇出：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-extensions`、`checks-node-core-test`、仅 PR 的 `extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 +1. `preflight` 决定究竟存在哪些通道。`docs-scope` 和 `changed-scope` 逻辑是这个作业内部的步骤，不是独立作业。 +2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，而不会等待更重的产物与平台矩阵作业。 +3. `build-artifacts` 与快速 Linux 通道并行运行，这样下游消费者一旦共享构建就绪即可开始。 +4. 更重的平台和运行时通道会在之后展开：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-extensions`、`checks-node-core-test`、仅 PR 的 `extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 范围逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。 -CI 工作流编辑会验证 Node CI 图和工作流 lint，但不会仅因为这些编辑本身就强制运行 Windows、Android 或 macOS 原生构建；这些平台通道仍然只对平台源码变更进行范围匹配。 -Windows Node 检查的范围仅限于 Windows 特定的进程/路径包装器、npm/pnpm/UI 运行器辅助工具、包管理器配置，以及执行该通道的 CI 工作流表面；无关的源码、插件、install-smoke 和纯测试变更仍会留在 Linux Node 通道中，因此不会为已由普通测试分片覆盖的内容占用一个 16 vCPU 的 Windows worker。 -独立的 `install-smoke` 工作流会通过其自身的 `preflight` 作业复用同一个范围脚本。它根据更窄的 changed-smoke 信号计算 `run_install_smoke`，因此 Docker/install smoke 会对安装、打包、容器相关变更、内置 extension 生产变更，以及 Docker smoke 作业所覆盖的 core plugin/channel/gateway/Plugin SDK 表面运行。纯测试和纯文档编辑不会占用 Docker worker。它的 QR package smoke 会强制重新运行 Docker `pnpm install` 层，同时保留 BuildKit pnpm store 缓存，因此仍能覆盖安装流程，而不必在每次运行时重新下载依赖。其 gateway-network e2e 会复用该作业前面构建的运行时镜像，因此在不增加另一次 Docker 构建的前提下，增加了真实的容器到容器 WebSocket 覆盖。本地 `test:docker:all` 会预构建一个共享的 live-test 镜像和一个共享的 `scripts/e2e/Dockerfile` built-app 镜像，然后在 `OPENCLAW_SKIP_DOCKER_BUILD=1` 下并行运行 live/E2E smoke 通道；默认并发数为 4，可通过 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整。本地聚合默认会在首次失败后停止调度新的池化通道，并且每个通道都有一个 120 分钟的超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖。对启动或 provider 敏感的通道会在并行池之后独占运行。可复用的 live/E2E 工作流也遵循共享镜像模式：它会在 Docker 矩阵之前先构建并推送一个带 SHA tag 的 GHCR Docker E2E 镜像，然后在矩阵中使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。定时的 live/E2E 工作流每天都会运行完整的发布路径 Docker 套件。QR 和安装器 Docker 测试则保留各自专注于安装的 Dockerfile。另有一个独立的 `docker-e2e-fast` 作业，会在 120 秒命令超时下运行有界的内置插件 Docker 配置文件：setup-entry 依赖修复以及合成的 bundled-loader 故障隔离。完整的内置更新/渠道矩阵仍然是手动/完整套件，因为它会执行重复的真实 npm update 和 doctor 修复过程。 +CI 工作流编辑会验证 Node CI 图以及工作流 lint，但不会仅凭这些改动就强制运行 Windows、Android 或 macOS 原生构建；这些平台通道仍然只对平台源码变更生效。 +Windows Node 检查的范围只覆盖 Windows 专用的进程/路径包装器、npm/pnpm/UI 运行器辅助、包管理器配置，以及执行该通道的 CI 工作流表面；无关的源码、插件、安装 smoke 和纯测试改动会保留在 Linux Node 通道中，这样就不会为了已经由常规测试分片覆盖的内容去占用一个 16 vCPU 的 Windows worker。 +独立的 `install-smoke` 工作流会通过其自己的 `preflight` 作业复用同一个范围脚本。它会根据更窄的 changed-smoke 信号计算 `run_install_smoke`，因此 Docker/安装 smoke 会在安装、打包、容器相关变更、内置扩展生产代码变更，以及 Docker smoke 作业实际覆盖的核心插件/渠道/Gateway 网关/插件 SDK 表面发生改动时运行。纯测试和纯文档编辑不会占用 Docker worker。它的 QR 包 smoke 会强制 Docker 的 `pnpm install` 层重新运行，同时保留 BuildKit 的 pnpm store 缓存，因此仍然可以验证安装流程，而无需每次运行都重新下载依赖。它的 gateway-network e2e 会复用该作业中先前构建的运行时镜像，因此在不新增一次 Docker 构建的情况下，增加了真实的容器到容器 WebSocket 覆盖。本地 `test:docker:all` 会预构建一个共享的 live-test 镜像和一个共享的 `scripts/e2e/Dockerfile` built-app 镜像，然后在设置 `OPENCLAW_SKIP_DOCKER_BUILD=1` 的情况下并行运行 live/E2E smoke 通道；默认并发数为 4，可通过 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整。默认情况下，本地聚合器会在首次失败后停止调度新的池化通道，并且每个通道都有一个 120 分钟的超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖。对启动或 provider 敏感的通道会在并行池之后独占运行。可复用的 live/E2E 工作流也遵循同样的共享镜像模式：在 Docker 矩阵之前先构建并推送一个带 SHA 标签的 GHCR Docker E2E 镜像，然后在矩阵中通过 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。计划执行的 live/E2E 工作流每天运行完整的发布路径 Docker 套件。QR 和安装器 Docker 测试保留各自专注于安装的 Dockerfile。另有一个单独的 `docker-e2e-fast` 作业，会在 120 秒命令超时限制下运行有界的内置插件 Docker 配置：setup-entry 依赖修复加上合成的 bundled-loader 故障隔离。完整的内置更新/渠道矩阵仍然是手动/全量套件，因为它会反复执行真实的 npm update 和 doctor repair 流程。 -本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。这个本地门禁在架构边界上比宽泛的 CI 平台范围更严格：core 生产变更会运行 core 生产 typecheck 加 core 测试，core 纯测试变更只运行 core 测试 typecheck/测试，extension 生产变更会运行 extension 生产 typecheck 加 extension 测试，extension 纯测试变更只运行 extension 测试 typecheck/测试。公开的 Plugin SDK 或 plugin-contract 变更会扩展到 extension 验证，因为 extensions 依赖这些 core 契约。仅发布元数据的版本提升会运行有针对性的 version/config/root-dependency 检查。未知的 root/config 变更会以安全优先方式回退到所有通道。 +本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，由 `scripts/check-changed.mjs` 执行。这个本地门禁在架构边界方面比宽泛的 CI 平台范围更严格：核心生产代码变更会运行核心生产 typecheck 加核心测试，核心纯测试变更只运行核心测试 typecheck/测试，扩展生产代码变更会运行扩展生产 typecheck 加扩展测试，而扩展纯测试变更只运行扩展测试 typecheck/测试。公共插件 SDK 或插件契约变更会扩展为扩展验证，因为扩展依赖这些核心契约。仅有发布元数据的版本号提升会运行定向的版本/配置/根依赖检查。未知的根目录/配置变更会采用安全失败策略，运行所有通道。 -在 push 上，`checks` 矩阵会额外加入仅 push 时运行的 `compat-node22` 通道。在 pull request 上，该通道会被跳过，矩阵只聚焦于常规测试/渠道通道。 +在 push 上，`checks` 矩阵会加入仅在 push 上运行的 `compat-node22` 通道。在拉取请求上，该通道会被跳过，矩阵会专注于常规测试/渠道通道。 -最慢的 Node 测试族会被拆分或均衡，以便每个作业都保持较小规模，同时避免过度预留 runner：渠道契约以三个加权分片运行，内置插件测试在六个 extension worker 之间均衡分配，小型 core 单元通道成对组合，auto-reply 改为三个均衡 worker 而不是六个很小的 worker，而 agentic gateway/plugin 配置则分布到现有仅源码的 agentic Node 作业中，而不是等待构建产物。范围较广的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件兜底配置。Extension 分片作业会以单个 Vitest worker 和更大的 Node heap 串行运行插件配置组，这样导入负载较重的插件批次就不会使小型 CI runner 过度提交。宽泛的 agents 通道使用共享的 Vitest 文件级并行调度器，因为它主要受导入/调度支配，而不是由某个单独的慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享运行时分片承担尾部。`check-additional` 会将 package-boundary compile/canary 工作保持在一起，并将运行时拓扑架构与 gateway watch 覆盖分离；boundary guard 分片会在一个作业内部并发运行其小型独立守卫。Gateway watch、渠道测试以及 core support-boundary 分片会在 `build-artifacts` 中于 `dist/` 和 `dist-runtime/` 已构建完成后并发运行，保留它们旧的检查名称作为轻量验证作业，同时避免额外占用两个 Blacksmith worker 和第二条产物消费者队列。 +最慢的 Node 测试家族会被拆分或平衡，以便每个作业都保持较小规模，同时不过度预留 runner：渠道契约以三个加权分片运行，内置插件测试在六个扩展 worker 之间平衡分配，小型核心单元通道会成对组合，auto-reply 使用三个平衡 worker 而不是六个很小的 worker，而智能体式 Gateway 网关/插件配置会分散到现有的仅源码智能体式 Node 作业中，而不是等待已构建产物。宽泛的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件兜底配置。扩展分片作业会以串行方式运行插件配置组，使用一个 Vitest worker 和更大的 Node 堆，以避免导入密集型插件批次让小型 CI runner 过度提交。宽泛的 agents 通道使用共享的 Vitest 文件级并行调度器，因为它受导入/调度主导，而不是由某个单一慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享运行时分片独自承担尾部耗时。`check-additional` 会将包边界 compile/canary 工作保留在一起，并将运行时拓扑架构与 gateway watch 覆盖分开；边界守卫分片会在一个作业内部并发运行其小型独立守卫。Gateway 网关 watch、渠道测试和核心 support-boundary 分片会在 `dist/` 和 `dist-runtime/` 已经构建完成后，在 `build-artifacts` 内部并发运行；这样既保留了它们原有的检查名称作为轻量验证器作业，又避免了额外两个 Blacksmith worker 和第二条产物消费者队列。 -Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的 source set 或 manifest；它的单元测试通道仍会在启用了 SMS/通话日志 BuildConfig 标志的情况下编译该 flavor，同时避免在每次与 Android 相关的 push 上重复执行 debug APK 打包作业。 +Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。third-party flavor 没有单独的源码集或 manifest；它的单元测试通道仍会使用 SMS/call-log `BuildConfig` 标志编译该 flavor，同时避免在每次与 Android 相关的 push 上重复执行 debug APK 打包作业。 -`extension-fast` 仅在 PR 上运行，因为 push 运行已经执行完整的内置插件分片。这能为代码审查提供已变更插件的反馈，同时避免在 `main` 上为 `checks-node-extensions` 已覆盖的内容额外占用一个 Blacksmith worker。 +`extension-fast` 仅在 PR 上运行，因为 push 运行已经会执行完整的内置插件分片。这样既能为评审保留已改动插件的反馈，又不会在 `main` 上额外占用一个 Blacksmith worker 去重复 `checks-node-extensions` 中已经存在的覆盖。 -当同一 PR 或 `main` ref 上有更新的 push 到达时，GitHub 可能会将被替代的作业标记为 `cancelled`。除非同一 ref 的最新运行也在失败，否则应将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已经被替代后继续排队。 +当同一个 PR 或 `main` 引用上有更新的 push 到来时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一引用上的最新运行也失败了，否则应将其视为 CI 噪音。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已经被更新运行取代后继续排队。 -CI 并发键采用了版本化（`CI-v7-*`），因此 GitHub 侧旧队列组中的僵尸任务不会无限期阻塞更新的 main 运行。 +CI 并发键采用带版本号的形式（`CI-v7-*`），这样 GitHub 端旧队列组中的僵尸任务就不会无限期阻塞较新的 main 运行。 ## Runner -| Runner | 作业 | -| ------ | ---- | -| `ubuntu-24.04` | `preflight`、快速安全作业及聚合（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速 protocol/contract/bundled 检查、分片的渠道契约检查、除 lint 外的 `check` 分片、`check-additional` 分片及聚合、Node 测试聚合验证器、文档检查、Python Skills、workflow-sanity、labeler、auto-response；install-smoke 的 preflight 也使用 GitHub 托管 Ubuntu，以便 Blacksmith 矩阵更早开始排队 | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node 测试分片、内置插件测试分片、`android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`，它仍然对 CPU 足够敏感，以至于 8 vCPU 的成本高于收益；install-smoke Docker 构建，在这里 32 vCPU 的排队时间成本也高于收益 | -| `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-node`；fork 会回退到 `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-swift`；fork 会回退到 `macos-latest` | +| Runner | 作业 | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`、快速安全作业及其聚合作业（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速协议/契约/内置检查、分片的渠道契约检查、除 lint 以外的 `check` 分片、`check-additional` 分片及聚合、Node 测试聚合验证器、文档检查、Python Skills、workflow-sanity、labeler、auto-response；install-smoke preflight 也使用 GitHub 托管的 Ubuntu，这样 Blacksmith 矩阵可以更早开始排队 | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node 测试分片、内置插件测试分片、`android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`，它对 CPU 仍然足够敏感，以至于 8 vCPU 的成本高于节省；install-smoke Docker 构建，在那里 32 vCPU 的排队时间成本高于节省 | +| `blacksmith-16vcpu-windows-2025` | `checks-windows` | +| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-node`；fork 会回退到 `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-swift`；fork 会回退到 `macos-latest` | -## 本地等价命令 +## 本地等效命令 ```bash pnpm changed:lanes # 检查 origin/main...HEAD 的本地 changed-lane 分类器 -pnpm check:changed # 智能本地门禁：按边界通道运行变更后的 typecheck/lint/测试 +pnpm check:changed # 智能本地门禁：按边界通道运行变更相关的 typecheck/lint/tests pnpm check # 快速本地门禁：生产 tsgo + 分片 lint + 并行快速守卫 pnpm check:test-types -pnpm check:timed # 相同门禁，但输出每阶段耗时 +pnpm check:timed # 同样的门禁，但带有每阶段耗时 pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression pnpm test # vitest 测试 pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # 文档格式 + lint + 断链 -pnpm build # 当 CI 的 artifact/build-smoke 通道相关时，构建 dist +pnpm check:docs # 文档格式 + lint + 断链检查 +pnpm build # 当 CI 产物/build-smoke 通道相关时，构建 dist node scripts/ci-run-timings.mjs # 汇总总耗时、排队时间和最慢作业 -node scripts/ci-run-timings.mjs --recent 10 # 比较最近成功的 main CI 运行 +node scripts/ci-run-timings.mjs --recent 10 # 比较最近 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/concepts/memory-qmd.md b/docs/zh-CN/concepts/memory-qmd.md index 64326ace4..140421bb8 100644 --- a/docs/zh-CN/concepts/memory-qmd.md +++ b/docs/zh-CN/concepts/memory-qmd.md @@ -1,39 +1,36 @@ --- read_when: - - 你想将 QMD 设置为你的记忆后端 - - 你想启用高级记忆功能，例如重排序或额外索引路径 -summary: 本地优先搜索 sidecar：支持 BM25、向量、重排序与查询扩展 + - 你想把 QMD 设置为你的记忆后端 + - 你希望使用更高级的记忆功能，例如重排序或额外的索引路径 +summary: 采用本地优先的搜索 sidecar，集成 BM25、向量、重排序和查询扩展 title: QMD 记忆引擎 x-i18n: - generated_at: "2026-04-23T20:46:25Z" + generated_at: "2026-04-23T22:14:40Z" model: gpt-5.4 provider: openai - source_hash: 7a811b7a2ec911d5e3813e22a24a2f8a1a5e4ca8741281418d084690d809bb06 + source_hash: 381affeebffa4fa935e89ab01e39f0accf88e4e23469acc4f966bdd72eb16142 source_path: concepts/memory-qmd.md workflow: 15 --- -[QMD](https://github.com/tobi/qmd) 是一个本地优先的搜索 sidecar，会与 -OpenClaw 一起运行。它将 BM25、向量搜索和重排序整合到一个 -二进制中，并且可以为工作区记忆文件之外的内容建立索引。 +[QMD](https://github.com/tobi/qmd) 是一个本地优先的搜索 sidecar，与 OpenClaw 一起运行。它将 BM25、向量搜索和重排序整合到单个二进制程序中，还可以为你的工作区记忆文件之外的内容建立索引。 -## 相比内置引擎增加了什么 +## 相比内置功能增加了什么 - **重排序和查询扩展**，以获得更好的召回效果。 -- **为额外目录建立索引** —— 项目文档、团队笔记、磁盘上的任意内容。 -- **为会话 transcript 建立索引** —— 回忆更早的对话。 -- **完全本地** —— 通过 Bun + node-llama-cpp 运行，会自动下载 GGUF 模型。 -- **自动回退** —— 如果 QMD 不可用，OpenClaw 会无缝回退到 - 内置引擎。 +- **为额外目录建立索引** —— 项目文档、团队笔记、磁盘上的任何内容。 +- **为会话转录建立索引** —— 回忆更早的对话。 +- **完全本地化** —— 通过 Bun + node-llama-cpp 运行，自动下载 GGUF 模型。 +- **自动回退** —— 如果 QMD 不可用，OpenClaw 会无缝回退到内置引擎。 ## 入门指南 ### 前提条件 - 安装 QMD：`npm install -g @tobilu/qmd` 或 `bun install -g @tobilu/qmd` -- 允许扩展的 SQLite 构建（在 macOS 上使用 `brew install sqlite`）。 -- QMD 必须位于 gateway 的 `PATH` 中。 -- macOS 和 Linux 可直接运行。Windows 最佳支持方式是通过 WSL2。 +- 支持扩展的 SQLite 构建版本（在 macOS 上使用 `brew install sqlite`）。 +- QMD 必须存在于 Gateway 网关的 `PATH` 中。 +- macOS 和 Linux 开箱即用。Windows 最佳支持方式是通过 WSL2。 ### 启用 @@ -45,33 +42,23 @@ OpenClaw 一起运行。它将 BM25、向量搜索和重排序整合到一个 } ``` -OpenClaw 会在 -`~/.openclaw/agents//qmd/` 下创建一个自包含的 QMD 主目录， -并自动管理 sidecar 生命周期 -—— 集合、更新和嵌入运行都会由它代为处理。 -它会优先使用当前的 QMD collection 和 MCP 查询形态，但在需要时仍会回退到 -旧版 `--mask` collection 标志和较旧的 MCP 工具名。 +OpenClaw 会在 `~/.openclaw/agents//qmd/` 下创建一个自包含的 QMD 主目录，并自动管理 sidecar 生命周期 —— 集合、更新和嵌入运行都会由系统替你处理。它会优先使用当前的 QMD collection 和 MCP query 形状，但在需要时仍会回退到旧版的 `--mask` collection 标志和更早的 MCP 工具名称。启动时的协调也会在仍存在同名旧版 QMD collection 时，将陈旧的托管 collection 重新创建为其规范模式。 ## sidecar 的工作方式 -- OpenClaw 会根据你的工作区记忆文件以及任何已配置的 - `memory.qmd.paths` 创建集合，然后在启动时和定期（默认每 5 分钟）运行 `qmd update` + `qmd embed`。 -- 默认工作区集合会跟踪 `MEMORY.md` 以及 `memory/` - 树。小写的 `memory.md` 不会作为根记忆文件建立索引。 -- 启动刷新会在后台进行，因此不会阻塞聊天启动。 -- 搜索会使用已配置的 `searchMode`（默认：`search`；也支持 - `vsearch` 和 `query`）。如果某个模式失败，OpenClaw 会使用 `qmd query` 重试。 +- OpenClaw 会根据你的工作区记忆文件以及任何已配置的 `memory.qmd.paths` 创建 collection，然后在启动时和周期性地（默认每 5 分钟）运行 `qmd update` + `qmd embed`。 +- 默认工作区 collection 会跟踪 `MEMORY.md` 以及 `memory/` 目录树。小写的 `memory.md` 不会作为根记忆文件建立索引。 +- 启动时刷新会在后台运行，因此不会阻塞聊天启动。 +- 搜索会使用已配置的 `searchMode`（默认：`search`；也支持 `vsearch` 和 `query`）。如果某种模式失败，OpenClaw 会使用 `qmd query` 重试。 - 如果 QMD 完全失败，OpenClaw 会回退到内置的 SQLite 引擎。 -首次搜索可能会很慢 —— QMD 会在第一次运行 `qmd query` 时自动下载用于 -重排序和查询扩展的 GGUF 模型（约 2 GB）。 +首次搜索可能会比较慢 —— QMD 会在第一次运行 `qmd query` 时自动下载用于重排序和查询扩展的 GGUF 模型（约 2 GB）。 ## 模型覆盖 -QMD 模型环境变量会从 gateway -进程中原样透传，因此你可以在不新增 OpenClaw 配置的情况下全局调优 QMD： +QMD 模型环境变量会从 Gateway 网关进程原样透传，因此你可以在不新增 OpenClaw 配置的情况下全局调优 QMD： ```bash export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf" @@ -79,12 +66,11 @@ export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf" export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf" ``` -更改嵌入模型后，请重新运行 embeddings，使索引与 -新的向量空间匹配。 +更改嵌入模型后，请重新运行嵌入，以便索引与新的向量空间匹配。 ## 为额外路径建立索引 -让 QMD 指向其他目录，以便这些内容也可被搜索： +将 QMD 指向其他目录，使其可被搜索： ```json5 { @@ -97,13 +83,11 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf" } ``` -来自额外路径的片段会在搜索结果中显示为 `qmd//`。 -`memory_get` 能识别此前缀，并从正确的 -collection 根目录读取内容。 +来自额外路径的片段会以 `qmd//` 的形式出现在搜索结果中。`memory_get` 能识别此前缀，并从正确的 collection 根目录读取内容。 -## 为会话 transcript 建立索引 +## 为会话转录建立索引 -启用会话索引以回忆更早的对话： +启用会话索引，以回忆更早的对话： ```json5 { @@ -116,13 +100,11 @@ collection 根目录读取内容。 } ``` -Transcript 会作为已净化的 User/Assistant 轮次导出到专用的 QMD -collection 中，位置在 `~/.openclaw/agents//qmd/sessions/`。 +转录会以经过清理的用户/助手轮次形式导出到专用的 QMD collection 中，路径为 `~/.openclaw/agents//qmd/sessions/`。 ## 搜索范围 -默认情况下，QMD 搜索结果会显示在私聊和渠道会话中 -（不包括群组）。可配置 `memory.qmd.scope` 来更改此行为： +默认情况下，QMD 搜索结果会显示在私信和渠道会话中（不包括群组）。通过配置 `memory.qmd.scope` 可更改此行为： ```json5 { @@ -137,50 +119,39 @@ collection 中，位置在 `~/.openclaw/agents//qmd/sessions/`。 } ``` -当 scope 拒绝某次搜索时，OpenClaw 会记录一条包含推导出的 channel 和 -chat type 的警告，这样更容易调试空结果问题。 +当范围规则拒绝一次搜索时，OpenClaw 会记录一条警告日志，其中包含推导出的渠道和聊天类型，从而使空结果更容易排查。 ## 引用 -当 `memory.citations` 为 `auto` 或 `on` 时，搜索片段会包含一个 -`Source: ` 页脚。设置 `memory.citations = "off"` 可省略该页脚， -同时仍会在内部将路径传递给智能体。 +当 `memory.citations` 为 `auto` 或 `on` 时，搜索片段会包含一个 `Source: ` 页脚。将 `memory.citations = "off"` 可省略该页脚，同时仍会在内部将路径传递给智能体。 -## 适用场景 +## 何时使用 -当你需要以下能力时，请选择 QMD： +当你有以下需求时，请选择 QMD： -- 使用重排序来获得更高质量的结果。 -- 搜索工作区之外的项目文档或笔记。 -- 回忆过去的会话对话。 -- 完全本地搜索，无需 API key。 +- 需要通过重排序获得更高质量的结果。 +- 需要搜索工作区之外的项目文档或笔记。 +- 需要回忆过去的会话对话。 +- 需要完全本地的搜索且不使用 API 密钥。 -对于更简单的设置，[内置引擎](/zh-CN/concepts/memory-builtin) 在 -无需额外依赖的情况下也能很好工作。 +对于更简单的设置，[内置引擎](/zh-CN/concepts/memory-builtin) 在无需额外依赖的情况下也能很好地工作。 ## 故障排除 -**找不到 QMD？** 请确保该二进制位于 gateway 的 `PATH` 中。如果 OpenClaw -作为服务运行，请创建一个符号链接： +**找不到 QMD？** 请确保该二进制文件位于 Gateway 网关的 `PATH` 中。如果 OpenClaw 作为服务运行，请创建一个符号链接： `sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd`。 -**首次搜索很慢？** QMD 会在首次使用时下载 GGUF 模型。可以使用与 OpenClaw 相同的 XDG 目录运行 -`qmd query "test"` 进行预热。 +**首次搜索很慢？** QMD 会在首次使用时下载 GGUF 模型。可使用与 OpenClaw 相同的 XDG 目录，通过 `qmd query "test"` 进行预热。 -**搜索超时？** 增加 `memory.qmd.limits.timeoutMs`（默认：4000ms）。 -对于较慢的硬件，可设为 `120000`。 +**搜索超时？** 增加 `memory.qmd.limits.timeoutMs`（默认值：4000ms）。对于较慢的硬件，可设置为 `120000`。 -**群聊中结果为空？** 请检查 `memory.qmd.scope` —— 默认只 -允许私聊和渠道会话。 +**群聊中结果为空？** 检查 `memory.qmd.scope` —— 默认只允许私信和渠道会话。 + +**根记忆搜索突然变得过于宽泛？** 重新启动 Gateway 网关，或等待下一次启动时协调。OpenClaw 在检测到同名冲突时，会将陈旧的托管 collection 重新创建为规范的 `MEMORY.md` 和 `memory/` 模式。 **工作区可见的临时仓库导致 `ENAMETOOLONG` 或索引损坏？** -QMD 遍历当前遵循底层 QMD 扫描器行为，而不是 -OpenClaw 内置的符号链接规则。请将临时 monorepo checkout 保存在 -诸如 `.tmp/` 之类的隐藏目录中，或放在已索引的 QMD 根目录之外，直到 QMD 提供 -安全处理循环的遍历或显式排除控制。 +QMD 遍历当前遵循底层 QMD 扫描器的行为，而不是 OpenClaw 内置的符号链接规则。请将临时 monorepo 检出放在诸如 `.tmp/` 这样的隐藏目录中，或放在已建立索引的 QMD 根目录之外，直到 QMD 提供防循环遍历或显式排除控制。 ## 配置 -完整配置表面（`memory.qmd.*`）、搜索模式、更新间隔、 -范围规则以及其他所有可调项，请参阅 -[Memory configuration reference](/zh-CN/reference/memory-config)。 +要查看完整的配置项（`memory.qmd.*`）、搜索模式、更新间隔、范围规则以及其他所有可调参数，请参阅 [记忆配置参考](/zh-CN/reference/memory-config)。 diff --git a/docs/zh-CN/gateway/cli-backends.md b/docs/zh-CN/gateway/cli-backends.md index ec2f72ee2..01dfc3c79 100644 --- a/docs/zh-CN/gateway/cli-backends.md +++ b/docs/zh-CN/gateway/cli-backends.md @@ -2,40 +2,40 @@ read_when: - 当 API 提供商失效时，你希望有一个可靠的回退方案 - 你正在运行 Codex CLI 或其他本地 AI CLI，并希望复用它们 - - 你想了解用于 CLI 后端工具访问的 MCP local loopback 桥接机制 -summary: CLI 后端：本地 AI CLI 回退，支持可选的 MCP 工具桥接 + - 你想了解用于 CLI 后端工具访问的 MCP local loopback 桥接】【。 +summary: CLI 后端：带可选 MCP 工具桥接的本地 AI CLI 回退方案 title: CLI 后端 x-i18n: - generated_at: "2026-04-23T21:49:31Z" + generated_at: "2026-04-23T22:14:42Z" model: gpt-5.4 provider: openai - source_hash: d4f3f2f0a02539455de1a9f3982590e507e5ccd1e4cc354658118eadf522150a + source_hash: 14633003fdffeb6061ee365973d78d88443dd24163b14e4ba77fe4e2fe7a450e source_path: gateway/cli-backends.md workflow: 15 --- # CLI 后端（回退运行时） -当 API 提供商不可用、受到速率限制或暂时行为异常时，OpenClaw 可以运行**本地 AI CLI** 作为**纯文本回退**。这是一种有意保持保守的设计： +当 API 提供商不可用、触发速率限制或暂时行为异常时，OpenClaw 可以运行**本地 AI CLI** 作为**纯文本回退方案**。这是有意保持保守的设计： -- **不会直接注入 OpenClaw 工具**，但设置了 `bundleMcp: true` 的后端可以通过 loopback MCP 桥接接收 Gateway 网关工具。 -- 对支持该能力的 CLI 提供 **JSONL 流式传输**。 -- **支持会话**（因此后续轮次能够保持连贯）。 -- 如果 CLI 接受图片路径，**图片可以透传**。 +- **OpenClaw 工具不会被直接注入**，但设置了 `bundleMcp: true` 的后端可以通过 loopback MCP 桥接接收 Gateway 网关工具。 +- 对支持该能力的 CLI 提供 **JSONL 分块流式传输**。 +- **支持会话**（因此后续轮次能保持连贯）。 +- 如果 CLI 接受图片路径，**图片也可以透传**。 -这被设计为一个**安全兜底机制**，而不是主要路径。当你希望在不依赖外部 API 的情况下获得“始终可用”的文本响应时，可以使用它。 +这被设计为一种**安全兜底机制**，而不是主要路径。当你希望在不依赖外部 API 的情况下获得“始终可用”的文本响应时，可以使用它。 -如果你想要一个具备 ACP 会话控制、后台任务、线程/会话绑定以及持久化外部编码会话的完整 harness 运行时，请改用 [ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。 +如果你需要具备 ACP 会话控制、后台任务、线程/对话绑定以及持久化外部编码会话的完整 harness 运行时，请改用 [ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。 ## 面向初学者的快速开始 -你可以**无需任何配置**使用 Codex CLI（内置的 OpenAI 插件会注册一个默认后端）： +你可以**无需任何配置**直接使用 Codex CLI（内置 OpenAI 插件会注册一个默认后端）： ```bash openclaw agent --message "hi" --model codex-cli/gpt-5.5 ``` -如果你的 Gateway 网关运行在 launchd/systemd 下，且 `PATH` 很精简，只需添加命令路径： +如果你的 Gateway 网关运行在 launchd/systemd 下，且 PATH 很精简，只需添加命令路径： ```json5 { @@ -51,13 +51,13 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5 } ``` -就是这样。除了 CLI 自身所需的认证外，不需要密钥，也不需要额外的认证配置。 +就是这样。除了 CLI 本身之外，不需要任何密钥，也不需要额外的认证配置。 -如果你在 Gateway 网关主机上将内置的 CLI 后端用作**主要消息提供商**，当你的配置在模型引用或 `agents.defaults.cliBackends` 下显式引用该后端时，OpenClaw 现在会自动加载其所属的内置插件。 +如果你在 Gateway 网关宿主机上把内置 CLI 后端用作**主要消息提供商**，当你的配置在模型引用中或在 `agents.defaults.cliBackends` 下显式引用该后端时，OpenClaw 现在会自动加载其所属的内置插件。 -## 将其用作回退 +## 将其用作回退方案 -将 CLI 后端加入你的回退列表，这样它只会在主要模型失败时运行： +把 CLI 后端加入你的回退列表，这样它只会在主模型失败时运行： ```json5 { @@ -78,8 +78,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5 说明： -- 如果你使用 `agents.defaults.models`（允许列表），你也必须在其中包含 CLI 后端模型。 -- 如果主要提供商失败（认证、速率限制、超时），OpenClaw 会接着尝试 CLI 后端。 +- 如果你使用 `agents.defaults.models`（允许列表），你也必须把 CLI 后端模型包含在其中。 +- 如果主提供商失败（认证、速率限制、超时），OpenClaw 接下来会尝试 CLI 后端。 ## 配置概览 @@ -89,8 +89,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5 agents.defaults.cliBackends ``` -每个条目都以**提供商 id** 为键（例如 `codex-cli`、`my-cli`）。 -该提供商 id 会成为模型引用左侧部分： +每个条目都以**provider id** 为键（例如 `codex-cli`、`my-cli`）。 +这个 provider id 会成为模型引用左侧部分： ``` / @@ -120,7 +120,7 @@ agents.defaults.cliBackends sessionMode: "existing", sessionIdFields: ["session_id", "conversation_id"], systemPromptArg: "--system", - // Codex 风格的 CLI 也可以改为指向一个提示文件： + // Codex 风格的 CLI 也可以改为指向提示词文件： // systemPromptFileConfigArg: "-c", // systemPromptFileConfigKey: "model_instructions_file", systemPromptWhen: "first", @@ -136,25 +136,28 @@ agents.defaults.cliBackends ## 工作原理 -1. 根据提供商前缀（`codex-cli/...`）**选择后端**。 +1. 根据 provider 前缀（`codex-cli/...`）**选择一个后端**。 2. 使用相同的 OpenClaw 提示词和工作区上下文**构建系统提示词**。 -3. 使用会话 id（如果支持）**执行 CLI**，以保持历史一致。 - 内置的 `claude-cli` 后端会为每个 OpenClaw 会话保持一个 Claude stdio 进程存活， - 并通过 stream-json stdin 发送后续轮次。 +3. 用会话 id（如果支持）**执行 CLI**，以便历史记录保持一致。 + 内置 `claude-cli` 后端会为每个 OpenClaw 会话保持一个 Claude stdio 进程存活，并通过 stream-json stdin 发送后续轮次。 4. **解析输出**（JSON 或纯文本），并返回最终文本。 -5. 按后端**持久化会话 id**，以便后续轮次复用同一个 CLI 会话。 +5. 为每个后端**持久化 session id**，这样后续轮次会复用相同的 CLI 会话。 -内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 员工告诉我们，允许使用 OpenClaw 风格的 Claude CLI，因此除非 Anthropic 发布新的策略，否则 OpenClaw 会将这种集成中的 `claude -p` 用法视为被认可的方式。 +内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 员工告诉我们，允许使用 OpenClaw 风格的 Claude CLI，因此除非 Anthropic 发布新的政策，否则 OpenClaw 会将 `claude -p` 的用法视为该集成的认可方式。 -内置的 OpenAI `codex-cli` 后端通过 Codex 的 `model_instructions_file` 配置覆盖项（`-c -model_instructions_file="..."`）传递 OpenClaw 的系统提示词。Codex 不提供类似 Claude 的 -`--append-system-prompt` 标志，因此 OpenClaw 会为每个新的 Codex CLI 会话将组装好的提示词写入一个临时文件。 +内置 OpenAI `codex-cli` 后端会通过 Codex 的 `model_instructions_file` 配置覆盖项（`-c +model_instructions_file="..."`）传递 OpenClaw 的系统提示词。Codex 没有提供类似 Claude 的 +`--append-system-prompt` 标志，因此 OpenClaw 会为每个新的 Codex CLI 会话把组装好的提示词写入临时文件。 -内置的 Anthropic `claude-cli` 后端会通过两种方式接收 OpenClaw 的 Skills 快照：一种是附加系统提示词中的精简版 OpenClaw Skills 目录，另一种是通过 `--plugin-dir` 传入的临时 Claude Code 插件。该插件仅包含对该智能体/会话可用的 Skills，因此 Claude Code 的原生 skill 解析器看到的过滤后集合，与 OpenClaw 原本会在提示词中声明的集合相同。针对 Skill 的环境变量/API 密钥覆盖仍然会由 OpenClaw 应用到本次运行的子进程环境中。 +内置 Anthropic `claude-cli` 后端会通过两种方式接收 OpenClaw 的 Skills 快照：一是附加系统提示词中的精简 OpenClaw Skills 目录，二是通过 `--plugin-dir` 传入的临时 Claude Code 插件。该插件只包含对该智能体/会话符合条件的 Skills，因此 Claude Code 的原生 skill 解析器看到的过滤结果，与 OpenClaw 原本会在提示词中公布的集合一致。对于运行所需的 Skill 环境变量/API 密钥覆盖，仍由 OpenClaw 应用到子进程环境中。 -在 OpenClaw 可以使用内置的 `claude-cli` 后端之前，Claude Code 本身必须已经在同一台主机上登录： +Claude CLI 还有它自己的非交互权限模式。OpenClaw 会将其映射到现有的 exec 策略，而不是增加 Claude 专用配置：当生效的请求 exec 策略为 YOLO（`tools.exec.security: "full"` 且 +`tools.exec.ask: "off"`）时，OpenClaw 会添加 `--permission-mode bypassPermissions`。 +每个智能体的 `agents.list[].tools.exec` 设置会覆盖该智能体的全局 `tools.exec`。如果你想强制使用其他 Claude 模式，请在 `agents.defaults.cliBackends.claude-cli.args` 和对应的 `resumeArgs` 下设置显式原始后端参数，例如 `--permission-mode default` 或 `--permission-mode acceptEdits`。 + +在 OpenClaw 可以使用内置 `claude-cli` 后端之前，Claude Code 本身必须已经在同一台主机上登录： ```bash claude auth login @@ -167,23 +170,23 @@ openclaw models auth login --provider anthropic --method cli --set-default ## 会话 - 如果 CLI 支持会话，请设置 `sessionArg`（例如 `--session-id`）或 - `sessionArgs`（占位符 `{sessionId}`），用于需要将 id 插入多个标志的情况。 -- 如果 CLI 使用带有不同标志的**恢复子命令**，请设置 - `resumeArgs`（恢复时替换 `args`），并可选设置 `resumeOutput` - （用于非 JSON 的恢复）。 + `sessionArgs`（占位符 `{sessionId}`），以便在需要把 ID 插入多个标志时使用。 +- 如果 CLI 使用带不同标志的**恢复子命令**，请设置 + `resumeArgs`（恢复时替换 `args`），并可选设置 `resumeOutput`（用于非 JSON 恢复）。 - `sessionMode`： - `always`：始终发送会话 id（如果未存储则生成新的 UUID）。 - - `existing`：仅在之前已存储时发送会话 id。 + - `existing`：仅在之前存储过会话 id 时发送。 - `none`：从不发送会话 id。 -- `claude-cli` 默认使用 `liveSession: "claude-stdio"`、`output: "jsonl"`、 - 和 `input: "stdin"`，这样在 Claude 进程仍处于活动状态时，后续轮次就能复用该实时 Claude 进程。现在默认就是预热的 stdio，包括那些省略传输字段的自定义配置。如果 Gateway 网关重启，或者空闲进程退出，OpenClaw 会从已存储的 Claude 会话 id 恢复。已存储的会话 id 会先针对现有且可读的项目转录进行校验，再执行恢复，因此虚假的绑定会以 `reason=transcript-missing` 被清除，而不是在 `--resume` 下悄悄启动一个全新的 Claude CLI 会话。 -- 已存储的 CLI 会话属于提供商自身的连续性状态。隐式的每日会话重置不会切断它们；`/reset` 和显式的 `session.reset` 策略仍然会切断。 +- `claude-cli` 默认使用 `liveSession: "claude-stdio"`、`output: "jsonl"`， + 以及 `input: "stdin"`，这样在活跃期间后续轮次会复用正在运行的 Claude 进程。 + warm stdio 现在是默认行为，包括那些省略传输字段的自定义配置也是如此。如果 Gateway 网关重启，或空闲进程退出，OpenClaw 会从已存储的 Claude session id 恢复。已存储的 session id 会在恢复前与现有且可读的项目转录记录进行校验，因此虚假的绑定会以 `reason=transcript-missing` 清除，而不是在 `--resume` 下悄悄启动一个新的 Claude CLI 会话。 +- 已存储的 CLI 会话属于 provider 所拥有的连续性。隐式的每日会话重置不会切断它们；`/reset` 和显式 `session.reset` 策略仍然会切断。 序列化说明： -- `serialize: true` 会保持同一执行通道中的运行顺序。 -- 大多数 CLI 会在一个提供商通道上串行执行。 -- 当所选认证身份发生变化时，OpenClaw 会放弃复用已存储的 CLI 会话，包括认证配置文件 id、静态 API 密钥、静态令牌，或 CLI 暴露该信息时的 OAuth 账户身份发生变化。OAuth 访问令牌和刷新令牌轮换不会切断已存储的 CLI 会话。如果某个 CLI 没有暴露稳定的 OAuth 账户 id，OpenClaw 会让该 CLI 自行强制执行恢复权限。 +- `serialize: true` 会保持同一 lane 的运行按顺序执行。 +- 大多数 CLI 都会在一个 provider lane 上串行执行。 +- 当所选认证身份发生变化时，OpenClaw 会放弃复用已存储的 CLI 会话，包括 auth profile id、静态 API 密钥、静态令牌，或 CLI 暴露的 OAuth 账户身份发生变化时。OAuth 访问令牌和刷新令牌的轮换不会切断已存储的 CLI 会话。如果某个 CLI 没有暴露稳定的 OAuth 账户 id，OpenClaw 会让该 CLI 自行强制执行恢复权限。 ## 图片（透传） @@ -194,24 +197,24 @@ imageArg: "--image", imageMode: "repeat" ``` -OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`，这些路径会作为 CLI 参数传入。如果缺少 `imageArg`，OpenClaw 会将文件路径附加到提示词中（路径注入），这对于那些能从普通路径自动加载本地文件的 CLI 已经足够。 +OpenClaw 会把 base64 图片写入临时文件。如果设置了 `imageArg`，这些路径会作为 CLI 参数传入。如果缺少 `imageArg`，OpenClaw 会把文件路径附加到提示词中（路径注入），这对那些能从普通路径自动加载本地文件的 CLI 来说已经足够。 ## 输入 / 输出 -- `output: "json"`（默认）会尝试解析 JSON 并提取文本和会话 id。 +- `output: "json"`（默认）会尝试解析 JSON 并提取文本 + session id。 - 对于 Gemini CLI 的 JSON 输出，当 `usage` 缺失或为空时，OpenClaw 会从 `response` 读取回复文本，并从 `stats` 读取用量。 -- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并提取最终的智能体消息以及存在时的会话标识符。 -- `output: "text"` 将 stdout 视为最终响应。 +- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并提取最终智能体消息以及存在时的会话标识符。 +- `output: "text"` 会把 stdout 视为最终响应。 输入模式： -- `input: "arg"`（默认）将提示词作为最后一个 CLI 参数传递。 -- `input: "stdin"` 通过 stdin 发送提示词。 -- 如果提示词很长并且设置了 `maxPromptArgChars`，则会使用 stdin。 +- `input: "arg"`（默认）会把提示词作为最后一个 CLI 参数传入。 +- `input: "stdin"` 会通过 stdin 发送提示词。 +- 如果提示词很长且设置了 `maxPromptArgChars`，则会改用 stdin。 ## 默认值（插件拥有） -内置的 OpenAI 插件也会为 `codex-cli` 注册一个默认值： +内置 OpenAI 插件也为 `codex-cli` 注册了默认值： - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -222,7 +225,7 @@ OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`， - `imageArg: "--image"` - `sessionMode: "existing"` -内置的 Google 插件也会为 `google-gemini-cli` 注册一个默认值： +内置 Google 插件也为 `google-gemini-cli` 注册了默认值： - `command: "gemini"` - `args: ["--output-format", "json", "--prompt", "{prompt}"]` @@ -233,31 +236,31 @@ OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`， - `sessionMode: "existing"` - `sessionIdFields: ["session_id", "sessionId"]` -前提条件：本地 Gemini CLI 必须已安装，并且可以通过 `PATH` 中的 -`gemini` 调用（`brew install gemini-cli` 或 +前置要求：本地 Gemini CLI 必须已安装，并且可以通过 `PATH` 中的 +`gemini` 使用（`brew install gemini-cli` 或 `npm install -g @google/gemini-cli`）。 Gemini CLI JSON 说明： - 回复文本从 JSON 的 `response` 字段读取。 -- 当 `usage` 不存在或为空时，用量会回退到 `stats`。 -- `stats.cached` 会被标准化为 OpenClaw `cacheRead`。 -- 如果缺少 `stats.input`，OpenClaw 会根据 +- 当 `usage` 不存在或为空时，用量会回退为 `stats`。 +- `stats.cached` 会被标准化为 OpenClaw 的 `cacheRead`。 +- 如果 `stats.input` 缺失，OpenClaw 会根据 `stats.input_tokens - stats.cached` 推导输入 token 数。 -仅在需要时覆盖（常见情况：使用绝对 `command` 路径）。 +仅在需要时覆盖即可（常见情况：使用绝对 `command` 路径）。 ## 插件拥有的默认值 CLI 后端默认值现在属于插件表面的一部分： - 插件通过 `api.registerCliBackend(...)` 注册它们。 -- 后端 `id` 会成为模型引用中的提供商前缀。 -- 位于 `agents.defaults.cliBackends.` 下的用户配置仍会覆盖插件默认值。 -- 特定后端的配置清理仍通过可选的 - `normalizeConfig` hook 由插件负责。 +- 后端 `id` 会成为模型引用中的 provider 前缀。 +- 位于 `agents.defaults.cliBackends.` 的用户配置仍会覆盖插件默认值。 +- 后端特定的配置清理由插件通过可选的 + `normalizeConfig` hook 继续拥有。 -如果插件需要细微的提示词/消息兼容性 shim，可以声明双向文本转换，而无需替换提供商或 CLI 后端： +需要进行极小提示词/消息兼容性适配的插件，可以声明双向文本转换，而无需替换 provider 或 CLI 后端： ```typescript api.registerTextTransforms({ @@ -274,51 +277,44 @@ api.registerTextTransforms({ }); ``` -`input` 会重写传递给 CLI 的系统提示词和用户提示词。`output` -会在 OpenClaw 处理其自身控制标记和渠道投递之前，重写流式传输的 assistant 增量内容以及解析后的最终文本。 +`input` 会重写传给 CLI 的系统提示词和用户提示词。`output` +会在 OpenClaw 处理其自身控制标记和渠道投递之前，重写流式 assistant 增量内容以及解析后的最终文本。 -对于输出与 Claude Code stream-json 兼容的 JSONL 的 CLI，请在该后端配置中设置 +对于输出与 Claude Code stream-json 兼容的 JSONL 的 CLI，请在该后端配置上设置 `jsonlDialect: "claude-stream-json"`。 -## Bundle MCP 覆盖层 +## 内置 MCP 覆盖层 CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过设置 -`bundleMcp: true` 选择加入一个生成的 MCP 配置覆盖层。 +`bundleMcp: true` 选择加入生成的 MCP 配置覆盖层。 -当前的内置行为： +当前内置行为： -- `claude-cli`：生成严格的 MCP 配置文件 -- `codex-cli`：为 `mcp_servers` 生成内联配置覆盖；生成的 - OpenClaw loopback 服务器会标记为 Codex 的每服务器工具批准模式， - 这样 MCP 调用就不会因为本地批准提示而卡住 -- `google-gemini-cli`：生成 Gemini system settings 文件 +- `claude-cli`：生成的严格 MCP 配置文件 +- `codex-cli`：针对 `mcp_servers` 的内联配置覆盖；生成的 OpenClaw loopback 服务器会标记为 Codex 的按服务器工具批准模式，因此 MCP 调用不会因本地批准提示而卡住 +- `google-gemini-cli`：生成的 Gemini system settings 文件 -启用 bundle MCP 时，OpenClaw： +启用 bundle MCP 时，OpenClaw 会： - 启动一个 loopback HTTP MCP 服务器，向 CLI 进程暴露 Gateway 网关工具 -- 使用每会话令牌（`OPENCLAW_MCP_TOKEN`）对桥接进行认证 -- 将工具访问范围限制在当前会话、账户和渠道上下文内 +- 使用每个会话单独的令牌（`OPENCLAW_MCP_TOKEN`）对桥接进行认证 +- 将工具访问范围限定在当前会话、账户和渠道上下文中 - 为当前工作区加载已启用的 bundle-MCP 服务器 -- 将它们与任何现有的后端 MCP 配置/设置结构合并 -- 使用所属扩展中由后端拥有的集成模式重写启动配置 +- 将它们与任何现有后端 MCP 配置/设置结构合并 +- 使用所属扩展中的后端自有集成模式重写启动配置 -如果没有启用任何 MCP 服务器，当后端选择加入 bundle MCP 时，OpenClaw 仍会注入严格配置，以便后台运行保持隔离。 +如果没有启用任何 MCP 服务器，只要某个后端选择启用 bundle MCP，OpenClaw 仍会注入严格配置，以便后台运行保持隔离。 ## 限制 -- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用注入到 - CLI 后端协议中。只有当后端选择加入 - `bundleMcp: true` 时，后端才会看到 Gateway 网关工具。 -- **流式传输是后端特定的。** 一些后端流式传输 JSONL；另一些则会缓冲 - 直到退出。 +- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用直接注入 CLI 后端协议。只有在后端选择启用 `bundleMcp: true` 时，后端才能看到 Gateway 网关工具。 +- **流式传输是后端特定的。** 某些后端会流式输出 JSONL；其他后端则会一直缓冲到退出时。 - **结构化输出** 取决于 CLI 的 JSON 格式。 -- **Codex CLI 会话** 通过文本输出恢复（没有 JSONL），其结构化程度 - 低于初始的 `--json` 运行。不过 OpenClaw 会话本身仍可正常工作。 +- **Codex CLI 会话** 通过文本输出恢复（不是 JSONL），其结构化程度低于初始 `--json` 运行。不过 OpenClaw 会话本身仍可正常工作。 ## 故障排除 - **找不到 CLI**：将 `command` 设置为完整路径。 -- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射到 CLI 模型。 -- **没有会话连续性**：确保已设置 `sessionArg`，且 `sessionMode` 不为 - `none`（Codex CLI 当前无法使用 JSON 输出恢复）。 +- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射为 CLI 模型。 +- **没有会话连续性**：确保设置了 `sessionArg`，并且 `sessionMode` 不是 `none`（Codex CLI 当前无法使用 JSON 输出恢复）。 - **图片被忽略**：设置 `imageArg`（并确认 CLI 支持文件路径）。 diff --git a/docs/zh-CN/providers/cloudflare-ai-gateway.md b/docs/zh-CN/providers/cloudflare-ai-gateway.md index b8b90e6fa..bb33650da 100644 --- a/docs/zh-CN/providers/cloudflare-ai-gateway.md +++ b/docs/zh-CN/providers/cloudflare-ai-gateway.md @@ -1,14 +1,14 @@ --- read_when: - 你想将 Cloudflare AI Gateway 与 OpenClaw 一起使用 - - 你需要账户 ID、gateway ID 或 API 密钥环境变量 -summary: Cloudflare AI Gateway 设置（身份验证 + 模型选择） -title: Cloudflare AI Gateway♀♀♀analysis to=final code omitted + - 你需要账户 ID、Gateway 网关 ID 或 API 密钥环境变量 +summary: Cloudflare AI Gateway 设置（认证 + 模型选择） +title: Cloudflare AI Gateway 网关 x-i18n: - generated_at: "2026-04-23T20:59:47Z" + generated_at: "2026-04-23T22:14:43Z" model: gpt-5.4 provider: openai - source_hash: 31e2886c6333ec47ebed3042c0802ad5aedba6f16fbddc2110728dcb1e86b499 + source_hash: fb10ef4bd92db88b2b3dac1773439ab2ba37916a72d1925995d74ef787fa1c8b source_path: providers/cloudflare-ai-gateway.md workflow: 15 --- @@ -18,35 +18,35 @@ Cloudflare AI Gateway 位于提供商 API 前方，可让你添加分析、缓 | 属性 | 值 | | ------------- | ---------------------------------------------------------------------------------------- | | 提供商 | `cloudflare-ai-gateway` | -| Base URL | `https://gateway.ai.cloudflare.com/v1///anthropic` | -| 默认模型 | `cloudflare-ai-gateway/claude-sonnet-4-5` | -| API 密钥 | `CLOUDFLARE_AI_GATEWAY_API_KEY`（你通过 Gateway 发起请求时使用的提供商 API 密钥） | +| 基础 URL | `https://gateway.ai.cloudflare.com/v1///anthropic` | +| 默认模型 | `cloudflare-ai-gateway/claude-sonnet-4-6` | +| API 密钥 | `CLOUDFLARE_AI_GATEWAY_API_KEY`（你通过 Gateway 网关发起请求时使用的提供商 API 密钥） | -对于通过 Cloudflare AI Gateway 路由的 Anthropic 模型，请使用你的**Anthropic API 密钥**作为提供商密钥。 +对于通过 Cloudflare AI Gateway 路由的 Anthropic 模型，请使用你的 **Anthropic API 密钥** 作为提供商密钥。 ## 入门指南 - - 运行新手引导，并选择 Cloudflare AI Gateway 身份验证选项： + + 运行新手引导并选择 Cloudflare AI Gateway 认证选项： ```bash openclaw onboard --auth-choice cloudflare-ai-gateway-api-key ``` - 这会提示你输入账户 ID、gateway ID 和 API 密钥。 + 这会提示你输入账户 ID、Gateway 网关 ID 和 API 密钥。 - 将模型添加到你的 OpenClaw 配置中： + 将该模型添加到你的 OpenClaw 配置中： ```json5 { agents: { defaults: { - model: { primary: "cloudflare-ai-gateway/claude-sonnet-4-5" }, + model: { primary: "cloudflare-ai-gateway/claude-sonnet-4-6" }, }, }, } @@ -62,7 +62,7 @@ Cloudflare AI Gateway 位于提供商 API 前方，可让你添加分析、缓 ## 非交互式示例 -对于脚本或 CI 设置，请在命令行上传入所有值： +对于脚本化或 CI 设置，请在命令行上传递所有值： ```bash openclaw onboard --non-interactive \ @@ -76,8 +76,8 @@ openclaw onboard --non-interactive \ ## 高级配置 - - 如果你在 Cloudflare 中启用了 Gateway 身份验证，请添加 `cf-aig-authorization` 标头。这是**附加于**你的提供商 API 密钥之外的。 + + 如果你在 Cloudflare 中启用了 Gateway 认证，请添加 `cf-aig-authorization` 标头。这是**对你的提供商 API 密钥的额外要求**。 ```json5 { @@ -94,16 +94,16 @@ openclaw onboard --non-interactive \ ``` - `cf-aig-authorization` 标头用于向 Cloudflare Gateway 本身进行身份验证，而提供商 API 密钥（例如你的 Anthropic 密钥）则用于向上游提供商进行身份验证。 + `cf-aig-authorization` 标头用于向 Cloudflare Gateway 网关本身进行认证，而提供商 API 密钥（例如你的 Anthropic 密钥）则用于向上游提供商进行认证。 - - 如果 Gateway 网关以守护进程形式运行（launchd/systemd），请确保 `CLOUDFLARE_AI_GATEWAY_API_KEY` 对该进程可用。 + + 如果 Gateway 网关以守护进程（`launchd`/`systemd`）方式运行，请确保 `CLOUDFLARE_AI_GATEWAY_API_KEY` 对该进程可用。 - 仅存在于 `~/.profile` 中的密钥对 launchd/systemd 守护进程没有帮助，除非该环境也被导入到了那里。请将密钥设置在 `~/.openclaw/.env` 中，或通过 `env.shellEnv` 提供，以确保 gateway 进程可以读取它。 + 仅存在于 `~/.profile` 中的密钥不会帮助 `launchd`/`systemd` 守护进程，除非该环境也被导入到那里。请在 `~/.openclaw/.env` 中设置该密钥，或通过 `env.shellEnv` 设置，以确保 Gateway 网关进程可以读取它。 @@ -113,9 +113,9 @@ openclaw onboard --non-interactive \ - 选择提供商、模型引用和故障切换行为。 + 选择提供商、模型引用和故障转移行为。 - 通用故障排除和常见问题。 + 常规故障排除和常见问题。 diff --git a/docs/zh-CN/providers/openai.md b/docs/zh-CN/providers/openai.md index 6c93a1c47..79749c4d9 100644 --- a/docs/zh-CN/providers/openai.md +++ b/docs/zh-CN/providers/openai.md @@ -1,44 +1,44 @@ --- read_when: - 你想在 OpenClaw 中使用 OpenAI 模型 - - 你想使用 Codex 订阅身份验证，而不是 API 密钥 + - 你想使用 Codex 订阅认证，而不是 API 密钥 - 你需要更严格的 GPT-5 智能体执行行为 -summary: 在 OpenClaw 中使用 OpenAI 的 API 密钥或 Codex 订阅 +summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI title: OpenAI x-i18n: - generated_at: "2026-04-23T21:49:31Z" + generated_at: "2026-04-23T22:14:42Z" model: gpt-5.4 provider: openai - source_hash: 25d8fb540af37366c84380feca3dae43e8b206ff77d6a22af3cdddc1cf0373fc + source_hash: 7cbe3f548cc53ca50c5e76dea0a940c4e0a807dce7f777cd1692280a820c1f29 source_path: providers/openai.md workflow: 15 --- -OpenAI 为 GPT 模型提供开发者 API。OpenClaw 在同一套规范的 OpenAI 模型引用后支持两种身份验证路径： +OpenAI 为 GPT 模型提供开发者 API。OpenClaw 在相同的规范 OpenAI 模型引用后面支持两种认证路径： - **API 密钥** — 直接访问 OpenAI Platform，并按使用量计费（`openai/*` 模型） -- **Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问。内部 auth/provider id 为 `openai-codex`，但新的模型引用仍应使用 `openai/*`。 +- **Codex 订阅** — 通过 ChatGPT/Codex 登录并使用订阅访问。内部认证/提供商 id 是 `openai-codex`，但新的模型引用仍应使用 `openai/*`。 -OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 OAuth。 +OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。 ## OpenClaw 功能覆盖范围 -| OpenAI 能力 | OpenClaw 界面 | 状态 | -| ------------------------- | ----------------------------------------- | ------------------------------------------------------ | -| 聊天 / Responses | `openai/` 模型提供商 | 是 | -| Codex 订阅模型 | `openai/` 搭配 `openai-codex` 身份验证 | 是 | -| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定 provider 时 | -| 图像 | `image_generate` | 是 | -| 视频 | `video_generate` | 是 | -| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 | -| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 | -| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 | -| 实时语音 | Voice Call `realtime.provider: "openai"` | 是 | -| Embeddings | memory embedding provider | 是 | +| OpenAI 能力 | OpenClaw 表面 | 状态 | +| ----------------------- | ----------------------------------------- | ------------------------------------------------ | +| 聊天 / Responses | `openai/` 模型提供商 | 是 | +| Codex 订阅模型 | 使用 `openai-codex` 认证的 `openai/` | 是 | +| 服务端网页搜索 | 原生 OpenAI Responses 工具 | 是，在启用网页搜索且未固定提供商时可用 | +| 图像 | `image_generate` | 是 | +| 视频 | `video_generate` | 是 | +| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 | +| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 | +| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 | +| 实时语音 | Voice Call `realtime.provider: "openai"` | 是 | +| 嵌入 | memory embedding provider | 是 | ## 入门指南 -选择你偏好的身份验证方式，并按照设置步骤进行。 +选择你偏好的认证方式，并按照设置步骤操作。 @@ -46,7 +46,7 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 - 从 [OpenAI Platform 控制台](https://platform.openai.com/api-keys) 创建或复制一个 API 密钥。 + 在 [OpenAI Platform 控制台](https://platform.openai.com/api-keys) 中创建或复制一个 API 密钥。 ```bash @@ -59,7 +59,7 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` - + ```bash openclaw models list --provider openai ``` @@ -68,13 +68,13 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 ### 路径摘要 - | 模型引用 | 路径 | 身份验证 | + | 模型引用 | 路径 | 认证 | |-----------|-------|------| | `openai/gpt-5.5` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | | `openai/gpt-5.5-pro` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | - `openai-codex/*` 仍可作为旧版兼容别名使用，但新的配置应使用 `openai/*`。 + `openai-codex/*` 仍然作为旧版兼容别名被接受，但新配置应使用 `openai/*`。 ### 配置示例 @@ -87,7 +87,7 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 ``` - OpenClaw **不**提供 `openai/gpt-5.3-codex-spark`。实际的 OpenAI API 请求会拒绝该模型，而当前 Codex 目录也未提供它。 + OpenClaw **不**提供 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，当前的 Codex 目录也同样不提供它。 @@ -107,7 +107,7 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 openclaw models auth login --provider openai-codex ``` - 对于无头环境或不适合回调的设置，可以添加 `--device-code`，通过 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调： + 对于无头环境或不适合回调的设置，可添加 `--device-code`，通过 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调： ```bash openclaw models auth login --provider openai-codex --device-code @@ -118,7 +118,7 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 openclaw config set agents.defaults.model.primary openai/gpt-5.5 ``` - + ```bash openclaw models list --provider openai-codex ``` @@ -127,12 +127,12 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 ### 路径摘要 - | 模型引用 | 路径 | 身份验证 | + | 模型引用 | 路径 | 认证 | |-----------|-------|------| | `openai/gpt-5.5` | ChatGPT/Codex OAuth | Codex 登录 | - `openai-codex/*` 和 `codex/*` 模型引用是旧版兼容别名。对于身份验证/配置文件命令，请继续使用 `openai-codex` provider id。 + `openai-codex/*` 和 `codex/*` 模型引用都是旧版兼容别名。对于认证/配置文件命令，请继续使用 `openai-codex` 提供商 id。 ### 配置示例 @@ -144,17 +144,18 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 ``` - 新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上述设备码流程登录——OpenClaw 会在自己的智能体身份验证存储中管理生成的凭证。 + 新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上述设备码流程登录 —— OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。 ### 状态指示器 聊天 `/status` 会显示当前 会话正在使用哪个嵌入式 harness。默认的 PI harness 显示为 `Runner: pi (embedded)`，并且 - 不会添加单独的标记。当选择内置的 Codex app-server harness 时， - `/status` 会在 `Fast` 后附加非 PI harness id，例如 - `Fast · codex`。现有会话会保留其记录的 harness id，因此如果你在更改 `embeddedHarness` 后希望 `/status` - 反映新的 PI/Codex 选择，请使用 `/new` 或 `/reset`。 + 不会添加单独的徽章。当选择内置的 Codex app-server harness 时， + `/status` 会在 `Fast` 旁边附加非 PI harness id，例如 + `Fast · codex`。现有会话会保留其已记录的 harness id，因此如果你更改了 `embeddedHarness` 后希望 `/status` + 反映新的 PI/Codex 选择，请使用 + `/new` 或 `/reset`。 ### 上下文窗口上限 @@ -165,7 +166,7 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 - 原生 `contextWindow`：`1000000` - 默认运行时 `contextTokens` 上限：`272000` - 实际使用中，较小的默认上限通常具有更好的延迟和质量表现。你可以使用 `contextTokens` 进行覆盖： + 在实践中，更小的默认上限通常具有更好的延迟和质量表现。你可以使用 `contextTokens` 覆盖它： ```json5 { @@ -180,7 +181,7 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 ``` - 使用 `contextWindow` 声明原生模型元数据。使用 `contextTokens` 限制运行时上下文预算。 + 使用 `contextWindow` 声明模型的原生元数据。使用 `contextTokens` 限制运行时上下文预算。 @@ -188,18 +189,19 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 ## 图像生成 -内置的 `openai` 插件通过 `image_generate` 工具注册图像生成功能。 -它通过同一个 `openai/gpt-image-2` 模型引用，同时支持基于 OpenAI API 密钥的图像生成和基于 Codex OAuth 的图像生成。 +内置的 `openai` 插件通过 `image_generate` 工具注册图像生成。 +它通过同一个 `openai/gpt-image-2` 模型引用，同时支持基于 OpenAI API 密钥的图像生成和基于 Codex OAuth 的图像 +生成。 -| 能力 | OpenAI API 密钥 | Codex OAuth | -| ------------------------- | ---------------------------------- | ------------------------------------ | -| 模型引用 | `openai/gpt-image-2` | `openai/gpt-image-2` | -| 身份验证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 | -| 传输 | OpenAI Images API | Codex Responses 后端 | -| 每次请求的最大图像数 | 4 | 4 | -| 编辑模式 | 已启用（最多 5 张参考图像） | 已启用（最多 5 张参考图像） | -| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 | -| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全情况下映射为受支持的尺寸 | +| 能力 | OpenAI API 密钥 | Codex OAuth | +| ----------------------- | --------------------------------- | ------------------------------------ | +| 模型引用 | `openai/gpt-image-2` | `openai/gpt-image-2` | +| 认证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 | +| 传输 | OpenAI Images API | Codex Responses 后端 | +| 每次请求最大图像数 | 4 | 4 | +| 编辑模式 | 已启用（最多 5 张参考图） | 已启用（最多 5 张参考图） | +| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 | +| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全情况下映射为受支持的尺寸 | ```json5 { @@ -212,38 +214,43 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 ``` -参见 [Image Generation](/zh-CN/tools/image-generation)，了解共享工具参数、provider 选择和故障切换行为。 +有关共享工具参数、提供商选择和故障切换行为，请参阅 [Image Generation](/zh-CN/tools/image-generation)。 -`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认模型。`gpt-image-1` 仍可作为显式模型覆盖使用，但新的 OpenAI 图像工作流应使用 `openai/gpt-image-2`。 +`gpt-image-2` 是 OpenAI 文生图和图像 +编辑的默认模型。`gpt-image-1` 仍可作为显式模型覆盖使用，但新的 +OpenAI 图像工作流应使用 `openai/gpt-image-2`。 -对于 Codex OAuth 安装，请继续使用相同的 `openai/gpt-image-2` 引用。如果没有 -`OPENAI_API_KEY`，OpenClaw 会解析为 `openai-codex` auth profile 存储的 OAuth 访问令牌， -并通过 Codex Responses 后端发送图像请求，因此这一路径无需公开的 OpenAI Images API 密钥也可使用。 +对于 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 endpoint。 生成： ``` -/tool image_generate model=openai/gpt-image-2 prompt="为 macOS 上的 OpenClaw 制作一张精美的发布海报" size=3840x2160 count=1 +/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1 ``` 编辑： ``` -/tool image_generate model=openai/gpt-image-2 prompt="保留物体形状，将材质改为半透明玻璃" image=/path/to/reference.png size=1024x1536 +/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536 ``` ## 视频生成 -内置的 `openai` 插件通过 `video_generate` 工具注册视频生成功能。 +内置的 `openai` 插件通过 `video_generate` 工具注册视频生成。 -| 能力 | 值 | -| ---------------- | --------------------------------------------------------------------------------- | -| 默认模型 | `openai/sora-2` | -| 模式 | 文生视频、图生视频、单视频编辑 | -| 参考输入 | 1 张图像或 1 个视频 | -| 尺寸覆盖 | 支持 | -| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并给出工具警告 | +| 能力 | 值 | +| --------------- | --------------------------------------------------------------------------------- | +| 默认模型 | `openai/sora-2` | +| 模式 | 文生视频、图生视频、单视频编辑 | +| 参考输入 | 1 张图像或 1 个视频 | +| 尺寸覆盖 | 支持 | +| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并产生工具警告 | ```json5 { @@ -256,22 +263,22 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 ``` -参见 [Video Generation](/zh-CN/tools/video-generation)，了解共享工具参数、provider 选择和故障切换行为。 +有关共享工具参数、提供商选择和故障切换行为，请参阅 [Video Generation](/zh-CN/tools/video-generation)。 ## GPT-5 提示词贡献 -OpenClaw 会为跨 provider 的 GPT-5 系列运行添加共享的 GPT-5 提示词贡献。它按模型 id 生效，因此 `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/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会收到相同的叠加层。较旧的 GPT-4.x 模型则不会。 -内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳覆盖层，因此即使其余 harness 提示词由 Codex 接管，强制通过 `embeddedHarness.runtime: "codex"` 运行的 `openai/gpt-5.x` 会话仍会保留相同的后续执行和主动心跳指导。 +内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和 heartbeat 叠加层，因此即使 Codex 接管了 harness 提示词的其余部分，强制通过 `embeddedHarness.runtime: "codex"` 的 `openai/gpt-5.x` 会话仍会保留相同的后续执行和主动 heartbeat 指引。 -GPT-5 贡献为人格持续性、执行安全、工具纪律、输出结构、完成检查和验证添加了带标签的行为契约。特定渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。对于匹配的模型，GPT-5 指导始终启用。友好的交互风格层是独立且可配置的。 +GPT-5 贡献为人格持久性、执行安全、工具纪律、输出形态、完成检查和验证添加了带标签的行为契约。特定渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。对于匹配的模型，GPT-5 指引始终启用。友好交互风格层是独立且可配置的。 -| 值 | 效果 | -| ---------------------- | ------------------------------------------- | -| `"friendly"`（默认） | 启用友好的交互风格层 | -| `"on"` | `"friendly"` 的别名 | -| `"off"` | 仅禁用友好风格层 | +| 值 | 效果 | +| ---------------------- | ----------------------------------- | +| `"friendly"`（默认） | 启用友好交互风格层 | +| `"on"` | `"friendly"` 的别名 | +| `"off"` | 仅禁用友好风格层 | @@ -299,26 +306,26 @@ GPT-5 贡献为人格持续性、执行安全、工具纪律、输出结构、 -旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退项读取，当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 配置时会使用它。 +当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 配置时，旧版的 `plugins.entries.openai.config.personality` 仍会作为兼容性回退被读取。 -## 语音与音频 +## 语音和语音处理 - 内置的 `openai` 插件为 `messages.tts` 界面注册了语音合成功能。 + 内置的 `openai` 插件为 `messages.tts` 表面注册了语音合成功能。 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | - | 音色 | `messages.tts.providers.openai.voice` | `coral` | - | 语速 | `messages.tts.providers.openai.speed` | （未设置） | - | 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts` 支持） | + | 声音 | `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 { @@ -333,23 +340,23 @@ GPT-5 贡献为人格持续性、执行安全、工具纪律、输出结构、 ``` - 设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS Base URL，而不会影响聊天 API 端点。 + 设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 base URL，而不会影响聊天 API 端点。 内置的 `openai` 插件通过 - OpenClaw 的媒体理解转录界面注册了批量语音转文本功能。 + OpenClaw 的媒体理解转录表面注册了批量语音转文本功能。 - 默认模型：`gpt-4o-transcribe` - 端点：OpenAI REST `/v1/audio/transcriptions` - 输入路径：multipart 音频文件上传 - - 在 OpenClaw 中，只要入站音频转录使用 - `tools.media.audio`，就支持该功能，包括 Discord 语音频道片段和渠道 + - 在 OpenClaw 中，凡是入站音频转录使用 + `tools.media.audio` 的地方都支持，包括 Discord 语音频道片段和渠道 音频附件 - 要强制对入站音频转录使用 OpenAI： + 要强制将 OpenAI 用于入站音频转录： ```json5 { @@ -369,8 +376,8 @@ GPT-5 贡献为人格持续性、执行安全、工具纪律、输出结构、 } ``` - 当由共享音频媒体配置或按次转录请求提供语言和提示词时， - 这些提示会转发给 OpenAI。 + 当由共享音频媒体配置或单次转录请求提供时， + 语言和提示词提示会被转发给 OpenAI。 @@ -387,7 +394,7 @@ GPT-5 贡献为人格持续性、执行安全、工具纪律、输出结构、 | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` | - 使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，音频格式为 G.711 u-law（`g711_ulaw` / `audio/pcmu`）。此流式 provider 用于 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` 转录路径。 @@ -398,7 +405,7 @@ GPT-5 贡献为人格持续性、执行安全、工具纪律、输出结构、 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` | - | 音色 | `...openai.voice` | `alloy` | + | 声音 | `...openai.voice` | `alloy` | | Temperature | `...openai.temperature` | `0.8` | | VAD 阈值 | `...openai.vadThreshold` | `0.5` | | 静音时长 | `...openai.silenceDurationMs` | `500` | @@ -413,29 +420,30 @@ GPT-5 贡献为人格持续性、执行安全、工具纪律、输出结构、 ## Azure OpenAI 端点 -内置的 `openai` provider 可通过覆盖 base URL，将图像生成请求定向到 Azure OpenAI 资源。在图像生成路径上，OpenClaw -会检测 `models.providers.openai.baseUrl` 中的 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) 下的 **实时语音** -折叠面板。 +不会受到 `models.providers.openai.baseUrl` 的影响。请参阅 [语音和语音处理](#voice-and-speech) 下 **实时 +语音** 折叠面板中的 Azure +设置。 -以下情况适合使用 Azure OpenAI： +在以下情况下使用 Azure OpenAI： - 你已经拥有 Azure OpenAI 订阅、配额或企业协议 - 你需要 Azure 提供的区域数据驻留或合规控制 -- 你希望将流量保留在现有的 Azure 租户内 +- 你希望将流量保留在现有 Azure 租户内 ### 配置 -若要通过内置 `openai` provider 使用 Azure 图像生成，请将 +要通过内置的 `openai` 提供商使用 Azure 图像生成，请将 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 -Azure OpenAI 密钥（而非 OpenAI Platform 密钥）： +Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）： ```json5 { @@ -460,84 +468,89 @@ OpenClaw 会为 Azure 图像生成 对于发送到已识别 Azure 主机的图像生成请求，OpenClaw 会： - 发送 `api-key` 请求头，而不是 `Authorization: Bearer` -- 使用以部署为范围的路径（`/openai/deployments/{deployment}/...`） +- 使用以 deployment 为作用域的路径（`/openai/deployments/{deployment}/...`） - 为每个请求附加 `?api-version=...` -其他 base URL（公共 OpenAI、兼容 OpenAI 的代理）将继续使用标准 +其他 base URL（公开 OpenAI、兼容 OpenAI 的代理）会继续使用标准 OpenAI 图像请求格式。 -`openai` provider 的图像生成路径的 Azure 路由要求 -OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义 -`openai.baseUrl` 视为公共 OpenAI 端点，因此在 Azure -图像部署上会失败。 +`openai` 提供商图像生成路径的 Azure 路由要求 +OpenClaw 2026.4.22 或更高版本。更早的版本会将任何自定义 +`openai.baseUrl` 视为公开 OpenAI 端点处理，因此会在 Azure +图像 deployment 上失败。 ### API 版本 - 设置 `AZURE_OPENAI_API_VERSION` 以为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本： + 设置 `AZURE_OPENAI_API_VERSION` 以固定 Azure 图像生成路径所使用的特定 Azure 预览版或 GA 版本： ```bash export AZURE_OPENAI_API_VERSION="2024-12-01-preview" ``` - 当该变量未设置时，默认值为 `2024-12-01-preview`。 + 当该环境变量未设置时，默认值为 `2024-12-01-preview`。 - ### 模型名称就是部署名称 + ### 模型名称就是 deployment 名称 - Azure OpenAI 将模型绑定到部署。对于通过内置 `openai` provider 路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段 - 必须是你在 Azure 门户中配置的**Azure 部署名称**，而不是公共 OpenAI 模型 id。 + Azure OpenAI 会将模型绑定到 deployment。对于通过内置 `openai` 提供商 + 路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段 + 必须是你在 Azure 门户中配置的 **Azure deployment 名称**，而不是 + 公开的 OpenAI 模型 id。 - 如果你创建了一个名为 `gpt-image-2-prod` 的部署来提供 `gpt-image-2`： + 如果你创建了一个名为 `gpt-image-2-prod` 的 deployment，用于提供 `gpt-image-2`： ``` - /tool image_generate model=openai/gpt-image-2-prod prompt="一张简洁的海报" size=1024x1024 count=1 + /tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1 ``` - 同样的部署名称规则也适用于通过内置 `openai` provider 路由的图像生成调用。 + 同样的 deployment 名称规则也适用于通过 + 内置 `openai` 提供商路由的图像生成调用。 ### 区域可用性 Azure 图像生成目前仅在部分区域可用 （例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、 - `uaenorth`）。在创建部署之前，请先查看 Microsoft 最新的区域列表， - 并确认你的区域提供了特定模型。 + `uaenorth`）。在创建 + deployment 之前，请先检查 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 门户中检查你的特定 deployment 和 API 版本所支持的参数 + 集合。 Azure OpenAI 使用原生传输和兼容行为，但不会接收 - OpenClaw 的隐藏归因请求头——参见 [Advanced configuration](#advanced-configuration) 下 **原生路由与 OpenAI 兼容路由** - 折叠面板。 + OpenClaw 的隐藏 attribution 请求头 —— 请参阅 [高级配置](#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/*` 提供商；请参阅 + 下方的“服务端压缩”折叠面板。 ## 高级配置 - - 对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都采用 WebSocket 优先并在失败时回退到 SSE（`"auto"`）。 + + OpenClaw 对 `openai/*` 和 `openai-codex/*` 都使用优先 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 | + | `"auto"`（默认） | 优先 WebSocket，回退到 SSE | | `"sse"` | 仅强制使用 SSE | | `"websocket"` | 仅强制使用 WebSocket | @@ -581,13 +594,13 @@ OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义 - - OpenClaw 为 `openai/*` 提供共享的快速模式切换： + + OpenClaw 为 `openai/*` 提供共享的 Fast 模式开关： - **聊天/UI：** `/fast status|on|off` - **配置：** `agents.defaults.models["/"].params.fastMode` - 启用后，OpenClaw 会将快速模式映射为 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。 + 启用后，OpenClaw 会将 Fast 模式映射到 OpenAI 的优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，并且 Fast 模式不会改写 `reasoning` 或 `text.verbosity`。 ```json5 { @@ -602,13 +615,13 @@ OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义 ``` - 会话级覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话将恢复为配置的默认值。 + 会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话将恢复为配置中的默认值。 - OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置它： + OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型进行设置： ```json5 { @@ -625,15 +638,15 @@ OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义 支持的值：`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` 不变。 - 对于直接的 OpenAI Responses 模型（位于 `api.openai.com` 的 `openai/*`），OpenClaw 会自动启用服务端压缩： + 对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用服务端压缩： - - 强制设置 `store: true`（除非模型兼容性将 `supportsStore` 设为 `false`） + - 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`） - 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]` - 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`） @@ -691,7 +704,7 @@ OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义 - `responsesServerCompaction` 仅控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制使用 `store: true`，除非兼容性将 `supportsStore` 设为 `false`。 + `responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性配置设置了 `supportsStore: false`。 @@ -710,32 +723,32 @@ OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义 ``` 使用 `strict-agentic` 时，OpenClaw 会： - - 当存在可用工具操作时，不再将仅有计划的轮次视为成功进展 - - 使用“立即行动”的引导重试该轮次 - - 对于较大工作自动启用 `update_plan` - - 如果模型持续规划而不执行操作，则明确显示阻塞状态 + - 当工具操作可用时，不再将仅规划的轮次视为成功推进 + - 使用立即执行的引导重试该轮次 + - 对于实质性工作自动启用 `update_plan` + - 如果模型持续规划而不执行，则显示明确的阻塞状态 - 仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他 provider 和较旧的模型系列保持默认行为。 + 仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列会保留默认行为。 - OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，以及通用的 OpenAI 兼容 `/v1` 代理： + OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，与通用 OpenAI 兼容 `/v1` 代理不同： **原生路由**（`openai/*`、Azure OpenAI）： - 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }` - - 对于拒绝 `reasoning.effort: "none"` 的模型或代理，省略禁用的 reasoning + - 对于会拒绝 `reasoning.effort: "none"` 的模型或代理，省略已禁用的 reasoning - 默认将工具 schema 设为严格模式 - - 仅在已验证的原生主机上附加隐藏归因请求头 - - 保留 OpenAI 专用的请求格式（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示） + - 仅在已验证的原生主机上附加隐藏 attribution 请求头 + - 保留 OpenAI 专用请求格式（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示） **代理/兼容路由：** - 使用更宽松的兼容行为 - 不强制严格工具 schema 或原生专用请求头 - Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因请求头。 + Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏的 attribution 请求头。 @@ -744,15 +757,15 @@ OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义 - 选择 provider、模型引用和故障切换行为。 + 选择提供商、模型引用和故障切换行为。 - 共享图像工具参数和 provider 选择。 + 共享图像工具参数和提供商选择。 - 共享视频工具参数和 provider 选择。 + 共享视频工具参数和提供商选择。 - - 身份验证详情和凭证复用规则。 + + 认证细节和凭证复用规则。 diff --git a/docs/zh-CN/reference/test.md b/docs/zh-CN/reference/test.md index c6a2ebe90..63f9a7612 100644 --- a/docs/zh-CN/reference/test.md +++ b/docs/zh-CN/reference/test.md @@ -1,51 +1,51 @@ --- read_when: - 运行或修复测试 -summary: 如何在本地运行测试（Vitest），以及何时使用 force/coverage 模式 +summary: 如何在本地运行测试（vitest），以及何时使用 force/coverage 模式 title: 测试 x-i18n: - generated_at: "2026-04-23T21:04:48Z" + generated_at: "2026-04-23T22:14:42Z" model: gpt-5.4 provider: openai - source_hash: f6b9c765c8a6a3ad668626e0787a9a94bcb250d2627594ef960ab024f229e8ca + source_hash: 3753fd6f29598318f15a34e623a06fac80430cae34d6b42ad06657a46c72fc54 source_path: reference/test.md workflow: 15 --- - 完整测试工具包（测试套件、实时测试、Docker）：[测试](/zh-CN/help/testing) -- `pnpm test:force`：会杀掉任何仍占用默认控制端口的残留 gateway 进程，然后使用隔离的 gateway 端口运行完整 Vitest 测试套件，从而避免服务器测试与正在运行的实例冲突。当之前的 gateway 运行把端口 18789 占住时，请使用这个命令。 -- `pnpm test:coverage`：使用 V8 coverage（通过 `vitest.unit.config.ts`）运行单元测试套件。这是一个按已加载文件计算的单元覆盖率门禁，而不是整个仓库的全文件覆盖率。阈值是 70% 的 lines/functions/statements 和 55% 的 branches。由于 `coverage.all` 为 false，该门禁只度量单元覆盖率套件中实际加载的文件，而不是把所有拆分 lane 中的源文件都视为未覆盖。 -- `pnpm test:coverage:changed`：仅针对相对 `origin/main` 发生变化的文件运行单元覆盖率。 -- `pnpm test:changed`：当 diff 只触及可路由的源码/测试文件时，会把 git 变更路径展开为带作用域的 Vitest lanes。配置/设置类变更仍会回退为原生 root projects 运行，以确保接线类修改在需要时能够更广泛地重跑。 -- `pnpm changed:lanes`：显示相对 `origin/main` 的 diff 所触发的架构 lanes。 -- `pnpm check:changed`：针对相对 `origin/main` 的 diff 运行智能变更门禁。它会让 core 变更运行 core 测试 lanes，让 extension 变更运行 extension 测试 lanes，让纯测试变更只运行测试 typecheck/tests，将公共插件 SDK 或插件契约变更扩展到 extension 验证，并让仅涉及发布元数据的版本号变更仅运行定向的版本/配置/根依赖检查。 -- `pnpm test`：会将显式文件/目录目标路由到带作用域的 Vitest lanes。未指定目标时，会使用固定分片组，并展开到叶子配置，以进行本地并行执行；extension 组始终展开到按 extension 划分的分片配置，而不是跑一个巨大的 root-project 进程。 -- 完整运行和 extension 分片运行会更新 `.artifacts/vitest-shard-timings.json` 中的本地耗时数据；之后的运行会使用这些耗时来平衡慢分片和快分片。设置 `OPENCLAW_TEST_PROJECTS_TIMINGS=0` 可忽略本地耗时制品。 -- 选定的 `plugin-sdk` 和 `commands` 测试文件现在会路由到专门的轻量 lanes，仅保留 `test/setup.ts`，而运行时较重的用例仍保留在原有 lanes 中。 -- 选定的 `plugin-sdk` 和 `commands` helper 源文件也会让 `pnpm test:changed` 映射到这些轻量 lanes 中的显式同级测试，因此小型 helper 修改可以避免重跑重量级运行时套件。 -- `auto-reply` 现在也被拆分为三个专门配置（`core`、`top-level`、`reply`），这样 reply harness 就不会压制较轻量的 top-level 状态/token/helper 测试。 -- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并在整个仓库配置中启用共享的非隔离 runner。 +- `pnpm test:force`：终止任何仍在占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整的 Vitest 测试套件，这样服务端测试就不会与正在运行的实例发生冲突。当先前的 Gateway 网关运行导致端口 `18789` 仍被占用时，使用此命令。 +- `pnpm test:coverage`：通过 V8 覆盖率运行单元测试套件（使用 `vitest.unit.config.ts`）。这是一个针对已加载文件的单元覆盖率门禁，而不是整个仓库的全文件覆盖率。阈值为：行数/函数/语句 70%，分支 55%。由于 `coverage.all` 为 false，该门禁衡量的是单元覆盖率测试套件加载的文件，而不是将拆分测试通道中的每个源文件都视为未覆盖。 +- `pnpm test:coverage:changed`：仅针对相对于 `origin/main` 发生变更的文件运行单元覆盖率。 +- `pnpm test:changed`：当 diff 只涉及可路由的源文件/测试文件时，会将变更的 Git 路径展开为有作用域的 Vitest 通道。配置/设置变更仍会回退到原生根项目运行方式，这样在确有需要时，接线类改动仍会触发更广泛的重跑。 +- `pnpm changed:lanes`：显示相对于 `origin/main` 的 diff 所触发的架构通道。 +- `pnpm check:changed`：针对相对于 `origin/main` 的 diff 运行智能变更门禁。它会将核心改动与核心测试通道一起运行，将扩展改动与扩展测试通道一起运行，将仅测试改动限制为仅做测试类型检查/测试，将公共 Plugin SDK 或插件契约变更扩展为扩展验证，并使仅含发布元数据的版本变更仍保持在有针对性的版本/配置/根依赖检查范围内。 +- `pnpm test`：通过有作用域的 Vitest 通道路由显式指定的文件/目录目标。未指定目标时，会使用固定的分片组，并展开为叶子配置以便在本地并行执行；扩展组始终会展开为按扩展划分的分片配置，而不是使用一个庞大的根项目进程。 +- 完整测试和扩展分片运行会更新 `.artifacts/vitest-shard-timings.json` 中的本地计时数据；后续运行会使用这些计时信息来平衡慢分片和快分片。设置 `OPENCLAW_TEST_PROJECTS_TIMINGS=0` 可忽略该本地计时产物。 +- 选定的 `plugin-sdk` 和 `commands` 测试文件现在会通过专用的轻量通道运行，这些通道仅保留 `test/setup.ts`，而运行时开销较大的用例仍留在原有通道中。 +- 选定的 `plugin-sdk` 和 `commands` 辅助源文件也会将 `pnpm test:changed` 映射到这些轻量通道中的显式同级测试，因此对小型辅助文件的改动无需重新运行那些依赖重型运行时的测试套件。 +- `auto-reply` 现在也被拆分为三个专用配置（`core`、`top-level`、`reply`），因此回复测试框架不会主导较轻量的顶层状态/token/辅助测试。 +- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并在整个仓库配置中启用了共享的非隔离运行器。 - `pnpm test:channels` 运行 `vitest.channels.config.ts`。 -- `pnpm test:extensions` 和 `pnpm test extensions` 运行所有 extension/plugin 分片。重量级渠道扩展和 OpenAI 会作为专门分片运行；其他 extension 组保持批处理。使用 `pnpm test extensions/` 可只运行一个内置插件 lane。 -- `pnpm test:perf:imports`：启用 Vitest 导入时长 + 导入分解报告，同时对于显式文件/目录目标仍使用带作用域的 lane 路由。 -- `pnpm test:perf:imports:changed`：与上面相同的导入分析，但只针对相对 `origin/main` 有变化的文件。 -- `pnpm test:perf:changed:bench -- --ref `：针对同一个已提交的 git diff，对比带路由的 changed-mode 路径与原生 root-project 运行的性能。 -- `pnpm test:perf:changed:bench -- --worktree`：在不先提交的情况下，对当前 worktree 的变更集做基准测试。 +- `pnpm test:extensions` 和 `pnpm test extensions` 运行所有扩展/插件分片。重量级渠道插件、浏览器插件以及 OpenAI 会作为专用分片运行；其他插件组仍保持批量运行。对单个内置插件通道，使用 `pnpm test extensions/`。 +- `pnpm test:perf:imports`：启用 Vitest 的导入时长 + 导入明细报告，同时仍对显式文件/目录目标使用有作用域的通道路由。 +- `pnpm test:perf:imports:changed`：与上面相同的导入分析，但仅针对相对于 `origin/main` 已变更的文件。 +- `pnpm test:perf:changed:bench -- --ref `：针对同一组已提交 Git diff，将路由后的 changed 模式路径与原生根项目运行进行基准对比。 +- `pnpm test:perf:changed:bench -- --worktree`：对当前工作树的变更集进行基准测试，无需先提交。 - `pnpm test:perf:profile:main`：为 Vitest 主线程写入 CPU profile（`.artifacts/vitest-main-profile`）。 -- `pnpm test:perf:profile:runner`：为单元 runner 写入 CPU + heap profiles（`.artifacts/vitest-runner-profile`）。 -- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`：串行运行每个 full-suite Vitest 叶子配置，并写入按组聚合的耗时数据，以及按配置划分的 JSON/log 制品。测试性能智能体会在尝试修复慢测试之前，将其作为基线。 -- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`：对比性能优化变更前后的分组报告。 +- `pnpm test:perf:profile:runner`：为单元测试运行器写入 CPU + 堆 profile（`.artifacts/vitest-runner-profile`）。 +- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`：串行运行每个完整测试套件的 Vitest 叶子配置，并写入分组时长数据以及每个配置对应的 JSON/日志产物。Test Performance Agent 会在尝试修复慢测试之前，将此结果作为基线。 +- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`：比较一次以性能为重点的改动前后两份分组报告。 - Gateway 网关集成：通过 `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` 或 `pnpm test:gateway` 选择启用。 -- `pnpm test:e2e`：运行 gateway 端到端冒烟测试（多实例 WS/HTTP/node pairing）。在 `vitest.e2e.config.ts` 中默认使用 `threads` + `isolate: false` 和自适应 workers；可通过 `OPENCLAW_E2E_WORKERS=` 调整，并通过 `OPENCLAW_E2E_VERBOSE=1` 获取详细日志。 -- `pnpm test:live`：运行 provider 实时测试（minimax/zai）。需要 API keys，并通过 `LIVE=1`（或 provider 专用的 `*_LIVE_TEST=1`）来取消跳过。 -- `pnpm test:docker:all`：先构建一次共享实时测试镜像和 Docker E2E 镜像，然后默认以并发度 4 运行 Docker 冒烟 lanes，并设置 `OPENCLAW_SKIP_DOCKER_BUILD=1`。可通过 `OPENCLAW_DOCKER_ALL_PARALLELISM=` 调整。除非设置 `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`，否则 runner 会在首次失败后停止安排新的并行 lane；每个 lane 的默认超时为 120 分钟，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖。对启动或 provider 敏感的 lanes 会在并行池之后以独占方式运行。每个 lane 的日志会写入 `.artifacts/docker-tests//`。 -- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行一次真实的代理聊天。需要一个可用的实时模型 key（例如在 `~/.profile` 中的 OpenAI），会拉取外部 Open WebUI 镜像，并且不像普通 unit/e2e 套件那样以 CI 稳定性为目标。 -- `pnpm test:docker:mcp-channels`：启动一个带种子的 Gateway 网关容器和第二个客户端容器，后者会启动 `openclaw mcp serve`，然后通过真实的 stdio bridge 验证路由会话发现、转录读取、附件元数据、实时事件队列行为、出站发送路由，以及 Claude 风格的渠道 + 权限通知。Claude 通知断言会直接读取原始 stdio MCP 帧，以便让冒烟测试反映桥接层的真实输出。 +- `pnpm test:e2e`：运行 Gateway 网关端到端冒烟测试（多实例 WS/HTTP/节点配对）。在 `vitest.e2e.config.ts` 中默认使用 `threads` + `isolate: false` 与自适应 workers；可通过 `OPENCLAW_E2E_WORKERS=` 调整，并设置 `OPENCLAW_E2E_VERBOSE=1` 以输出详细日志。 +- `pnpm test:live`：运行 provider 实时测试（minimax/zai）。需要 API key，并设置 `LIVE=1`（或 provider 专用的 `*_LIVE_TEST=1`）才会取消跳过。 +- `pnpm test:docker:all`：先构建共享的实时测试镜像和 Docker E2E 镜像一次，然后在默认并发数 4 下以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行 Docker 冒烟测试通道。可通过 `OPENCLAW_DOCKER_ALL_PARALLELISM=` 调整。运行器会在首次失败后停止调度新的池化通道，除非设置 `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`；每个通道默认有 120 分钟超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖。对启动敏感或 provider 敏感的通道会在并行池之后独占运行。每个通道的日志会写入 `.artifacts/docker-tests//`。 +- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行一次真实的代理聊天。需要可用的实时模型 key（例如 `~/.profile` 中的 OpenAI），会拉取外部 Open WebUI 镜像，并不像常规单元/e2e 测试套件那样预期具备 CI 稳定性。 +- `pnpm test:docker:mcp-channels`：启动一个带种子数据的 Gateway 网关容器和第二个客户端容器，后者会启动 `openclaw mcp serve`，然后验证路由会话发现、转录读取、附件元数据、实时事件队列行为、出站发送路由，以及通过真实 stdio bridge 传输的 Claude 风格渠道 + 权限通知。Claude 通知断言会直接读取原始 stdio MCP 帧，因此该冒烟测试反映的是 bridge 实际发出的内容。 ## 本地 PR 门禁 -用于本地 PR 落地/门禁检查时，请运行： +在本地执行 PR 合并/门禁检查时，运行： - `pnpm check:changed` - `pnpm check` @@ -54,12 +54,12 @@ x-i18n: - `pnpm test` - `pnpm check:docs` -如果 `pnpm test` 在高负载宿主机上偶发失败，请先重跑一次，再判断是否为真实回归；之后可用 `pnpm test ` 进行隔离。对于内存受限宿主机，请使用： +如果 `pnpm test` 在高负载主机上出现偶发失败，在将其视为回归之前先重跑一次，然后使用 `pnpm test ` 做隔离。对于内存受限的主机，使用： - `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test` - `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed` -## 模型延迟基准（本地 keys） +## 模型延迟基准（本地 key） 脚本：[`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts) @@ -69,7 +69,7 @@ x-i18n: - 可选环境变量：`MINIMAX_API_KEY`、`MINIMAX_BASE_URL`、`MINIMAX_MODEL`、`ANTHROPIC_API_KEY` - 默认提示词：“Reply with a single word: ok. No punctuation or extra text.” -最近一次运行（2025-12-31，20 次）： +上次运行（2025-12-31，20 次）： - minimax 中位数 1279ms（最小 1114，最大 2431） - opus 中位数 2454ms（最小 1224，最大 3170） @@ -99,17 +99,17 @@ x-i18n: - `startup`：`--version`、`--help`、`health`、`health --json`、`status --json`、`status` - `real`：`health`、`status`、`status --json`、`sessions`、`sessions --json`、`agents list --json`、`gateway status`、`gateway status --json`、`gateway health --json`、`config get gateway.port` -- `all`：同时包含两个预设 +- `all`：两个预设都包含 -输出包括每条命令的 `sampleCount`、avg、p50、p95、min/max、exit-code/signal 分布，以及最大 RSS 摘要。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写入 V8 profiles，从而让计时与 profile 捕获使用同一套 harness。 +输出内容包括每个命令的 `sampleCount`、平均值、p50、p95、最小/最大值、exit-code/signal 分布，以及最大 RSS 汇总。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写入 V8 profile，因此计时与 profile 采集使用的是同一套测试框架。 -保存输出约定： +已保存输出约定： -- `pnpm test:startup:bench:smoke` 会将定向 smoke 制品写入 `.artifacts/cli-startup-bench-smoke.json` -- `pnpm test:startup:bench:save` 会使用 `runs=5` 和 `warmup=1` 将全套件制品写入 `.artifacts/cli-startup-bench-all.json` -- `pnpm test:startup:bench:update` 会使用 `runs=5` 和 `warmup=1` 刷新受版本控制的基线夹具 `test/fixtures/cli-startup-bench.json` +- `pnpm test:startup:bench:smoke` 会将定向冒烟产物写入 `.artifacts/cli-startup-bench-smoke.json` +- `pnpm test:startup:bench:save` 会使用 `runs=5` 和 `warmup=1` 将完整测试套件产物写入 `.artifacts/cli-startup-bench-all.json` +- `pnpm test:startup:bench:update` 会使用 `runs=5` 和 `warmup=1` 刷新已签入的基线夹具 `test/fixtures/cli-startup-bench.json` -受版本控制的夹具： +已签入夹具： - `test/fixtures/cli-startup-bench.json` - 使用 `pnpm test:startup:bench:update` 刷新 @@ -117,19 +117,19 @@ x-i18n: ## 新手引导 E2E（Docker） -Docker 是可选的；只有在进行容器化新手引导冒烟测试时才需要它。 +Docker 是可选的；只有在运行容器化新手引导冒烟测试时才需要它。 -在干净的 Linux 容器中运行完整冷启动流程： +在干净的 Linux 容器中执行完整冷启动流程： ```bash scripts/e2e/onboard-docker.sh ``` -该脚本会通过伪 TTY 驱动交互式向导，验证配置/工作区/会话文件，然后启动 gateway 并运行 `openclaw health`。 +该脚本会通过 pseudo-tty 驱动交互式向导，验证 config/workspace/session 文件，然后启动 Gateway 网关并运行 `openclaw health`。 -## QR 导入冒烟（Docker） +## QR 导入冒烟测试（Docker） -确保维护中的 QR 运行时辅助工具能在受支持的 Docker Node 运行时下加载（默认 Node 24，兼容 Node 22）： +确保维护中的 QR 运行时辅助程序可在受支持的 Docker Node 运行时中加载（默认 Node 24，兼容 Node 22）： ```bash pnpm test:docker:qr diff --git a/docs/zh-CN/tools/exec-approvals.md b/docs/zh-CN/tools/exec-approvals.md index ec65ccb8f..8d7e81dbf 100644 --- a/docs/zh-CN/tools/exec-approvals.md +++ b/docs/zh-CN/tools/exec-approvals.md @@ -1,74 +1,63 @@ --- read_when: - - 配置 exec 审批或 allowlist 时പ്പ to=final code omitted - - 在 macOS 应用中实现 exec 审批 UX 时ેણ to=final code omitted - - 审查沙箱逃逸提示及其影响时 -summary: exec 审批、allowlist 和沙箱逃逸提示ուռ to=final code omitted -title: Exec 审批 + - 配置执行审批或允许列表 + - 在 macOS 应用中实现执行审批 UX + - 审查沙箱逃逸提示及其影响 +summary: 执行审批、允许列表和沙箱逃逸提示 +title: 执行审批 x-i18n: - generated_at: "2026-04-23T21:07:48Z" + generated_at: "2026-04-23T22:14:42Z" model: gpt-5.4 provider: openai - source_hash: aed029a7aff5b4a9e67e5fc20a91ca80b1ddabb562cb5a1ce05c2a6222321698 + source_hash: a4090e0726d9cee3372a11e6bf8f7899546e68f4fabea42dcb55b87593e9315c source_path: tools/exec-approvals.md workflow: 15 --- -Exec 审批是用于让 -沙箱隔离智能体在真实主机（`gateway` 或 `node`）上运行命令的**配套应用 / 节点主机护栏**。它是一个安全联锁：只有当策略 + allowlist +（可选的）用户 -审批全部同意时，命令才会被允许。Exec 审批会**叠加在**工具策略和 elevated 门控**之上**（除非 elevated 设为 `full`，此时会跳过审批）。 +执行审批是 **配套应用 / 节点主机防护栏**，用于让处于沙箱隔离的智能体在真实主机（`gateway` 或 `node`）上运行命令。它是一种安全联锁机制：只有当策略 + 允许列表 +（可选的）用户审批全部同意时，命令才会被允许执行。执行审批会**叠加在**工具策略和 elevated 门控之上（除非 elevated 设为 `full`，此时会跳过审批）。 -生效策略是 `tools.exec.*` 与 approvals 默认值中**更严格**的那个； -如果某个 approvals 字段被省略，则使用 `tools.exec` 的值。主机 exec -还会使用该机器上的本地审批状态 —— 如果 `~/.openclaw/exec-approvals.json` 中设置了主机本地 `ask: "always"`，那么即使会话或配置默认值请求 `ask: "on-miss"`，也仍然会持续提示。 +生效策略取 `tools.exec.*` 与审批默认值中**更严格**的一方；如果某个 approvals 字段被省略，则使用 `tools.exec` 的值。主机执行也会使用该机器上的本地 approvals 状态——如果 `~/.openclaw/exec-approvals.json` 中主机本地配置了 `ask: "always"`，即使会话或配置默认值请求 `ask: "on-miss"`，系统仍会持续提示。 ## 检查生效策略 -- `openclaw approvals get`、`... --gateway`、`... --node ` —— 显示请求的策略、主机策略来源以及生效结果。 -- `openclaw exec-policy show` —— 本地机器上的合并视图。 -- `openclaw exec-policy set|preset` —— 一步同步本地请求策略与本地主机审批文件。 +- `openclaw approvals get`、`... --gateway`、`... --node ` —— 显示请求的策略、主机策略来源以及最终生效结果。 +- `openclaw exec-policy show` —— 本地机器的合并视图。 +- `openclaw exec-policy set|preset` —— 一步同时同步本地请求策略和本地主机 approvals 文件。 -当某个本地作用域请求 `host=node` 时，`exec-policy show` 会在运行时将该作用域报告为由节点管理，而不是假装本地审批文件是真实来源。 +当本地作用域请求 `host=node` 时，`exec-policy show` 会在运行时将该作用域报告为由节点管理，而不是假装本地 approvals 文件是真实来源。 -如果配套应用 UI **不可用**，任何本来会触发提示的请求都会由**ask 回退**来处理（默认：拒绝）。 +如果配套应用 UI **不可用**，任何原本会触发提示的请求都会根据 **ask fallback** 处理（默认：拒绝）。 -原生聊天审批客户端可以在待处理审批消息上加入特定渠道的操作方式。例如，Matrix 会添加表情快捷方式（`✅` -允许一次、`❌` 拒绝、`♾️` 始终允许），同时仍保留消息中的 `/approve ...` -命令作为回退。 +原生聊天审批客户端可以在待审批消息上预置特定渠道的交互方式。例如，Matrix 会预置反应快捷方式（`✅` 允许一次、`❌` 拒绝、`♾️` 始终允许），同时仍保留消息中的 `/approve ...` 命令作为后备方式。 -## 它适用于哪里 +## 适用范围 -Exec 审批在执行主机上本地强制执行： +执行审批会在执行主机本地强制生效： -- **gateway 主机** → gateway 机器上的 `openclaw` 进程 -- **节点主机** → 节点运行器（macOS 配套应用或无头节点主机） +- **gateway host** → Gateway 网关机器上的 `openclaw` 进程 +- **node host** → 节点运行器（macOS 配套应用或无头节点主机） 信任模型说明： -- 已通过 Gateway 网关认证的调用方会被视为该 Gateway 网关的受信任操作员。 +- 通过 Gateway 网关认证的调用方，是该 Gateway 网关的受信任操作员。 - 已配对节点会将这种受信任操作员能力扩展到节点主机。 -- Exec 审批会降低意外执行风险，但它不是按用户划分的认证边界。 -- 已批准的节点主机运行会绑定规范执行上下文：规范 cwd、精确 argv、在存在时绑定 env， - 以及在适用时固定可执行路径。 -- 对于 shell 脚本和直接解释器/运行时文件调用，OpenClaw 还会尝试绑定 - 一个具体的本地文件操作数。如果该绑定文件在审批后、执行前发生变化， - 则该运行会被拒绝，而不是执行已漂移的内容。 -- 这种文件绑定是有意设计为尽力而为，而不是对每个 - 解释器/运行时加载器路径建立完整语义模型。如果审批模式无法识别出恰好一个可绑定的具体本地 - 文件，它会拒绝签发基于审批的运行，而不是假装具有完整覆盖能力。 +- 执行审批可降低意外执行风险，但它不是按用户划分的身份验证边界。 +- 经批准的节点主机执行会绑定规范执行上下文：规范 cwd、精确 argv、存在时的 env 绑定，以及适用时固定的可执行文件路径。 +- 对于 shell 脚本和直接解释器 / 运行时文件调用，OpenClaw 还会尝试绑定一个具体的本地文件操作数。如果该已绑定文件在审批后、执行前发生变化，则会拒绝执行，而不是运行已漂移的内容。 +- 这种文件绑定有意设计为尽力而为，并不是对所有解释器 / 运行时加载路径的完整语义模型。如果审批模式无法识别并绑定**唯一一个**具体本地文件，它会拒绝签发基于审批的执行，而不是假装提供了完整覆盖。 macOS 拆分： -- **节点主机服务** 会通过本地 IPC 将 `system.run` 转发给 **macOS 应用**。 -- **macOS 应用** 负责执行审批 + 以 UI 上下文运行命令。 +- **node host service** 会通过本地 IPC 将 `system.run` 转发给 **macOS app**。 +- **macOS app** 负责强制执行审批并在 UI 上下文中执行命令。 ## 设置与存储 -审批信息位于执行主机上的本地 JSON 文件中： +审批信息保存在执行主机本地的 JSON 文件中： `~/.openclaw/exec-approvals.json` @@ -109,28 +98,32 @@ macOS 拆分： ## 无审批 “YOLO” 模式 -如果你希望主机 exec 在没有审批提示的情况下运行，你必须同时打开**两层**策略： +如果你希望主机执行在没有审批提示的情况下运行，就必须同时放开**两层**策略： -- OpenClaw 配置中的请求 exec 策略（`tools.exec.*`） -- `~/.openclaw/exec-approvals.json` 中的主机本地审批策略 +- OpenClaw 配置中的请求执行策略（`tools.exec.*`） +- `~/.openclaw/exec-approvals.json` 中的主机本地 approvals 策略 -除非你显式收紧它，否则这现在是默认主机行为： +这现在是默认的主机行为，除非你显式收紧它： -- `tools.exec.security`：在 `gateway`/`node` 上为 `full` -- `tools.exec.ask`：`off` -- 主机 `askFallback`：`full` +- `tools.exec.security`: 在 `gateway`/`node` 上设为 `full` +- `tools.exec.ask`: `off` +- 主机 `askFallback`: `full` 重要区别： -- `tools.exec.host=auto` 决定 exec 在哪里运行：有沙箱时使用沙箱，否则使用 gateway。 -- YOLO 决定主机 exec 如何被审批：`security=full` 加 `ask=off`。 -- 在 YOLO 模式下，OpenClaw 不会在已配置主机 exec 策略之上，再额外增加单独的启发式命令混淆审批门控或脚本预检拒绝层。 -- `auto` 不会让 gateway 路由成为来自沙箱隔离会话的免费覆盖。允许从 `auto` 发起逐次调用的 `host=node` 请求，而 `host=gateway` 只有在没有活动沙箱运行时的情况下，才允许从 `auto` 发起。如果你想要一个稳定的非 auto 默认值，请设置 `tools.exec.host` 或显式使用 `/exec host=...`。 +- `tools.exec.host=auto` 用于选择执行运行位置：有沙箱时在沙箱中，否则在 gateway。 +- YOLO 用于选择主机执行如何获批：`security=full` 加 `ask=off`。 +- 暴露自身非交互权限模式的 CLI 后端 provider 可以遵循此策略。 + Claude CLI 会在 OpenClaw 请求的执行策略为 YOLO 时添加 `--permission-mode bypassPermissions`。你可以通过 + `agents.defaults.cliBackends.claude-cli.args` / `resumeArgs` 下的显式 Claude 参数覆盖该后端行为，例如 + `--permission-mode default`、`acceptEdits` 或 `bypassPermissions`。 +- 在 YOLO 模式下，OpenClaw 不会在已配置的主机执行策略之上，再额外添加单独的启发式命令混淆审批门控或脚本预检拒绝层。 +- `auto` 不会让来自沙箱隔离会话的 gateway 路由请求变成可随意覆盖的“免费通行证”。每次调用的 `host=node` 请求在 `auto` 下是允许的，而 `host=gateway` 只有在没有活动沙箱运行时时才允许从 `auto` 使用。如果你想要稳定的非 auto 默认值，请设置 `tools.exec.host` 或显式使用 `/exec host=...`。 -如果你想要更保守的设置，请将任一层重新收紧为 `allowlist` / `on-miss` +如果你希望采用更保守的设置，可将任一层重新收紧为 `allowlist` / `on-miss` 或 `deny`。 -持久化的 gateway 主机“永不提示”设置： +持久化 gateway host “永不提示” 配置： ```bash openclaw config set tools.exec.host gateway @@ -139,7 +132,7 @@ openclaw config set tools.exec.ask off openclaw gateway restart ``` -然后将主机审批文件设置为匹配状态： +然后将主机 approvals 文件设为匹配值： ```bash openclaw approvals set --stdin <<'EOF' @@ -154,22 +147,21 @@ openclaw approvals set --stdin <<'EOF' EOF ``` -当前机器上相同 gateway 主机策略的本地快捷方式： +在当前机器上为相同 gateway host 策略提供的本地快捷方式： ```bash openclaw exec-policy preset yolo ``` -这个本地快捷方式会同时更新： +该本地快捷方式会同时更新： - 本地 `tools.exec.host/security/ask` - 本地 `~/.openclaw/exec-approvals.json` 默认值 -它有意仅限本地使用。如果你需要远程更改 gateway 主机或节点主机审批， -请继续使用 `openclaw approvals set --gateway` 或 +它有意仅限本地使用。如果你需要远程更改 gateway host 或 node host 的审批，请继续使用 `openclaw approvals set --gateway` 或 `openclaw approvals set --node `。 -对于节点主机，请改为在该节点上应用相同的审批文件： +对于节点主机，请在该节点上应用相同的 approvals 文件： ```bash openclaw approvals set --node --stdin <<'EOF' @@ -184,68 +176,67 @@ openclaw approvals set --node --stdin <<'EOF' EOF ``` -重要的本地限制： +重要的仅限本地限制： - `openclaw exec-policy` 不会同步节点审批 - `openclaw exec-policy set --host node` 会被拒绝 -- 节点 exec 审批会在运行时从节点获取，因此面向节点的更新必须使用 `openclaw approvals --node ...` +- 节点执行审批会在运行时从节点获取，因此面向节点的更新必须使用 `openclaw approvals --node ...` -仅当前会话快捷方式： +仅会话快捷方式： -- `/exec security=full ask=off` 仅更改当前会话。 -- `/elevated full` 是一个 break-glass 快捷方式，它也会跳过该会话的 exec 审批。 +- `/exec security=full ask=off` 只会更改当前会话。 +- `/elevated full` 是一个紧急放行快捷方式，也会跳过该会话的执行审批。 -如果主机审批文件保持得比配置更严格，则仍以更严格的主机策略为准。 +如果主机 approvals 文件仍比配置更严格，则仍以更严格的主机策略为准。 -## 策略控制项 +## 策略开关 -### 安全（`exec.security`） +### 安全级别（`exec.security`） -- **deny**：阻止所有主机 exec 请求。 -- **allowlist**：仅允许 allowlist 中的命令。 -- **full**：允许一切（等同于 elevated）。 +- **deny**：阻止所有主机执行请求。 +- **allowlist**：仅允许允许列表中的命令。 +- **full**：允许全部（等同于 elevated）。 -### Ask（`exec.ask`） +### 询问方式（`exec.ask`） - **off**：从不提示。 -- **on-miss**：仅当 allowlist 未匹配时提示。 -- **always**：对每条命令都提示。 -- 当生效 ask 模式为 `always` 时，`allow-always` 的持久信任不会抑制提示 +- **on-miss**：仅当允许列表未匹配时提示。 +- **always**：每条命令都提示。 +- 当生效的询问模式为 `always` 时，`allow-always` 的持久信任不会抑制提示 -### Ask 回退（`askFallback`） +### 询问后备（`askFallback`） -如果某次请求需要提示，但没有可达 UI，则由回退来决定： +如果需要提示但没有可达 UI，则由 fallback 决定： - **deny**：阻止。 -- **allowlist**：仅在 allowlist 匹配时允许。 +- **allowlist**：仅当允许列表匹配时允许。 - **full**：允许。 -### 内联解释器 eval 加固（`tools.exec.strictInlineEval`） +### 行内解释器 eval 加固（`tools.exec.strictInlineEval`） -当 `tools.exec.strictInlineEval=true` 时，OpenClaw 会将内联代码 eval 形式视为仅可通过审批执行，即使解释器二进制本身已经位于 allowlist 中。 +当 `tools.exec.strictInlineEval=true` 时，OpenClaw 会将行内代码 eval 形式视为“仅可通过审批执行”，即使解释器二进制本身已经在允许列表中。 示例： - `python -c` -- `node -e`、`node --eval`、`node -p` +- `node -e`, `node --eval`, `node -p` - `ruby -e` -- `perl -e`、`perl -E` +- `perl -e`, `perl -E` - `php -r` - `lua -e` - `osascript -e` -这是针对那些无法干净映射到单一稳定文件操作数的解释器加载器所做的纵深防御。在严格模式下： +这是针对无法干净映射到单一稳定文件操作数的解释器加载路径所做的纵深防御。在严格模式下： - 这些命令仍然需要显式审批； -- `allow-always` 不会自动为它们持久化新的 allowlist 条目。 +- `allow-always` 不会自动为它们持久化新的允许列表条目。 -## Allowlist（按智能体） +## 允许列表（按智能体区分） -Allowlist 是**按智能体**划分的。如果存在多个智能体，请在 macOS 应用中切换你正在 -编辑的智能体。模式使用**不区分大小写的 glob 匹配**。 -模式应解析为**二进制路径**（仅文件名条目会被忽略）。 +允许列表是**按智能体**划分的。如果存在多个智能体，请在 macOS 应用中切换你正在编辑的智能体。模式是**不区分大小写的 glob 匹配**。 +模式应解析为**二进制路径**（仅文件名的条目会被忽略）。 旧版 `agents.default` 条目会在加载时迁移到 `agents.main`。 -像 `echo ok && pwd` 这样的 shell 链仍然要求每个顶层片段都满足 allowlist 规则。 +像 `echo ok && pwd` 这样的 shell 链式命令，仍然要求每个顶层片段都满足允许列表规则。 示例： @@ -253,301 +244,255 @@ Allowlist 是**按智能体**划分的。如果存在多个智能体，请在 ma - `~/.local/bin/*` - `/opt/homebrew/bin/rg` -每个 allowlist 条目会跟踪： +每个允许列表条目会跟踪： -- **id**：供 UI 标识使用的稳定 UUID（可选） -- **last used**：最近使用时间戳 -- **last used command** -- **last resolved path** +- **id**：用于 UI 身份识别的稳定 UUID（可选） +- **last used**：上次使用时间戳 +- **last used command**：上次使用的命令 +- **last resolved path**：上次解析到的路径 ## 自动允许 Skill CLI -当启用 **Auto-allow skill CLIs** 时，已知 Skills -引用的可执行文件会在节点上（macOS 节点或无头节点主机）被视为已加入 allowlist。这会 -通过 Gateway RPC 使用 `skills.bins` 获取 skill bin 列表。如果你希望严格手动 allowlist，请禁用此功能。 +启用 **Auto-allow skill CLIs** 后，已知 Skills 引用的可执行文件会在节点（macOS 节点或无头节点主机）上被视为已加入允许列表。此功能通过 Gateway RPC 使用 +`skills.bins` 获取 skill bin 列表。如果你希望采用严格的手动允许列表，请禁用该功能。 重要信任说明： -- 这是一个**隐式便利 allowlist**，与手动路径 allowlist 条目分离。 -- 它适用于 Gateway 和节点位于同一信任边界内的受信任操作员环境。 -- 如果你要求严格的显式信任，请保持 `autoAllowSkills: false`，并仅使用手动路径 allowlist 条目。 +- 这是一个**隐式的便捷允许列表**，独立于手动路径允许列表条目。 +- 它适用于 Gateway 网关与节点处于同一信任边界内的受信任操作员环境。 +- 如果你需要严格的显式信任，请保持 `autoAllowSkills: false`，并仅使用手动路径允许列表条目。 -## Safe bins（仅 stdin） +## 安全 bin（仅 stdin） -`tools.exec.safeBins` 定义了一小组**仅 stdin** 的二进制（例如 -`cut`），它们可在 allowlist 模式下**无需**显式 allowlist -条目即可运行。Safe bins 会拒绝位置文件参数和类似路径的 token，因此 -它们只能处理传入流。请将其视为流过滤器的窄快速路径， -而不是通用信任列表。 +`tools.exec.safeBins` 定义了一小组**仅限 stdin** 的二进制程序（例如 `cut`），它们在 allowlist 模式下**无需**显式允许列表条目即可运行。安全 bin 会拒绝位置文件参数和类似路径的 token，因此它们只能处理输入流。应将其视为流过滤器的狭窄快速通道，而不是通用信任列表。 -**不要**将解释器或运行时二进制（例如 `python3`、`node`、 -`ruby`、`bash`、`sh`、`zsh`）添加到 `safeBins` 中。如果某个命令本身就能执行代码、 -执行子命令或读取文件，请优先使用显式 allowlist 条目， -并保持审批提示开启。自定义 safe bins 必须在 -`tools.exec.safeBinProfiles.` 中定义显式 profile。 +**不要**将解释器或运行时二进制程序（例如 `python3`、`node`、 +`ruby`、`bash`、`sh`、`zsh`）添加到 `safeBins`。如果某条命令按设计就能执行代码、执行子命令或读取文件，应优先使用显式允许列表条目，并保持审批提示开启。自定义安全 bin 必须在 `tools.exec.safeBinProfiles.` 中定义显式 profile。 -默认 safe bins： +默认安全 bin： [//]: # "SAFE_BIN_DEFAULTS:START" -`cut`、`uniq`、`head`、`tail`、`tr`、`wc` +`cut`, `uniq`, `head`, `tail`, `tr`, `wc` [//]: # "SAFE_BIN_DEFAULTS:END" -`grep` 和 `sort` 不在默认列表中。如果你选择启用它们，请为其非 stdin 工作流保留显式 -allowlist 条目。对于处于 safe-bin 模式下的 `grep`，请使用 `-e`/`--regexp` 提供模式；位置模式形式会被拒绝， -这样文件操作数就无法伪装成含糊的位置参数。 +`grep` 和 `sort` 不在默认列表中。如果你选择启用它们，请继续为其非 stdin 工作流保留显式允许列表条目。对于处于安全 bin 模式的 `grep`， +请使用 `-e`/`--regexp` 提供模式；位置模式形式会被拒绝，以防文件操作数通过模糊的位置参数被偷偷带入。 -### Argv 验证与被拒绝标志 +### Argv 校验与被拒绝的标志 -验证是基于 argv 形状的确定性验证（不检查主机文件系统是否存在），这样可以防止通过 allow/deny 差异形成文件存在性预言机行为。对默认 safe bins，面向文件的选项会被拒绝；长选项采用关闭失败方式验证（未知标志和歧义缩写会被拒绝）。 +校验仅根据 argv 形态确定，且具有确定性（不检查主机文件系统中是否存在相关路径），这样可防止通过 allow/deny 差异形成文件存在性预言机行为。默认安全 bin 会拒绝面向文件的选项；长选项会按 fail-closed 方式校验（未知标志和含糊缩写都会被拒绝）。 -按 safe-bin profile 列出的被拒绝标志： +按安全 bin profile 划分的被拒绝标志： [//]: # "SAFE_BIN_DENIED_FLAGS:START" -- `grep`：`--dereference-recursive`、`--directories`、`--exclude-from`、`--file`、`--recursive`、`-R`、`-d`、`-f`、`-r` -- `jq`：`--argfile`、`--from-file`、`--library-path`、`--rawfile`、`--slurpfile`、`-L`、`-f` -- `sort`：`--compress-program`、`--files0-from`、`--output`、`--random-source`、`--temporary-directory`、`-T`、`-o` -- `wc`：`--files0-from` +- `grep`: `--dereference-recursive`, `--directories`, `--exclude-from`, `--file`, `--recursive`, `-R`, `-d`, `-f`, `-r` +- `jq`: `--argfile`, `--from-file`, `--library-path`, `--rawfile`, `--slurpfile`, `-L`, `-f` +- `sort`: `--compress-program`, `--files0-from`, `--output`, `--random-source`, `--temporary-directory`, `-T`, `-o` +- `wc`: `--files0-from` [//]: # "SAFE_BIN_DENIED_FLAGS:END" -Safe bins 还会强制将 argv token 在执行时视为**字面文本** -（不进行 glob 展开，也不展开 `$VARS`）用于仅 stdin 的片段，因此像 -`*` 或 `$HOME/...` 这样的模式不能被用来夹带文件读取。 +安全 bin 还会在执行时强制将 argv token 视为**字面文本**（不会进行 glob 展开，也不会展开 `$VARS`）用于仅 stdin 的片段，因此像 `*` 或 `$HOME/...` 这样的模式不能被用来偷偷读取文件。 ### 受信任的二进制目录 -Safe bins 必须从受信任的二进制目录中解析（系统默认目录加上可选的 `tools.exec.safeBinTrustedDirs`）。`PATH` 条目绝不会被自动信任。 -默认受信任目录是有意保持最小化的：`/bin`、`/usr/bin`。如果 -你的 safe-bin 可执行文件位于包管理器/用户路径中（例如 -`/opt/homebrew/bin`、`/usr/local/bin`、`/opt/local/bin`、`/snap/bin`），请将它们 -显式添加到 `tools.exec.safeBinTrustedDirs`。 +安全 bin 必须从受信任的二进制目录解析（系统默认值加上可选的 `tools.exec.safeBinTrustedDirs`）。`PATH` 条目绝不会被自动视为受信任。默认受信任目录有意保持最小：`/bin`、`/usr/bin`。如果你的安全 bin 可执行文件位于包管理器 / 用户路径中（例如 +`/opt/homebrew/bin`、`/usr/local/bin`、`/opt/local/bin`、`/snap/bin`），请将它们显式添加到 `tools.exec.safeBinTrustedDirs`。 -### Shell 链接、包装器与多路复用器 +### Shell 链式调用、包装器和多路复用器 -当每个顶层片段都满足 allowlist（包括 safe bins 或 skill 自动允许）时，允许使用 shell 链接（`&&`、`||`、`;`）。在 allowlist 模式下，重定向仍然不受支持。命令替换（`$()` / 反引号）在 allowlist 解析期间会被拒绝，包括双引号内；如果你需要字面量 `$()` 文本，请使用单引号。 +当每个顶层片段都满足允许列表要求时，shell 链式调用（`&&`、`||`、`;`）是允许的（包括安全 bin 或 Skills 自动允许）。重定向在 allowlist 模式下仍不受支持。命令替换（`$()` / 反引号）会在 allowlist 解析期间被拒绝，包括双引号内部；如果你需要字面量的 `$()` 文本，请使用单引号。 -在 macOS 配套应用审批中，包含 shell 控制或 -展开语法（`&&`、`||`、`;`、`|`、`` ` ``、`$`、`<`、`>`、`(`、`)`）的原始 shell 文本 -会被视为 allowlist 未命中，除非 shell 二进制本身已位于 allowlist 中。 +在 macOS 配套应用审批中，包含 shell 控制或展开语法（`&&`、`||`、`;`、`|`、`` ` ``、`$`、`<`、`>`、`(`、`)`）的原始 shell 文本会被视为允许列表未命中，除非 shell 二进制本身已在允许列表中。 -对于 shell 包装器（`bash|sh|zsh ... -c/-lc`），按请求范围的 env 覆盖会被缩减为一小组显式 allowlist（`TERM`、`LANG`、`LC_*`、`COLORTERM`、 +对于 shell 包装器（`bash|sh|zsh ... -c/-lc`），请求作用域内的 env 覆盖会被缩减为一个小型显式允许列表（`TERM`、`LANG`、`LC_*`、`COLORTERM`、 `NO_COLOR`、`FORCE_COLOR`）。 -对于 allowlist 模式下的 `allow-always` 决策，已知的调度包装器（`env`、 -`nice`、`nohup`、`stdbuf`、`timeout`）会持久化内部可执行文件路径，而不是 -包装器路径。Shell 多路复用器（`busybox`、`toybox`）在用于 -shell applet（`sh`、`ash` 等）时也会以相同方式解包。如果某个包装器或多路复用器 -无法被安全解包，则不会自动持久化任何 allowlist 条目。 +对于 allowlist 模式下的 `allow-always` 决策，已知分发包装器（`env`、 +`nice`、`nohup`、`stdbuf`、`timeout`）会持久化内部可执行文件路径，而不是包装器路径。Shell 多路复用器（`busybox`、`toybox`）也会以相同方式对 shell applet（`sh`、`ash` 等）进行解包。如果包装器或多路复用器无法被安全解包，则不会自动持久化任何允许列表条目。 -如果你将 `python3` 或 `node` 之类的解释器加入 allowlist，请优先设置 -`tools.exec.strictInlineEval=true`，这样内联 eval 仍然需要显式 -审批。在严格模式下，`allow-always` 仍可持久化无害的 -解释器/脚本调用，但内联 eval 承载器不会被自动持久化。 +如果你将 `python3` 或 `node` 等解释器加入允许列表，建议启用 +`tools.exec.strictInlineEval=true`，这样行内 eval 仍然需要显式审批。在严格模式下，`allow-always` 仍可持久化无害的解释器 / 脚本调用，但行内 eval 载体不会被自动持久化。 -### Safe bins 与 allowlist 的区别 +### 安全 bin 与 allowlist 的区别 -| 主题 | `tools.exec.safeBins` | Allowlist（`exec-approvals.json`） | +| 主题 | `tools.exec.safeBins` | 允许列表（`exec-approvals.json`） | | ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ | -| 目标 | 自动允许窄范围 stdin 过滤器 | 显式信任特定可执行文件 | -| 匹配类型 | 可执行文件名 + safe-bin argv 策略 | 已解析可执行路径 glob 模式 | -| 参数范围 | 受 safe-bin profile 和字面 token 规则限制 | 仅匹配路径；其余参数由你自行负责 | +| 目标 | 自动允许范围狭窄的 stdin 过滤器 | 显式信任特定可执行文件 | +| 匹配类型 | 可执行文件名 + 安全 bin argv 策略 | 已解析可执行文件路径 glob 模式 | +| 参数范围 | 受安全 bin profile 和字面量 token 规则限制 | 仅匹配路径；其余参数由你自行负责 | | 典型示例 | `head`、`tail`、`tr`、`wc` | `jq`、`python3`、`node`、`ffmpeg`、自定义 CLI | -| 最佳用途 | 管道中的低风险文本转换 | 任何行为更广泛或有副作用的工具 | +| 最佳用途 | 管道中的低风险文本转换 | 任何行为更广泛或具有副作用的工具 | 配置位置： - `safeBins` 来自配置（`tools.exec.safeBins` 或按智能体的 `agents.list[].tools.exec.safeBins`）。 - `safeBinTrustedDirs` 来自配置（`tools.exec.safeBinTrustedDirs` 或按智能体的 `agents.list[].tools.exec.safeBinTrustedDirs`）。 - `safeBinProfiles` 来自配置（`tools.exec.safeBinProfiles` 或按智能体的 `agents.list[].tools.exec.safeBinProfiles`）。按智能体的 profile 键会覆盖全局键。 -- allowlist 条目位于主机本地 `~/.openclaw/exec-approvals.json` 的 `agents..allowlist` 下（或通过 Control UI / `openclaw approvals allowlist ...` 管理）。 -- 当解释器/运行时 bin 出现在 `safeBins` 中且没有显式 profile 时，`openclaw security audit` 会发出 `tools.exec.safe_bins_interpreter_unprofiled` 警告。 -- `openclaw doctor --fix` 可以为缺失的自定义 `safeBinProfiles.` 条目生成 `{}` 脚手架（之后请再审查并收紧）。解释器/运行时 bin 不会自动生成脚手架。 +- allowlist 条目保存在主机本地 `~/.openclaw/exec-approvals.json` 的 `agents..allowlist` 下（或通过 Control UI / `openclaw approvals allowlist ...`）。 +- 当解释器 / 运行时 bin 出现在 `safeBins` 中但没有显式 profile 时，`openclaw security audit` 会发出 `tools.exec.safe_bins_interpreter_unprofiled` 警告。 +- `openclaw doctor --fix` 可以为缺失的自定义 `safeBinProfiles.` 条目生成为 `{}` 脚手架（之后请进行审查并收紧）。解释器 / 运行时 bin 不会被自动生成脚手架。 自定义 profile 示例： __OC_I18N_900005__ -如果你显式选择将 `jq` 加入 `safeBins`，OpenClaw 仍会在 safe-bin -模式下拒绝 `env` 内置项，因此 `jq -n env` 无法在没有显式 allowlist 路径 -或审批提示的情况下转储主机进程环境。 +如果你显式选择将 `jq` 加入 `safeBins`，OpenClaw 在安全 bin 模式下仍会拒绝 +`env` 内建，因此 `jq -n env` 不能在没有显式 allowlist 路径或审批提示的情况下转储主机进程环境。 -## Control UI 编辑 +## 编辑 Control UI -使用 **Control UI → Nodes → Exec approvals** 卡片来编辑默认值、按智能体 -覆盖和 allowlist。选择一个范围（Defaults 或某个智能体），调整策略， -添加/移除 allowlist 模式，然后点击 **Save**。UI 会显示每个模式的**最近使用** -元数据，方便你保持列表整洁。 +使用 **Control UI → Nodes → Exec approvals** 卡片来编辑默认值、按智能体的覆盖项以及允许列表。选择一个作用域（默认值或某个智能体），调整策略，添加 / 移除允许列表模式，然后点击 **Save**。UI 会显示每个模式的 **last used** 元数据，方便你保持列表整洁。 -目标选择器可选择 **Gateway**（本地审批）或某个**节点**。节点 -必须广播 `system.execApprovals.get/set`（macOS 应用或无头节点主机）。 -如果某个节点尚未广播 exec approvals，请直接编辑其本地 +目标选择器可选择 **Gateway**（本地审批）或 **Node**。节点必须声明 `system.execApprovals.get/set`（macOS 应用或无头节点主机）。如果某个节点尚未声明执行审批，请直接编辑其本地 `~/.openclaw/exec-approvals.json`。 -CLI：`openclaw approvals` 支持 gateway 或 node 编辑（请参见 [Approvals CLI](/cli/approvals)）。 +CLI：`openclaw approvals` 支持编辑 gateway 或节点（参见 [Approvals CLI](/cli/approvals)）。 ## 审批流程 当需要提示时，gateway 会向操作员客户端广播 `exec.approval.requested`。 -Control UI 和 macOS 应用会通过 `exec.approval.resolve` 解决它，然后 gateway 再将 -已批准请求转发到节点主机。 +Control UI 和 macOS 应用通过 `exec.approval.resolve` 进行处理，然后 gateway 会将已批准的请求转发到节点主机。 -对于 `host=node`，审批请求会包含一个规范的 `systemRunPlan` 载荷。gateway 在转发已批准的 `system.run` -请求时，会将该计划作为权威命令/cwd/session 上下文。 +对于 `host=node`，审批请求会包含一个规范化的 `systemRunPlan` 负载。Gateway 网关在转发已批准的 `system.run` +请求时，会将该计划作为权威的命令 / cwd / 会话上下文。 -这对于异步审批延迟非常重要： +这对于异步审批延迟很重要： - 节点 exec 路径会预先准备一个规范计划 -- 审批记录会保存该计划及其绑定元数据 -- 一旦审批通过，最终转发的 `system.run` 调用会复用该已存储计划， - 而不是相信后来调用方的编辑 -- 如果调用方在审批请求创建后更改了 `command`、`rawCommand`、`cwd`、`agentId` 或 - `sessionKey`，gateway 会将转发的运行拒绝为审批不匹配 +- 审批记录会存储该计划及其绑定元数据 +- 一旦获批，最终转发的 `system.run` 调用会复用已存储的计划 + 而不是信任调用方之后的修改 +- 如果调用方在审批请求创建之后更改了 `command`、`rawCommand`、`cwd`、`agentId` 或 + `sessionKey`，Gateway 网关会将该转发执行拒绝为审批不匹配 -## 解释器/运行时命令 +## 解释器 / 运行时命令 -基于审批的解释器/运行时执行有意保持保守： +基于审批的解释器 / 运行时执行有意保持保守： - 始终绑定精确的 argv/cwd/env 上下文。 -- 对于直接 shell 脚本和直接运行时文件形式，会尽力绑定到一个具体的本地 - 文件快照。 -- 对于仍能解析为单一直接本地文件的常见包管理器包装形式（例如 - `pnpm exec`、`pnpm node`、`npm exec`、`npx`），会在绑定前进行解包。 -- 如果 OpenClaw 无法为某个解释器/运行时命令识别出恰好一个具体本地文件 - （例如包脚本、eval 形式、运行时特定加载链或含糊的多文件 - 形式），则会拒绝基于审批的执行，而不是声称拥有自己并不具备的语义覆盖。 -- 对于这些工作流，请优先使用沙箱隔离、单独主机边界，或 - 显式的受信任 allowlist/full 工作流，在那种工作流中由操作员接受更广泛的运行时语义。 +- 直接 shell 脚本和直接运行时文件形式会尽力绑定到一个具体的本地文件快照。 +- 仍然解析为单个直接本地文件的常见包管理器包装形式（例如 + `pnpm exec`、`pnpm node`、`npm exec`、`npx`）会在绑定前先解包。 +- 如果 OpenClaw 无法为某条解释器 / 运行时命令识别出**唯一一个**具体本地文件 + （例如包脚本、eval 形式、运行时特定的加载器链，或存在歧义的多文件形式）， + 则会拒绝基于审批的执行，而不是声称自己覆盖了并不具备的语义。 +- 对于这些工作流，建议优先使用沙箱隔离、单独的主机边界，或显式的受信任 + allowlist/full 工作流，由操作员接受更广泛的运行时语义。 -当需要审批时，exec 工具会立即返回一个审批 id。使用该 id 来 -关联后续系统事件（`Exec finished` / `Exec denied`）。如果在超时前没有任何决定到达， -该请求会被视为审批超时，并作为拒绝原因呈现。 +当需要审批时，exec 工具会立即返回一个审批 id。使用该 id 关联后续系统事件（`Exec finished` / `Exec denied`）。如果在超时前没有收到决定，请求会被视为审批超时，并作为拒绝原因呈现。 ### 后续投递行为 -在已批准的异步 exec 完成后，OpenClaw 会向同一会话发送一个后续 `agent` 轮次。 +批准后的异步 exec 完成后，OpenClaw 会向同一会话发送一个后续的 `agent` 轮次。 -- 如果存在有效的外部投递目标（可投递渠道加目标 `to`），则后续投递使用该渠道。 -- 在仅 webchat 或内部会话流程中，如果没有外部目标，则后续投递保持仅会话（`deliver: false`）。 -- 如果调用方显式请求严格的外部投递，但没有可解析的外部渠道，则请求会以 `INVALID_REQUEST` 失败。 -- 如果启用了 `bestEffortDeliver` 且无法解析任何外部渠道，则投递会降级为仅会话，而不是失败。 +- 如果存在有效的外部投递目标（可投递渠道加目标 `to`），后续投递会使用该渠道。 +- 在仅 webchat 或无外部目标的内部会话流中，后续投递会保持为仅会话（`deliver: false`）。 +- 如果调用方显式请求严格外部投递，但没有可解析的外部渠道，请求会以 `INVALID_REQUEST` 失败。 +- 如果启用了 `bestEffortDeliver` 且无法解析出外部渠道，则投递会降级为仅会话，而不是失败。 -确认对话框会包含： +确认对话框包含： - command + args - cwd - agent id -- 已解析的可执行路径 +- 已解析的可执行文件路径 - host + 策略元数据 操作： - **Allow once** → 立即运行 -- **Always allow** → 添加到 allowlist + 运行 +- **Always allow** → 添加到允许列表 + 运行 - **Deny** → 阻止 ## 将审批转发到聊天渠道 -你可以将 exec 审批提示转发到任意聊天渠道（包括插件渠道），并使用 `/approve` 进行批准。 -这会使用常规出站投递流水线。 +你可以将 exec 审批提示转发到任意聊天渠道（包括渠道插件），并使用 `/approve` 进行审批。这会使用正常的出站投递流水线。 配置： __OC_I18N_900006__ 在聊天中回复： __OC_I18N_900007__ -`/approve` 命令同时处理 exec 审批和插件审批。如果 ID 不匹配任何待处理 exec 审批，它会自动改为检查插件审批。 +`/approve` 命令同时处理 exec 审批和插件审批。如果该 ID 未匹配任何待处理 exec 审批，它会自动改为检查插件审批。 ### 插件审批转发 -插件审批转发与 exec 审批使用相同的投递流水线，但在 `approvals.plugin` 下拥有独立的 -配置。启用或禁用其中一个不会影响另一个。 +插件审批转发使用与 exec 审批相同的投递流水线，但它有独立配置，位于 `approvals.plugin`。启用或禁用其中一个不会影响另一个。 __OC_I18N_900008__ -配置形状与 `approvals.exec` 完全相同：`enabled`、`mode`、`agentFilter`、 -`sessionFilter` 和 `targets` 的工作方式一致。 +配置结构与 `approvals.exec` 完全相同：`enabled`、`mode`、`agentFilter`、 +`sessionFilter` 和 `targets` 的工作方式都一样。 -支持共享交互式回复的渠道会为 exec 和 -插件审批渲染相同的审批按钮。不支持共享交互式 UI 的渠道则会回退为带 `/approve` +支持共享交互式回复的渠道，会为 exec 审批和插件审批渲染相同的审批按钮。不支持共享交互式 UI 的渠道，会回退为带有 `/approve` 说明的纯文本。 -### 任意渠道中的同聊天审批 +### 任意渠道中的同一聊天审批 -当某个 exec 或插件审批请求源自可投递聊天界面时，默认情况下，同一聊天 -现在可以通过 `/approve` 来批准它。这适用于 Slack、Matrix 和 -Microsoft Teams 等渠道，此外还适用于现有的 Web UI 和终端 UI 流程。 +当 exec 或插件审批请求来自可投递的聊天界面时，默认情况下，同一聊天现在就可以通过 `/approve` 对其进行审批。这适用于 Slack、Matrix 和 Microsoft Teams 等渠道，以及现有的 Web UI 和终端 UI 流程。 -这条共享文本命令路径使用该会话的常规渠道认证模型。如果 -源聊天已经可以发送命令并接收回复，那么审批请求就不再需要 -单独的原生投递 adapter 才能保持待处理状态。 +这种共享文本命令路径使用该会话的正常渠道认证模型。如果发起聊天本身已经可以发送命令并接收回复，那么审批请求就不再需要单独的原生投递适配器才能保持待处理状态。 -Discord 和 Telegram 也支持同聊天 `/approve`，但这些渠道即使在原生审批投递被禁用时， -仍会使用其已解析的审批人列表进行授权。 +Discord 和 Telegram 也支持在同一聊天中使用 `/approve`，但即使禁用了原生审批投递，这些渠道在授权时仍会使用其已解析的 approver 列表。 对于 Telegram 和其他直接调用 Gateway 网关的原生审批客户端， -这种回退有意被限定在“找不到审批”失败的情况。真实的 -exec 审批拒绝/错误不会静默重试为插件审批。 +这种回退被有意限制在“未找到审批”类失败上。真正的 exec 审批拒绝 / 错误不会被静默重试为插件审批。 ### 原生审批投递 -有些渠道还可以充当原生审批客户端。原生客户端会在共享同聊天 `/approve` -流程之上，增加审批人私信、源聊天扇出以及渠道特定的交互式审批 UX。 +某些渠道还可以充当原生审批客户端。原生客户端会在共享的同一聊天 `/approve` +流程之上，增加 approver 私信、原始聊天扇出以及渠道特定的交互式审批 UX。 -当存在原生审批卡片/按钮时，该原生 UI 就是主要的 -面向智能体路径。除非工具结果表明聊天审批不可用或 -手动审批是唯一剩余路径，否则智能体不应再额外回显一条重复的纯聊天 -`/approve` 命令。 +当原生审批卡片 / 按钮可用时，该原生 UI 是面向智能体的主要路径。 +除非工具结果表明聊天审批不可用，或手动审批是唯一剩余路径，否则智能体不应再额外回显重复的纯聊天 `/approve` 命令。 通用模型： -- 主机 exec 策略仍然决定是否需要 exec 审批 +- 主机 exec 策略仍决定是否需要 exec 审批 - `approvals.exec` 控制是否将审批提示转发到其他聊天目标 - `channels..execApprovals` 控制该渠道是否充当原生审批客户端 -在以下全部条件为真时，原生审批客户端会自动启用以私信为优先的投递： +当以下条件全部满足时，原生审批客户端会自动启用“优先私信”投递： - 该渠道支持原生审批投递 -- 可通过显式 `execApprovals.approvers` 或该 - 渠道文档化的回退来源解析出审批人 +- 可以从显式 `execApprovals.approvers` 或该渠道文档记录的回退来源中解析出 approver - `channels..execApprovals.enabled` 未设置或为 `"auto"` -将 `enabled: false` 设为显式禁用某个原生审批客户端。将 `enabled: true` 设为在审批人可解析时强制 -启用。公开的源聊天投递仍通过 +将 `enabled: false` 设为显式禁用某个原生审批客户端。将 `enabled: true` 设为在 approver 可解析时强制启用它。公开的原始聊天投递仍通过 `channels..execApprovals.target` 显式控制。 -常见问题：[为什么聊天审批会有两套 exec 审批配置？](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals) +常见问题：[为什么聊天审批会有两个 exec 审批配置？](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals) - Discord：`channels.discord.execApprovals.*` - Slack：`channels.slack.execApprovals.*` - Telegram：`channels.telegram.execApprovals.*` -这些原生审批客户端会在共享同聊天 `/approve` 流程和共享审批按钮之上，增加私信路由和可选的渠道扇出。 +这些原生审批客户端在共享的同一聊天 `/approve` 流程和共享审批按钮之上，增加了私信路由和可选的渠道扇出。 共享行为： -- Slack、Matrix、Microsoft Teams 以及类似的可投递聊天，会对同聊天 `/approve` 使用正常的渠道认证模型 -- 当某个原生审批客户端自动启用时，默认的原生投递目标是审批人私信 -- 对于 Discord 和 Telegram，只有已解析的审批人可以执行批准或拒绝 -- Discord 审批人可以是显式配置的（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断 -- Telegram 审批人可以是显式配置的（`execApprovals.approvers`），也可以从现有所有者配置（`allowFrom`，以及在支持时的私信 `defaultTo`）推断 -- Slack 审批人可以是显式配置的（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断 -- Slack 原生按钮会保留审批 id 类型，因此 `plugin:` id 可以解析插件审批， - 而无需第二层 Slack 本地回退 -- Matrix 原生私信/渠道路由和表情快捷方式同时处理 exec 和插件审批； +- Slack、Matrix、Microsoft Teams 以及类似的可投递聊天，针对同一聊天中的 `/approve` 使用正常的渠道认证模型 +- 当原生审批客户端自动启用时，默认原生投递目标是 approver 私信 +- 对于 Discord 和 Telegram，只有已解析的 approver 才能批准或拒绝 +- Discord approver 可以是显式指定的（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断 +- Telegram approver 可以是显式指定的（`execApprovals.approvers`），也可以从现有 owner 配置推断（`allowFrom`，以及在支持时的私信 `defaultTo`） +- Slack approver 可以是显式指定的（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断 +- Slack 原生按钮会保留审批 id 类型，因此 `plugin:` id 可以解析到插件审批 + 而不需要第二层 Slack 本地回退逻辑 +- Matrix 原生私信 / 渠道路由和反应快捷方式同时处理 exec 审批和插件审批； 插件授权仍来自 `channels.matrix.dm.allowFrom` -- 请求者本身不需要是审批人 -- 当源聊天本身已支持命令和回复时，源聊天可以直接通过 `/approve` 批准 -- 原生 Discord 审批按钮按审批 id 类型路由：`plugin:` id 会 - 直接进入插件审批，其余所有情况都进入 exec 审批 -- 原生 Telegram 审批按钮与 `/approve` 使用相同的有界 exec 到插件回退 -- 当原生 `target` 启用源聊天投递时，审批提示会包含命令文本 -- 待处理 exec 审批默认在 30 分钟后过期 -- 如果没有操作员 UI 或已配置审批客户端可以接受请求，则提示会回退到 `askFallback` +- 请求者本身不需要是 approver +- 当原始聊天已支持命令和回复时，原始聊天可以直接使用 `/approve` 进行审批 +- 原生 Discord 审批按钮会按审批 id 类型路由：`plugin:` id 会直接进入插件审批，其余全部进入 exec 审批 +- 原生 Telegram 审批按钮遵循与 `/approve` 相同的、受限的 exec 到插件回退逻辑 +- 当原生 `target` 启用原始聊天投递时，审批提示会包含命令文本 +- 待处理 exec 审批默认会在 30 分钟后过期 +- 如果没有操作员 UI 或已配置的审批客户端可以接受该请求，提示会回退到 `askFallback` -Telegram 默认投递到审批人私信（`target: "dm"`）。如果你 -希望审批提示也出现在发起的 Telegram 聊天/话题中，可切换为 `channel` 或 `both`。对于 Telegram forum 话题，OpenClaw 会为审批提示和审批后的后续消息保留该话题。 +Telegram 默认发送到 approver 私信（`target: "dm"`）。如果你希望审批提示也出现在原始 Telegram 聊天 / 话题中，可以切换为 `channel` 或 `both`。对于 Telegram 论坛话题，OpenClaw 会为审批提示和审批后的后续消息保留该话题。 -请参见： +参见： - [Discord](/channels/discord) - [Telegram](/channels/telegram) @@ -556,35 +501,33 @@ Telegram 默认投递到审批人私信（`target: "dm"`）。如果你 __OC_I18N_900009__ 安全说明： -- Unix socket 模式为 `0600`，token 存储在 `exec-approvals.json` 中。 -- 同 UID 对端检查。 -- Challenge/response（nonce + HMAC token + request hash）+ 短 TTL。 +- Unix socket 模式 `0600`，token 存储在 `exec-approvals.json` 中。 +- 同一 UID 对等方检查。 +- 质询 / 响应机制（nonce + HMAC token + 请求哈希）+ 短 TTL。 ## 系统事件 Exec 生命周期会以系统消息形式呈现： -- `Exec running`（仅当命令超过运行通知阈值时） +- `Exec running`（仅当命令超过运行提示阈值时） - `Exec finished` - `Exec denied` -这些事件会在节点上报事件后发布到智能体会话中。 -Gateway 主机 exec 审批在命令完成时也会发出相同的生命周期事件（以及可选地在运行超过阈值时发出）。 -受审批控制的 exec 会复用审批 id 作为这些消息中的 `runId`，以便轻松关联。 +这些消息会在节点报告事件后发布到智能体的会话中。 +Gateway host 的 exec 审批在命令完成时（以及可选地在运行超过阈值时）会发出相同的生命周期事件。 +受审批门控的 exec 会在这些消息中复用审批 id 作为 `runId`，以便轻松关联。 -## 被拒绝审批的行为 +## 审批被拒绝时的行为 -当异步 exec 审批被拒绝时，OpenClaw 会阻止智能体复用 -会话中此前相同命令的任何输出。拒绝原因会附带明确说明：当前没有任何命令输出可用，这样就能阻止 -智能体声称有新输出，或用先前成功运行留下的过期结果来重复已被拒绝的命令。 +当异步 exec 审批被拒绝时，OpenClaw 会阻止智能体复用该会话中此前同一命令任意一次运行的输出。拒绝原因会附带明确说明，指出没有可用的命令输出，从而阻止智能体声称存在新的输出，或使用先前成功运行留下的陈旧结果来重复被拒绝的命令。 ## 影响 -- **full** 权限很大；尽可能优先使用 allowlist。 -- **ask** 能让你保持在审批回路中，同时仍允许快速审批。 -- 按智能体的 allowlist 可防止一个智能体的审批泄露到其他智能体。 -- 审批仅适用于来自**已授权发送者**的主机 exec 请求。未授权发送者无法发出 `/exec`。 -- `/exec security=full` 是面向已授权操作员的会话级便利方式，并且按设计会跳过审批。若要硬性阻止主机 exec，请将 approvals security 设为 `deny`，或通过工具策略拒绝 `exec` 工具。 +- **full** 权限很强；尽可能优先使用 allowlist。 +- **ask** 让你保持在决策环路中，同时仍支持快速审批。 +- 按智能体划分的允许列表可防止某个智能体的审批泄漏到其他智能体。 +- 审批仅适用于来自**已授权发送者**的主机 exec 请求。未授权发送者不能发出 `/exec`。 +- `/exec security=full` 是面向已授权操作员的会话级便捷方式，并且按设计会跳过审批。若要硬性阻止主机 exec，请将 approvals security 设为 `deny`，或通过工具策略拒绝 `exec` 工具。 ## 相关内容 @@ -593,16 +536,16 @@ Gateway 主机 exec 审批在命令完成时也会发出相同的生命周期事 Shell 命令执行工具。 - 同样会跳过审批的 break-glass 路径。 + 也会跳过审批的紧急放行路径。 - + 沙箱模式和工作区访问。 - + 安全模型与加固。 - - 何时应使用哪一种控制方式。 + + 何时使用各类控制方式。 基于 Skill 的自动允许行为。 diff --git a/docs/zh-CN/tools/image-generation.md b/docs/zh-CN/tools/image-generation.md index 205fff1a1..07eaf0122 100644 --- a/docs/zh-CN/tools/image-generation.md +++ b/docs/zh-CN/tools/image-generation.md @@ -2,19 +2,19 @@ read_when: - 通过智能体生成图像 - 配置图像生成提供商和模型 - - 了解 `image_generate` 工具参数 + - 理解 `image_generate` 工具参数 summary: 使用已配置的提供商（OpenAI、OpenAI Codex OAuth、Google Gemini、fal、MiniMax、ComfyUI、Vydra、xAI）生成和编辑图像 title: 图像生成 x-i18n: - generated_at: "2026-04-23T21:49:31Z" + generated_at: "2026-04-23T22:14:42Z" model: gpt-5.4 provider: openai - source_hash: efba2038e097843053a33f2afe3e98d22a83d79fefc84872c2c7c47dbe888dc0 + source_hash: 77b104fb5e7d1a512d77493218276b9000c03a05b7579719ac9d182603d6b03e source_path: tools/image-generation.md workflow: 15 --- -`image_generate` 工具允许智能体使用你已配置的提供商创建和编辑图像。生成的图像会作为媒体附件自动包含在智能体的回复中。 +`image_generate` 工具让智能体能够使用你已配置的提供商创建和编辑图像。生成的图像会作为媒体附件自动附加到智能体的回复中。 只有在至少有一个图像生成提供商可用时，此工具才会显示。如果你在智能体的工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel`、设置提供商 API 密钥，或使用 OpenAI Codex OAuth 登录。 @@ -37,11 +37,14 @@ x-i18n: } ``` -Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。如果没有可用的 `OPENAI_API_KEY`，OpenClaw 会解析现有的 `openai-codex` OAuth 配置文件，并通过 Codex Responses 后端发送图像请求。 +Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了 +`openai-codex` OAuth 配置文件时，OpenClaw 会通过该 OAuth 配置文件路由图像请求，而不是先尝试 `OPENAI_API_KEY`。 +显式的自定义 `models.providers.openai` 图像配置（例如 API 密钥或 +自定义 / Azure 基础 URL）会切换回直接使用 OpenAI Images API 路由。 -3. 向智能体发出请求：_“生成一张友好机器人吉祥物的图像。”_ +3. 向智能体提问：_“生成一张友好的机器人吉祥物图像。”_ -智能体会自动调用 `image_generate`。无需工具允许列表——当提供商可用时，它默认启用。 +智能体会自动调用 `image_generate`。无需允许列表配置——当提供商可用时，它默认启用。 ## 支持的提供商 @@ -51,7 +54,7 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。如果没有可 | Google | `gemini-3.1-flash-image-preview` | 是 | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | | fal | `fal-ai/flux/dev` | 是 | `FAL_KEY` | | MiniMax | `image-01` | 是（主体参考） | `MINIMAX_API_KEY` 或 MiniMax OAuth (`minimax-portal`) | -| ComfyUI | `workflow` | 是（1 张图像，由工作流配置） | 云端使用 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` | +| ComfyUI | `workflow` | 是（1 张图像，按工作流配置） | 云端使用 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` | | Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` | | xAI | `grok-imagine-image` | 是（最多 5 张图像） | `XAI_API_KEY` | @@ -63,22 +66,22 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。如果没有可 ## 工具参数 -| 参数 | 类型 | 说明 | +| 参数 | 类型 | 描述 | | ------------- | -------- | ------------------------------------------------------------------------------------- | -| `prompt` | string | 图像生成提示词（`action: "generate"` 时必需） | -| `action` | string | `"generate"`（默认）或 `"list"`，用于查看提供商 | -| `model` | string | 提供商/模型覆盖，例如 `openai/gpt-image-2` | -| `image` | string | 编辑模式下的单张参考图像路径或 URL | -| `images` | string[] | 编辑模式下的多张参考图像（最多 5 张） | +| `prompt` | string | 图像生成提示词（`action: "generate"` 时必填） | +| `action` | string | `"generate"`（默认）或 `"list"`，用于检查提供商 | +| `model` | string | 提供商 / 模型覆盖，例如 `openai/gpt-image-2` | +| `image` | string | 用于编辑模式的单张参考图像路径或 URL | +| `images` | string[] | 用于编辑模式的多张参考图像（最多 5 张） | | `size` | string | 尺寸提示：`1024x1024`、`1536x1024`、`1024x1536`、`2048x2048`、`3840x2160` | | `aspectRatio` | string | 宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` | | `resolution` | string | 分辨率提示：`1K`、`2K` 或 `4K` | | `count` | number | 要生成的图像数量（1–4） | | `filename` | string | 输出文件名提示 | -并非所有提供商都支持所有参数。当某个回退提供商支持接近的几何选项而非你精确请求的选项时，OpenClaw 会在提交前重新映射为最接近的受支持尺寸、宽高比或分辨率。真正不支持的覆盖项仍会在工具结果中报告。 +并非所有提供商都支持所有参数。当回退提供商支持接近的几何选项而非精确请求值时，OpenClaw 会在提交前重新映射到最接近的受支持尺寸、宽高比或分辨率。真正不受支持的覆盖项仍会在工具结果中报告。 -工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重新映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值会反映实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。 +工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重新映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值会反映实际发送的内容，而 `details.normalization` 会记录从请求值到实际应用值的转换。 ## 配置 @@ -101,36 +104,51 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。如果没有可 生成图像时，OpenClaw 会按以下顺序尝试提供商： -1. 工具调用中的 **`model` 参数**（如果智能体指定了该参数） +1. 工具调用中的 **`model` 参数**（如果智能体指定了） 2. 配置中的 **`imageGenerationModel.primary`** 3. 按顺序使用 **`imageGenerationModel.fallbacks`** -4. **自动检测** —— 仅使用具备认证支持的提供商默认值： - - 当前默认提供商优先 - - 其余已注册图像生成提供商，按 provider-id 顺序 +4. **自动检测**——仅使用由认证支持的提供商默认值： + - 先使用当前默认提供商 + - 然后按提供商 ID 顺序使用其余已注册的图像生成提供商 -如果某个提供商失败（认证错误、速率限制等），会自动尝试下一个候选项。如果全部失败，错误信息会包含每次尝试的详细信息。 +如果某个提供商失败（认证错误、速率限制等），系统会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详细信息。 注意： -- 自动检测具备认证感知能力。只有当 OpenClaw 实际能够对某个提供商进行认证时，该提供商默认值才会进入候选列表。 -- 自动检测默认启用。如果你希望图像生成仅使用显式的 `model`、`primary` 和 `fallbacks` 条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。 -- 使用 `action: "list"` 可检查当前已注册的提供商、它们的默认模型以及认证环境变量提示。 +- 自动检测具有认证感知能力。只有当 OpenClaw 实际能够为某个提供商完成认证时， + 该提供商默认值才会进入候选列表。 +- 自动检测默认启用。如果你希望图像生成仅使用显式配置的 `model`、`primary` 和 `fallbacks` + 条目，请设置 + `agents.defaults.mediaGenerationAutoProviderFallback: false`。 +- 使用 `action: "list"` 可检查当前已注册的提供商、 + 它们的默认模型以及认证环境变量提示。 ### 图像编辑 OpenAI、Google、fal、MiniMax、ComfyUI 和 xAI 支持编辑参考图像。传入参考图像路径或 URL： ``` -"生成这张照片的水彩版本" + image: "/path/to/photo.jpg" +"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg" ``` OpenAI、Google 和 xAI 通过 `images` 参数最多支持 5 张参考图像。fal、MiniMax 和 ComfyUI 支持 1 张。 ### OpenAI `gpt-image-2` -OpenAI 图像生成默认使用 `openai/gpt-image-2`。可用时会使用 `OPENAI_API_KEY`。如果未配置 API 密钥，OpenClaw 会复用与 Codex 订阅聊天模型相同的 `openai-codex` OAuth 配置文件，并通过 Codex Responses 后端发送图像请求。较旧的 `openai/gpt-image-1` 模型仍可显式选择，但新的 OpenAI 图像生成和图像编辑请求应使用 `gpt-image-2`。 +OpenAI 图像生成默认使用 `openai/gpt-image-2`。如果配置了 +`openai-codex` OAuth 配置文件，OpenClaw 会复用 Codex 订阅聊天模型所使用的同一 OAuth +配置文件，并通过 Codex Responses 后端发送图像请求；对于该请求，它不会静默回退到 +`OPENAI_API_KEY`。若要强制使用直接的 OpenAI Images API 路由， +请显式配置 `models.providers.openai`，包括 API 密钥、自定义基础 URL +或 Azure 端点。较旧的 +`openai/gpt-image-1` 模型仍可显式选择，但新的 OpenAI +图像生成与图像编辑请求应使用 `gpt-image-2`。 -`gpt-image-2` 同时支持文生图生成和通过同一个 `image_generate` 工具进行参考图像编辑。OpenClaw 会将 `prompt`、`count`、`size` 和参考图像转发给 OpenAI。OpenAI 不会直接接收 `aspectRatio` 或 `resolution`；在可能的情况下，OpenClaw 会将它们映射为受支持的 `size`，否则工具会将它们报告为被忽略的覆盖项。 +`gpt-image-2` 通过同一个 `image_generate` 工具同时支持文生图生成和参考图像 +编辑。OpenClaw 会将 `prompt`、 +`count`、`size` 和参考图像转发给 OpenAI。OpenAI 不会直接接收 +`aspectRatio` 或 `resolution`；在可能的情况下，OpenClaw 会将它们映射为受支持的 +`size`，否则工具会将其报告为被忽略的覆盖项。 生成一张 4K 横向图像： @@ -156,9 +174,10 @@ OpenAI 图像生成默认使用 `openai/gpt-image-2`。可用时会使用 `OPENA /tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024 ``` -如果你想通过 Azure OpenAI 部署而不是 `api.openai.com` 路由 OpenAI 图像生成，请参阅 OpenAI 提供商文档中的 [Azure OpenAI endpoints](/zh-CN/providers/openai#azure-openai-endpoints)。 +若要通过 Azure OpenAI 部署而不是 +`api.openai.com` 路由 OpenAI 图像生成，请参阅 OpenAI 提供商文档中的 [Azure OpenAI endpoints](/zh-CN/providers/openai#azure-openai-endpoints)。 -MiniMax 图像生成可通过两种内置 MiniMax 认证路径使用： +MiniMax 图像生成同时支持两种内置 MiniMax 认证路径： - `minimax/image-01` 用于 API 密钥配置 - `minimax-portal/image-01` 用于 OAuth 配置 @@ -167,29 +186,32 @@ MiniMax 图像生成可通过两种内置 MiniMax 认证路径使用： | 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI | | --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- | -| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（输出由工作流定义） | 是（1 张） | 是（最多 4 张） | -| 编辑/参考 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由工作流配置） | 否 | 是（最多 5 张图像） | +| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（工作流定义的输出） | 是（1 张） | 是（最多 4 张） | +| 编辑 / 参考 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，按工作流配置） | 否 | 是（最多 5 张图像） | | 尺寸控制 | 是（最高 4K） | 是 | 是 | 否 | 否 | 否 | 否 | | 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 | 是 | | 分辨率（1K/2K/4K） | 否 | 是 | 是 | 否 | 否 | 否 | 是（1K/2K） | ### xAI `grok-imagine-image` -内置 xAI 提供商在仅提示词请求时使用 `/v1/images/generations`，而在存在 `image` 或 `images` 时使用 `/v1/images/edits`。 +内置 xAI 提供商在纯提示词请求时使用 `/v1/images/generations`， +当存在 `image` 或 `images` 时使用 `/v1/images/edits`。 - 模型：`xai/grok-imagine-image`、`xai/grok-imagine-image-pro` - 数量：最多 4 张 -- 参考：一个 `image` 或最多五个 `images` +- 参考图：单个 `image` 或最多五个 `images` - 宽高比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`2:3`、`3:2` - 分辨率：`1K`、`2K` -- 输出：作为由 OpenClaw 管理的图像附件返回 +- 输出：以 OpenClaw 管理的图像附件形式返回 -在这些控制项出现在共享的跨提供商 `image_generate` 契约中之前，OpenClaw 有意不公开 xAI 原生的 `quality`、`mask`、`user` 或其他仅原生支持的宽高比选项。 +在这些控制项进入共享的跨提供商 `image_generate` 契约之前， +OpenClaw 有意不暴露 xAI 原生的 `quality`、`mask`、`user` 或 +额外的仅原生可用宽高比。 ## 相关内容 - [Tools Overview](/zh-CN/tools) — 所有可用的智能体工具 -- [fal](/zh-CN/providers/fal) — fal 图像和视频提供商设置 +- [fal](/zh-CN/providers/fal) — fal 图像与视频提供商设置 - [ComfyUI](/zh-CN/providers/comfy) — 本地 ComfyUI 和 Comfy Cloud 工作流设置 - [Google (Gemini)](/zh-CN/providers/google) — Gemini 图像提供商设置 - [MiniMax](/zh-CN/providers/minimax) — MiniMax 图像提供商设置 @@ -197,4 +219,4 @@ MiniMax 图像生成可通过两种内置 MiniMax 认证路径使用： - [Vydra](/zh-CN/providers/vydra) — Vydra 图像、视频和语音设置 - [xAI](/zh-CN/providers/xai) — Grok 图像、视频、搜索、代码执行和 TTS 设置 - [Configuration Reference](/zh-CN/gateway/configuration-reference#agent-defaults) — `imageGenerationModel` 配置 -- [Models](/zh-CN/concepts/models) — 模型配置和故障转移 +- [Models](/zh-CN/concepts/models) — 模型配置与故障切换