openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-03 17:27:57 +00:00
parent e0173c311f
commit f3b39ccc2a
3 changed files with 311 additions and 303 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

235
docs/zh-CN/concepts/mantis.md
View File

@ -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/<run-id>/
@ -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.
| <inline screenshot> | <inline screenshot> |
```
当运行因 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，截图在上传前是否应脱敏或裁剪？

198
docs/zh-CN/gateway/config-tools.md
View File

@ -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`：
<Note>
本地新手引导会在未设置时默认将新的本地配置设为 `tools.profile: "coding"`（会保留现有的显式配置档）。
本地新手引导会在未设置时将新的本地配置默认为 `tools.profile: "coding"`（会保留已有的显式配置档）。
</Note>
| 配置档 | 包含 |
| 配置档 | 包含内容 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `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:
```
<ParamField path="historySize" type="number">
为循环分析保留的最大工具调用历史记录。
为循环分析保留的最大工具调用历史。
</ParamField>
<ParamField path="warningThreshold" type="number">
重复无进展模式的警告阈值。
</ParamField>
<ParamField path="criticalThreshold" type="number">
用于阻止严重循环的更高重复阈值。
用于阻止关键循环的更高重复阈值。
</ParamField>
<ParamField path="globalCircuitBreakerThreshold" type="number">
任何无进展运行的硬停止阈值。
@ -158,10 +166,10 @@ x-i18n:
对重复的相同工具/相同参数调用发出警告。
</ParamField>
<ParamField path="detectors.knownPollNoProgress" type="boolean">
对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/进行阻止。
对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。
</ParamField>
<ParamField path="detectors.pingPong" type="boolean">
对交替出现的无进展成对模式发出警告/进行阻止。
对交替出现的无进展成对模式发出警告/阻止。
</ParamField>
<Warning>
@ -238,30 +246,30 @@ x-i18n:
```
<AccordionGroup>
<Accordion title="Media model entry fields">
<Accordion title="媒体模型条目字段">
**提供商条目**（`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` 完成仍通过请求方会话中介。
</Accordion>
</AccordionGroup>
@ -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:
```
<AccordionGroup>
<Accordion title="Visibility scopes">
<Accordion title="可见性范围">
- `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`。
</Accordion>
</AccordionGroup>
@ -330,10 +338,10 @@ x-i18n:
<AccordionGroup>
<Accordion title="Attachment notes">
- 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝它们。
- 文件会具象化到子工作区的 `.openclaw/attachments/<uuid>/`，并带有 `.manifest.json`。
- 附件内容会从转录持久化中自动遮蔽。
- Base64 输入会通过严格的字母表/填充检查和预解码大小防护进行验证。
- 目录权限为 `0700`，文件权限为 `0600`。
- 文件会物化到子工作区的 `.openclaw/attachments/<uuid>/`，并带有 `.manifest.json`。
- 附件内容会自动从转录持久化中删改。
- Base64 输入会通过严格的字母表/填充检查和解码前大小保护进行验证。
- 文件权限为：目录 `0700`，文件 `0600`。
- 清理遵循 `cleanup` 策略：`delete` 始终移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。
</Accordion>
@ -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` 或 `~
```
<AccordionGroup>
<Accordion title="凭证和合并优先级">
- 对于自定义凭证需求，使用 `authHeader: true` + `headers`。
- 使用 `OPENCLAW_AGENT_DIR`（或 `PI_CODING_AGENT_DIR`，旧版环境变量别名）覆盖智能体配置根目录。
<Accordion title="Auth and merge precedence">
- 对自定义认证需求使用 `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"`。
- 标记持久化以来源为权威：标记会从活跃来源配置快照（解析前）写入，而不是从已解析的运行时密钥值写入。
- 标记持久化以来源为准：标记会从活动源配置快照（解析前）写入，而不是从已解析的运行时密钥值写入。
</Accordion>
</AccordionGroup>
@ -436,64 +444,64 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~
### 提供商字段详情
<AccordionGroup>
<Accordion title="顶层目录">
<Accordion title="Top-level catalog">
- `models.mode`：提供商目录行为（`merge` 或 `replace`）。
- `models.providers`：按提供商 ID 键控的自定义提供商映射。
- 安全编辑：使用 `openclaw config set models.providers.<id> '<json>' --strict-json --merge` 或 `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` 进行增量更新。除非你传入 `--replace`，否则 `config set` 会拒绝破坏性替换。
- 安全编辑：使用 `openclaw config set models.providers.<id> '<json>' --strict-json --merge` 或 `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` 进行增量更新。除非传入 `--replace`，否则 `config set` 会拒绝破坏性替换。
</Accordion>
<Accordion title="提供商连接和凭证">
- `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`。
<Accordion title="Provider connection and auth">
- `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`：用于代理/租户路由的额外静态标头。
</Accordion>
<Accordion title="请求传输覆盖项">
<Accordion title="Request transport overrides">
`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`。
</Accordion>
<Accordion title="模型目录条目">
<Accordion title="Model catalog entries">
- `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` 数组展平为普通字符串。
</Accordion>
<Accordion title="Amazon Bedrock 发现">
- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根目录。
<Accordion title="Amazon Bedrock discovery">
- `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 数。
</Accordion>
</AccordionGroup>
交互式自定义提供商新手引导会针对 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` 可强制使用纯文本元数据。
### 提供商示例
<AccordionGroup>
<Accordion title="Cerebras（GLM 4.7 / GPT OSS）">
内置的 `cerebras` 提供商插件可以通过 `openclaw onboard --auth-choice cerebras-api-key` 配置此项。仅在覆盖默认值时使用显式提供商配置。
<Accordion title="Cerebras (GLM 4.7 / GPT OSS)">
内置的 `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`。
</Accordion>
<Accordion title="Kimi Coding">
@ -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`。
</Accordion>
<Accordion title="本地模型（LM Studio）">
参见 [本地模型](/zh-CN/gateway/local-models)。简而言之：在高性能硬件上通过 LM Studio Responses API 运行大型本地模型；保留合并的托管模型作为回退。
<Accordion title="Local models (LM Studio)">
参见[本地模型](/zh-CN/gateway/local-models)。简而言之：在性能足够的硬件上通过 LM Studio Responses API 运行大型本地模型；保留已合并的托管模型作为后备。
</Accordion>
<Accordion title="MiniMax M2.7（直连）">
<Accordion title="MiniMax M2.7 (direct)">
```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`。
</Accordion>
<Accordion title="Moonshot AI（Kimi）">
<Accordion title="Moonshot AI (Kimi)">
```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。
</Accordion>
<Accordion title="OpenCode">
@ -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`。
</Accordion>
<Accordion title="Synthetic（兼容 Anthropic）">
<Accordion title="Synthetic (Anthropic-compatible)">
```json5
{
env: { SYNTHETIC_API_KEY: "sk-..." },
@ -678,7 +686,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~
基础 URL 应省略 `/v1`（Anthropic 客户端会追加它）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。
</Accordion>
<Accordion title="Z.AI（GLM-4.7）">
<Accordion title="Z.AI (GLM-4.7)">
```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`

181
docs/zh-CN/tools/exec.md
View File

@ -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:
</ParamField>
<ParamField path="yieldMs" type="number" default="10000">
在此延迟（毫秒）后自动将命令转入后台。
经过此延迟（毫秒）后自动将命令转入后台。
</ParamField>
<ParamField path="background" type="boolean" default="false">
@ -40,7 +40,7 @@ x-i18n:
</ParamField>
<ParamField path="timeout" type="number" default="tools.exec.timeoutSec">
覆盖此调用配置的 exec 超时时间。仅当命令应在没有 exec 进程超时的情况下运行时，才设置 `timeout: 0`。
覆盖此次调用配置的 exec 超时时间。只有在命令应在没有 exec 进程超时限制的情况下运行时，才设置 `timeout: 0`。
</ParamField>
<ParamField path="pty" type="boolean" default="false">
@ -48,7 +48,7 @@ x-i18n:
</ParamField>
<ParamField path="host" type="'auto' | 'sandbox' | 'gateway' | 'node'" default="auto">
执行位置。`auto` 在沙箱运行时处于活动状态时解析为 `sandbox`，否则解析为 `gateway`。
执行位置。`auto` 会在沙箱运行时处于活动状态时解析为 `sandbox`，否则解析为 `gateway`。
</ParamField>
<ParamField path="security" type="'deny' | 'allowlist' | 'full'">
@ -56,64 +56,64 @@ x-i18n:
</ParamField>
<ParamField path="ask" type="'off' | 'on-miss' | 'always'">
`gateway` / `node` 执行的批准提示行为。
`gateway` / `node` 执行的审批提示行为。
</ParamField>
<ParamField path="node" type="string">
当 `host=node` 时的节点 ID/名称。
`host=node` 时的节点 ID/名称。
</ParamField>
<ParamField path="elevated" type="boolean" default="false">
请求提升模式 —— 逃逸沙箱并进入配置的主机路径。仅当提升解析为 `full` 时，才会强制使用 `security=full`。
请求提升模式 — 逃逸沙箱并进入配置的主机路径。只有在 elevated 解析为 `full` 时，才会强制使用 `security=full`。
</ParamField>
注意：
- `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":"<id>"}
```
轮询用于按需查看状态，而不是等待循环。如果启用了自动完成唤醒，
命令在输出内容或失败时可以唤醒会话。
轮询用于按需获取状态，而不是等待循环。如果启用了自动完成唤醒，命令在产生输出或失败时可以唤醒会话。
发送按键（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) — 工具策略和提升的访问权限