chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
2911a1255a
commit
4e958669d3
@ -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 <gatewayWsUrl>`：Gateway 网关 WebSocket URL（默认来自配置）。
|
||||
- `--token <token>`：Gateway 网关令牌（如果需要）。
|
||||
- `--timeout <ms>`：请求超时（毫秒）。
|
||||
- `--timeout <ms>`：请求超时时间（毫秒）。
|
||||
- `--expect-final`：等待最终的 Gateway 网关响应。
|
||||
- `--browser-profile <name>`：选择一个浏览器配置文件（默认来自配置）。
|
||||
- `--json`：机器可读输出（在支持的地方）。
|
||||
- `--browser-profile <name>`：选择浏览器配置文件（默认来自配置）。
|
||||
- `--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 <ref>
|
||||
```
|
||||
|
||||
文件 + 对话框辅助：
|
||||
文件与对话框辅助：
|
||||
|
||||
```bash
|
||||
openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>
|
||||
@ -178,6 +178,8 @@ openclaw browser download <ref> 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)
|
||||
|
||||
## 相关内容
|
||||
|
||||
|
||||
@ -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 '<json>' --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 '<json>' --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=<id|auto|pi>` 会覆盖 `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=<id|auto|pi>` 覆盖 `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/<model>"].params.thinking`。
|
||||
Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/<model>"].params.tool_stream` 设置为 `false` 可禁用它。
|
||||
Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `adaptive` 思考模式。
|
||||
Z.AI GLM-4.x 模型会自动启用思考模式，除非你设置 `--thinking off` 或自行定义 `agents.defaults.models["zai/<model>"].params.thinking`。
|
||||
Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/<model>"].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
|
||||
|
||||
<Accordion title="`cache-ttl` 模式行为">
|
||||
|
||||
- `mode: "cache-ttl"` 会启用修剪流程。
|
||||
- `ttl` 控制何时可以再次运行修剪（在上次缓存触碰之后）。
|
||||
- 修剪会先对过大的工具结果执行软修剪；如仍有需要，再对更旧的工具结果执行硬清除。
|
||||
- `mode: "cache-ttl"` 会启用裁剪过程。
|
||||
- `ttl` 控制多久之后才能再次运行裁剪（从上次缓存触碰后开始计算）。
|
||||
- 裁剪会先对过大的工具结果进行软裁剪，然后在需要时对更旧的工具结果执行硬清除。
|
||||
|
||||
**软修剪** 会保留开头和结尾，并在中间插入 `...`。
|
||||
**软裁剪**会保留开头和结尾，并在中间插入 `...`。
|
||||
|
||||
**硬清除** 会用占位符替换整个工具结果。
|
||||
**硬清除**会用占位符替换整个工具结果。
|
||||
|
||||
说明：
|
||||
|
||||
- 图像块永远不会被修剪 / 清除。
|
||||
- 比例基于字符数（近似值），而不是精确 token 数。
|
||||
- 如果助手消息少于 `keepLastAssistants` 条，则会跳过修剪。
|
||||
- 图像块永远不会被裁剪/清除。
|
||||
- 比例按字符计算（近似），不是精确 token 数。
|
||||
- 如果助手消息少于 `keepLastAssistants` 条，则跳过裁剪。
|
||||
|
||||
</Accordion>
|
||||
|
||||
行为详情参见 [会话修剪](/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.<channel>.blockStreamingCoalesce`（以及按账号的变体）。Signal / Slack / Discord / Google Chat 默认使用 `minChars: 1500`。
|
||||
- 渠道覆盖项：`channels.<channel>.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)。
|
||||
|
||||
<a id="agentsdefaultssandbox"></a>
|
||||
|
||||
### `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:<id>"` 默认也会被阻止，除非你显式设置
|
||||
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急放行）。
|
||||
`"host"` 被阻止。默认情况下，`"container:<id>"` 也被阻止，除非你显式设置
|
||||
`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=<derived from OPENCLAW_BROWSER_CDP_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=<N>` 更改；设置为 `0` 会使用 Chromium 的
|
||||
默认启用；如果你的工作流需要 WebGL/3D，可通过
|
||||
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。
|
||||
- 如果你的工作流依赖扩展，使用
|
||||
`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 可重新启用扩展。
|
||||
- `--renderer-process-limit=2` 可以通过
|
||||
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 修改；设为 `0` 可使用 Chromium 的
|
||||
默认进程限制。
|
||||
- 另外，当启用 `noSandbox` 时，还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。
|
||||
- 这些默认值是容器镜像基线；如需更改容器默认行为，请使用自定义浏览器镜像和自定义
|
||||
入口点。
|
||||
- 当启用 `noSandbox` 时，还会附加 `--no-sandbox`。
|
||||
- 这些默认值属于容器镜像基线；如需更改容器默认值，请使用带自定义入口点的自定义浏览器镜像。
|
||||
|
||||
</Accordion>
|
||||
|
||||
浏览器沙箱隔离和 `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 绑定层级顺序。
|
||||
|
||||
### 按智能体划分的访问配置
|
||||
### 按智能体访问配置
|
||||
|
||||
<Accordion title="完全访问（无沙箱）">
|
||||
|
||||
@ -1090,7 +1091,7 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像
|
||||
|
||||
</Accordion>
|
||||
|
||||
有关优先级细节，参见 [多智能体沙箱隔离与工具](/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 # 可选的浏览器镜像
|
||||
<Accordion title="会话字段详情">
|
||||
|
||||
- **`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.<timestamp>` 转录归档的保留时长。默认与 `pruneAfter` 相同；设置为 `false` 可禁用。
|
||||
- `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下记录警告；在 `enforce` 模式下会优先删除最旧的产物 / 会话。
|
||||
- `maxEntries`：`sessions.json` 中条目的最大数量（默认 `500`）。
|
||||
- `rotateBytes`：当 `sessions.json` 超过此大小时执行轮转（默认 `10mb`）。
|
||||
- `resetArchiveRetention`：`*.reset.<timestamp>` 转录归档的保留时长。默认等于 `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` 表示禁用；提供商可覆盖）
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -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.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.responsePrefix`。
|
||||
按渠道/账号的覆盖项：`channels.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.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.<channel>.ackReaction`、`channels.<channel>.accounts.<id>.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.<provider>` 中。
|
||||
- `talk.provider` 在配置了多个 Talk 提供商时，必须匹配 `talk.providers` 中的一个键。
|
||||
- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.<provider>`。
|
||||
- 语音 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`）。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -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 <name>` 向 OpenShell 请求特定沙箱的 SSH 配置。
|
||||
- 核心层会将该 SSH 配置写入临时文件，打开 SSH 会话，并复用 `backend: "ssh"` 所使用的同一远程文件系统桥接。
|
||||
- 只有在 `mirror` 模式下，生命周期才有所不同：执行 `exec` 前从本地同步到远程，执行后再同步回来。
|
||||
- OpenClaw 会通过 `openshell sandbox ssh-config <name>` 向 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=<N>` 控制，其中 `0` 表示保留 Chromium 默认值。
|
||||
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 控制，其中 `0` 会保留 Chromium 的默认值。
|
||||
|
||||
如果你需要不同的运行时配置，请使用自定义浏览器镜像并提供
|
||||
你自己的 entrypoint。对于本地（非容器）Chromium 配置，请使用
|
||||
`browser.extraArgs` 来追加额外的启动标志。
|
||||
你自己的入口点。对于本地（非容器）Chromium 配置，使用
|
||||
`browser.extraArgs` 追加额外启动标志。
|
||||
|
||||
安全默认值：
|
||||
|
||||
- `network: "host"` 会被阻止。
|
||||
- `network: "container:<id>"` 默认会被阻止（存在命名空间加入绕过风险）。
|
||||
- 破玻璃覆盖项：`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:<id>"` 需要设置 `dangerouslyAllowContainerNamespaceJoin: true`，并且仅应用于破玻璃场景。
|
||||
- `readOnlyRoot: true` 会阻止写入；请将 `readOnlyRoot: false`，或构建自定义镜像。
|
||||
- 安装包时 `user` 必须为 root（省略 `user` 或设置 `user: "0:0"`）。
|
||||
- 默认 `docker.network` 为 `"none"`（无出口），因此安装软件包会失败。
|
||||
- `docker.network: "container:<id>"` 需要 `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)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user