diff --git a/docs/zh-CN/cli/browser.md b/docs/zh-CN/cli/browser.md index 40809f7fa..937179d84 100644 --- a/docs/zh-CN/cli/browser.md +++ b/docs/zh-CN/cli/browser.md @@ -1,15 +1,15 @@ --- read_when: - - 你会使用 `openclaw browser`，并且想查看常见任务的示例 - - 你想通过一个节点主机来控制另一台机器上运行的浏览器 + - 你使用 `openclaw browser`，并且想要查看常见任务的示例 + - 你想通过节点主机来控制另一台机器上运行的浏览器 - 你想通过 Chrome MCP 连接到你本地已登录的 Chrome summary: '`openclaw browser` 的 CLI 参考（生命周期、配置文件、标签页、操作、状态和调试）' title: 浏览器 x-i18n: - generated_at: "2026-04-25T07:22:23Z" + generated_at: "2026-04-25T09:15:38Z" model: gpt-5.4 provider: openai - source_hash: 292fc15c72de0aea069b1b87de471e645dbaa3e568e2c7fa493cbcd7c6791a9e + source_hash: 8516a139ad04c20df6fadb261b4fd7175a145cee7edd3cec51d8acdbfe40de26 source_path: cli/browser.md workflow: 15 --- @@ -26,10 +26,10 @@ x-i18n: - `--url `：Gateway 网关 WebSocket URL（默认来自配置）。 - `--token `：Gateway 网关令牌（如果需要）。 -- `--timeout `：请求超时（毫秒）。 +- `--timeout `：请求超时时间（毫秒）。 - `--expect-final`：等待最终的 Gateway 网关响应。 -- `--browser-profile `：选择一个浏览器配置文件（默认来自配置）。 -- `--json`：机器可读输出（在支持的地方）。 +- `--browser-profile `：选择浏览器配置文件（默认来自配置）。 +- `--json`：机器可读输出（在支持的情况下）。 ## 快速开始（本地） @@ -40,11 +40,11 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -智能体也可以使用 `browser({ action: "doctor" })` 运行相同的就绪检查。 +智能体也可以使用相同的就绪检查：`browser({ action: "doctor" })`。 ## 快速故障排除 -如果 `start` 因 `not reachable after start` 失败，请先排查 CDP 就绪状态。如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则说明浏览器控制平面是健康的，失败通常是导航 SSRF 策略导致的。 +如果 `start` 因 `not reachable after start` 失败，请先排查 CDP 就绪状态。如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则浏览器控制平面是健康的，失败通常是导航 SSRF 策略导致的。 最小排查步骤： @@ -72,7 +72,7 @@ openclaw browser --browser-profile openclaw reset-profile - 对于 `attachOnly` 和远程 CDP 配置文件，即使 OpenClaw 本身没有启动浏览器进程，`openclaw browser stop` 也会关闭当前控制会话并清除临时模拟覆盖。 - 对于本地受管配置文件，`openclaw browser stop` 会停止已启动的浏览器进程。 -## 如果命令缺失 +## 如果命令不存在 如果 `openclaw browser` 是未知命令，请检查 `~/.openclaw/openclaw.json` 中的 `plugins.allow`。 @@ -86,15 +86,15 @@ openclaw browser --browser-profile openclaw reset-profile } ``` -当插件允许列表排除了 `browser` 时，`browser.enabled=true` 不会恢复该 CLI 子命令。 +当插件允许列表排除了 `browser` 时，`browser.enabled=true` 不会恢复这个 CLI 子命令。 相关内容：[浏览器工具](/zh-CN/tools/browser#missing-browser-command-or-tool) ## 配置文件 -配置文件是具名的浏览器路由配置。实际使用中： +配置文件是命名的浏览器路由配置。实际使用中： -- `openclaw`：启动或连接到一个专用的由 OpenClaw 管理的 Chrome 实例（隔离的用户数据目录）。 +- `openclaw`：启动或连接到专用的 OpenClaw 托管 Chrome 实例（隔离的用户数据目录）。 - `user`：通过 Chrome DevTools MCP 控制你现有的已登录 Chrome 会话。 - 自定义 CDP 配置文件：指向本地或远程 CDP 端点。 @@ -106,7 +106,7 @@ openclaw browser create-profile --name remote --cdp-url https://browser-host.exa openclaw browser delete-profile --name work ``` -使用特定配置文件： +使用指定配置文件： ```bash openclaw browser --browser-profile work tabs @@ -125,7 +125,7 @@ openclaw browser focus docs openclaw browser close t1 ``` -`tabs` 会先返回 `suggestedTargetId`，然后返回稳定的 `tabId`（例如 `t1`）、可选标签以及原始 `targetId`。智能体应将 `suggestedTargetId` 传回 `focus`、`close`、快照和操作中使用。你可以使用 `open --label`、`tab new --label` 或 `tab label` 分配标签；标签、标签页 ID、原始目标 ID 以及唯一的目标 ID 前缀都可被接受。 +`tabs` 会先返回 `suggestedTargetId`，然后是稳定的 `tabId`（例如 `t1`）、可选标签以及原始 `targetId`。智能体应将 `suggestedTargetId` 传回给 `focus`、`close`、快照和操作。你可以使用 `open --label`、`tab new --label` 或 `tab label` 分配标签；标签、标签页 ID、原始目标 ID，以及唯一的目标 ID 前缀都可以被接受。 ## 快照 / 截图 / 操作 @@ -147,10 +147,10 @@ openclaw browser screenshot --labels 说明： -- `--full-page` 仅用于整页截图；不能与 `--ref` 或 `--element` 组合使用。 -- `existing-session` / `user` 配置文件支持整页截图和基于快照输出的 `--ref` 截图，但不支持 CSS `--element` 截图。 +- `--full-page` 仅用于页面截图；不能与 `--ref` 或 `--element` 一起使用。 +- `existing-session` / `user` 配置文件支持页面截图，以及基于快照输出中 `--ref` 的截图，但不支持基于 CSS `--element` 的截图。 - `--labels` 会在截图上叠加当前快照引用标签。 -- `snapshot --urls` 会将已发现的链接目标追加到 AI 快照中，这样智能体就可以选择直接的导航目标，而不必仅根据链接文本猜测。 +- `snapshot --urls` 会将发现的链接目标追加到 AI 快照中，以便智能体可以直接选择导航目标，而不是仅凭链接文本猜测。 导航 / 点击 / 输入（基于 ref 的 UI 自动化）： @@ -169,7 +169,7 @@ openclaw browser wait --text "Done" openclaw browser evaluate --fn '(el) => el.textContent' --ref ``` -文件 + 对话框辅助： +文件与对话框辅助： ```bash openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref @@ -178,6 +178,8 @@ openclaw browser download report.pdf openclaw browser dialog --accept ``` +受管的 Chrome 配置文件会将普通点击触发的下载保存到 OpenClaw 下载目录（默认为 `/tmp/openclaw/downloads`，或已配置的临时根目录）。当智能体需要等待特定文件并返回其路径时，请使用 `waitfordownload` 或 `download`；这些显式等待器会接管下一次下载。 + ## 状态和存储 视口 + 模拟： @@ -221,7 +223,7 @@ openclaw browser trace stop --out trace.zip ## 通过 MCP 使用现有 Chrome -使用内置的 `user` 配置文件，或创建你自己的 `existing-session` 配置文件： +使用内置的 `user` 配置文件，或者创建你自己的 `existing-session` 配置文件： ```bash openclaw browser --browser-profile user tabs @@ -230,30 +232,30 @@ openclaw browser create-profile --name brave-live --driver existing-session --us openclaw browser --browser-profile chrome-live tabs ``` -此路径仅适用于宿主机。对于 Docker、无头服务器、Browserless 或其他远程设置，请改用 CDP 配置文件。 +这条路径仅适用于宿主机。对于 Docker、无头服务器、Browserless 或其他远程设置，请改用 CDP 配置文件。 -当前 existing-session 的限制： +当前 `existing-session` 的限制： -- 基于快照的操作使用 ref，而不是 CSS 选择器 -- 当调用方省略 `timeoutMs` 时，`browser.actionTimeoutMs` 会将受支持的 `act` 请求默认设置为 60000 毫秒；但单次调用的 `timeoutMs` 仍然优先生效。 +- 基于快照的操作使用 refs，而不是 CSS 选择器 +- 当调用方省略 `timeoutMs` 时，`browser.actionTimeoutMs` 会将受支持的 `act` 请求默认设置为 60000 ms；但每次调用的 `timeoutMs` 仍然优先 - `click` 仅支持左键点击 - `type` 不支持 `slowly=true` - `press` 不支持 `delayMs` -- `hover`、`scrollintoview`、`drag`、`select`、`fill` 和 `evaluate` 会拒绝单次调用的超时覆盖 +- `hover`、`scrollintoview`、`drag`、`select`、`fill` 和 `evaluate` 会拒绝每次调用的超时覆盖 - `select` 仅支持一个值 - 不支持 `wait --load networkidle` - 文件上传需要 `--ref` / `--input-ref`，不支持 CSS `--element`，并且当前一次仅支持一个文件 - 对话框钩子不支持 `--timeout` -- 截图支持整页截图和 `--ref`，但不支持 CSS `--element` +- 截图支持页面捕获和 `--ref`，但不支持 CSS `--element` - `responsebody`、下载拦截、PDF 导出和批量操作仍然需要受管浏览器或原始 CDP 配置文件 ## 远程浏览器控制（节点主机代理） -如果 Gateway 网关运行在与浏览器不同的机器上，请在安装了 Chrome / Brave / Edge / Chromium 的机器上运行一个**节点主机**。Gateway 网关会将浏览器操作代理到该节点（无需单独的浏览器控制服务器）。 +如果 Gateway 网关运行在与浏览器不同的机器上，请在安装有 Chrome/Brave/Edge/Chromium 的机器上运行一个**节点主机**。Gateway 网关会将浏览器操作代理到该节点（不需要单独的浏览器控制服务器）。 -使用 `gateway.nodes.browser.mode` 控制自动路由，并在连接了多个节点时使用 `gateway.nodes.browser.node` 固定到特定节点。 +使用 `gateway.nodes.browser.mode` 来控制自动路由，并使用 `gateway.nodes.browser.node` 在连接了多个节点时固定到特定节点。 -安全性和远程设置：[浏览器工具](/zh-CN/tools/browser)、[远程访问](/zh-CN/gateway/remote)、[Tailscale](/zh-CN/gateway/tailscale)、[安全](/zh-CN/gateway/security) +安全与远程设置：[浏览器工具](/zh-CN/tools/browser)、[远程访问](/zh-CN/gateway/remote)、[Tailscale](/zh-CN/gateway/tailscale)、[安全](/zh-CN/gateway/security) ## 相关内容 diff --git a/docs/zh-CN/gateway/config-agents.md b/docs/zh-CN/gateway/config-agents.md index f46c28781..5240af3f9 100644 --- a/docs/zh-CN/gateway/config-agents.md +++ b/docs/zh-CN/gateway/config-agents.md @@ -6,15 +6,15 @@ read_when: summary: 智能体默认值、多智能体路由、会话、消息和 talk 配置 title: 配置 — 智能体 x-i18n: - generated_at: "2026-04-25T07:51:42Z" + generated_at: "2026-04-25T09:15:37Z" model: gpt-5.4 provider: openai - source_hash: ec43da7bb26dc2b0e99e972d0373b9b3f4dd443cc4ed95fc9807bc4d04483e45 + source_hash: feceed7f2ca92def3382c21de1a9245bf264cab49122b7a35157f55b7ad9932f source_path: gateway/config-agents.md workflow: 15 --- -在 `agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下按智能体作用域划分的配置键。对于渠道、工具、Gateway 网关运行时以及其他顶层键，请参阅 [配置参考](/zh-CN/gateway/configuration-reference)。 +在 `agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下的智能体作用域配置键。对于渠道、工具、Gateway 网关运行时以及其他顶层键，请参见 [配置参考](/zh-CN/gateway/configuration-reference)。 ## 智能体默认值 @@ -30,7 +30,7 @@ x-i18n: ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示中的 Runtime 行。如果未设置，OpenClaw 会从工作区开始向上遍历并自动检测。 +可选的仓库根目录，会显示在系统提示中的 Runtime 行里。如果未设置，OpenClaw 会从工作区开始向上遍历并自动检测。 ```json5 { @@ -49,15 +49,15 @@ x-i18n: list: [ { id: "writer" }, // 继承 github、weather { id: "docs", skills: ["docs-search"] }, // 替换默认值 - { id: "locked-down", skills: [] }, // 没有 Skills + { id: "locked-down", skills: [] }, // 无 Skills ], }, } ``` -- 省略 `agents.defaults.skills` 表示默认不限制 Skills。 -- 省略 `agents.list[].skills` 表示继承默认值。 -- 设置 `agents.list[].skills: []` 表示不使用任何 Skills。 +- 省略 `agents.defaults.skills`，则默认 Skills 不受限制。 +- 省略 `agents.list[].skills` 以继承默认值。 +- 将 `agents.list[].skills: []` 设为无 Skills。 - 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。 ### `agents.defaults.skipBootstrap` @@ -74,8 +74,8 @@ x-i18n: 控制何时将工作区引导文件注入到系统提示中。默认值：`"always"`。 -- `"continuation-skip"`：安全的续接轮次（在一次已完成的助手响应之后）会跳过工作区引导内容的重新注入，从而减小提示大小。Heartbeat 运行和压缩后的重试仍会重建上下文。 -- `"never"`：在每一轮都禁用工作区引导和上下文文件注入。仅对完全自行管理提示生命周期的智能体使用此选项（自定义上下文引擎、自行构建上下文的原生运行时，或专门的不使用引导文件的工作流）。Heartbeat 和压缩恢复轮次也会跳过注入。 +- `"continuation-skip"`：安全的续写轮次（在助手完成响应之后）会跳过工作区引导内容的重新注入，从而减少提示大小。Heartbeat 运行和压缩后的重试仍会重建上下文。 +- `"never"`：在每一轮都禁用工作区引导和上下文文件注入。仅对完全自行管理提示生命周期的智能体使用此项（自定义上下文引擎、自行构建上下文的原生运行时，或专门的不使用引导文件的工作流）。Heartbeat 和压缩恢复轮次也会跳过注入。 ```json5 { @@ -85,7 +85,7 @@ x-i18n: ### `agents.defaults.bootstrapMaxChars` -每个工作区引导文件在被截断前允许的最大字符数。默认值：`12000`。 +每个工作区引导文件在截断前允许的最大字符数。默认值：`12000`。 ```json5 { @@ -95,7 +95,7 @@ x-i18n: ### `agents.defaults.bootstrapTotalMaxChars` -在所有工作区引导文件中注入的总最大字符数。默认值：`60000`。 +所有工作区引导文件合计可注入的最大字符数。默认值：`60000`。 ```json5 { @@ -105,11 +105,12 @@ x-i18n: ### `agents.defaults.bootstrapPromptTruncationWarning` -控制在引导上下文被截断时，智能体可见的警告文本。默认值：`"once"`。 +控制在引导上下文被截断时，向智能体显示的警告文本。 +默认值：`"once"`。 - `"off"`：绝不将警告文本注入系统提示。 -- `"once"`：对每个唯一的截断签名注入一次警告（推荐）。 -- `"always"`：只要存在截断，就在每次运行时注入警告。 +- `"once"`：对于每个唯一的截断签名，仅注入一次警告（推荐）。 +- `"always"`：只要存在截断，每次运行都注入警告。 ```json5 { @@ -119,7 +120,7 @@ x-i18n: ### 上下文预算归属映射 -OpenClaw 有多个高容量的提示 / 上下文预算，它们被有意按子系统拆分，而不是全部流经一个通用开关。 +OpenClaw 具有多个高容量的提示/上下文预算，它们被有意按子系统拆分，而不是统一通过一个通用开关来控制。 - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`： @@ -132,7 +133,7 @@ OpenClaw 有多个高容量的提示 / 上下文预算，它们被有意按子 - `agents.defaults.contextLimits.*`： 有界的运行时摘录和由运行时拥有的注入块。 - `memory.qmd.limits.*`： - 已索引的内存搜索片段与注入大小限制。 + 已索引的内存搜索片段和注入大小控制。 仅当某个智能体需要不同预算时，才使用对应的按智能体覆盖项： @@ -162,7 +163,7 @@ OpenClaw 有多个高容量的提示 / 上下文预算，它们被有意按子 #### `agents.defaults.contextLimits` -有界运行时上下文表面的共享默认值。 +用于有界运行时上下文面的共享默认值。 ```json5 { @@ -179,14 +180,14 @@ OpenClaw 有多个高容量的提示 / 上下文预算，它们被有意按子 } ``` -- `memoryGetMaxChars`：`memory_get` 摘录在添加截断元数据和续接提示前的默认上限。 +- `memoryGetMaxChars`：`memory_get` 摘录的默认上限，在添加截断元数据和续写提示之前生效。 - `memoryGetDefaultLines`：当省略 `lines` 时，`memory_get` 的默认行窗口。 - `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。 -- `postCompactionMaxChars`：在压缩后刷新注入期间使用的 `AGENTS.md` 摘录上限。 +- `postCompactionMaxChars`：用于压缩后刷新注入期间 `AGENTS.md` 摘录的上限。 #### `agents.list[].contextLimits` -用于共享 `contextLimits` 开关的按智能体覆盖项。省略的字段会继承自 `agents.defaults.contextLimits`。 +共享 `contextLimits` 开关的按智能体覆盖项。省略的字段会继承 `agents.defaults.contextLimits`。 ```json5 { @@ -245,11 +246,11 @@ Skills 提示预算的按智能体覆盖项。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，转录 / 工具图像块中图像最长边的最大像素尺寸。 +在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。 默认值：`1200`。 -较低的值通常会减少视觉 token 使用量和以截图为主的运行中的请求负载大小。 -较高的值会保留更多视觉细节。 +较低的值通常会减少视觉 token 使用量和请求负载大小，适合大量截图的运行。 +较高的值则能保留更多视觉细节。 ```json5 { @@ -259,7 +260,7 @@ Skills 提示预算的按智能体覆盖项。 ### `agents.defaults.userTimezone` -系统提示上下文使用的时区（不影响消息时间戳）。会回退到主机时区。 +系统提示上下文所使用的时区（不影响消息时间戳）。默认回退到主机时区。 ```json5 { @@ -307,7 +308,7 @@ Skills 提示预算的按智能体覆盖项。 primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // 全局默认提供商参数 + params: { cacheRetention: "long" }, // 全局默认 provider 参数 embeddedHarness: { runtime: "pi", // pi | auto | 已注册的 harness id，例如 codex fallback: "pi", // pi | none @@ -326,53 +327,53 @@ Skills 提示预算的按智能体覆盖项。 } ``` -- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 +- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 字符串形式只设置主模型。 - - 对象形式设置主模型以及按顺序排列的故障转移模型。 -- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 + - 对象形式设置主模型以及按顺序排列的故障切换模型。 +- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 作为 `image` 工具路径的视觉模型配置使用。 - - 当选中的 / 默认模型无法接受图像输入时，也用作回退路由。 -- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 用于共享的图像生成能力，以及未来任何生成图像的工具 / 插件表面。 - - 典型值：`google/gemini-3.1-flash-image-preview` 用于原生 Gemini 图像生成，`fal/fal-ai/flux/dev` 用于 fal，或 `openai/gpt-image-2` 用于 OpenAI Images。 - - 如果你直接选择某个 provider / model，也要配置匹配的提供商凭证（例如，`google/*` 需要 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` 需要 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 需要 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推断一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的图像生成提供商。 -- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 + - 当选定/默认模型无法接受图像输入时，也用作回退路由。 +- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 用于共享的图像生成能力，以及任何未来会生成图像的工具/插件表面。 + - 常见值：用于原生 Gemini 图像生成的 `google/gemini-3.1-flash-image-preview`、用于 fal 的 `fal/fal-ai/flux/dev`，或用于 OpenAI Images 的 `openai/gpt-image-2`。 + - 如果你直接选择某个 provider/model，也要配置匹配的提供商认证（例如，`google/*` 对应 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` 对应 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 对应 `FAL_KEY`）。 + - 如果省略，`image_generate` 仍然可以推断一个基于认证的提供商默认值。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的图像生成提供商。 +- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 用于共享的音乐生成能力和内置的 `music_generate` 工具。 - - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 - - 如果省略，`music_generate` 仍可推断一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的音乐生成提供商。 - - 如果你直接选择某个 provider / model，也要配置匹配的提供商凭证 / API key。 -- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 + - 常见值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 + - 如果省略，`music_generate` 仍然可以推断一个基于认证的提供商默认值。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的音乐生成提供商。 + - 如果你直接选择某个 provider/model，也要配置匹配的提供商认证/API key。 +- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 用于共享的视频生成能力和内置的 `video_generate` 工具。 - - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 - - 如果省略，`video_generate` 仍可推断一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的视频生成提供商。 - - 如果你直接选择某个 provider / model，也要配置匹配的提供商凭证 / API key。 + - 常见值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 + - 如果省略，`video_generate` 仍然可以推断一个基于认证的提供商默认值。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的视频生成提供商。 + - 如果你直接选择某个 provider/model，也要配置匹配的提供商认证/API key。 - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 -- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 +- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 用于 `pdf` 工具的模型路由。 - - 如果省略，PDF 工具会回退到 `imageModel`，然后再回退到解析后的会话 / 默认模型。 -- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb`，`pdf` 工具使用的默认 PDF 大小上限。 + - 如果省略，PDF 工具会先回退到 `imageModel`，再回退到已解析的会话/默认模型。 +- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。 - `pdfMaxPages`：`pdf` 工具在提取回退模式下考虑的默认最大页数。 -- `verboseDefault`：智能体的默认详细输出级别。可选值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 -- `elevatedDefault`：智能体的默认增强输出级别。可选值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 -- `model.primary`：格式为 `provider/model`（例如，使用 API key 访问时为 `openai/gpt-5.4`，或使用 Codex OAuth 时为 `openai-codex/gpt-5.5`）。如果你省略 provider，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 唯一匹配的已配置 provider，最后才回退到已配置的默认 provider（这是已弃用的兼容行为，因此更推荐显式使用 `provider/model`）。如果该 provider 不再提供已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider / model，而不是暴露一个过期且已移除 provider 的默认值。 -- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可以包含 `alias`（快捷名称）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`extra_body` / `extraBody`）。 - - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非你传入 `--replace`，否则 `config set` 会拒绝可能删除现有允许列表条目的替换操作。 - - 按 provider 作用域的配置 / 新手引导流程会把所选 provider 模型合并到该映射中，并保留已配置的其他无关 provider。 - - 对于直接使用的 OpenAI Responses 模型，服务端压缩会自动启用。使用 `params.responsesServerCompaction: false` 可停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。 -- `params`：应用到所有模型的全局默认 provider 参数。设置在 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 -- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配智能体 id）再按键覆盖。详情参见 [提示缓存](/zh-CN/reference/prompt-caching)。 -- `params.extra_body` / `params.extraBody`：高级透传 JSON，会合并进 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果它与生成的请求键冲突，额外请求体优先；非原生 completions 路由之后仍会剥离 OpenAI 专用的 `store`。 -- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。未指定 runtime 时，默认使用 OpenClaw Pi。使用 `runtime: "pi"` 可强制使用内置 PI harness，使用 `runtime: "auto"` 可让已注册的插件 harness 认领其支持的模型，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动回退到 PI。显式插件运行时（例如 `codex`）默认是失败即关闭，除非你在相同覆盖作用域中设置 `fallback: "pi"`。保持模型引用使用标准形式 `provider/model`；通过运行时配置而不是旧版运行时 provider 前缀来选择 Codex、Claude CLI、Gemini CLI 和其他执行后端。参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes) 了解它与 provider / model 选择的区别。 -- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 和回退 add / remove 命令）会保存为标准对象形式，并尽可能保留现有回退列表。 -- `maxConcurrent`：跨会话并行运行的最大智能体数量（每个会话内部仍然串行）。默认值：4。 +- `verboseDefault`：智能体的默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 +- `elevatedDefault`：智能体的默认增强输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 +- `model.primary`：格式为 `provider/model`（例如，使用 API key 访问时为 `openai/gpt-5.4`，或使用 Codex OAuth 时为 `openai-codex/gpt-5.5`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此更推荐显式使用 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是暴露一个陈旧的、已移除提供商默认值。 +- `models`：`/model` 使用的已配置模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`extra_body`/`extraBody`）。 + - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非你传入 `--replace`，否则 `config set` 会拒绝任何会移除现有允许列表条目的替换操作。 + - 作用域为提供商的配置/新手引导流程会将选定的提供商模型合并到这个映射中，并保留其他已配置提供商的不相关条目。 + - 对于直接使用的 OpenAI Responses 模型，会自动启用服务端压缩。使用 `params.responsesServerCompaction: false` 可停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。 +- `params`：应用于所有模型的全局默认提供商参数。在 `agents.defaults.params` 中设置（例如 `{ cacheRetention: "long" }`）。 +- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后再由 `agents.list[].params`（匹配的智能体 id）按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 +- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并到 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果它与生成的请求键冲突，以额外请求体为准；非原生 completions 路由之后仍会剥离仅 OpenAI 使用的 `store`。 +- `embeddedHarness`：默认的低层嵌入式智能体运行时策略。省略 `runtime` 时默认使用 OpenClaw Pi。使用 `runtime: "pi"` 可强制使用内置 PI harness，使用 `runtime: "auto"` 可让已注册插件 harness 认领受支持的模型，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动回退到 PI。像 `codex` 这样的显式插件运行时默认是失败即关闭，除非你在同一覆盖作用域中设置 `fallback: "pi"`。保持模型引用采用规范格式 `provider/model`；通过运行时配置来选择 Codex、Claude CLI、Gemini CLI 和其他执行后端，而不是使用旧式运行时提供商前缀。参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes) 了解这与 provider/model 选择的区别。 +- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退项 add/remove 命令）会保存规范对象形式，并尽可能保留现有回退列表。 +- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话本身仍是串行）。默认值：4。 ### `agents.defaults.embeddedHarness` -`embeddedHarness` 用于控制哪个底层执行器运行嵌入式智能体轮次。 -大多数部署应保持默认的 OpenClaw Pi 运行时。 +`embeddedHarness` 控制哪个底层执行器运行嵌入式智能体轮次。 +大多数部署应保留默认的 OpenClaw Pi 运行时。 当受信任的插件提供原生 harness 时使用它，例如内置的 -Codex 应用服务器 harness。关于其概念模型，参见 +Codex 应用服务器 harness。其思维模型请参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 ```json5 @@ -389,14 +390,14 @@ Codex 应用服务器 harness。关于其概念模型，参见 } ``` -- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置的 Codex 插件注册为 `codex`。 -- `fallback`：`"pi"` 或 `"none"`。在 `runtime: "auto"` 中，若省略 `fallback`，默认是 `"pi"`，这样旧配置在没有插件 harness 认领运行时仍可继续使用 PI。在显式插件运行时模式下，例如 `runtime: "codex"`，若省略 `fallback`，默认是 `"none"`，这样缺少 harness 时会失败，而不是静默使用 PI。运行时覆盖不会从更宽泛的作用域继承 fallback；当你明确需要该兼容回退时，请与显式 runtime 一起设置 `fallback: "pi"`。选中的插件 harness 一旦失败，总是会直接暴露错误。 -- 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 会覆盖该进程的 fallback。 -- 对于仅使用 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `embeddedHarness.runtime: "codex"`。为了提升可读性，你也可以显式设置 `embeddedHarness.fallback: "none"`；这本就是显式插件运行时的默认值。 -- 在第一次嵌入式运行后，harness 选择会按 session id 固定。配置 / 环境变量更改只影响新的或已重置的会话，不影响现有转录。具有转录历史但没有记录固定信息的旧会话，会被视为固定到 PI。`/status` 会报告实际运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。 -- 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用它们各自的 provider / model 设置。 +- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置的 Codex 插件注册的 id 为 `codex`。 +- `fallback`：`"pi"` 或 `"none"`。在 `runtime: "auto"` 中，如果省略，默认回退为 `"pi"`，这样旧配置在没有插件 harness 认领运行时仍可继续使用 PI。在显式插件运行时模式下，例如 `runtime: "codex"`，如果省略，默认回退为 `"none"`，这样缺少 harness 时会直接失败，而不是静默使用 PI。运行时覆盖项不会从更宽的作用域继承 `fallback`；如果你确实想要这种兼容性回退，请在显式运行时旁边同时设置 `fallback: "pi"`。所选插件 harness 的失败总是会直接暴露。 +- 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 覆盖该进程的 fallback。 +- 对于仅使用 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `embeddedHarness.runtime: "codex"`。你也可以出于可读性显式设置 `embeddedHarness.fallback: "none"`；这是显式插件运行时的默认值。 +- 在首次嵌入式运行后，harness 选择会按每个会话 id 固定。配置/环境变量的变更只影响新会话或已重置的会话，不影响现有转录。带有转录历史但未记录固定值的旧会话会被视为固定到 PI。`/status` 会报告生效的运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。 +- 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的 provider/model 设置。 -**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时生效）： +**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： | 别名 | 模型 | | ------------------- | -------------------------------------------------- | @@ -411,13 +412,13 @@ Codex 应用服务器 harness。关于其概念模型，参见 你配置的别名始终优先于默认值。 -Z.AI GLM-4.x 模型会自动启用思考模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设置为 `false` 可禁用它。 -Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `adaptive` 思考模式。 +Z.AI GLM-4.x 模型会自动启用思考模式，除非你设置 `--thinking off` 或自行定义 `agents.defaults.models["zai/"].params.thinking`。 +Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用它。 +Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `adaptive` 思考。 ### `agents.defaults.cliBackends` -用于纯文本回退运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时，可作为备份。 +用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，它可作为备用方案。 ```json5 { @@ -446,12 +447,12 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada ``` - CLI 后端以文本为主；工具始终禁用。 -- 设置了 `sessionArg` 时支持会话。 +- 设置 `sessionArg` 时支持会话。 - 当 `imageArg` 接受文件路径时，支持图像透传。 ### `agents.defaults.systemPromptOverride` -用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体设置（`agents.list[].systemPromptOverride`）。按智能体的值优先；空值或仅包含空白的值会被忽略。适用于受控的提示实验。 +用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体（`agents.list[].systemPromptOverride`）设置。按智能体的值优先；空值或仅空白字符的值会被忽略。适用于受控提示实验。 ```json5 { @@ -465,7 +466,7 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada ### `agents.defaults.promptOverlays` -按模型家族应用的、与 provider 无关的提示叠加层。GPT-5 家族模型 id 会跨 provider 接收共享的行为契约；`personality` 只控制友好的交互风格层。 +按模型家族应用的、与提供商无关的提示覆盖层。GPT-5 系列模型 id 会在不同提供商之间接收共享的行为契约；`personality` 只控制友好的交互风格层。 ```json5 { @@ -482,28 +483,28 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada ``` - `"friendly"`（默认）和 `"on"` 会启用友好的交互风格层。 -- `"off"` 只禁用友好层；带标签的 GPT-5 行为契约仍保持启用。 +- `"off"` 只会禁用友好层；带标签的 GPT-5 行为契约仍然启用。 - 当这个共享设置未设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。 ### `agents.defaults.heartbeat` -周期性 Heartbeat 运行。 +定期 Heartbeat 运行。 ```json5 { agents: { defaults: { heartbeat: { - every: "30m", // 0m disables + every: "30m", // 0m 禁用 model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt - lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files - isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + includeSystemPromptSection: true, // 默认值：true；false 会从系统提示中省略 Heartbeat 部分 + lightContext: false, // 默认值：false；true 仅保留工作区引导文件中的 HEARTBEAT.md + isolatedSession: false, // 默认值：false；true 会在全新会话中运行每次 heartbeat（无对话历史） session: "main", to: "+15555550123", - directPolicy: "allow", // allow (default) | block - target: "none", // default: none | options: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow（默认）| block + target: "none", // 默认值：none | 可选值：last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -514,15 +515,15 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 凭证）或 `1h`（OAuth 凭证）。设置为 `0m` 可禁用。 -- `includeSystemPromptSection`：设为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入到引导上下文中。默认值：`true`。 -- `suppressToolErrorWarnings`：设为 true 时，会在 Heartbeat 运行期间抑制工具错误警告负载。 -- `timeoutSeconds`：Heartbeat 智能体轮次在被中止前允许的最大秒数。若不设置，则使用 `agents.defaults.timeoutSeconds`。 -- `directPolicy`：直接 / 私信投递策略。`allow`（默认）允许直接目标投递。`block` 会阻止直接目标投递，并发出 `reason=dm-blocked`。 -- `lightContext`：设为 true 时，Heartbeat 运行会使用轻量级引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：设为 true 时，每次 Heartbeat 都会在一个全新会话中运行，不带任何先前的对话历史。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。每次 Heartbeat 的 token 成本可从约 100K 降至约 2–5K。 -- 按智能体设置：使用 `agents.list[].heartbeat`。如果任意智能体定义了 `heartbeat`，**则只有这些智能体** 会运行 Heartbeat。 -- Heartbeat 会运行完整的智能体轮次——间隔越短，消耗的 token 越多。 +- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 +- `includeSystemPromptSection`：为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入引导上下文。默认值：`true`。 +- `suppressToolErrorWarnings`：为 true 时，在 Heartbeat 运行期间抑制工具错误警告负载。 +- `timeoutSeconds`：Heartbeat 智能体轮次在被中止前允许的最长秒数。留空则使用 `agents.defaults.timeoutSeconds`。 +- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并发出 `reason=dm-blocked`。 +- `lightContext`：为 true 时，Heartbeat 运行使用轻量级引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次 Heartbeat 都会在一个没有先前对话历史的全新会话中运行。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次 Heartbeat 的 token 成本从约 100K 降低到约 2-5K token。 +- 按智能体设置：使用 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 Heartbeat。 +- Heartbeat 会运行完整的智能体轮次——更短的间隔会消耗更多 token。 ### `agents.defaults.compaction` @@ -532,16 +533,16 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id of a registered compaction provider plugin (optional) + provider: "my-provider", // 已注册的 compaction provider 插件 id（可选） timeoutSeconds: 900, reserveTokensFloor: 24000, keepRecentTokens: 50000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用 qualityGuard: { enabled: true, maxRetries: 1 }, - postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection - model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override - notifyUser: true, // send brief notices when compaction starts and completes (default: false) + postCompactionSections: ["Session Startup", "Red Lines"], // [] 禁用重新注入 + model: "openrouter/anthropic/claude-sonnet-4-6", // 可选的仅 compaction 使用的模型覆盖 + notifyUser: true, // 在 compaction 开始和完成时发送简短通知（默认值：false） memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -554,21 +555,21 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada } ``` -- `mode`：`default` 或 `safeguard`（针对长历史记录的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `provider`：已注册压缩 provider 插件的 id。设置后，会调用该 provider 的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置实现。设置 provider 会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 中止一次压缩操作前允许的最大秒数。默认值：`900`。 -- `keepRecentTokens`：Pi 切分点预算，用于把最近的转录尾部按原文保留。手动 `/compact` 在显式设置时会遵循此值；否则手动压缩就是一个硬检查点。 -- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要时预先添加内置的不透明标识符保留指导。 -- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的自定义标识符保留文本。 -- `qualityGuard`：对 safeguard 摘要执行输出格式错误后的重试检查。在 safeguard 模式下默认启用；设置 `enabled: false` 可跳过审计。 -- `postCompactionSections`：压缩后要重新注入的可选 `AGENTS.md` H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。当未设置，或显式设置为该默认对时，也会接受旧版的 `Every Session` / `Safety` 标题作为兼容回退。 -- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖。若你希望主会话保持使用某个模型，而压缩摘要使用另一个模型，就用它；若未设置，压缩会使用会话的主模型。 -- `notifyUser`：设为 `true` 时，会在压缩开始和完成时向用户发送简短通知（例如，“正在压缩上下文...” 和 “上下文压缩完成”）。默认关闭，以保持压缩静默进行。 -- `memoryFlush`：在自动压缩前执行一次静默的智能体轮次，以存储持久记忆。当工作区为只读时会跳过。 +- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `provider`：已注册的 compaction provider 插件 id。设置后，会调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时回退到内置实现。设置 provider 会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：OpenClaw 在中止单次 compaction 操作前允许的最大秒数。默认值：`900`。 +- `keepRecentTokens`：Pi 切分点预算，用于原样保留最近的转录尾部。手动 `/compact` 在显式设置时会遵循它；否则手动 compaction 是一个硬检查点。 +- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指南。 +- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 +- `qualityGuard`：对 safeguard 摘要执行输出格式异常时重试检查。在 safeguard 模式下默认启用；设为 `enabled: false` 可跳过审计。 +- `postCompactionSections`：可选的 `AGENTS.md` H2/H3 小节名称，在 compaction 后重新注入。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。当未设置，或显式设置为这对默认值时，也接受旧版 `Every Session`/`Safety` 标题作为兼容回退。 +- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当你希望主会话继续使用一个模型，而 compaction 摘要使用另一个模型时使用；未设置时，compaction 使用会话的主模型。 +- `notifyUser`：为 `true` 时，在 compaction 开始和完成时向用户发送简短通知（例如 “Compacting context...” 和 “Compaction complete”）。默认关闭，以保持 compaction 静默。 +- `memoryFlush`：自动 compaction 前的静默智能体轮次，用于存储持久记忆。工作区为只读时会跳过。 ### `agents.defaults.contextPruning` -在把内容发送给 LLM 之前，从内存上下文中修剪 **旧的工具结果**。**不会** 修改磁盘上的会话历史。 +在发送给 LLM 之前，从内存上下文中裁剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -576,7 +577,7 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // duration (ms/s/m/h), default unit: minutes + ttl: "1h", // 时长（ms/s/m/h），默认单位：分钟 keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -592,23 +593,23 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada -- `mode: "cache-ttl"` 会启用修剪流程。 -- `ttl` 控制何时可以再次运行修剪（在上次缓存触碰之后）。 -- 修剪会先对过大的工具结果执行软修剪；如仍有需要，再对更旧的工具结果执行硬清除。 +- `mode: "cache-ttl"` 会启用裁剪过程。 +- `ttl` 控制多久之后才能再次运行裁剪（从上次缓存触碰后开始计算）。 +- 裁剪会先对过大的工具结果进行软裁剪，然后在需要时对更旧的工具结果执行硬清除。 -**软修剪** 会保留开头和结尾，并在中间插入 `...`。 +**软裁剪**会保留开头和结尾，并在中间插入 `...`。 -**硬清除** 会用占位符替换整个工具结果。 +**硬清除**会用占位符替换整个工具结果。 说明： -- 图像块永远不会被修剪 / 清除。 -- 比例基于字符数（近似值），而不是精确 token 数。 -- 如果助手消息少于 `keepLastAssistants` 条，则会跳过修剪。 +- 图像块永远不会被裁剪/清除。 +- 比例按字符计算（近似），不是精确 token 数。 +- 如果助手消息少于 `keepLastAssistants` 条，则跳过裁剪。 -行为详情参见 [会话修剪](/zh-CN/concepts/session-pruning)。 +行为细节参见 [会话裁剪](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -620,19 +621,19 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) + humanDelay: { mode: "natural" }, // off | natural | custom（使用 minMs/maxMs） }, }, } ``` - 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。 -- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号的变体）。Signal / Slack / Discord / Google Chat 默认使用 `minChars: 1500`。 +- 渠道覆盖项：`channels..blockStreamingCoalesce`（以及按账号的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 - `humanDelay`：分块回复之间的随机停顿。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。 行为和分块细节参见 [流式传输](/zh-CN/concepts/streaming)。 -### 正在输入指示器 +### 输入中指示器 ```json5 { @@ -645,16 +646,16 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada } ``` -- 默认值：直接聊天 / 提及时使用 `instant`，未被提及的群聊使用 `message`。 +- 默认值：直接聊天/提及时使用 `instant`，未提及的群聊使用 `message`。 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 -参见 [正在输入指示器](/zh-CN/concepts/typing-indicators)。 +参见 [输入中指示器](/zh-CN/concepts/typing-indicators)。 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -700,7 +701,7 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / inline contents also supported: + // 也支持 SecretRefs / 内联内容： // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -754,45 +755,45 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada **后端：** - `docker`：本地 Docker 运行时（默认） -- `ssh`：通用的基于 SSH 的远程运行时 +- `ssh`：通用 SSH 支持的远程运行时 - `openshell`：OpenShell 运行时 -当选择 `backend: "openshell"` 时，运行时专用设置会移至 +当选择 `backend: "openshell"` 时，运行时专属设置会移动到 `plugins.entries.openshell.config`。 **SSH 后端配置：** - `target`：`user@host[:port]` 形式的 SSH 目标 - `command`：SSH 客户端命令（默认值：`ssh`） -- `workspaceRoot`：用于按作用域划分工作区的远程绝对根目录 +- `workspaceRoot`：用于按作用域工作区的远程绝对根路径 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 -- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRefs，OpenClaw 会在运行时将其物化为临时文件 +- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRefs，OpenClaw 会在运行时将其实体化为临时文件 - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 -**SSH 凭证优先级：** +**SSH 认证优先级：** - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从当前活动的 secrets 运行时快照中解析 +- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从当前激活的 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重建后，对远程工作区执行一次初始化 -- 然后保持远程 SSH 工作区为标准状态 +- 在创建或重建后对远程工作区进行一次初始化 +- 然后保持远程 SSH 工作区为规范副本 - 通过 SSH 路由 `exec`、文件工具和媒体路径 -- 不会自动把远程更改同步回主机 +- 不会自动将远程更改同步回主机 - 不支持沙箱浏览器容器 **工作区访问：** -- `none`：每个作用域的沙箱工作区位于 `~/.openclaw/sandboxes` 下 +- `none`：位于 `~/.openclaw/sandboxes` 下的按作用域沙箱工作区 - `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` - `rw`：智能体工作区以读写方式挂载到 `/workspace` **作用域：** -- `session`：每个会话一个容器 + 工作区 +- `session`：每会话一个容器 + 工作区 - `agent`：每个智能体一个容器 + 工作区（默认） - `shared`：共享容器和工作区（无跨会话隔离） @@ -809,10 +810,10 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // optional - gatewayEndpoint: "https://lab.example", // optional - policy: "strict", // optional OpenShell policy id - providers: ["openai"], // optional + gateway: "lab", // 可选 + gatewayEndpoint: "https://lab.example", // 可选 + policy: "strict", // 可选的 OpenShell policy id + providers: ["openai"], // 可选 autoProviders: true, timeoutSeconds: 120, }, @@ -824,29 +825,29 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada **OpenShell 模式：** -- `mirror`：在执行前把本地内容初始化到远程，执行后再同步回本地；本地工作区保持为标准状态 -- `remote`：在创建沙箱时只对远程执行一次初始化，之后保持远程工作区为标准状态 +- `mirror`：在执行前将本地内容初始化到远程，执行后再同步回本地；本地工作区保持为规范副本 +- `remote`：在创建沙箱时仅对远程进行一次初始化，然后保持远程工作区为规范副本 -在 `remote` 模式下，于 OpenClaw 之外在主机本地进行的编辑，在初始化步骤之后不会自动同步到沙箱中。 -传输方式是通过 SSH 连接到 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。 +在 `remote` 模式下，在 OpenClaw 之外于主机本地所做的编辑，在初始化步骤之后不会自动同步到沙箱中。 +传输方式是通过 SSH 连接到 OpenShell 沙箱，但插件负责沙箱生命周期和可选的镜像同步。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 +**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。它需要网络出口、可写根文件系统以及 root 用户。 **容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 -`"host"` 会被阻止。`"container:"` 默认也会被阻止，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急放行）。 +`"host"` 被阻止。默认情况下，`"container:"` 也被阻止，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急破窗模式）。 -**入站附件** 会被暂存到活动工作区中的 `media/inbound/*`。 +**入站附件** 会暂存到当前活动工作区中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的绑定会合并。 +**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入到系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。 -noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短期有效的 token URL（而不是在共享 URL 中暴露密码）。 +**沙箱浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入到系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。 +noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有效的 token URL（而不是在共享 URL 中暴露密码）。 - `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。 -- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。只有在你明确需要全局 bridge 连通性时才设置为 `bridge`。 -- `cdpSourceRange` 可选地将容器边缘的 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅会把额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 +- `network` 默认值为 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确需要全局 bridge 连通性时，才设置为 `bridge`。 +- `cdpSourceRange` 可选地将容器边缘的 CDP 入站限制为某个 CIDR 范围（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 仅会将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 - 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` @@ -864,27 +865,27 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短期有 - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - 默认启用 `--disable-extensions` + - `--disable-extensions`（默认启用） - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` - 默认启用；如果 WebGL / 3D 使用场景需要，可通过 - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用它们。 - - 如果你的工作流依赖扩展，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展。 - - `--renderer-process-limit=2` 可通过 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 更改；设置为 `0` 会使用 Chromium 的 + 默认启用；如果你的工作流需要 WebGL/3D，可通过 + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。 + - 如果你的工作流依赖扩展，使用 + `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 可重新启用扩展。 + - `--renderer-process-limit=2` 可以通过 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 可使用 Chromium 的 默认进程限制。 - - 另外，当启用 `noSandbox` 时，还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 这些默认值是容器镜像基线；如需更改容器默认行为，请使用自定义浏览器镜像和自定义 - 入口点。 + - 当启用 `noSandbox` 时，还会附加 `--no-sandbox`。 + - 这些默认值属于容器镜像基线；如需更改容器默认值，请使用带自定义入口点的自定义浏览器镜像。 -浏览器沙箱隔离和 `sandbox.docker.binds` 仅适用于 Docker。 +浏览器沙箱隔离和 `sandbox.docker.binds` 仅支持 Docker。 构建镜像： ```bash scripts/sandbox-setup.sh # 主沙箱镜像 -scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 +scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ``` ### `agents.list`（按智能体覆盖） @@ -899,13 +900,13 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } - thinkingDefault: "high", // per-agent thinking level override - reasoningDefault: "on", // per-agent reasoning visibility override - fastModeDefault: false, // per-agent fast mode override + model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks } + thinkingDefault: "high", // 按智能体覆盖思考级别 + reasoningDefault: "on", // 按智能体覆盖推理可见性 + fastModeDefault: false, // 按智能体覆盖快速模式 embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // overrides matching defaults.models params by key - skills: ["docs-search"], // replaces agents.defaults.skills when set + params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params + skills: ["docs-search"], // 设置后替换 agents.defaults.skills identity: { name: "Samantha", theme: "helpful sloth", @@ -936,27 +937,27 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 } ``` -- `id`：稳定的智能体 id（必需）。 -- `default`：若设置了多个，首个生效（会记录警告）。如果都未设置，则列表中的第一个条目为默认值。 -- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 会禁用全局回退）。仅覆盖 `primary` 的 cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。 -- `params`：按智能体的流参数，会合并到 `agents.defaults.models` 中选定模型条目之上。可用于像 `cacheRetention`、`temperature` 或 `maxTokens` 这样的智能体特定覆盖，而不必复制整个模型目录。 -- `skills`：可选的按智能体 Skills 允许列表。如果省略，智能体会在设置了 `agents.defaults.skills` 时继承它；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。 -- `thinkingDefault`：可选的按智能体默认思考级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置按消息或按会话覆盖时，它会覆盖该智能体的 `agents.defaults.thinkingDefault`。所选 provider / model 配置决定哪些值有效；对于 Google Gemini，`adaptive` 会保持 provider 自有的动态思考（在 Gemini 3 / 3.1 上省略 `thinkingLevel`，在 Gemini 2.5 上使用 `thinkingBudget: -1`）。 -- `reasoningDefault`：可选的按智能体默认推理可见性（`on | off | stream`）。当未设置按消息或按会话推理覆盖时生效。 -- `fastModeDefault`：可选的按智能体快速模式默认值（`true | false`）。当未设置按消息或按会话快速模式覆盖时生效。 -- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex" }` 可让某个智能体仅使用 Codex，而其他智能体继续使用默认的 `auto` 模式 PI 回退。 -- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 以及 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `id`：稳定的智能体 id（必填）。 +- `default`：如果设置了多个，以第一个为准（会记录警告）。如果一个都没设置，则列表中的第一个条目为默认值。 +- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖二者（`[]` 会禁用全局回退）。只覆盖 `primary` 的 cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。 +- `params`：按智能体的流参数，会合并到 `agents.defaults.models` 中选定模型条目之上。适合做智能体专属覆盖，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 +- `skills`：可选的按智能体 Skills 允许列表。如果省略，在设置了 `agents.defaults.skills` 时，智能体会继承它；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。 +- `thinkingDefault`：可选的按智能体默认思考级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当没有按消息或按会话的覆盖时，它会覆盖该智能体的 `agents.defaults.thinkingDefault`。所选 provider/model 配置决定哪些值有效；对于 Google Gemini，`adaptive` 会保留提供商自有的动态思考（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。 +- `reasoningDefault`：可选的按智能体默认推理可见性（`on | off | stream`）。在没有按消息或按会话的推理覆盖时生效。 +- `fastModeDefault`：可选的按智能体快速模式默认值（`true | false`）。在没有按消息或按会话的快速模式覆盖时生效。 +- `embeddedHarness`：可选的按智能体低层 harness 策略覆盖。使用 `{ runtime: "codex" }` 可使某个智能体仅使用 Codex，而其他智能体仍保留默认的 `auto` 模式 PI 回退。 +- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 和 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 - `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。 -- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name` / `emoji`。 -- `subagents.allowAgents`：`sessions_spawn` 允许的智能体 id 列表（`["*"]` = 任意；默认：仅同一智能体）。 -- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些将以非沙箱方式运行的目标。 -- `subagents.requireAgentId`：设为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认值：false）。 +- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。 +- `subagents.allowAgents`：`sessions_spawn` 的智能体 id 允许列表（`["*"]` = 任意；默认：仅相同智能体）。 +- 沙箱继承保护：如果请求方会话处于沙箱中，`sessions_spawn` 会拒绝那些会以非沙箱方式运行的目标。 +- `subagents.requireAgentId`：为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认值：false）。 --- ## 多智能体路由 -在一个 Gateway 网关中运行多个彼此隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关内运行多个彼此隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -975,27 +976,27 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 ### 绑定匹配字段 -- `type`（可选）：普通路由使用 `route`（未指定时默认即为 route），持久 ACP 对话绑定使用 `acp`。 -- `match.channel`（必需） +- `type`（可选）：普通路由使用 `route`（缺失 `type` 时默认为 route），持久 ACP 对话绑定使用 `acp`。 +- `match.channel`（必填） - `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） -- `match.guildId` / `match.teamId`（可选；特定渠道） -- `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }` +- `match.guildId` / `match.teamId`（可选；特定渠道使用） +- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }` -**确定性的匹配顺序：** +**确定性匹配顺序：** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId`（精确匹配，无 peer / guild / team） -5. `match.accountId: "*"`（整个渠道） +4. `match.accountId`（精确匹配，无 peer/guild/team） +5. `match.accountId: "*"`（整个渠道范围） 6. 默认智能体 -在每一层内，首个匹配的 `bindings` 条目胜出。 +在每一层中，第一个匹配的 `bindings` 条目获胜。 -对于 `type: "acp"` 条目，OpenClaw 会按精确会话标识（`match.channel` + account + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 按精确的对话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。 -### 按智能体划分的访问配置 +### 按智能体访问配置 @@ -1090,7 +1091,7 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 -有关优先级细节，参见 [多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 +有关优先级细节，请参见 [多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1116,22 +1117,22 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) + parentForkMaxTokens: 100000, // 高于此 token 数时跳过父线程分叉（0 表示禁用） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duration or false - maxDiskBytes: "500mb", // optional hard budget - highWaterBytes: "400mb", // optional cleanup target + resetArchiveRetention: "30d", // 时长或 false + maxDiskBytes: "500mb", // 可选硬预算 + highWaterBytes: "400mb", // 可选清理目标 }, threadBindings: { enabled: true, - idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) - maxAgeHours: 0, // default hard max age in hours (`0` disables) + idleHours: 24, // 默认按小时计算的不活动自动取消聚焦（`0` 表示禁用） + maxAgeHours: 0, // 默认按小时计算的硬性最大时长（`0` 表示禁用） }, - mainKey: "main", // legacy (runtime always uses "main") + mainKey: "main", // 旧版字段（运行时始终使用 "main"） agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1144,34 +1145,34 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在某个渠道上下文中，每个发送者都有独立的隔离会话。 - - `global`：某个渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。 + - `per-sender`（默认）：在一个渠道上下文内，每个发送者都有独立会话。 + - `global`：渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。 - **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - `per-peer`：按发送者 id 跨渠道隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号场景）。 -- **`identityLinks`**：将规范 id 映射到带 provider 前缀的 peer，用于跨渠道共享会话。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在空闲 `idleMinutes` 后重置。如果两者都配置，先到期者生效。 -- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 仍可作为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建分叉线程会话时允许的父会话最大 `totalTokens`（默认 `100000`）。 - - 如果父会话的 `totalTokens` 超过该值，OpenClaw 会启动一个新的线程会话，而不是继承父级转录历史。 - - 设置为 `0` 可禁用此保护，并始终允许父级分叉。 -- **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：在智能体到智能体交互期间，智能体之间允许的最大往返回复轮数（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链式交互。 -- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。首个 deny 规则胜出。 + - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 +- **`identityLinks`**：将规范 id 映射到带提供商前缀的 peer，用于跨渠道共享会话。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。当两者都配置时，以先到期者为准。 +- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。 +- **`parentForkMaxTokens`**：创建分叉线程会话时允许的父会话 `totalTokens` 最大值（默认 `100000`）。 + - 如果父会话的 `totalTokens` 高于该值，OpenClaw 会启动一个全新的线程会话，而不是继承父转录历史。 + - 设为 `0` 可禁用此保护，并始终允许父会话分叉。 +- **`mainKey`**：旧版字段。运行时始终对主直接聊天桶使用 `"main"`。 +- **`agentToAgent.maxPingPongTurns`**：在智能体到智能体交换期间，智能体之间最大往返信息轮次（整数，范围：`0`–`5`）。`0` 会禁用来回链式回复。 +- **`sendPolicy`**：可按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个拒绝规则优先。 - **`maintenance`**：会话存储清理 + 保留控制。 - - `mode`：`warn` 仅发出警告；`enforce` 会实际执行清理。 + - `mode`：`warn` 仅发出警告；`enforce` 则应用清理。 - `pruneAfter`：过期条目的时间阈值（默认 `30d`）。 - - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 - - `rotateBytes`：当 `sessions.json` 超过此大小时轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` 转录归档的保留时长。默认与 `pruneAfter` 相同；设置为 `false` 可禁用。 - - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下记录警告；在 `enforce` 模式下会优先删除最旧的产物 / 会话。 + - `maxEntries`：`sessions.json` 中条目的最大数量（默认 `500`）。 + - `rotateBytes`：当 `sessions.json` 超过此大小时执行轮转（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留时长。默认等于 `pruneAfter`；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的制品/会话。 - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - - `enabled`：主默认开关（provider 可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认的按空闲时间自动取消聚焦小时数（`0` 为禁用；provider 可覆盖） - - `maxAgeHours`：默认的硬最大存在时长小时数（`0` 为禁用；provider 可覆盖） + - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） + - `idleHours`：默认按小时计算的不活动自动取消聚焦（`0` 表示禁用；提供商可覆盖） + - `maxAgeHours`：默认按小时计算的硬性最大时长（`0` 表示禁用；提供商可覆盖） @@ -1182,7 +1183,7 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 ```json5 { messages: { - responsePrefix: "🦞", // or "auto" + responsePrefix: "🦞", // 或 "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1197,7 +1198,7 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 }, }, inbound: { - debounceMs: 2000, // 0 disables + debounceMs: 2000, // 0 表示禁用 byChannel: { whatsapp: 5000, slack: 1500, @@ -1209,36 +1210,36 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 ### 响应前缀 -按渠道 / 账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 +按渠道/账号的覆盖项：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。 **模板变量：** -| 变量 | 说明 | 示例 | -| ----------------- | ---------------------- | --------------------------- | -| `{model}` | 模型短名称 | `claude-opus-4-6` | -| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供商名称 | `anthropic` | -| `{thinkingLevel}` | 当前思考级别 | `high`、`low`、`off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| 变量 | 说明 | 示例 | +| ----------------- | ---------------- | --------------------------- | +| `{model}` | 短模型名 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前思考级别 | `high`、`low`、`off` | +| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 ### 确认反应 -- 默认为活动智能体的 `identity.emoji`，否则为 `"👀"`。设置为 `""` 可禁用。 +- 默认使用当前智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 - 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 -- 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上回复后移除确认反应。 +- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，在回复后移除确认反应。 - `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期 Status 反应。 - 在 Slack 和 Discord 上，未设置时，如果确认反应处于活动状态，则保持 Status 反应启用。 - 在 Telegram 上，必须显式设置为 `true` 才会启用生命周期 Status 反应。 + 在 Slack 和 Discord 上，未设置时，如果确认反应处于启用状态，则保持 Status 反应启用。 + 在 Telegram 上，必须显式将其设为 `true` 才会启用生命周期 Status 反应。 -### 入站去抖 +### 入站防抖 -将来自同一发送者的快速连续纯文本消息批处理为一次智能体轮次。媒体 / 附件会立即刷新。控制命令会绕过去抖。 +将来自同一发送者的快速纯文本消息合并为一个智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -1288,19 +1289,19 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 } ``` -- `auto` 控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好，`/tts status` 会显示实际状态。 -- `summaryModel` 会为自动摘要覆盖 `agents.defaults.model.primary`。 -- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需主动启用）。 -- API key 会回退到 `ELEVENLABS_API_KEY` / `XI_API_KEY` 和 `OPENAI_API_KEY`。 -- 内置语音提供商由插件负责。如果设置了 `plugins.allow`，请包含你要使用的每个 TTS 提供商插件，例如用于 Edge TTS 的 `microsoft`。旧版 provider id `edge` 仍可作为 `microsoft` 的别名使用。 -- `providers.openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为：配置，然后 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 -- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型 / 语音校验。 +- `auto` 控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好，`/tts status` 会显示生效状态。 +- `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。 +- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需显式启用）。 +- API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 +- 内置语音提供商由插件拥有。如果设置了 `plugins.allow`，请包含你想使用的每个 TTS 提供商插件，例如用于 Edge TTS 的 `microsoft`。旧版 `edge` provider id 可作为 `microsoft` 的别名使用。 +- `providers.openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置，然后是 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 +- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型/语音校验。 --- -## Talk +## talk -Talk 模式的默认值（macOS / iOS / Android）。 +Talk 模式（macOS/iOS/Android）的默认值。 ```json5 { @@ -1328,15 +1329,15 @@ Talk 模式的默认值（macOS / iOS / Android）。 } ``` -- `talk.provider` 在配置了多个 Talk 提供商时，必须匹配 `talk.providers` 中的某个键。 -- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.` 中。 +- `talk.provider` 在配置了多个 Talk 提供商时，必须匹配 `talk.providers` 中的一个键。 +- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.`。 - 语音 id 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 - `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 -- 只有在未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。 -- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 -- `providers.mlx.modelId` 用于选择 macOS 本地 MLX helper 所使用的 Hugging Face 仓库。如果省略，macOS 会使用 `mlx-community/Soprano-80M-bf16`。 -- macOS MLX 播放会在存在时通过内置的 `openclaw-mlx-tts` helper 运行，否则使用 `PATH` 上的可执行文件；开发时可通过 `OPENCLAW_MLX_TTS_BIN` 覆盖 helper 路径。 -- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多长时间再发送转录。未设置时会保持平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- `ELEVENLABS_API_KEY` 回退仅在未配置 Talk API key 时生效。 +- `providers.*.voiceAliases` 让 Talk 指令可以使用友好名称。 +- `providers.mlx.modelId` 选择 macOS 本地 MLX helper 使用的 Hugging Face 仓库。如果省略，macOS 使用 `mlx-community/Soprano-80M-bf16`。 +- macOS MLX 播放会在存在时通过内置的 `openclaw-mlx-tts` helper 运行，或者使用 `PATH` 上的可执行文件；开发时可通过 `OPENCLAW_MLX_TTS_BIN` 覆盖 helper 路径。 +- `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多久才发送转录。未设置时会保留平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- diff --git a/docs/zh-CN/gateway/sandboxing.md b/docs/zh-CN/gateway/sandboxing.md index 8dadeb3d9..819150d38 100644 --- a/docs/zh-CN/gateway/sandboxing.md +++ b/docs/zh-CN/gateway/sandboxing.md @@ -1,54 +1,55 @@ --- read_when: You want a dedicated explanation of sandboxing or need to tune agents.defaults.sandbox. status: active -summary: OpenClaw 沙箱隔离的工作方式：模式、作用域、工作区访问和镜像 +summary: OpenClaw 沙箱隔离如何工作：模式、作用域、工作区访问和镜像 title: 沙箱隔离 x-i18n: - generated_at: "2026-04-24T03:39:45Z" + generated_at: "2026-04-25T09:15:35Z" model: gpt-5.4 provider: openai - source_hash: 07be63b71a458a17020f33a24d60e6d8d7007d4eaea686a21acabf4815c3f653 + source_hash: 4f22778690a4d41033c7abf9e97d54e53163418f8d45f1a816ce2be9d124fedf source_path: gateway/sandboxing.md workflow: 15 --- OpenClaw 可以在**沙箱后端内运行工具**，以降低影响范围。 + 这是**可选的**，并由配置控制（`agents.defaults.sandbox` 或 `agents.list[].sandbox`）。如果关闭沙箱隔离，工具会在宿主机上运行。 -Gateway 网关本身保持在宿主机上；启用后，工具执行会在隔离的沙箱中运行。 +Gateway 网关会继续运行在宿主机上；启用后，工具执行会在隔离的沙箱中进行。 -这并不是一个完美的安全边界，但当模型做出错误操作时，它能显著限制文件系统 +这并不是一个完美的安全边界，但当模型做出愚蠢操作时，它能显著限制文件系统 和进程访问。 -## 哪些内容会进入沙箱 +## 什么会被沙箱隔离 - 工具执行（`exec`、`read`、`write`、`edit`、`apply_patch`、`process` 等）。 - 可选的沙箱隔离浏览器（`agents.defaults.sandbox.browser`）。 - 默认情况下，当浏览器工具需要它时，沙箱浏览器会自动启动（确保 CDP 可达）。 通过 `agents.defaults.sandbox.browser.autoStart` 和 `agents.defaults.sandbox.browser.autoStartTimeoutMs` 配置。 - - 默认情况下，沙箱浏览器容器会使用专用的 Docker 网络（`openclaw-sandbox-browser`），而不是全局 `bridge` 网络。 - 通过 `agents.defaults.sandbox.browser.network` 配置。 - - 可选的 `agents.defaults.sandbox.browser.cdpSourceRange` 可使用 CIDR 允许列表限制容器边缘的 CDP 入站访问（例如 `172.21.0.1/32`）。 - - noVNC 观察者访问默认受密码保护；OpenClaw 会生成一个短时有效的 token URL，用于提供本地 bootstrap 页面，并通过 URL fragment（而不是 query/header 日志）在 noVNC 中携带密码打开。 - - `agents.defaults.sandbox.browser.allowHostControl` 允许沙箱会话显式将宿主机浏览器作为目标。 - - 可选允许列表可对 `target: "custom"` 进行限制：`allowedControlUrls`、`allowedControlHosts`、`allowedControlPorts`。 + - 默认情况下，沙箱浏览器容器使用专用的 Docker 网络（`openclaw-sandbox-browser`），而不是全局的 `bridge` 网络。 + 使用 `agents.defaults.sandbox.browser.network` 配置。 + - 可选的 `agents.defaults.sandbox.browser.cdpSourceRange` 可通过 CIDR 允许列表限制容器边界的 CDP 入站连接（例如 `172.21.0.1/32`）。 + - noVNC 观察者访问默认受密码保护；OpenClaw 会生成一个短期有效的令牌 URL，用于提供本地引导页面，并在 URL 片段中（而非查询参数 / 请求头日志中）携带密码打开 noVNC。 + - `agents.defaults.sandbox.browser.allowHostControl` 允许沙箱隔离会话显式将目标指向宿主机浏览器。 + - 可选允许列表可限制 `target: "custom"`：`allowedControlUrls`、`allowedControlHosts`、`allowedControlPorts`。 -不会进入沙箱的内容： +不会被沙箱隔离的内容： - Gateway 网关进程本身。 -- 任何被显式允许在沙箱外运行的工具（例如 `tools.elevated`）。 - - **提升权限的 `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`；当 exec 目标为 `node` 时则为 `node`）。** - - 如果关闭了沙箱隔离，`tools.elevated` 不会改变执行行为（本来就在宿主机上运行）。参见 [Elevated Mode](/zh-CN/tools/elevated)。 +- 任何被明确允许在沙箱外运行的工具（例如 `tools.elevated`）。 + - **提权 exec 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，或者当 exec 目标为 `node` 时使用 `node`）。** + - 如果沙箱隔离已关闭，`tools.elevated` 不会改变执行行为（本来就在宿主机上运行）。参见 [Elevated Mode](/zh-CN/tools/elevated)。 ## 模式 `agents.defaults.sandbox.mode` 控制**何时**使用沙箱隔离： - `"off"`：不使用沙箱隔离。 -- `"non-main"`：仅对**非主**会话使用沙箱隔离（如果你希望普通聊天仍在宿主机上运行，这是默认推荐值）。 -- `"all"`：每个会话都在沙箱中运行。 - 注意：`"non-main"` 基于 `session.mainKey`（默认 `"main"`），而不是基于智能体 id。 - 群组/渠道会话使用各自的 key，因此它们会被视为非主会话，并进入沙箱。 +- `"non-main"`：仅对**非主**会话启用沙箱隔离（如果你希望普通聊天运行在宿主机上，这是默认选择）。 +- `"all"`：所有会话都在沙箱中运行。 + 注意：`"non-main"` 是基于 `session.mainKey`（默认值为 `"main"`），而不是基于智能体 id。 + 群组 / 渠道会话使用它们自己的键，因此会被视为非主会话，并会被沙箱隔离。 ## 作用域 @@ -56,48 +57,48 @@ Gateway 网关本身保持在宿主机上；启用后，工具执行会在隔离 - `"agent"`（默认）：每个智能体一个容器。 - `"session"`：每个会话一个容器。 -- `"shared"`：所有启用沙箱的会话共享一个容器。 +- `"shared"`：所有已启用沙箱隔离的会话共享一个容器。 ## 后端 -`agents.defaults.sandbox.backend` 控制**由哪种运行时**提供沙箱： +`agents.defaults.sandbox.backend` 控制**由哪个运行时**提供沙箱： -- `"docker"`（启用沙箱隔离时的默认值）：本地 Docker 支持的沙箱运行时。 -- `"ssh"`：通用的 SSH 支持远程沙箱运行时。 -- `"openshell"`：OpenShell 支持的沙箱运行时。 +- `"docker"`（启用沙箱隔离时的默认值）：基于本地 Docker 的沙箱运行时。 +- `"ssh"`：通用的基于 SSH 的远程沙箱运行时。 +- `"openshell"`：基于 OpenShell 的沙箱运行时。 -SSH 专用配置位于 `agents.defaults.sandbox.ssh` 下。 -OpenShell 专用配置位于 `plugins.entries.openshell.config` 下。 +SSH 专属配置位于 `agents.defaults.sandbox.ssh` 下。 +OpenShell 专属配置位于 `plugins.entries.openshell.config` 下。 ### 选择后端 -| | Docker | SSH | OpenShell | -| ------------------- | -------------------------- | ---------------------- | ------------------------------------- | -| **运行位置** | 本地容器 | 任意可通过 SSH 访问的主机 | OpenShell 管理的沙箱 | -| **设置** | `scripts/sandbox-setup.sh` | SSH 密钥 + 目标主机 | 启用 OpenShell 插件 | -| **工作区模型** | Bind-mount 或复制 | 远程为准（初始化一次） | `mirror` 或 `remote` | -| **网络控制** | `docker.network`（默认：none） | 取决于远程主机 | 取决于 OpenShell | -| **浏览器沙箱** | 支持 | 不支持 | 尚不支持 | -| **Bind mounts** | `docker.binds` | 不适用 | 不适用 | -| **最适合** | 本地开发、完全隔离 | 卸载到远程机器运行 | 由托管远程沙箱提供，并可选双向同步 | +| | Docker | SSH | OpenShell | +| ------------------- | --------------------------- | ------------------------ | -------------------------------------- | +| **运行位置** | 本地容器 | 任意可通过 SSH 访问的主机 | OpenShell 管理的沙箱 | +| **设置** | `scripts/sandbox-setup.sh` | SSH 密钥 + 目标主机 | 启用 OpenShell 插件 | +| **工作区模型** | 绑定挂载或复制 | 远程为准（一次性初始化） | `mirror` 或 `remote` | +| **网络控制** | `docker.network`（默认：无） | 取决于远程主机 | 取决于 OpenShell | +| **浏览器沙箱** | 支持 | 不支持 | 尚不支持 | +| **绑定挂载** | `docker.binds` | 不适用 | 不适用 | +| **最适合** | 本地开发、完整隔离 | 卸载到远程机器执行 | 受管远程沙箱，并可选择双向同步 | ### Docker 后端 -默认情况下，沙箱隔离是关闭的。如果你启用了沙箱隔离但未选择 -后端，OpenClaw 会使用 Docker 后端。它通过 Docker daemon socket（`/var/run/docker.sock`） -在本地执行工具和沙箱浏览器。沙箱容器的隔离性由 Docker namespaces 决定。 +默认情况下，沙箱隔离是关闭的。如果你启用了沙箱隔离但没有选择 +后端，OpenClaw 会使用 Docker 后端。它通过 Docker 守护进程套接字（`/var/run/docker.sock`）在本地执行工具和沙箱浏览器。沙箱容器的 +隔离由 Docker 命名空间决定。 **Docker-out-of-Docker（DooD）约束**： -如果你将 OpenClaw Gateway 网关本身部署为 Docker 容器，它会通过宿主机的 Docker socket（DooD）来编排同级沙箱容器。这会带来一个特定的路径映射约束： +如果你将 OpenClaw Gateway 网关本身部署为 Docker 容器，它会通过宿主机的 Docker 套接字（DooD）编排同级沙箱容器。这会引入一个特定的路径映射约束： -- **配置必须使用宿主机路径**：`openclaw.json` 中的 `workspace` 配置**必须**包含**宿主机的绝对路径**（例如 `/home/user/.openclaw/workspaces`），而不是 Gateway 网关容器内部路径。当 OpenClaw 请求 Docker daemon 启动一个沙箱时，daemon 会相对于宿主机操作系统命名空间来解析路径，而不是 Gateway 网关命名空间。 -- **FS Bridge 一致性（完全相同的卷映射）**：OpenClaw Gateway 网关原生进程也会将 heartbeat 和 bridge 文件写入 `workspace` 目录。由于 Gateway 网关在其自身容器化环境中也会使用同一个精确的字符串（即宿主机路径）进行解析，因此 Gateway 网关部署**必须**包含一个完全相同的卷映射，以便原生链接宿主机命名空间（`-v /home/user/.openclaw:/home/user/.openclaw`）。 +- **配置必须使用宿主机路径**：`openclaw.json` 中的 `workspace` 配置必须包含**宿主机的绝对路径**（例如 `/home/user/.openclaw/workspaces`），而不是 Gateway 网关容器内部路径。当 OpenClaw 请求 Docker 守护进程生成沙箱时，守护进程会相对于宿主机 OS 命名空间解析路径，而不是 Gateway 网关命名空间。 +- **文件系统桥接一致性（完全相同的卷映射）**：OpenClaw Gateway 网关原生进程也会将心跳和桥接文件写入 `workspace` 目录。由于 Gateway 网关会在它自己的容器化环境中，以完全相同的字符串（宿主机路径）进行解析，因此 Gateway 网关部署必须包含完全相同的卷映射，以便原生链接到宿主机命名空间（`-v /home/user/.openclaw:/home/user/.openclaw`）。 -如果你只在容器内部映射路径，而没有与宿主机绝对路径保持一致，OpenClaw 在容器环境中尝试写入 heartbeat 时会原生抛出 `EACCES` 权限错误，因为这个完全限定路径字符串在原生环境中并不存在。 +如果你仅在容器内部映射路径，而没有与宿主机绝对路径保持一致，OpenClaw 在容器环境中尝试写入心跳文件时会原生抛出 `EACCES` 权限错误，因为这个完整限定路径字符串在原生环境中并不存在。 ### SSH 后端 -当你希望 OpenClaw 在任意可通过 SSH 访问的机器上，对 `exec`、文件工具和媒体读取进行沙箱隔离时，请使用 `backend: "ssh"`。 +当你希望 OpenClaw 在任意可通过 SSH 访问的机器上对 `exec`、文件工具和媒体读取进行沙箱隔离时，使用 `backend: "ssh"`。 ```json5 { @@ -116,7 +117,7 @@ OpenShell 专用配置位于 `plugins.entries.openshell.config` 下。 identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // 或者使用 SecretRefs / 内联内容，而不是本地文件： + // Or use SecretRefs / inline contents instead of local files: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -127,33 +128,35 @@ OpenShell 专用配置位于 `plugins.entries.openshell.config` 下。 } ``` -工作方式如下： +其工作方式如下： -- OpenClaw 会在 `sandbox.ssh.workspaceRoot` 下，为每个作用域创建一个远程根目录。 -- 在创建或重建后的首次使用时，OpenClaw 会先将本地工作区一次性播种到远程工作区。 -- 此后，`exec`、`read`、`write`、`edit`、`apply_patch`、提示媒体读取以及入站媒体暂存，都会通过 SSH 直接作用于远程工作区。 +- OpenClaw 会在 `sandbox.ssh.workspaceRoot` 下为每个作用域创建一个远程根目录。 +- 在创建或重建后的首次使用时，OpenClaw 会将本地工作区初始化到该远程工作区一次。 +- 之后，`exec`、`read`、`write`、`edit`、`apply_patch`、提示词媒体读取以及入站媒体暂存，都会直接通过 SSH 针对远程工作区执行。 - OpenClaw 不会自动将远程变更同步回本地工作区。 认证材料： -- `identityFile`、`certificateFile`、`knownHostsFile`：使用现有本地文件，并通过 OpenSSH 配置传入。 -- `identityData`、`certificateData`、`knownHostsData`：使用内联字符串或 SecretRefs。OpenClaw 会通过常规 secrets 运行时快照解析它们，将其写入权限为 `0600` 的临时文件，并在 SSH 会话结束时删除。 -- 如果同一项同时设置了 `*File` 和 `*Data`，则该 SSH 会话中 `*Data` 优先。 +- `identityFile`、`certificateFile`、`knownHostsFile`：使用现有本地文件，并通过 OpenSSH 配置传递。 +- `identityData`、`certificateData`、`knownHostsData`：使用内联字符串或 SecretRefs。OpenClaw 会通过常规 secrets 运行时快照解析它们，将其以 `0600` 权限写入临时文件，并在 SSH 会话结束时删除。 +- 如果同一项同时设置了 `*File` 和 `*Data`，则该 SSH 会话优先使用 `*Data`。 -这是一个**以远程为准**的模型。初始播种后，远程 SSH 工作区会成为真正的沙箱状态。 +这是一个**远程为准**模型。初始初始化完成后，远程 SSH 工作区就成为真实的沙箱状态。 重要影响： -- 在播种步骤之后，如果你在 OpenClaw 之外对宿主机本地做了编辑，这些更改在远程端不可见，直到你重建沙箱。 -- `openclaw sandbox recreate` 会删除每个作用域对应的远程根目录，并在下次使用时重新从本地播种。 +- 在初始化步骤之后，如果你在 OpenClaw 外部对宿主机本地文件进行了编辑，远程端不会看到这些更改，除非你重建沙箱。 +- `openclaw sandbox recreate` 会删除每个作用域的远程根目录，并在下次使用时重新从本地初始化。 - SSH 后端不支持浏览器沙箱隔离。 - `sandbox.docker.*` 设置不适用于 SSH 后端。 ### OpenShell 后端 -当你希望 OpenClaw 在 OpenShell 管理的远程环境中对工具进行沙箱隔离时，请使用 `backend: "openshell"`。完整的设置指南、配置参考和工作区模式对比，请参见专门的 [OpenShell 页面](/zh-CN/gateway/openshell)。 +当你希望 OpenClaw 在 OpenShell 管理的远程环境中对工具进行沙箱隔离时，使用 `backend: "openshell"`。有关完整设置指南、配置 +参考以及工作区模式对比，请参见专门的 +[OpenShell 页面](/zh-CN/gateway/openshell)。 -OpenShell 复用了与通用 SSH 后端相同的核心 SSH 传输和远程文件系统桥接，并增加了 OpenShell 特有的生命周期管理 +OpenShell 复用了与通用 SSH 后端相同的核心 SSH 传输和远程文件系统桥接，并增加了 OpenShell 专属生命周期 （`sandbox create/get/delete`、`sandbox ssh-config`），以及可选的 `mirror` 工作区模式。 @@ -187,121 +190,121 @@ OpenShell 复用了与通用 SSH 后端相同的核心 SSH 传输和远程文件 OpenShell 模式： -- `mirror`（默认）：本地工作区保持为准。OpenClaw 会在执行 `exec` 前将本地文件同步到 OpenShell，并在 `exec` 后将远程工作区同步回本地。 -- `remote`：沙箱创建后，OpenShell 工作区成为准来源。OpenClaw 会先从本地工作区向远程工作区进行一次播种，此后文件工具和 `exec` 都会直接作用于远程沙箱，而不会把变更同步回来。 +- `mirror`（默认）：本地工作区保持为准。OpenClaw 会在 exec 之前将本地文件同步到 OpenShell，并在 exec 之后将远程工作区同步回本地。 +- `remote`：沙箱创建后，OpenShell 工作区成为准本。OpenClaw 会从本地工作区向远程工作区初始化一次，之后文件工具和 exec 会直接针对远程沙箱运行，而不会将更改同步回本地。 远程传输细节： -- OpenClaw 会通过 `openshell sandbox ssh-config ` 向 OpenShell 请求特定沙箱的 SSH 配置。 -- 核心层会将该 SSH 配置写入临时文件，打开 SSH 会话，并复用 `backend: "ssh"` 所使用的同一远程文件系统桥接。 -- 只有在 `mirror` 模式下，生命周期才有所不同：执行 `exec` 前从本地同步到远程，执行后再同步回来。 +- OpenClaw 会通过 `openshell sandbox ssh-config ` 向 OpenShell 请求沙箱专属 SSH 配置。 +- 核心会将该 SSH 配置写入临时文件，打开 SSH 会话，并复用 `backend: "ssh"` 使用的同一个远程文件系统桥接。 +- 仅在 `mirror` 模式下生命周期不同：在 exec 之前将本地同步到远程，然后在 exec 之后同步回来。 当前 OpenShell 的限制： -- 尚不支持沙箱浏览器 +- 尚不支持 sandbox 浏览器 - OpenShell 后端不支持 `sandbox.docker.binds` -- `sandbox.docker.*` 下的 Docker 专用运行时控制项仍然只适用于 Docker 后端 +- `sandbox.docker.*` 下的 Docker 专属运行时参数仍然仅适用于 Docker 后端 #### 工作区模式 -OpenShell 有两种工作区模型。这是实践中最关键的部分。 +OpenShell 有两种工作区模型。实际上，这部分最为重要。 ##### `mirror` -当你希望**本地工作区保持为准**时，请使用 `plugins.entries.openshell.config.mode: "mirror"`。 +当你希望**本地工作区保持为准**时，使用 `plugins.entries.openshell.config.mode: "mirror"`。 行为： - 在 `exec` 之前，OpenClaw 会将本地工作区同步到 OpenShell 沙箱中。 - 在 `exec` 之后，OpenClaw 会将远程工作区同步回本地工作区。 -- 文件工具仍然通过沙箱桥接运行，但在每轮之间，本地工作区仍是事实来源。 +- 文件工具仍通过沙箱桥接运行，但在各轮之间，本地工作区仍然是事实来源。 适用场景： -- 你会在 OpenClaw 之外本地编辑文件，并希望这些更改自动出现在沙箱中 +- 你会在 OpenClaw 外部本地编辑文件，并希望这些变更自动出现在沙箱中 - 你希望 OpenShell 沙箱的行为尽可能接近 Docker 后端 -- 你希望宿主机工作区在每次 `exec` 轮次后都能反映沙箱写入结果 +- 你希望宿主机工作区在每次 exec 轮次之后反映沙箱写入结果 代价： -- 在每次 `exec` 前后都会产生额外的同步成本 +- exec 前后会产生额外的同步开销 ##### `remote` -当你希望**OpenShell 工作区成为准来源**时，请使用 `plugins.entries.openshell.config.mode: "remote"`。 +当你希望**OpenShell 工作区成为准本**时，使用 `plugins.entries.openshell.config.mode: "remote"`。 行为： -- 当沙箱首次创建时，OpenClaw 会先将本地工作区一次性播种到远程工作区。 -- 此后，`exec`、`read`、`write`、`edit` 和 `apply_patch` 都会直接作用于远程 OpenShell 工作区。 -- OpenClaw 在执行 `exec` 之后**不会**将远程更改同步回本地工作区。 -- 提示阶段的媒体读取仍然可用，因为文件和媒体工具会通过沙箱桥接读取，而不是假定使用本地主机路径。 -- 传输层通过 SSH 连接到由 `openshell sandbox ssh-config` 返回的 OpenShell 沙箱。 +- 当沙箱首次创建时，OpenClaw 会先将本地工作区初始化到远程工作区一次。 +- 之后，`exec`、`read`、`write`、`edit` 和 `apply_patch` 会直接针对远程 OpenShell 工作区运行。 +- OpenClaw 在 exec 后**不会**将远程变更同步回本地工作区。 +- 提示阶段的媒体读取仍然可用，因为文件和媒体工具是通过沙箱桥接读取，而不是假定存在本地宿主机路径。 +- 传输方式是通过 SSH 连接到 `openshell sandbox ssh-config` 返回的 OpenShell 沙箱。 重要影响： -- 如果你在播种步骤之后，在 OpenClaw 之外于宿主机上编辑文件，远程沙箱将**不会**自动看到这些更改。 -- 如果沙箱被重建，远程工作区会再次从本地工作区重新播种。 -- 如果使用 `scope: "agent"` 或 `scope: "shared"`，该远程工作区也会在相同作用域内共享。 +- 如果你在初始化步骤后于 OpenClaw 外部在宿主机上编辑文件，远程沙箱**不会**自动看到这些更改。 +- 如果沙箱被重建，远程工作区会再次从本地工作区初始化。 +- 当使用 `scope: "agent"` 或 `scope: "shared"` 时，该远程工作区也会在相同作用域内共享。 适用场景： -- 沙箱应主要驻留在远程 OpenShell 一侧 -- 你希望降低每轮同步开销 -- 你不希望宿主机本地编辑在无提示的情况下覆盖远程沙箱状态 +- 沙箱应主要存在于远程 OpenShell 一侧 +- 你希望降低每轮的同步开销 +- 你不希望宿主机本地编辑悄悄覆盖远程沙箱状态 -如果你将沙箱视为一个临时执行环境，请选择 `mirror`。 +如果你将沙箱视为临时执行环境，请选择 `mirror`。 如果你将沙箱视为真实工作区，请选择 `remote`。 #### OpenShell 生命周期 -OpenShell 沙箱仍然通过常规沙箱生命周期进行管理： +OpenShell 沙箱仍通过常规沙箱生命周期进行管理： - `openclaw sandbox list` 会显示 OpenShell 运行时以及 Docker 运行时 - `openclaw sandbox recreate` 会删除当前运行时，并让 OpenClaw 在下次使用时重新创建它 -- 清理逻辑同样具备后端感知能力 +- 清理逻辑同样会识别后端类型 -对于 `remote` 模式，recreate 尤其重要： +对于 `remote` 模式，recreate 特别重要： -- recreate 会删除该作用域下作为准来源的远程工作区 -- 下次使用时会从本地工作区重新播种一个新的远程工作区 +- recreate 会删除该作用域的规范远程工作区 +- 下次使用时会从本地工作区初始化一个新的远程工作区 对于 `mirror` 模式，recreate 主要是重置远程执行环境， -因为本地工作区本来就保持为准来源。 +因为无论如何本地工作区仍然是准本。 ## 工作区访问 -`agents.defaults.sandbox.workspaceAccess` 控制**沙箱能看到什么**： +`agents.defaults.sandbox.workspaceAccess` 控制**沙箱可以看到什么**： -- `"none"`（默认）：工具只能看到位于 `~/.openclaw/sandboxes` 下的沙箱工作区。 -- `"ro"`：将智能体工作区以只读方式挂载到 `/agent`（会禁用 `write`/`edit`/`apply_patch`）。 +- `"none"`（默认）：工具只能看到 `~/.openclaw/sandboxes` 下的沙箱工作区。 +- `"ro"`：将智能体工作区以只读方式挂载到 `/agent`（会禁用 `write` / `edit` / `apply_patch`）。 - `"rw"`：将智能体工作区以读写方式挂载到 `/workspace`。 -在 OpenShell 后端中： +使用 OpenShell 后端时： -- `mirror` 模式仍然在每次 `exec` 轮次之间使用本地工作区作为准来源 -- `remote` 模式在初始播种后使用远程 OpenShell 工作区作为准来源 +- `mirror` 模式仍然在各个 exec 轮次之间使用本地工作区作为准本来源 +- `remote` 模式在初次初始化后使用远程 OpenShell 工作区作为准本来源 - `workspaceAccess: "ro"` 和 `"none"` 仍会以相同方式限制写入行为 -入站媒体会被复制到活动沙箱工作区中（`media/inbound/*`）。 -Skills 说明：`read` 工具以沙箱根目录为基准。在 `workspaceAccess: "none"` 时， +入站媒体会被复制到当前沙箱工作区（`media/inbound/*`）。 +Skills 注意：`read` 工具以沙箱根目录为根。使用 `workspaceAccess: "none"` 时， OpenClaw 会将符合条件的 Skills 镜像到沙箱工作区（`.../skills`）中， -使其可被读取。在 `"rw"` 下，工作区中的 Skills 可从 -`/workspace/skills` 读取。 +以便能够读取它们。使用 `"rw"` 时，可从 +`/workspace/skills` 读取工作区 Skills。 -## 自定义 bind mounts +## 自定义绑定挂载 `agents.defaults.sandbox.docker.binds` 会将额外的宿主机目录挂载到容器中。 格式：`host:container:mode`（例如 `"/home/user/source:/source:rw"`）。 -全局和每智能体的 binds 会**合并**，而不是相互替换。在 `scope: "shared"` 下，每智能体 binds 会被忽略。 +全局和每个智能体的 binds 会**合并**，而不是替换。在 `scope: "shared"` 下，会忽略每个智能体的 binds。 -`agents.defaults.sandbox.browser.binds` 会仅将额外宿主机目录挂载到**沙箱浏览器**容器中。 +`agents.defaults.sandbox.browser.binds` 仅会将额外的宿主机目录挂载到**沙箱浏览器**容器中。 -- 设置后（包括设为 `[]`），它会在浏览器容器中替代 `agents.defaults.sandbox.docker.binds`。 -- 如果省略，浏览器容器会回退到 `agents.defaults.sandbox.docker.binds`（向后兼容）。 +- 设置后（包括 `[]`），它会替代浏览器容器中的 `agents.defaults.sandbox.docker.binds`。 +- 未设置时，浏览器容器会回退使用 `agents.defaults.sandbox.docker.binds`（向后兼容）。 -示例（只读源码 + 一个额外的数据目录）： +示例（只读源码 + 一个额外数据目录）： ```json5 { @@ -327,33 +330,34 @@ OpenClaw 会将符合条件的 Skills 镜像到沙箱工作区（`.../skills`） } ``` -安全说明： +安全注意事项： -- Binds 会绕过沙箱文件系统：它们会以你设置的模式（`:ro` 或 `:rw`）暴露宿主机路径。 -- OpenClaw 会阻止危险的 bind 源（例如：`docker.sock`、`/etc`、`/proc`、`/sys`、`/dev`，以及会暴露这些路径的父级挂载点）。 -- OpenClaw 也会阻止常见的主目录凭据根路径，例如 `~/.aws`、`~/.cargo`、`~/.config`、`~/.docker`、`~/.gnupg`、`~/.netrc`、`~/.npm` 和 `~/.ssh`。 -- Bind 校验不只是字符串匹配。OpenClaw 会先规范化源路径，然后通过最深的现有祖先路径再次解析，再重新检查受阻路径和允许根路径。 -- 这意味着即使最终叶子路径还不存在，利用父级符号链接逃逸的方式也会被安全拒绝。例如：如果 `run-link` 指向该位置，那么 `/workspace/run-link/new-file` 仍会解析为 `/var/run/...`。 -- 允许的源根路径也会以同样方式进行规范化，因此一个在符号链接解析前看起来位于允许列表内的路径，仍可能因 `outside allowed roots` 而被拒绝。 -- 敏感挂载（secrets、SSH 密钥、服务凭据）除非绝对必要，否则应使用 `:ro`。 -- 如果你只需要对工作区进行只读访问，可结合 `workspaceAccess: "ro"` 一起使用；bind 模式仍然独立生效。 -- 参见 [Sandbox vs Tool Policy vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated)，了解 binds 如何与工具策略和提升权限 exec 交互。 +- 绑定挂载会绕过沙箱文件系统：它们会以你设置的模式（`:ro` 或 `:rw`）暴露宿主机路径。 +- OpenClaw 会阻止危险的绑定来源（例如：`docker.sock`、`/etc`、`/proc`、`/sys`、`/dev`，以及会暴露它们的父级挂载）。 +- OpenClaw 还会阻止常见的家目录凭证根路径，例如 `~/.aws`、`~/.cargo`、`~/.config`、`~/.docker`、`~/.gnupg`、`~/.netrc`、`~/.npm` 和 `~/.ssh`。 +- 绑定校验不只是字符串匹配。OpenClaw 会先规范化源路径，然后通过最深层已存在祖先路径再次解析，之后再重新检查被阻止路径和允许根路径。 +- 这意味着即使最终叶子节点尚不存在，父级符号链接逃逸也仍会以关闭方式失败。示例：如果 `run-link` 指向那里，`/workspace/run-link/new-file` 仍会解析为 `/var/run/...`。 +- 允许的源根路径也会以相同方式规范化，因此某个路径即使在符号链接解析前看起来位于允许列表内，仍可能因 `outside allowed roots` 而被拒绝。 +- 敏感挂载（secrets、SSH 密钥、服务凭证）除非绝对必要，否则应使用 `:ro`。 +- 如果你只需要对工作区的读取权限，可结合 `workspaceAccess: "ro"` 使用；绑定模式仍然彼此独立。 +- 有关 binds 如何与工具策略和提权 exec 交互，请参见 [Sandbox vs Tool Policy vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated)。 ## 镜像 + 设置 默认 Docker 镜像：`openclaw-sandbox:bookworm-slim` -构建一次： +构建一次即可： ```bash scripts/sandbox-setup.sh ``` -注意：默认镜像**不**包含 Node。如果某个 Skill 需要 Node（或其他运行时），可以选择构建自定义镜像，或通过 +注意：默认镜像**不**包含 Node。如果某个 Skill 需要 Node（或 +其他运行时），你可以构建自定义镜像，或者通过 `sandbox.docker.setupCommand` 安装（需要网络出口 + 可写根文件系统 + root 用户）。 -如果你想使用一个功能更完整、带有常见工具（例如 +如果你想要一个功能更完整、包含常用工具（例如 `curl`、`jq`、`nodejs`、`python3`、`git`）的沙箱镜像，请构建： ```bash @@ -369,10 +373,10 @@ scripts/sandbox-common-setup.sh scripts/sandbox-browser-setup.sh ``` -默认情况下，Docker 沙箱容器运行时**没有网络**。 +默认情况下，Docker 沙箱容器**没有网络**。 可通过 `agents.defaults.sandbox.docker.network` 覆盖。 -内置的沙箱浏览器镜像还会为容器化工作负载应用较为保守的 Chromium 启动默认值。 +内置的沙箱浏览器镜像还会为容器化工作负载应用保守的 Chromium 启动默认值。 当前容器默认值包括： - `--remote-debugging-address=127.0.0.1` @@ -392,69 +396,69 @@ scripts/sandbox-browser-setup.sh - `--no-zygote` - `--metrics-recording-only` - `--renderer-process-limit=2` -- 在启用 `noSandbox` 时，使用 `--no-sandbox` 和 `--disable-setuid-sandbox`。 +- 启用 `noSandbox` 时使用 `--no-sandbox`。 - 三个图形强化标志（`--disable-3d-apis`、 - `--disable-software-rasterizer`、`--disable-gpu`）是可选的，在容器缺乏 GPU 支持时很有用。如果你的工作负载需要 WebGL 或其他 3D/浏览器特性，请设置 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`。 -- `--disable-extensions` 默认启用；对于依赖扩展的流程，可通过 - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 禁用它。 + `--disable-software-rasterizer`、`--disable-gpu`）是可选的；当容器缺少 GPU 支持时会很有用。如果你的工作负载需要 WebGL 或其他 3D / 浏览器功能，请设置 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`。 +- `--disable-extensions` 默认启用，可通过 + `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 关闭，以支持依赖扩展的流程。 - `--renderer-process-limit=2` 由 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 控制，其中 `0` 表示保留 Chromium 默认值。 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 控制，其中 `0` 会保留 Chromium 的默认值。 如果你需要不同的运行时配置，请使用自定义浏览器镜像并提供 -你自己的 entrypoint。对于本地（非容器）Chromium 配置，请使用 -`browser.extraArgs` 来追加额外的启动标志。 +你自己的入口点。对于本地（非容器）Chromium 配置，使用 +`browser.extraArgs` 追加额外启动标志。 安全默认值： - `network: "host"` 会被阻止。 - `network: "container:"` 默认会被阻止（存在命名空间加入绕过风险）。 -- 破玻璃覆盖项：`agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`。 +- 破窗覆盖：`agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`。 Docker 安装和容器化 Gateway 网关部署说明见： [Docker](/zh-CN/install/docker) 对于 Docker Gateway 网关部署，`scripts/docker/setup.sh` 可以引导生成沙箱配置。 -设置 `OPENCLAW_SANDBOX=1`（或 `true`/`yes`/`on`）即可启用该路径。你也可以 -通过 `OPENCLAW_DOCKER_SOCKET` 覆盖 socket 位置。完整设置与环境变量 +设置 `OPENCLAW_SANDBOX=1`（或 `true` / `yes` / `on`）可启用该路径。你还可以 +使用 `OPENCLAW_DOCKER_SOCKET` 覆盖套接字位置。完整设置和环境变量 参考： [Docker](/zh-CN/install/docker#agent-sandbox)。 -## `setupCommand`（一次性容器设置） +## setupCommand（一次性容器设置） -`setupCommand` 会在沙箱容器创建后**只运行一次**（而不是每次运行都执行）。 +`setupCommand` 会在沙箱容器创建后**运行一次**（而不是每次运行都执行）。 它会通过 `sh -lc` 在容器内执行。 路径： - 全局：`agents.defaults.sandbox.docker.setupCommand` -- 每智能体：`agents.list[].sandbox.docker.setupCommand` +- 每个智能体：`agents.list[].sandbox.docker.setupCommand` 常见陷阱： -- 默认 `docker.network` 为 `"none"`（无网络出口），因此安装包会失败。 -- `docker.network: "container:"` 需要设置 `dangerouslyAllowContainerNamespaceJoin: true`，并且仅应用于破玻璃场景。 -- `readOnlyRoot: true` 会阻止写入；请将 `readOnlyRoot: false`，或构建自定义镜像。 -- 安装包时 `user` 必须为 root（省略 `user` 或设置 `user: "0:0"`）。 +- 默认 `docker.network` 为 `"none"`（无出口），因此安装软件包会失败。 +- `docker.network: "container:"` 需要 `dangerouslyAllowContainerNamespaceJoin: true`，并且仅适用于破窗场景。 +- `readOnlyRoot: true` 会阻止写入；请设置 `readOnlyRoot: false` 或构建自定义镜像。 +- 安装软件包时，`user` 必须是 root（省略 `user` 或设置 `user: "0:0"`）。 - 沙箱 exec **不会**继承宿主机 `process.env`。请使用 - `agents.defaults.sandbox.docker.env`（或自定义镜像）来提供 Skill API 密钥。 + `agents.defaults.sandbox.docker.env`（或自定义镜像）为 Skill API 密钥提供环境变量。 -## 工具策略 + 逃逸通道 +## 工具策略 + 逃逸口 -工具的允许/拒绝策略仍会先于沙箱规则生效。如果某个工具在全局 -或某个智能体级别被拒绝，启用沙箱隔离也不会把它重新启用。 +在应用沙箱规则之前，工具允许 / 拒绝策略仍然会先执行。如果某个工具在全局 +或针对某个智能体被拒绝，沙箱隔离也不会把它重新启用。 -`tools.elevated` 是一个显式逃逸通道，它会让 `exec` 在沙箱外运行（默认使用 `gateway`，当 exec 目标为 `node` 时使用 `node`）。 -`/exec` 指令仅对已授权发送方生效，并按会话持久化；如果你想彻底禁用 +`tools.elevated` 是一个显式逃逸口，它会让 `exec` 在沙箱外运行（默认使用 `gateway`，当 exec 目标为 `node` 时使用 `node`）。 +`/exec` 指令仅适用于已授权发送者，并且会按会话持久化；如果要彻底禁用 `exec`，请使用工具策略 deny（参见 [Sandbox vs Tool Policy vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated)）。 调试： -- 使用 `openclaw sandbox explain` 检查实际生效的沙箱模式、工具策略和 fix-it 配置键。 -- 参见 [Sandbox vs Tool Policy vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated)，了解“为什么这里被阻止了？”的思维模型。 - 请保持严格锁定。 +- 使用 `openclaw sandbox explain` 检查实际生效的沙箱模式、工具策略以及 fix-it 配置键。 +- 关于“为什么这被阻止了？”的思考模型，请参见 [Sandbox vs Tool Policy vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated)。 + 保持严格锁定。 ## 多智能体覆盖 -每个智能体都可以覆盖沙箱和工具配置： +每个智能体都可以覆盖 sandbox + tools： `agents.list[].sandbox` 和 `agents.list[].tools`（以及用于沙箱工具策略的 `agents.list[].tools.sandbox.tools`）。 优先级请参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 @@ -476,8 +480,8 @@ Docker 安装和容器化 Gateway 网关部署说明见： ## 相关文档 -- [OpenShell](/zh-CN/gateway/openshell) -- 托管沙箱后端设置、工作区模式和配置参考 -- [沙箱配置](/zh-CN/gateway/config-agents#agentsdefaultssandbox) -- [Sandbox vs Tool Policy vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated) -- 调试“为什么这里被阻止了？” -- [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools) -- 每智能体覆盖与优先级 +- [OpenShell](/zh-CN/gateway/openshell) -- 受管沙箱后端设置、工作区模式和配置参考 +- [Sandbox Configuration](/zh-CN/gateway/config-agents#agentsdefaultssandbox) +- [Sandbox vs Tool Policy vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated) -- 调试“为什么这被阻止了？” +- [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools) -- 每个智能体的覆盖和优先级 - [Security](/zh-CN/gateway/security)