diff --git a/docs/zh-CN/concepts/mantis.md b/docs/zh-CN/concepts/mantis.md index 800752972..85ab1c2ba 100644 --- a/docs/zh-CN/concepts/mantis.md +++ b/docs/zh-CN/concepts/mantis.md @@ -1,65 +1,65 @@ --- read_when: - - 为 OpenClaw 缺陷构建或运行实时可视化 QA + - 为 OpenClaw 缺陷构建或运行实时视觉 QA - 为拉取请求添加前后验证 - 添加 Discord、Slack、WhatsApp 或其他实时传输场景 - 调试需要截图、浏览器自动化或 VNC 访问的 QA 运行 -summary: Mantis 是一个可视化端到端验证系统，用于在实时传输协议上复现 OpenClaw 缺陷，捕获修改前后的证据，并将工件附加到 PR。 +summary: Mantis 是用于在实时传输协议上复现 OpenClaw 缺陷、捕获前后对比证据，并将工件附加到 PR 的可视化端到端验证系统。 title: Mantis x-i18n: - generated_at: "2026-05-03T17:21:31Z" + generated_at: "2026-05-03T17:26:38Z" model: gpt-5.5 provider: openai - source_hash: a93378f980358d2687be13ade2db9d0eff8e64d92ca0ad0ee8f38deeb4786a6f + source_hash: 8918ce7fe1c90184a0bcfc8427f2cd90cb969e3c93027dff08506108bf19c205 source_path: concepts/mantis.md workflow: 16 --- -Mantis 是 OpenClaw 端到端验证系统，用于需要真实运行时、真实传输协议和可见证据的 bug。它会在已知有问题的 ref 上运行一个场景、捕获证据，再在候选 ref 上运行同一场景，并将对比结果发布为 artifact，维护者可从 PR 或本地命令检查。 +Mantis 是 OpenClaw 的端到端验证系统，适用于需要真实运行时、真实传输协议和可见证据的 bug。它会针对已知不良 ref 运行一个场景，捕获证据，再针对候选 ref 运行同一场景，并将比较结果发布为制品，维护者可以从 PR 或本地命令中检查。 -Mantis 从 Discord 开始，因为 Discord 提供了一条高价值的首条线路：真实 bot 认证、真实公会频道、reaction、thread、原生命令，以及人类可用来视觉确认传输协议所展示内容的浏览器 UI。 +Mantis 从 Discord 开始，因为 Discord 为我们提供了一个高价值的首条验证通道：真实 bot 凭证、真实公会渠道、回应、线程、原生命令，以及一个让人类可以直观确认传输协议显示内容的浏览器 UI。 ## 目标 -- 用用户看到的相同传输协议形态，复现来自 GitHub issue 或 PR 的 bug。 -- 在应用修复前，在 baseline ref 上捕获 **before** artifact。 -- 在应用修复后，在 candidate ref 上捕获 **after** artifact。 -- 尽可能使用确定性的 oracle，例如 Discord REST reaction 读取或频道 transcript 检查。 +- 使用用户看到的同类传输协议形态，复现 GitHub issue 或 PR 中的 bug。 +- 在应用修复之前，在 baseline ref 上捕获一个 **before** 制品。 +- 在应用修复之后，在候选 ref 上捕获一个 **after** 制品。 +- 尽可能使用确定性的判定器，例如 Discord REST 回应读取或渠道转录检查。 - 当 bug 有可见 UI 表面时捕获截图。 - 从智能体控制的 CLI 在本地运行，并从 GitHub 远程运行。 -- 当登录、浏览器自动化或提供商认证卡住时，保留足够的机器状态以便 VNC 救援。 -- 当运行被阻塞、需要手动 VNC 帮助或完成时，向 operator Discord 频道发布简洁 Status。 +- 当登录、浏览器自动化或提供商凭证卡住时，保留足够的机器状态以便 VNC 救援。 +- 当运行受阻、需要手动 VNC 帮助或完成时，向操作员 Discord 渠道发布简洁状态。 ## 非目标 -- Mantis 不是单元测试的替代品。修复被理解后，Mantis 运行通常应转化为更小的回归测试。 -- Mantis 不是常规快速 CI gate。它更慢、使用实时凭证，并且仅用于实时环境很重要的 bug。 -- Mantis 不应要求人类参与常规操作。手动 VNC 是救援路径，而不是正常路径。 -- Mantis 不会在 artifact、日志、截图、Markdown 报告或 PR 评论中存储原始密钥。 +- Mantis 不是单元测试的替代品。在理解修复后，Mantis 运行通常应转化为更小的回归测试。 +- Mantis 不是常规快速 CI 门禁。它更慢、使用实时凭据，并且仅保留给实时环境确实重要的 bug。 +- Mantis 的正常运行不应需要人类介入。手动 VNC 是救援路径，不是理想路径。 +- Mantis 不会在制品、日志、截图、Markdown 报告或 PR 评论中存储原始密钥。 ## 所有权 -Mantis 位于 OpenClaw QA 栈中。 +Mantis 位于 OpenClaw QA 技术栈中。 - OpenClaw 拥有场景运行时、传输协议适配器、证据 schema，以及 `pnpm openclaw qa mantis` 下的本地 CLI。 -- QA Lab 拥有实时传输协议 harness 组件、浏览器捕获 helper 和 artifact 写入器。 -- 当需要远程 VM 时，Crabbox 拥有已预热的 Linux 机器。 -- GitHub Actions 拥有远程 workflow 入口点和 artifact 保留策略。 -- ClawSweeper 拥有 GitHub 评论路由：解析维护者命令、分发 workflow，以及发布最终 PR 评论。 -- 当场景需要智能体式设置、调试或卡住状态报告时，OpenClaw 智能体通过 Codex 驱动 Mantis。 +- QA Lab 拥有实时传输协议 harness 组件、浏览器捕获帮助工具和制品写入器。 +- 需要远程 VM 时，Crabbox 拥有预热后的 Linux 机器。 +- GitHub Actions 拥有远程 workflow 入口点和制品保留。 +- ClawSweeper 拥有 GitHub 评论路由：解析维护者命令、调度 workflow，以及发布最终 PR 评论。 +- 当场景需要智能体式设置、调试或卡住状态报告时，OpenClaw 智能体会通过 Codex 驱动 Mantis。 -这个边界将传输协议知识保留在 OpenClaw 中，将机器调度保留在 Crabbox 中，并将维护者 workflow 粘合逻辑保留在 ClawSweeper 中。 +此边界将传输协议知识保留在 OpenClaw 中，将机器调度保留在 Crabbox 中，并将维护者 workflow 胶水逻辑保留在 ClawSweeper 中。 ## 命令形态 -第一个本地命令会验证 Discord bot、公会、频道、消息发送、reaction 发送和 artifact 路径： +第一个本地命令会验证 Discord bot、公会、渠道、消息发送、回应发送和制品路径： ```bash pnpm openclaw qa mantis discord-smoke \ --output-dir .artifacts/qa-e2e/mantis/discord-smoke ``` -后续的 before 和 after runner 应接受这种形态： +后续的 before 和 after 运行器应接受这种形态： ```bash pnpm openclaw qa mantis run \ @@ -70,12 +70,12 @@ pnpm openclaw qa mantis run \ --output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions ``` -GitHub smoke workflow 是 `Mantis Discord Smoke`。第一个真实场景的 before 和 after GitHub workflow 是 `Mantis Discord Status Reactions`。它接受： +GitHub 冒烟 workflow 是 `Mantis Discord Smoke`。第一个真实场景的 before 和 after GitHub workflow 是 `Mantis Discord Status Reactions`。它接受： - `baseline_ref`：预期会复现 queued-only 行为的 ref。 - `candidate_ref`：预期会显示 `queued -> thinking -> done` 的 ref。 -它会 checkout workflow harness ref，构建独立的 baseline 和 candidate worktree，针对每个 worktree 运行 `discord-status-reactions-tool-only`，并将 `baseline/`、`candidate/`、`comparison.json` 和 `mantis-report.md` 上传为 Actions artifact。 +它会检出 workflow harness ref，构建单独的 baseline 和 candidate worktree，针对每个 worktree 运行 `discord-status-reactions-tool-only`，并将 `baseline/`、`candidate/`、`comparison.json` 和 `mantis-report.md` 作为 Actions 制品上传。 ClawSweeper 命令示例： @@ -84,42 +84,42 @@ ClawSweeper 命令示例： @clawsweeper verify e2e discord ``` -第一个命令是明确且聚焦场景的。第二个命令后续可以根据 label、变更文件和 ClawSweeper review 发现，将 PR 或 issue 映射到推荐的 Mantis 场景。 +第一个命令明确且聚焦于场景。第二个命令之后可以根据标签、已变更文件和 ClawSweeper 审查发现，将 PR 或 issue 映射到推荐的 Mantis 场景。 ## 运行生命周期 -1. 获取凭证。 +1. 获取凭据。 2. 分配或复用 VM。 3. 为 baseline ref 准备干净的 checkout。 -4. 安装依赖，并且只构建场景所需内容。 +4. 安装依赖，并仅构建场景所需内容。 5. 使用隔离的状态目录启动子 OpenClaw Gateway 网关。 6. 配置实时传输协议、提供商、模型和浏览器 profile。 7. 运行场景并捕获 baseline 证据。 8. 停止 Gateway 网关并保留日志。 -9. 在同一 VM 中准备 candidate ref。 +9. 在同一 VM 中准备候选 ref。 10. 运行同一场景并捕获 candidate 证据。 -11. 比较 oracle 结果和视觉证据。 -12. 写入 Markdown、JSON、日志、截图和可选 trace artifact。 -13. 上传 GitHub Actions artifact。 -14. 发布简洁的 PR 或 Discord Status 消息。 +11. 比较判定器结果和视觉证据。 +12. 写入 Markdown、JSON、日志、截图和可选 trace 制品。 +13. 上传 GitHub Actions 制品。 +14. 发布简洁的 PR 或 Discord 状态消息。 -场景应能以两种不同方式失败： +场景应能够以两种不同方式失败： -- **Bug reproduced**：baseline 以预期方式失败。 -- **Harness failure**：环境设置、凭证、Discord API、浏览器或提供商在 bug oracle 有意义之前失败。 +- **已复现 bug**：baseline 以预期方式失败。 +- **Harness 失败**：环境设置、凭据、Discord API、浏览器或提供商在 bug 判定器有意义之前失败。 最终报告必须区分这些情况，以免维护者将不稳定环境误认为产品行为。 ## Discord MVP -第一个场景应面向公会频道中的 Discord Status reaction，其中 source reply delivery mode 是 `message_tool_only`。 +第一个场景应针对公会渠道中的 Discord 状态回应，其中源回复投递模式为 `message_tool_only`。 -为什么它是一个好的 Mantis 种子： +它是一个适合 Mantis 起步的原因： -- 它在 Discord 中以触发消息上的 reaction 可见。 -- 它通过 Discord message reaction 状态拥有强 REST oracle。 -- 它会覆盖真实 OpenClaw Gateway 网关、Discord bot 认证、消息分发、source reply delivery mode、Status reaction 状态和模型轮次生命周期。 -- 它足够窄，能让第一个实现保持扎实。 +- 它在 Discord 中表现为触发消息上的回应，是可见的。 +- 它通过 Discord 消息回应状态提供强 REST 判定器。 +- 它会覆盖真实的 OpenClaw Gateway 网关、Discord bot 凭证、消息分发、源回复投递模式、状态回应状态和模型轮次生命周期。 +- 它足够窄，能让第一版实现保持诚实。 预期场景形态： @@ -152,9 +152,9 @@ evidence: screenshotMessageRow: true ``` -Baseline 证据应显示 queued 确认 reaction，但在 tool-only mode 下没有生命周期转换。Candidate 证据应显示当 `messages.statusReactions.enabled` 显式为 true 时，生命周期 Status reaction 会运行。 +Baseline 证据应显示 queued 确认回应，但在 tool-only 模式下没有生命周期转换。Candidate 证据应显示当 `messages.statusReactions.enabled` 被显式设为 true 时，生命周期状态回应会运行。 -可执行的第一片是 opt-in Discord live QA 场景： +第一个可执行切片是选择启用的 Discord 实时 QA 场景： ```bash pnpm openclaw qa discord \ @@ -166,24 +166,23 @@ pnpm openclaw qa discord \ --output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate ``` -它会用 always-on guild handling、`visibleReplies: -"message_tool"`、`ackReaction: "👀"` 和显式 Status reaction 配置 SUT。oracle 会轮询真实的 Discord 触发消息，并期望观察到的序列为 `👀 -> 🤔 -> 👍`。Artifact 包括 `discord-qa-reaction-timelines.json`、`discord-status-reactions-tool-only-timeline.html` 和 `discord-status-reactions-tool-only-timeline.png`。 +它会将 SUT 配置为始终开启公会处理、`visibleReplies: "message_tool"`、`ackReaction: "👀"` 和显式状态回应。判定器会轮询真实的 Discord 触发消息，并期望观察到的序列为 `👀 -> 🤔 -> 👍`。制品包括 `discord-qa-reaction-timelines.json`、`discord-status-reactions-tool-only-timeline.html` 和 `discord-status-reactions-tool-only-timeline.png`。 ## 现有 QA 组件 -Mantis 应基于现有私有 QA 栈构建，而不是从零开始： +Mantis 应基于现有私有 QA 技术栈构建，而不是从零开始： -- `pnpm openclaw qa discord` 已经使用 driver 和 SUT bot 运行实时 Discord lane。 -- 实时传输协议 runner 已经在 `.artifacts/qa-e2e/` 下写入报告和 observed-message artifact。 -- Convex credential lease 已经提供对共享实时传输协议凭证的独占访问。 -- 浏览器控制服务已经支持截图、snapshot、headless managed profile 和远程 CDP profile。 -- QA Lab 已经有用于传输协议形态测试的 debugger UI 和 bus。 +- `pnpm openclaw qa discord` 已经会使用 driver 和 SUT bot 运行一个实时 Discord 通道。 +- 实时传输协议运行器已经会在 `.artifacts/qa-e2e/` 下写入报告和 observed-message 制品。 +- Convex 凭据租约已经为共享实时传输协议凭据提供独占访问。 +- 浏览器控制服务已经支持截图、快照、无头托管 profile 和远程 CDP profile。 +- QA Lab 已经拥有用于传输协议形态测试的调试器 UI 和总线。 -第一个 Mantis 实现可以是在这些组件之上的轻量 before/after runner，再加一个视觉证据层。 +第一版 Mantis 实现可以是这些组件之上的一个薄 before/after 运行器，再加一个视觉证据层。 ## 证据模型 -每次运行都会写入稳定的 artifact 目录： +每次运行都会写入稳定的制品目录： ```text .artifacts/qa-e2e/mantis// @@ -203,65 +202,65 @@ Mantis 应基于现有私有 QA 栈构建，而不是从零开始： run.log ``` -`mantis-summary.json` 应是机器可读的事实来源。Markdown 报告用于 PR 评论和人工 review。 +`mantis-summary.json` 应是机器可读的事实来源。Markdown 报告用于 PR 评论和人工审查。 -summary 必须包含： +摘要必须包括： -- 测试过的 ref 和 SHA +- 已测试的 refs 和 SHA - 传输协议和场景 id -- 机器提供商以及机器 id 或 lease id -- 不含密钥值的凭证来源 +- 机器提供商和机器 id 或租约 id +- 不含密钥值的凭据来源 - baseline 结果 - candidate 结果 - bug 是否在 baseline 上复现 - candidate 是否修复了它 -- artifact 路径 -- 已清理敏感信息的设置或清理问题 +- 制品路径 +- 已清理的设置或清理问题 -截图是证据，不是密钥。它们仍然需要遵守脱敏规范：私有频道名称、用户名或消息内容可能会出现。对于公开 PR，在脱敏方案更完善之前，优先使用 GitHub Actions artifact 链接，而不是内联图片。 +截图是证据，不是密钥。它们仍然需要遵守脱敏纪律：私有渠道名称、用户名或消息内容可能会出现。对于公开 PR，在脱敏方案更强之前，优先使用 GitHub Actions 制品链接，而不是内联图片。 ## 浏览器和 VNC -浏览器 lane 有两种模式： +浏览器通道有两种模式： -- **Headless automation**：CI 默认模式。Chrome 启用 CDP 运行，Playwright 或 OpenClaw 浏览器控制捕获截图。 -- **VNC rescue**：当登录、MFA、Discord 反自动化或视觉调试需要人类时，在同一 VM 上启用。 +- **无头自动化**：CI 的默认模式。Chrome 会启用 CDP 运行，Playwright 或 OpenClaw 浏览器控制会捕获截图。 +- **VNC 救援**：当登录、MFA、Discord 反自动化或视觉调试需要人类介入时，在同一 VM 上启用。 -Discord observer 浏览器 profile 应足够持久，避免每次运行都登录，但要与个人浏览器状态隔离。profile 属于 Mantis 机器池，不属于开发者笔记本电脑。 +Discord 观察者浏览器 profile 应具备足够持久性，避免每次运行都登录，但要与个人浏览器状态隔离。profile 属于 Mantis 机器池，而不是开发者笔记本电脑。 -当 Mantis 卡住时，它会发布一条 Discord Status 消息，包含： +当 Mantis 卡住时，它会发布一条 Discord 状态消息，其中包含： -- run id -- scenario id +- 运行 id +- 场景 id - 机器提供商 -- artifact 目录 -- 可用时的 VNC 或 noVNC 连接说明 -- 简短阻塞说明 +- 制品目录 +- 如可用，VNC 或 noVNC 连接说明 +- 简短阻塞原因文本 -第一个私有部署可以将这些消息发布到现有 operator 频道，后续再迁移到专用 Mantis 频道。 +第一个私有部署可以将这些消息发布到现有操作员渠道，之后再迁移到专用 Mantis 渠道。 ## 机器 -Mantis 的第一个远程实现应优先通过 Crabbox 使用 AWS。Crabbox 为我们提供已预热机器、lease tracking、hydration、日志、结果和清理。如果 AWS 容量太慢或不可用，则在相同机器接口后添加 Hetzner 提供商。 +第一版远程实现中，Mantis 应优先通过 Crabbox 使用 AWS。Crabbox 为我们提供预热机器、租约跟踪、hydration、日志、结果和清理。如果 AWS 容量太慢或不可用，请在同一机器接口后添加 Hetzner 提供商。 最低 VM 要求： -- Linux，并安装支持桌面的 Chrome 或 Chromium +- Linux，并安装可用于桌面的 Chrome 或 Chromium - 用于浏览器自动化的 CDP 访问 - 用于救援的 VNC 或 noVNC - Node 22 和 pnpm - OpenClaw checkout 和依赖缓存 - 使用 Playwright 时的 Playwright Chromium 浏览器缓存 -- 足够运行一个 OpenClaw Gateway 网关、一个浏览器和一次模型运行的 CPU 与内存 -- 到 Discord、GitHub、模型提供商和凭证 broker 的出站访问 +- 足够的 CPU 和内存，可运行一个 OpenClaw Gateway 网关、一个浏览器和一次模型运行 +- 可出站访问 Discord、GitHub、模型提供商和凭据 broker -VM 不应在预期凭证或浏览器 profile 存储之外保留长期存在的原始密钥。 +VM 不应在预期凭据或浏览器 profile 存储之外保留长期存在的原始密钥。 ## 密钥 -远程运行的密钥位于 GitHub organization 或 repository secrets 中，本地运行的密钥位于由本地 operator 控制的 secret 文件中。 +远程运行的密钥位于 GitHub 组织或仓库密钥中，本地运行的密钥位于由本地操作员控制的密钥文件中。 -推荐的 secret 名称： +推荐密钥名称： - `OPENCLAW_QA_DISCORD_MANTIS_BOT_TOKEN` - `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN` @@ -269,32 +268,32 @@ VM 不应在预期凭证或浏览器 profile 存储之外保留长期存在的 - `OPENCLAW_QA_DISCORD_GUILD_ID` - `OPENCLAW_QA_DISCORD_CHANNEL_ID` - `OPENCLAW_QA_DISCORD_NOTIFY_CHANNEL_ID` -- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1`，用于公开 GitHub artifact 上传 +- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` 用于公开 GitHub 制品上传 - `OPENCLAW_QA_CONVEX_SITE_URL` - `OPENCLAW_QA_CONVEX_SECRET_CI` -长期来看，Convex 凭证池应继续作为实时传输协议凭证的常规来源。GitHub secrets 用于 bootstrap broker 和 fallback lane。 +长期来看，Convex 凭据池应继续作为实时传输协议凭据的常规来源。GitHub 密钥用于引导 broker 和 fallback 通道。 -Mantis runner 绝不能打印： +Mantis 运行器绝不能打印： - Discord bot token - 提供商 API key - 浏览器 cookie -- auth profile 内容 +- 凭证 profile 内容 - VNC 密码 -- 原始凭证 payload +- 原始凭据 payload -公开 artifact 上传还应对 Discord 目标元数据进行脱敏，例如 bot、公会、频道和消息 id。GitHub smoke workflow 因此启用了 `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1`。 +公开制品上传还应脱敏 Discord 目标元数据，例如 bot、公会、渠道和消息 id。GitHub 冒烟 workflow 因此启用了 `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1`。 -如果 token 被意外粘贴到 issue、PR、chat 或日志中，请在新 secret 存储后轮换它。 +如果 token 被意外粘贴到 issue、PR、聊天或日志中，请在新密钥存储完成后轮换它。 -## GitHub Artifact 和 PR 评论 +## GitHub 制品和 PR 评论 -Mantis 工作流应将完整证据包上传为短期有效的 Actions 工件。当工作流为错误报告或修复 PR 运行时，还应将已脱敏的 PNG 截图发布到 `qa-artifacts` 分支，并在该错误报告或修复 PR 上更新或插入一条评论，内嵌修复前/后的截图。不要只把主要证明发布在通用 QA 自动化 PR 上。原始日志、观测到的消息和其他体积较大的证据保留在 Actions 工件中。 +Mantis 工作流应将完整证据包作为短期 Actions artifact 上传。当工作流为错误报告或修复 PR 运行时，还应将已脱敏的 PNG 截图发布到 `qa-artifacts` 分支，并在该错误或修复 PR 上更新或插入一条评论，内联显示前后对比截图。不要只把主要证明发布在通用 QA 自动化 PR 上。原始日志、观察到的消息以及其他体积较大的证据保留在 Actions artifact 中。 -生产工作流应使用 Mantis GitHub App 发布这些评论，而不是使用 `github-actions[bot]`。将应用 ID 和私钥存储为 `MANTIS_GITHUB_APP_ID` 和 `MANTIS_GITHUB_APP_PRIVATE_KEY` GitHub Actions 机密。工作流应在已有 Mantis 拥有的评论时更新它；如果只存在较旧的 `github-actions[bot]` 评论，则应创建一条新的 Mantis 拥有的评论，而不是重写旧版机器人评论。 +生产工作流应使用 Mantis GitHub App 发布这些评论，而不是使用 `github-actions[bot]`。将 app id 和私钥存储为 `MANTIS_GITHUB_APP_ID` 和 `MANTIS_GITHUB_APP_PRIVATE_KEY` GitHub Actions secrets。如果 app 被重命名，请将 `MANTIS_GITHUB_APP_BOT_LOGIN` 设置为 GitHub Actions 变量，值为新的 bot login，例如 `openclaw-mantis[bot]`。当已有 Mantis 拥有的评论时，工作流应更新该评论；如果只存在较旧的 `github-actions[bot]` 评论，则应创建一条新的 Mantis 拥有的评论，而不是重写旧版 bot 评论。 -PR 评论应简短且可视化： +PR 评论应简短且直观： ```md Mantis Discord Status Reactions QA @@ -314,60 +313,60 @@ candidate showed the expected queued -> thinking -> done sequence. | | | ``` -当运行因 harness 失败而失败时，评论必须说明这一点，而不是暗示候选修复失败。 +当运行因为 harness 失败而失败时，评论必须说明这一点，而不是暗示候选修复失败。 ## 私有部署说明 -私有部署可能已经有一个 Mantis Discord 应用。当该应用具备正确的机器人权限并且可以安全轮换时，复用该应用，而不是创建另一个应用。 +私有部署可能已经有一个 Mantis Discord 应用。当该应用具备正确的 bot 权限并且可以安全轮换时，请复用该应用，而不是再创建一个 app。 -通过机密或部署配置设置初始操作员通知渠道。它可以先指向现有维护者或运维渠道，等专用 Mantis 渠道存在后再迁移过去。 +通过 secrets 或部署配置设置初始操作员通知渠道。它可以先指向现有的维护者或运维渠道，等专用 Mantis 渠道存在后再迁移过去。 -不要在本文档中放入服务器 ID、渠道 ID、机器人令牌、浏览器 Cookie 或 VNC 密码。将它们存储在 GitHub 机密、凭证代理或操作员的本地机密存储中。 +不要在本文档中放入 guild id、channel id、bot token、浏览器 cookie 或 VNC 密码。将它们存储在 GitHub secrets、凭证代理或操作员的本地密钥存储中。 ## 添加场景 Mantis 场景应声明： -- ID 和标题 +- id 和标题 - 传输协议 -- 必需凭证 +- 所需凭证 - 基线 ref 策略 - 候选 ref 策略 - OpenClaw 配置补丁 - 设置步骤 - 刺激输入 -- 预期基线判定器 -- 预期候选判定器 +- 预期基线 oracle +- 预期候选 oracle - 视觉捕获目标 - 超时预算 - 清理步骤 -场景应优先使用小型、类型化的判定器： +场景应优先使用小型、带类型的 oracle： -- 用于反应错误的 Discord 反应状态 +- 用于 reaction 错误的 Discord reaction 状态 - 用于线程错误的 Discord 消息引用 -- 用于 Slack 错误的 Slack 线程 `ts` 和反应 API 状态 -- 用于电子邮件错误的电子邮件消息 ID 和标头 +- 用于 Slack 错误的 Slack thread ts 和 reaction API 状态 +- 用于电子邮件错误的电子邮件 message id 和 header - 当 UI 是唯一可靠可观测对象时使用浏览器截图 -视觉检查应作为附加手段。如果平台 API 能证明错误，就使用 API 作为通过/失败判定器，并保留截图以增强人工信心。 +视觉检查应是增量补充。如果平台 API 可以证明错误，就使用 API 作为通过/失败 oracle，并保留截图用于增强人工信心。 ## 提供商扩展 -在 Discord 之后，同一个运行器可以添加： +在 Discord 之后，同一个 runner 可以添加： -- Slack：反应、线程、应用提及、模态窗口、文件上传。 -- 电子邮件：在连接器不足时，使用 `gog` 进行 Gmail 认证和消息线程处理。 -- WhatsApp：二维码登录、重新识别、消息投递、媒体、反应。 -- Telegram：群组提及门控、命令、可用时的反应。 -- Matrix：加密房间、线程或回复关系、重启恢复。 +- Slack：reaction、thread、app mention、modal、文件上传。 +- 电子邮件：在 connectors 不够用的地方，使用 `gog` 进行 Gmail 认证和消息线程处理。 +- WhatsApp：二维码登录、重新识别、消息投递、媒体、reaction。 +- Telegram：群组提及门控、命令、可用时的 reaction。 +- Matrix：加密房间、thread 或 reply relation、重启恢复。 -每种传输协议都应有一个低成本冒烟场景，以及一个或多个错误类别场景。昂贵的视觉场景应保持为可选启用。 +每种传输协议都应有一个低成本 smoke 场景，以及一个或多个错误类别场景。昂贵的视觉场景应保持为可选启用。 ## 未决问题 -- 复用现有 Mantis 机器人时，哪个 Discord 机器人应作为驱动方，哪个应作为被测系统？ -- 观察者浏览器登录在第一阶段应使用真人 Discord 账户、测试账户，还是仅使用机器人可读的 REST 证据？ -- GitHub 应为 PR 保留 Mantis 工件多长时间？ -- ClawSweeper 应在何时自动推荐 Mantis，而不是等待维护者命令？ -- 针对公开 PR，截图在上传前是否应脱敏或裁剪？ +- 当复用现有 Mantis bot 时，哪个 Discord bot 应作为 driver，哪个应作为 SUT？ +- 第一阶段中，observer 浏览器登录应使用真人 Discord 账号、测试账号，还是只使用 bot 可读取的 REST 证据？ +- GitHub 应为 PR 保留 Mantis artifact 多久？ +- ClawSweeper 什么时候应自动推荐 Mantis，而不是等待维护者命令？ +- 对于公开 PR，截图在上传前是否应脱敏或裁剪？ diff --git a/docs/zh-CN/gateway/config-tools.md b/docs/zh-CN/gateway/config-tools.md index 850a8b83e..16530f44c 100644 --- a/docs/zh-CN/gateway/config-tools.md +++ b/docs/zh-CN/gateway/config-tools.md @@ -4,51 +4,51 @@ read_when: - 注册自定义提供商或覆盖基础 URL - 设置 OpenAI 兼容的自托管端点 sidebarTitle: Tools and custom providers -summary: 工具配置（策略、实验性开关、提供商支持的工具）和自定义提供商/基础 URL 设置 +summary: 工具配置（策略、实验性开关、由提供商支持的工具）和自定义提供商/基础 URL 设置 title: 配置 — 工具和自定义提供商 x-i18n: - generated_at: "2026-05-01T02:52:46Z" + generated_at: "2026-05-03T17:26:32Z" model: gpt-5.5 provider: openai - source_hash: 97e6bd8c762f6f7a9985b99ec016dde22c8ea8adc925778b11c2ae5103b887a8 + source_hash: 75a39342f40e9c329a7c61855e805ec43532cbdb89fbe801acc26830fd63b4da source_path: gateway/config-tools.md workflow: 16 --- -`tools.*` 配置键以及自定义提供商 / base-URL 设置。对于智能体、渠道和其他顶层配置键，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。 +`tools.*` 配置键以及自定义提供商 / 基础 URL 设置。对于智能体、渠道和其他顶层配置键，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。 ## 工具 ### 工具配置档 -`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础允许列表： +`tools.profile` 会先设置基础允许列表，然后再应用 `tools.allow`/`tools.deny`： -本地新手引导会在未设置时默认将新的本地配置设为 `tools.profile: "coding"`（会保留现有的显式配置档）。 +本地新手引导会在未设置时将新的本地配置默认为 `tools.profile: "coding"`（会保留已有的显式配置档）。 -| 配置档 | 包含 | +| 配置档 | 包含内容 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `minimal` | 仅 `session_status` | -| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | +| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | | `full` | 无限制（与未设置相同） | ### 工具组 | 组 | 工具 | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution`（`bash` 可作为 `exec` 的别名） | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | -| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | +| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | +| `group:fs` | `read`、`write`、`edit`、`apply_patch` | +| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | +| `group:memory` | `memory_search`、`memory_get` | +| `group:web` | `web_search`、`x_search`、`web_fetch` | +| `group:ui` | `browser`、`canvas` | +| `group:automation` | `cron`、`gateway` | | `group:messaging` | `message` | | `group:nodes` | `nodes` | | `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | | `group:openclaw` | 所有内置工具（不包括提供商插件） | ### `tools.allow` / `tools.deny` @@ -61,9 +61,17 @@ x-i18n: } ``` +`write` 和 `apply_patch` 是独立的工具 ID。`allow: ["write"]` 也会为兼容模型启用 `apply_patch`，但 `deny: ["write"]` 不会拒绝 `apply_patch`。若要阻止所有文件变更，请拒绝 `group:fs`，或显式列出每个会变更文件的工具： + +```json5 +{ + tools: { deny: ["write", "edit", "apply_patch"] }, +} +``` + ### `tools.byProvider` -进一步限制特定提供商或模型的工具。顺序：基础配置档 → 提供商配置档 → 允许/拒绝。 +进一步限制特定提供商或模型可用的工具。顺序：基础配置档 → 提供商配置档 → 允许/拒绝。 ```json5 { @@ -79,7 +87,7 @@ x-i18n: ### `tools.elevated` -控制沙箱外的提权 exec 访问： +控制沙箱外的提升权限 `exec` 访问： ```json5 { @@ -95,9 +103,9 @@ x-i18n: } ``` -- 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 -- `/elevated on|off|ask|full` 按会话存储状态；内联指令仅应用于单条消息。 -- 提权 `exec` 会绕过沙箱隔离，并使用配置的逃逸路径（默认为 `gateway`；当 exec 目标是 `node` 时为 `node`）。 +- 每个智能体的覆盖项（`agents.list[].tools.elevated`）只能进一步收紧限制。 +- `/elevated on|off|ask|full` 按会话存储状态；内联指令只应用于单条消息。 +- 提升权限的 `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认为 `gateway`，或在 exec 目标为 `node` 时使用 `node`）。 ### `tools.exec` @@ -121,7 +129,7 @@ x-i18n: ### `tools.loopDetection` -工具循环安全检查**默认禁用**。设置 `enabled: true` 可启用检测。设置可以在 `tools.loopDetection` 中全局定义，并可在 `agents.list[].tools.loopDetection` 为每个智能体覆盖。 +工具循环安全检查**默认禁用**。设置 `enabled: true` 可启用检测。设置可以在 `tools.loopDetection` 中全局定义，并在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 ```json5 { @@ -143,13 +151,13 @@ x-i18n: ``` - 为循环分析保留的最大工具调用历史记录。 + 为循环分析保留的最大工具调用历史。 重复无进展模式的警告阈值。 - 用于阻止严重循环的更高重复阈值。 + 用于阻止关键循环的更高重复阈值。 任何无进展运行的硬停止阈值。 @@ -158,10 +166,10 @@ x-i18n: 对重复的相同工具/相同参数调用发出警告。 - 对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/进行阻止。 + 对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。 - 对交替出现的无进展成对模式发出警告/进行阻止。 + 对交替出现的无进展成对模式发出警告/阻止。 @@ -238,30 +246,30 @@ x-i18n: ``` - + **提供商条目**（`type: "provider"` 或省略）： - `provider`：API 提供商 ID（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） - `model`：模型 ID 覆盖 - - `profile` / `preferredProfile`：`auth-profiles.json` 配置文件选择 + - `profile` / `preferredProfile`：`auth-profiles.json` 配置档案选择 **CLI 条目**（`type: "cli"`）： - `command`：要运行的可执行文件 - - `args`：模板化参数（支持 `{{MediaPath}}`、`{{Prompt}}`、`{{MaxChars}}` 等；`openclaw doctor --fix` 会把已弃用的 `{input}` 占位符迁移到 `{{MediaPath}}`） + - `args`：模板化参数（支持 `{{MediaPath}}`、`{{Prompt}}`、`{{MaxChars}}` 等；`openclaw doctor --fix` 会将已弃用的 `{input}` 占位符迁移到 `{{MediaPath}}`） **通用字段：** - `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai`/`anthropic`/`minimax` → 图像，`google` → 图像+音频+视频，`groq` → 音频。 - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：逐条目覆盖。 - - 当智能体调用显式 `image` 工具时，`tools.media.image.timeoutSeconds` 和匹配的图像模型 `timeoutSeconds` 条目也会生效。 + - 当智能体调用显式的 `image` 工具时，`tools.media.image.timeoutSeconds` 和匹配的图像模型 `timeoutSeconds` 条目也会生效。 - 失败会回退到下一个条目。 - 提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 + 提供商身份验证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 **异步完成字段：** - - `asyncCompletion.directSend`：当为 `true` 时，支持直接完成递送的已完成异步媒体任务会先尝试直接渠道递送。默认值：`false`（请求方会话唤醒/模型递送路径）。目前这适用于异步 `video_generate`；即使启用此项，异步 `music_generate` 完成仍通过请求方会话中转。 + - `asyncCompletion.directSend`：当为 `true` 时，支持直接完成投递的已完成异步媒体任务会先尝试直接渠道投递。默认值：`false`（请求方会话唤醒/模型投递路径）。目前这适用于异步 `video_generate`；即使启用此项，异步 `music_generate` 完成仍通过请求方会话中介。 @@ -281,7 +289,7 @@ x-i18n: ### `tools.sessions` -控制哪些会话可被会话工具（`sessions_list`、`sessions_history`、`sessions_send`）作为目标。 +控制哪些会话可以被会话工具（`sessions_list`、`sessions_history`、`sessions_send`）作为目标。 默认值：`tree`（当前会话 + 由它生成的会话，例如子智能体）。 @@ -297,12 +305,12 @@ x-i18n: ``` - + - `self`：仅当前会话键。 - - `tree`：当前会话 + 由当前会话生成的会话（子智能体）。 - - `agent`：属于当前智能体 ID 的任何会话（如果你在同一智能体 ID 下按发送者运行会话，可能包含其他用户）。 - - `all`：任何会话。跨智能体目标定位仍需要 `tools.agentToAgent`。 - - 沙箱夹制：当当前会话处于沙箱隔离且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 + - `tree`：当前会话 + 当前会话生成的会话（子智能体）。 + - `agent`：属于当前智能体 ID 的任何会话（如果你在同一智能体 ID 下按发送者运行会话，可能包括其他用户）。 + - `all`：任何会话。跨智能体定向仍需要 `tools.agentToAgent`。 + - 沙箱限制：当当前会话是沙箱隔离的，并且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 @@ -330,10 +338,10 @@ x-i18n: - 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝它们。 - - 文件会具象化到子工作区的 `.openclaw/attachments//`，并带有 `.manifest.json`。 - - 附件内容会从转录持久化中自动遮蔽。 - - Base64 输入会通过严格的字母表/填充检查和预解码大小防护进行验证。 - - 目录权限为 `0700`，文件权限为 `0600`。 + - 文件会物化到子工作区的 `.openclaw/attachments//`，并带有 `.manifest.json`。 + - 附件内容会自动从转录持久化中删改。 + - Base64 输入会通过严格的字母表/填充检查和解码前大小保护进行验证。 + - 文件权限为：目录 `0700`，文件 `0600`。 - 清理遵循 `cleanup` 策略：`delete` 始终移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。 @@ -343,7 +351,7 @@ x-i18n: ### `tools.experimental` -实验性内置工具标志。默认关闭，除非适用 strict-agentic GPT-5 自动启用规则。 +实验性内置工具标志。默认关闭，除非适用严格智能体 GPT-5 自动启用规则。 ```json5 { @@ -355,9 +363,9 @@ x-i18n: } ``` -- `planTool`：启用结构化的 `update_plan` 工具，用于跟踪非平凡的多步骤工作。 -- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或每个智能体覆盖项）针对 OpenAI 或 OpenAI Codex GPT-5 系列运行设置为 `"strict-agentic"`。设置为 `true` 可在该范围之外强制启用该工具，或设置为 `false` 可即使在 strict-agentic GPT-5 运行中也保持关闭。 -- 启用后，系统提示还会添加使用指南，使模型仅在实质性工作中使用它，并最多保持一个步骤为 `in_progress`。 +- `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 +- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或单个智能体覆盖项）针对 OpenAI 或 OpenAI Codex GPT-5 系列运行设置为 `"strict-agentic"`。设置为 `true` 可在该范围之外强制开启该工具，或设置为 `false` 可即使在严格智能体 GPT-5 运行中也保持关闭。 +- 启用后，系统提示也会添加使用指导，让模型只在实质性工作中使用它，并最多保持一个步骤为 `in_progress`。 ### `agents.defaults.subagents` @@ -378,9 +386,9 @@ x-i18n: ``` - `model`：生成的子智能体的默认模型。如果省略，子智能体会继承调用方的模型。 -- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 目标智能体 ID 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时时间（秒）。`0` 表示无超时。 -- 每个子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 的目标智能体 ID 默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时时间（秒）。`0` 表示不超时。 +- 单个子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- @@ -416,19 +424,19 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ ``` - - - 对于自定义凭证需求，使用 `authHeader: true` + `headers`。 - - 使用 `OPENCLAW_AGENT_DIR`（或 `PI_CODING_AGENT_DIR`，旧版环境变量别名）覆盖智能体配置根目录。 + + - 对自定义认证需求使用 `authHeader: true` + `headers`。 + - 使用 `OPENCLAW_AGENT_DIR`（或 `PI_CODING_AGENT_DIR`，一个旧版环境变量别名）覆盖智能体配置根目录。 - 匹配提供商 ID 的合并优先级： - 非空的智能体 `models.json` `baseUrl` 值优先。 - - 非空的智能体 `apiKey` 值仅在该提供商未由当前配置/凭证配置文件上下文中的 SecretRef 管理时优先。 - - 由 SecretRef 管理的提供商 `apiKey` 值会从来源标记（环境变量引用为 `ENV_VAR_NAME`，文件/exec 引用为 `secretref-managed`）刷新，而不是持久化已解析的密钥。 - - 由 SecretRef 管理的提供商标头值会从来源标记（环境变量引用为 `secretref-env:ENV_VAR_NAME`，文件/exec 引用为 `secretref-managed`）刷新。 - - 空的或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - - 匹配模型的 `contextWindow`/`maxTokens` 使用显式配置值和隐式目录值之间较高的值。 - - 匹配模型的 `contextTokens` 会在存在显式运行时上限时保留它；使用它可在不更改原生模型元数据的情况下限制有效上下文。 + - 非空的智能体 `apiKey` 值仅在当前配置/认证配置文件上下文中该提供商未由 SecretRef 管理时优先。 + - SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用为 `ENV_VAR_NAME`，文件/执行引用为 `secretref-managed`），而不是持久化已解析的密钥。 + - SecretRef 管理的提供商标头值会从源标记刷新（环境变量引用为 `secretref-env:ENV_VAR_NAME`，文件/执行引用为 `secretref-managed`）。 + - 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 + - 匹配模型的 `contextWindow`/`maxTokens` 使用显式配置值和隐式目录值中的较高者。 + - 匹配模型的 `contextTokens` 会在存在显式运行时上限时保留它；用它来限制有效上下文，而不改变原生模型元数据。 - 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 - - 标记持久化以来源为权威：标记会从活跃来源配置快照（解析前）写入，而不是从已解析的运行时密钥值写入。 + - 标记持久化以来源为准：标记会从活动源配置快照（解析前）写入，而不是从已解析的运行时密钥值写入。 @@ -436,64 +444,64 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ ### 提供商字段详情 - + - `models.mode`：提供商目录行为（`merge` 或 `replace`）。 - `models.providers`：按提供商 ID 键控的自定义提供商映射。 - - 安全编辑：使用 `openclaw config set models.providers. '' --strict-json --merge` 或 `openclaw config set models.providers..models '' --strict-json --merge` 进行增量更新。除非你传入 `--replace`，否则 `config set` 会拒绝破坏性替换。 + - 安全编辑：使用 `openclaw config set models.providers. '' --strict-json --merge` 或 `openclaw config set models.providers..models '' --strict-json --merge` 进行增量更新。除非传入 `--replace`，否则 `config set` 会拒绝破坏性替换。 - - - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。对于 MLX、vLLM、SGLang 以及大多数 OpenAI 兼容本地服务器等自托管 `/v1/chat/completions` 后端，使用 `openai-completions`。带有 `baseUrl` 但没有 `api` 的自定义提供商默认使用 `openai-completions`；仅在后端支持 `/v1/responses` 时设置 `openai-responses`。 + + - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。对于自托管的 `/v1/chat/completions` 后端，例如 MLX、vLLM、SGLang 和大多数 OpenAI 兼容本地服务器，请使用 `openai-completions`。带有 `baseUrl` 但没有 `api` 的自定义提供商默认使用 `openai-completions`；仅当后端支持 `/v1/responses` 时才设置 `openai-responses`。 - `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef/环境变量替换）。 - - `models.providers.*.auth`：凭证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 + - `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 - `models.providers.*.contextWindow`：当模型条目未设置 `contextWindow` 时，此提供商下模型的默认原生上下文窗口。 - `models.providers.*.contextTokens`：当模型条目未设置 `contextTokens` 时，此提供商下模型的默认有效运行时上下文上限。 - `models.providers.*.maxTokens`：当模型条目未设置 `maxTokens` 时，此提供商下模型的默认输出 token 上限。 - `models.providers.*.timeoutSeconds`：可选的每提供商模型 HTTP 请求超时时间（秒），包括连接、标头、正文和总请求中止处理。 - - `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，将 `options.num_ctx` 注入请求（默认：`true`）。 - - `models.providers.*.authHeader`：需要时强制在 `Authorization` 标头中传输凭证。 + - `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，向请求注入 `options.num_ctx`（默认：`true`）。 + - `models.providers.*.authHeader`：需要时强制通过 `Authorization` 标头传输凭证。 - `models.providers.*.baseUrl`：上游 API 基础 URL。 - `models.providers.*.headers`：用于代理/租户路由的额外静态标头。 - + `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖项。 - `request.headers`：额外标头（与提供商默认值合并）。值接受 SecretRef。 - - `request.auth`：凭证策略覆盖。模式：`"provider-default"`（使用提供商内置凭证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`、可选 `prefix`）。 - - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。 - - `request.tls`：直接连接的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（均接受 SecretRef）、`serverName`、`insecureSkipVerify`。 - - `request.allowPrivateNetwork`：当为 `true` 时，如果 DNS 解析到私有、CGNAT 或类似范围，则允许通过提供商 HTTP fetch 防护访问 `baseUrl` 的 HTTPS（操作员为受信任的自托管 OpenAI 兼容端点选择加入）。除非明确设置为 `false`，否则 `localhost`、`127.0.0.1` 和 `[::1]` 等 loopback 模型提供商流 URL 会自动允许；LAN、tailnet 和私有 DNS 主机仍需要选择加入。WebSocket 对标头/TLS 使用同一个 `request`，但不使用该 fetch SSRF 门禁。默认值为 `false`。 + - `request.auth`：认证策略覆盖项。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（带 `token`）、`"header"`（带 `headerName`、`value`、可选 `prefix`）。 + - `request.proxy`：HTTP 代理覆盖项。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（带 `url`）。两种模式都接受可选的 `tls` 子对象。 + - `request.tls`：直接连接的 TLS 覆盖项。字段：`ca`、`cert`、`key`、`passphrase`（全部接受 SecretRef）、`serverName`、`insecureSkipVerify`。 + - `request.allowPrivateNetwork`：当为 `true` 时，如果 DNS 解析到私有、CGNAT 或类似范围，允许通过提供商 HTTP fetch 保护访问 `baseUrl` 的 HTTPS（操作员对可信自托管 OpenAI 兼容端点的选择加入）。local loopback 模型提供商流 URL，例如 `localhost`、`127.0.0.1` 和 `[::1]` 会自动允许，除非此项明确设置为 `false`；LAN、tailnet 和私有 DNS 主机仍需选择加入。WebSocket 使用相同的 `request` 来处理标头/TLS，但不使用该 fetch SSRF 门控。默认值为 `false`。 - + - `models.providers.*.models`：显式提供商模型目录条目。 - - `models.providers.*.models.*.input`：模型输入模态。仅文本模型使用 `["text"]`，原生图像/视觉模型使用 `["text", "image"]`。只有在所选模型标记为支持图像时，图像附件才会注入智能体轮次。 + - `models.providers.*.models.*.input`：模型输入模态。纯文本模型使用 `["text"]`，原生图像/视觉模型使用 `["text", "image"]`。只有当所选模型标记为支持图像时，图像附件才会注入智能体轮次。 - `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。这会覆盖该模型的提供商级 `contextWindow`。 - - `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。这会覆盖提供商级 `contextTokens`；当你希望有效上下文预算小于模型原生 `contextWindow` 时使用它；`openclaw models list` 会在两者不同时显示这两个值。 - - `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于带有非空非原生 `baseUrl`（主机不是 `api.openai.com`）的 `api: "openai-completions"`，OpenClaw 会在运行时强制将其设为 `false`。空的/省略的 `baseUrl` 保持默认 OpenAI 行为。 - - `models.providers.*.models.*.compat.requiresStringContent`：面向仅字符串 OpenAI 兼容聊天端点的可选兼容性提示。当为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组展平为普通字符串。 + - `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。这会覆盖提供商级 `contextTokens`；当你希望有效上下文预算小于模型原生 `contextWindow` 时使用它；`openclaw models list` 会在两个值不同时显示两者。 + - `models.providers.*.models.*.compat.supportsDeveloperRole`：可选的兼容性提示。对于 `api: "openai-completions"` 且非空的非原生 `baseUrl`（主机不是 `api.openai.com`），OpenClaw 会在运行时强制将其设为 `false`。空/省略的 `baseUrl` 保持默认 OpenAI 行为。 + - `models.providers.*.models.*.compat.requiresStringContent`：用于仅字符串 OpenAI 兼容聊天端点的可选兼容性提示。当为 `true` 时，OpenClaw 会在发送请求前，将纯文本 `messages[].content` 数组展平为普通字符串。 - - - `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根目录。 + + - `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根。 - `plugins.entries.amazon-bedrock.config.discovery.enabled`：开启/关闭隐式发现。 - `plugins.entries.amazon-bedrock.config.discovery.region`：用于发现的 AWS 区域。 - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用于定向发现的可选提供商 ID 过滤器。 - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新的轮询间隔。 - - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的回退上下文窗口。 - - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的回退最大输出 token 数。 + - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：发现模型的回退上下文窗口。 + - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：发现模型的回退最大输出 token 数。 -交互式自定义提供商新手引导会针对 GPT-4o、Claude、Gemini、Qwen-VL、LLaVA、Pixtral、InternVL、Mllama、MiniCPM-V 和 GLM-4V 等常见视觉模型 ID 推断图像输入，并跳过已知纯文本系列的额外问题。未知模型 ID 仍会提示是否支持图像。非交互式新手引导使用相同推断；传入 `--custom-image-input` 可强制图像能力元数据，或传入 `--custom-text-input` 可强制纯文本元数据。 +交互式自定义提供商新手引导会为常见视觉模型 ID 推断图像输入，例如 GPT-4o、Claude、Gemini、Qwen-VL、LLaVA、Pixtral、InternVL、Mllama、MiniCPM-V 和 GLM-4V，并对已知纯文本系列跳过额外问题。未知模型 ID 仍会提示确认图像支持。非交互式新手引导使用相同推断；传入 `--custom-image-input` 可强制使用支持图像的元数据，或传入 `--custom-text-input` 可强制使用纯文本元数据。 ### 提供商示例 - - 内置的 `cerebras` 提供商插件可以通过 `openclaw onboard --auth-choice cerebras-api-key` 配置此项。仅在覆盖默认值时使用显式提供商配置。 + + 内置的 `cerebras` 提供商插件可以通过 `openclaw onboard --auth-choice cerebras-api-key` 配置此项。仅在覆盖默认值时才使用显式提供商配置。 ```json5 { @@ -527,7 +535,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` - 对 Cerebras 使用 `cerebras/zai-glm-4.7`；对 Z.AI 直连使用 `zai/glm-4.7`。 + 对于 Cerebras 使用 `cerebras/zai-glm-4.7`；对于 Z.AI 直连使用 `zai/glm-4.7`。 @@ -543,13 +551,13 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` - Anthropic 兼容的内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 + 兼容 Anthropic 的内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 - - 参见 [本地模型](/zh-CN/gateway/local-models)。简而言之：在高性能硬件上通过 LM Studio Responses API 运行大型本地模型；保留合并的托管模型作为回退。 + + 参见[本地模型](/zh-CN/gateway/local-models)。简而言之：在性能足够的硬件上通过 LM Studio Responses API 运行大型本地模型；保留已合并的托管模型作为后备。 - + ```json5 { agents: { @@ -584,10 +592,10 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` - 设置 `MINIMAX_API_KEY`。快捷方式：`openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。模型目录默认仅包含 M2.7。在兼容 Anthropic 的流式传输路径上，除非你显式设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax 思考。`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 + 设置 `MINIMAX_API_KEY`。快捷方式：`openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。模型目录默认仅包含 M2.7。在兼容 Anthropic 的流式路径上，除非你显式自行设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax 思考。`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 - + ```json5 { env: { MOONSHOT_API_KEY: "sk-..." }, @@ -623,7 +631,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ 对于中国端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 - 原生 Moonshot 端点会在共享的 `openai-completions` 传输上声明流式用量兼容性，OpenClaw 会基于端点能力而不仅仅是内置提供商 ID 来启用它。 + 原生 Moonshot 端点会在共享的 `openai-completions` 传输上声明流式用量兼容性，而 OpenClaw 会根据端点能力启用该行为，而不是只依赖内置提供商 ID。 @@ -641,7 +649,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ 设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。对 Zen 目录使用 `opencode/...` 引用，对 Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 - + ```json5 { env: { SYNTHETIC_API_KEY: "sk-..." }, @@ -678,7 +686,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ 基础 URL 应省略 `/v1`（Anthropic 客户端会追加它）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 - + ```json5 { agents: { @@ -690,7 +698,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` - 设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 + 设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 - 通用端点：`https://api.z.ai/api/paas/v4` - 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` diff --git a/docs/zh-CN/tools/exec.md b/docs/zh-CN/tools/exec.md index fe81f3cbf..93e9281d7 100644 --- a/docs/zh-CN/tools/exec.md +++ b/docs/zh-CN/tools/exec.md @@ -1,21 +1,21 @@ --- read_when: - 使用或修改 exec 工具 - - 调试 stdin 或 TTY 行为 -summary: Exec 工具用法、stdin 模式和 TTY 支持 + - 调试标准输入或终端行为 +summary: 执行工具用法、stdin 模式和 TTY 支持 title: 执行工具 x-i18n: - generated_at: "2026-05-02T20:51:29Z" + generated_at: "2026-05-03T17:26:34Z" model: gpt-5.5 provider: openai - source_hash: 67d2847f70142b326f527a79ffddab1015b897e8ec4d7ce4557430e57fe0956a + source_hash: dbc8dda08abfd4d7b2e2cd5c7319a7eddf1575156bbfbc52df841908589c8c81 source_path: tools/exec.md workflow: 16 --- 在工作区中运行 shell 命令。支持通过 `process` 进行前台 + 后台执行。 -如果 `process` 被禁用，`exec` 会同步运行并忽略 `yieldMs`/`background`。 -后台会话按智能体限定作用域；`process` 只能看到同一智能体的会话。 +如果 `process` 被禁用，`exec` 会同步运行，并忽略 `yieldMs`/`background`。 +后台会话按智能体划分范围；`process` 只能看到同一智能体的会话。 ## 参数 @@ -32,7 +32,7 @@ x-i18n: -在此延迟（毫秒）后自动将命令转入后台。 +经过此延迟（毫秒）后自动将命令转入后台。 @@ -40,7 +40,7 @@ x-i18n: -覆盖此调用配置的 exec 超时时间。仅当命令应在没有 exec 进程超时的情况下运行时，才设置 `timeout: 0`。 +覆盖此次调用配置的 exec 超时时间。只有在命令应在没有 exec 进程超时限制的情况下运行时，才设置 `timeout: 0`。 @@ -48,7 +48,7 @@ x-i18n: -执行位置。`auto` 在沙箱运行时处于活动状态时解析为 `sandbox`，否则解析为 `gateway`。 +执行位置。`auto` 会在沙箱运行时处于活动状态时解析为 `sandbox`，否则解析为 `gateway`。 @@ -56,64 +56,64 @@ x-i18n: -`gateway` / `node` 执行的批准提示行为。 +`gateway` / `node` 执行的审批提示行为。 -当 `host=node` 时的节点 ID/名称。 +`host=node` 时的节点 ID/名称。 -请求提升模式 —— 逃逸沙箱并进入配置的主机路径。仅当提升解析为 `full` 时，才会强制使用 `security=full`。 +请求提升模式 — 逃逸沙箱并进入配置的主机路径。只有在 elevated 解析为 `full` 时，才会强制使用 `security=full`。 注意： -- `host` 默认值为 `auto`：当会话的沙箱运行时处于活动状态时使用沙箱，否则使用 Gateway 网关。 +- `host` 默认为 `auto`：会话的沙箱运行时处于活动状态时使用沙箱，否则使用 Gateway 网关。 - `host` 只接受 `auto`、`sandbox`、`gateway` 或 `node`。它不是主机名选择器；类似主机名的值会在命令运行前被拒绝。 -- `auto` 是默认路由策略，不是通配符。允许从 `auto` 逐次调用设置 `host=node`；仅当没有活动的沙箱运行时时，才允许逐次调用设置 `host=gateway`。 -- 即使没有额外配置，`host=auto` 仍然“直接可用”：没有沙箱时它解析为 `gateway`；存在实时沙箱时它会留在沙箱中。 -- `elevated` 会逃逸沙箱并进入配置的主机路径：默认是 `gateway`，或在 `tools.exec.host=node`（或会话默认值为 `host=node`）时为 `node`。仅当当前会话/提供商启用提升访问时才可用。 -- `gateway`/`node` 批准由 `~/.openclaw/exec-approvals.json` 控制。 +- `auto` 是默认路由策略，不是通配符。允许从 `auto` 进行单次调用的 `host=node`；只有在没有活动沙箱运行时时，才允许单次调用的 `host=gateway`。 +- 在没有额外配置的情况下，`host=auto` 仍然“直接可用”：没有沙箱意味着它解析为 `gateway`；实时沙箱意味着它留在沙箱中。 +- `elevated` 会逃逸沙箱并进入配置的主机路径：默认是 `gateway`，或者当 `tools.exec.host=node`（或会话默认值为 `host=node`）时是 `node`。它仅在当前会话/提供商启用提升访问时可用。 +- `gateway`/`node` 审批由 `~/.openclaw/exec-approvals.json` 控制。 - `node` 需要已配对的节点（配套应用或无头节点主机）。 -- 如果有多个节点可用，请设置 `exec.node` 或 `tools.exec.node` 来选择一个。 -- `exec host=node` 是节点的唯一 shell 执行路径；旧版 `nodes.run` 包装器已被移除。 -- `timeout` 适用于前台、后台、`yieldMs`、Gateway 网关、沙箱和节点 `system.run` 执行。如果省略，OpenClaw 会使用 `tools.exec.timeoutSec`；显式 `timeout: 0` 会禁用该调用的 exec 进程超时。 -- 在非 Windows 主机上，exec 会在已设置时使用 `SHELL`；如果 `SHELL` 是 `fish`，它会优先从 `PATH` 使用 `bash`（或 `sh`） +- 如果有多个节点可用，请设置 `exec.node` 或 `tools.exec.node` 来选择其中一个。 +- `exec host=node` 是节点唯一的 shell 执行路径；旧版 `nodes.run` 包装器已被移除。 +- `timeout` 适用于前台、后台、`yieldMs`、Gateway 网关、沙箱和节点 `system.run` 执行。如果省略，OpenClaw 使用 `tools.exec.timeoutSec`；显式 `timeout: 0` 会禁用此次调用的 exec 进程超时。 +- 在非 Windows 主机上，exec 会在设置了 `SHELL` 时使用它；如果 `SHELL` 是 `fish`，则会优先使用 `PATH` 中的 `bash`（或 `sh`） 以避免与 fish 不兼容的脚本，然后在两者都不存在时回退到 `SHELL`。 -- 在 Windows 主机上，exec 会优先发现 PowerShell 7（`pwsh`）（Program Files、ProgramW6432，然后是 PATH）， +- 在 Windows 主机上，exec 优先发现 PowerShell 7（`pwsh`）（Program Files、ProgramW6432，然后是 PATH）， 然后回退到 Windows PowerShell 5.1。 -- 主机执行（`gateway`/`node`）会拒绝 `env.PATH` 和加载器覆盖项（`LD_*`/`DYLD_*`），以 - 防止二进制劫持或注入代码。 -- OpenClaw 会在生成的命令环境中（包括 PTY 和沙箱执行）设置 `OPENCLAW_SHELL=exec`，以便 shell/profile 规则能检测 exec 工具上下文。 -- `openclaw channels login` 会被 `exec` 阻止，因为它是交互式渠道认证流程；请在 Gateway 网关主机上的终端中运行它，或在存在渠道原生登录工具时从聊天中使用该工具。 +- 主机执行（`gateway`/`node`）会拒绝 `env.PATH` 和加载器覆盖项（`LD_*`/`DYLD_*`）， + 以防止二进制劫持或注入代码。 +- OpenClaw 会在派生的命令环境中设置 `OPENCLAW_SHELL=exec`（包括 PTY 和沙箱执行），这样 shell/profile 规则可以检测 exec 工具上下文。 +- `openclaw channels login` 会被 `exec` 阻止，因为它是交互式渠道认证流程；请在 Gateway 网关主机的终端中运行它，或者在存在渠道原生登录工具时从聊天中使用该工具。 - 重要：沙箱隔离**默认关闭**。如果沙箱隔离关闭，隐式 `host=auto` - 会解析为 `gateway`。显式 `host=sandbox` 仍会以关闭方式失败，而不是静默地 - 在 Gateway 网关主机上运行。请启用沙箱隔离，或使用带批准的 `host=gateway`。 -- 脚本预检检查（用于常见 Python/Node shell 语法错误）只检查有效 `workdir` 边界内的文件。如果脚本路径解析到 `workdir` 之外，则会跳过该文件的预检。 -- 对于现在开始的长时间运行工作，启动一次即可，并在启用时依赖自动 - 完成唤醒，前提是命令有输出或失败。 - 使用 `process` 查看日志、Status、输入或干预；不要用 - sleep 循环、timeout 循环或重复轮询来模拟调度。 -- 对于应在稍后或按计划发生的工作，请使用 cron，而不是 - `exec` sleep/delay 模式。 + 会解析为 `gateway`。显式 `host=sandbox` 仍会失败关闭，而不是静默 + 在 Gateway 网关主机上运行。请启用沙箱隔离，或使用带审批的 `host=gateway`。 +- 脚本预检检查（针对常见 Python/Node shell 语法错误）只检查有效 `workdir` 边界内的文件。如果脚本路径解析到 `workdir` 之外，则会跳过该文件的预检。 +- 对于现在开始的长时间运行工作，请启动一次，并在启用自动 + 完成唤醒且命令有输出或失败时依赖它。 + 使用 `process` 查看日志、状态、输入或进行干预；不要用 sleep 循环、timeout 循环或重复轮询来模拟 + 调度。 +- 对于应稍后发生或按计划执行的工作，请使用 cron，而不是 + `exec` sleep/延迟模式。 ## 配置 -- `tools.exec.notifyOnExit`（默认值：true）：为 true 时，后台化的 exec 会话会在退出时排入系统事件并请求 Heartbeat。 -- `tools.exec.approvalRunningNoticeMs`（默认值：10000）：当受批准门控的 exec 运行时间超过此值时，发出一次“正在运行”通知（0 表示禁用）。 -- `tools.exec.timeoutSec`（默认值：1800）：每个命令的默认 exec 超时时间（秒）。逐次调用的 `timeout` 会覆盖它；逐次调用的 `timeout: 0` 会禁用 exec 进程超时。 +- `tools.exec.notifyOnExit`（默认值：true）：为 true 时，转入后台的 exec 会话会在退出时将系统事件入队并请求 Heartbeat。 +- `tools.exec.approvalRunningNoticeMs`（默认值：10000）：当受审批限制的 exec 运行时间超过此值时，发出一次“running”通知（0 表示禁用）。 +- `tools.exec.timeoutSec`（默认值：1800）：每条命令的默认 exec 超时时间，单位为秒。单次调用的 `timeout` 会覆盖它；单次调用的 `timeout: 0` 会禁用 exec 进程超时。 - `tools.exec.host`（默认值：`auto`；当沙箱运行时处于活动状态时解析为 `sandbox`，否则解析为 `gateway`） -- `tools.exec.security`（默认值：沙箱为 `deny`，Gateway 网关 + 节点未设置时为 `full`） +- `tools.exec.security`（默认值：沙箱为 `deny`，未设置时 Gateway 网关 + 节点为 `full`） - `tools.exec.ask`（默认值：`off`） -- 免批准主机 exec 是 Gateway 网关 + 节点的默认行为。如果你需要批准/允许列表行为，请同时收紧 `tools.exec.*` 和主机 `~/.openclaw/exec-approvals.json`；参见 [Exec 批准](/zh-CN/tools/exec-approvals#yolo-mode-no-approval)。 -- YOLO 来自主机策略默认值（`security=full`、`ask=off`），而不是来自 `host=auto`。如果你想强制 Gateway 网关或节点路由，请设置 `tools.exec.host` 或使用 `/exec host=...`。 -- 在 `security=full` 加 `ask=off` 模式下，主机 exec 会直接遵循配置的策略；没有额外的启发式命令混淆预过滤器或脚本预检拒绝层。 +- 无需审批的主机 exec 是 Gateway 网关 + 节点的默认值。如果你想要审批/允许列表行为，请同时收紧 `tools.exec.*` 和主机 `~/.openclaw/exec-approvals.json`；请参阅 [Exec 审批](/zh-CN/tools/exec-approvals#yolo-mode-no-approval)。 +- YOLO 来自主机策略默认值（`security=full`、`ask=off`），不是来自 `host=auto`。如果你想强制 Gateway 网关或节点路由，请设置 `tools.exec.host` 或使用 `/exec host=...`。 +- 在 `security=full` 加 `ask=off` 模式下，主机 exec 会直接遵循配置的策略；没有额外的启发式命令混淆预过滤或脚本预检拒绝层。 - `tools.exec.node`（默认值：未设置） -- `tools.exec.strictInlineEval`（默认值：false）：为 true 时，内联解释器 eval 形式（如 `python -c`、`node -e`、`ruby -e`、`perl -e`、`php -r`、`lua -e` 和 `osascript -e`）始终需要显式批准。`allow-always` 仍可持久保存良性的解释器/脚本调用，但内联 eval 形式每次仍会提示。 -- `tools.exec.pathPrepend`：为 exec 运行预置到 `PATH` 的目录列表（仅 Gateway 网关 + 沙箱）。 -- `tools.exec.safeBins`：只读取 stdin 的安全二进制文件，无需显式允许列表条目即可运行。有关行为详情，请参见 [安全二进制文件](/zh-CN/tools/exec-approvals-advanced#safe-bins-stdin-only)。 -- `tools.exec.safeBinTrustedDirs`：额外的显式可信目录，用于 `safeBins` 路径检查。`PATH` 条目永远不会被自动信任。内置默认值为 `/bin` 和 `/usr/bin`。 +- `tools.exec.strictInlineEval`（默认值：false）：为 true 时，内联解释器 eval 形式（如 `python -c`、`node -e`、`ruby -e`、`perl -e`、`php -r`、`lua -e` 和 `osascript -e`）始终需要显式审批。`allow-always` 仍可持久化良性的解释器/脚本调用，但内联 eval 形式每次仍会提示。 +- `tools.exec.pathPrepend`：要为 exec 运行预置到 `PATH` 的目录列表（仅限 Gateway 网关 + 沙箱）。 +- `tools.exec.safeBins`：仅限 stdin 的安全二进制文件，可在没有显式允许列表条目的情况下运行。有关行为详情，请参阅[安全二进制文件](/zh-CN/tools/exec-approvals-advanced#safe-bins-stdin-only)。 +- `tools.exec.safeBinTrustedDirs`：用于 `safeBins` 路径检查的其他显式受信任目录。`PATH` 条目永远不会自动受信任。内置默认值为 `/bin` 和 `/usr/bin`。 - `tools.exec.safeBinProfiles`：每个安全二进制文件的可选自定义 argv 策略（`minPositional`、`maxPositional`、`allowedValueFlags`、`deniedFlags`）。 示例： @@ -130,13 +130,14 @@ x-i18n: ### PATH 处理 -- `host=gateway`：将你的登录 shell `PATH` 合并到 exec 环境中。主机执行会拒绝 `env.PATH` 覆盖项。守护进程本身仍使用最小化 `PATH`： +- `host=gateway`：将你的登录 shell `PATH` 合并到 exec 环境中。主机执行会拒绝 `env.PATH` 覆盖项。守护进程本身仍使用最小 `PATH`： - macOS：`/opt/homebrew/bin`、`/usr/local/bin`、`/usr/bin`、`/bin` - Linux：`/usr/local/bin`、`/usr/bin`、`/bin` - `host=sandbox`：在容器内运行 `sh -lc`（登录 shell），因此 `/etc/profile` 可能会重置 `PATH`。 OpenClaw 会在 profile sourcing 后通过内部环境变量预置 `env.PATH`（无 shell 插值）； - `tools.exec.pathPrepend` 也适用于这里。 -- `host=node`：只有你传入的未被阻止的 env 覆盖项会发送到节点。主机执行会拒绝 `env.PATH` 覆盖项，并且节点主机会忽略它们。如果你需要在节点上添加额外 PATH 条目，请配置节点主机服务环境（systemd/launchd），或将工具安装到标准位置。 + `tools.exec.pathPrepend` 也适用于此处。 +- `host=node`：只会把你传入的未被阻止的 env 覆盖项发送到节点。主机执行会拒绝 `env.PATH` 覆盖项，节点主机也会忽略它们。如果你需要在节点上添加额外的 PATH 条目， + 请配置节点主机服务环境（systemd/launchd），或将工具安装到标准位置。 按智能体绑定节点（在配置中使用智能体列表索引）： @@ -145,11 +146,11 @@ openclaw config get agents.list openclaw config set agents.list[0].tools.exec.node "node-id-or-name" ``` -控制 UI：Nodes 选项卡包含一个小型“Exec 节点绑定”面板，用于相同设置。 +控制 UI：Nodes 标签页包含一个小型“Exec 节点绑定”面板，用于相同设置。 -## 会话覆盖（`/exec`） +## 会话覆盖项（`/exec`） -使用 `/exec` 为 `host`、`security`、`ask` 和 `node` 设置**按会话**的默认值。 +使用 `/exec` 为 `host`、`security`、`ask` 和 `node` 设置**按会话**默认值。 发送不带参数的 `/exec` 可显示当前值。 示例： @@ -160,52 +161,52 @@ openclaw config set agents.list[0].tools.exec.node "node-id-or-name" ## 授权模型 -`/exec` 只会对**已授权发送者**生效（渠道允许列表/配对加 `commands.useAccessGroups`）。 -它只更新**会话状态**，不会写入配置。要强制禁用 exec，请通过工具 -策略（`tools.deny: ["exec"]` 或按智能体）拒绝它。除非你显式设置 -`security=full` 和 `ask=off`，否则主机批准仍会生效。 +`/exec` 仅对**已授权发送者**生效（渠道允许列表/配对加 `commands.useAccessGroups`）。 +它只更新**会话状态**，不会写入配置。要硬禁用 exec，请通过工具策略 +拒绝它（`tools.deny: ["exec"]` 或按智能体设置）。除非你显式设置 +`security=full` 和 `ask=off`，否则主机审批仍然适用。 -## Exec 批准（配套应用 / 节点主机） +## Exec 审批（配套应用 / 节点主机） -沙箱隔离的智能体在 `exec` 于 Gateway 网关或节点主机上运行前，可以要求按请求批准。 -有关策略、允许列表和 UI 流程，请参见 [Exec 批准](/zh-CN/tools/exec-approvals)。 +沙箱隔离的智能体可以在 `exec` 于 Gateway 网关或节点主机上运行前要求逐请求审批。 +请参阅 [Exec 审批](/zh-CN/tools/exec-approvals)，了解策略、允许列表和 UI 流程。 -需要批准时，exec 工具会立即返回 -`status: "approval-pending"` 和批准 ID。批准（或拒绝/超时）后， +需要审批时，exec 工具会立即返回 +`status: "approval-pending"` 和审批 ID。审批通过后（或拒绝 / 超时后）， Gateway 网关会发出系统事件（`Exec finished` / `Exec denied`）。如果命令在 -`tools.exec.approvalRunningNoticeMs` 后仍在运行，会发出一次 `Exec running` 通知。 -在具有原生批准卡片/按钮的渠道上，智能体应优先依赖该 -原生 UI，并且仅当工具结果明确表示聊天批准不可用，或手动批准是 -唯一路径时，才包含手动 `/approve` 命令。 +`tools.exec.approvalRunningNoticeMs` 之后仍在运行，会发出一次 `Exec running` 通知。 +在带有原生审批卡片/按钮的渠道上，智能体应优先依赖该 +原生 UI，并且只在工具 +结果明确表示聊天审批不可用或手动审批是唯一路径时，才包含手动 `/approve` 命令。 ## 允许列表 + 安全二进制文件 手动允许列表强制执行会匹配解析后的二进制路径 glob 和裸命令名 -glob。裸名称仅匹配通过 PATH 调用的命令，因此当命令为 `rg` 时，`rg` 可以匹配 -`/opt/homebrew/bin/rg`，但不能匹配 `./rg` 或 `/tmp/rg`。 -当 `security=allowlist` 时，只有每个 pipeline -片段都在允许列表中或是安全二进制文件时，shell 命令才会被自动允许。链式命令（`;`、`&&`、`||`）和重定向 +glob。裸名称只匹配通过 PATH 调用的命令，因此当命令为 `rg` 时，`rg` 可以匹配 +`/opt/homebrew/bin/rg`，但不会匹配 `./rg` 或 `/tmp/rg`。 +当 `security=allowlist` 时，只有在每个管道 +片段都位于允许列表中或是安全二进制文件时，shell 命令才会被自动允许。链式命令（`;`、`&&`、`||`）和重定向 在允许列表模式下会被拒绝，除非每个顶层片段都满足 允许列表（包括安全二进制文件）。重定向仍不受支持。 -持久 `allow-always` 信任不会绕过该规则：链式命令仍要求每个 +持久的 `allow-always` 信任不会绕过该规则：链式命令仍要求每个 顶层片段都匹配。 -`autoAllowSkills` 是 exec 批准中的独立便利路径。它不同于 -手动路径允许列表条目。对于严格的显式信任，请保持 `autoAllowSkills` 禁用。 +`autoAllowSkills` 是 exec 审批中的另一条便利路径。它与 +手动路径允许列表条目不同。若要严格显式信任，请保持 `autoAllowSkills` 禁用。 -将这两个控件用于不同任务： +将这两个控制项用于不同任务： -- `tools.exec.safeBins`：小型、只读取 stdin 的流过滤器。 -- `tools.exec.safeBinTrustedDirs`：用于安全二进制文件可执行路径的显式额外可信目录。 -- `tools.exec.safeBinProfiles`：自定义安全二进制文件的显式 argv 策略。 -- allowlist：对可执行路径的显式信任。 +- `tools.exec.safeBins`：小型、仅限 stdin 的流过滤器。 +- `tools.exec.safeBinTrustedDirs`：用于安全二进制可执行路径的显式额外受信任目录。 +- `tools.exec.safeBinProfiles`：用于自定义安全二进制文件的显式 argv 策略。 +- 允许列表：对可执行路径的显式信任。 -不要将 `safeBins` 视为通用允许列表，也不要添加解释器/运行时二进制文件（例如 `python3`、`node`、`ruby`、`bash`）。如果你需要这些，请使用显式允许列表条目，并保持启用批准提示。 +不要将 `safeBins` 当作通用允许列表，也不要添加解释器/运行时二进制文件（例如 `python3`、`node`、`ruby`、`bash`）。如果你需要这些，请使用显式允许列表条目，并保持审批提示启用。 当解释器/运行时 `safeBins` 条目缺少显式配置文件时，`openclaw security audit` 会发出警告，并且 `openclaw doctor --fix` 可以搭建缺失的自定义 `safeBinProfiles` 条目。 -当你显式将 `jq` 等宽泛行为的二进制文件加回 `safeBins` 时，`openclaw security audit` 和 `openclaw doctor` 也会发出警告。 -如果你显式允许列出解释器，请启用 `tools.exec.strictInlineEval`，使内联代码求值形式仍然需要新的批准。 +当你显式将 `jq` 等宽泛行为的二进制文件重新添加到 `safeBins` 时，`openclaw security audit` 和 `openclaw doctor` 也会发出警告。 +如果你显式允许列出解释器，请启用 `tools.exec.strictInlineEval`，这样内联代码求值形式仍然需要新的审批。 -有关完整策略详情和示例，请参阅 [Exec 批准](/zh-CN/tools/exec-approvals-advanced#safe-bins-stdin-only) 和 [安全二进制文件与允许列表](/zh-CN/tools/exec-approvals-advanced#safe-bins-versus-allowlist)。 +有关完整策略细节和示例，请参阅 [Exec 审批](/zh-CN/tools/exec-approvals-advanced#safe-bins-stdin-only) 和 [安全二进制文件与允许列表](/zh-CN/tools/exec-approvals-advanced#safe-bins-versus-allowlist)。 ## 示例 @@ -222,8 +223,7 @@ glob。裸名称仅匹配通过 PATH 调用的命令，因此当命令为 `rg` {"tool":"process","action":"poll","sessionId":""} ``` -轮询用于按需查看状态，而不是等待循环。如果启用了自动完成唤醒， -命令在输出内容或失败时可以唤醒会话。 +轮询用于按需获取状态，而不是等待循环。如果启用了自动完成唤醒，命令在产生输出或失败时可以唤醒会话。 发送按键（tmux 风格）： @@ -247,8 +247,8 @@ glob。裸名称仅匹配通过 PATH 调用的命令，因此当命令为 `rg` ## apply_patch -`apply_patch` 是 `exec` 的子工具，用于结构化多文件编辑。 -它默认对 OpenAI 和 OpenAI Codex 模型启用。仅当你想禁用它或将其限制到特定模型时才使用配置： +`apply_patch` 是 `exec` 的子工具，用于结构化的多文件编辑。 +它默认对 OpenAI 和 OpenAI Codex 模型启用。只有当你想禁用它或将它限制到特定模型时，才使用配置： ```json5 { @@ -260,17 +260,18 @@ glob。裸名称仅匹配通过 PATH 调用的命令，因此当命令为 `rg` } ``` -注意： +注意事项： - 仅适用于 OpenAI/OpenAI Codex 模型。 - 工具策略仍然适用；`allow: ["write"]` 会隐式允许 `apply_patch`。 +- `deny: ["write"]` 不会拒绝 `apply_patch`；当补丁写入也应被阻止时，请显式拒绝 `apply_patch`，或使用 `deny: ["group:fs"]`。 - 配置位于 `tools.exec.applyPatch` 下。 -- `tools.exec.applyPatch.enabled` 默认为 `true`；将其设为 `false` 可为 OpenAI 模型禁用该工具。 -- `tools.exec.applyPatch.workspaceOnly` 默认为 `true`（限制在工作区内）。只有当你有意希望 `apply_patch` 在工作区目录外写入/删除时，才将其设为 `false`。 +- `tools.exec.applyPatch.enabled` 默认为 `true`；将其设置为 `false` 可对 OpenAI 模型禁用该工具。 +- `tools.exec.applyPatch.workspaceOnly` 默认为 `true`（限制在工作区内）。仅当你有意希望 `apply_patch` 在工作区目录之外写入/删除时，才将其设置为 `false`。 ## 相关内容 -- [Exec 批准](/zh-CN/tools/exec-approvals) — shell 命令的批准门禁 +- [Exec 审批](/zh-CN/tools/exec-approvals) — shell 命令的审批门禁 - [沙箱隔离](/zh-CN/gateway/sandboxing) — 在沙箱隔离环境中运行命令 - [后台进程](/zh-CN/gateway/background-process) — 长时间运行的 exec 和 process 工具 -- [安全](/zh-CN/gateway/security) — 工具策略和提升访问权限 +- [安全性](/zh-CN/gateway/security) — 工具策略和提升的访问权限