@gguf/claw 2026.2.1 → 2026.2.3

package/docs/zh-CN/gateway/remote-gateway-readme.md

@@ -0,0 +1,164 @@
+---
+read_when: 通过 SSH 将 macOS 应用连接到远程 Gateway网关
+summary: 为 OpenClaw.app 连接远程 Gateway网关设置 SSH 隧道
+title: 远程 Gateway网关设置
+x-i18n:
+  generated_at: "2026-02-01T20:35:41Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b1ae266a7cb4911b82ae3ec6cb98b1b57aca592aeb1dc8b74bbce9b0ea9dd1d1
+  source_path: gateway/remote-gateway-readme.md
+  workflow: 14
+---
+
+# 使用远程 Gateway网关运行 OpenClaw.app
+
+OpenClaw.app 使用 SSH 隧道连接到远程 Gateway网关。本指南将介绍如何进行设置。
+
+## 概述
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        客户端机器                              │
+│                                                              │
+│  OpenClaw.app ──► ws://127.0.0.1:18789（本地端口）              │
+│                     │                                        │
+│                     ▼                                        │
+│  SSH 隧道 ──────────────────────────────────────────────────│
+│                     │                                        │
+└─────────────────────┼──────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────────────┐
+│                         远程机器                               │
+│                                                              │
+│  Gateway网关 WebSocket ──► ws://127.0.0.1:18789 ──►              │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 快速设置
+
+### 第 1 步：添加 SSH 配置
+
+编辑 `~/.ssh/config` 并添加：
+
+```ssh
+Host remote-gateway
+    HostName <REMOTE_IP>          # 例如 172.27.187.184
+    User <REMOTE_USER>            # 例如 jefferson
+    LocalForward 18789 127.0.0.1:18789
+    IdentityFile ~/.ssh/id_rsa
+```
+
+将 `<REMOTE_IP>` 和 `<REMOTE_USER>` 替换为你的实际值。
+
+### 第 2 步：复制 SSH 密钥
+
+将你的公钥复制到远程机器（需输入一次密码）：
+
+```bash
+ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>
+```
+
+### 第 3 步：设置 Gateway网关令牌
+
+```bash
+launchctl setenv OPENCLAW_GATEWAY_TOKEN "<your-token>"
+```
+
+### 第 4 步：启动 SSH 隧道
+
+```bash
+ssh -N remote-gateway &
+```
+
+### 第 5 步：重启 OpenClaw.app
+
+```bash
+# 退出 OpenClaw.app（⌘Q），然后重新打开：
+open /path/to/OpenClaw.app
+```
+
+应用现在将通过 SSH 隧道连接到远程 Gateway网关。
+
+---
+
+## 登录时自动启动隧道
+
+要在登录时自动启动 SSH 隧道，请创建一个 Launch Agent。
+
+### 创建 PLIST 文件
+
+将以下内容保存为 `~/Library/LaunchAgents/bot.molt.ssh-tunnel.plist`：
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>bot.molt.ssh-tunnel</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/bin/ssh</string>
+        <string>-N</string>
+        <string>remote-gateway</string>
+    </array>
+    <key>KeepAlive</key>
+    <true/>
+    <key>RunAtLoad</key>
+    <true/>
+</dict>
+</plist>
+```
+
+### 加载 Launch Agent
+
+```bash
+launchctl bootstrap gui/$UID ~/Library/LaunchAgents/bot.molt.ssh-tunnel.plist
+```
+
+隧道现在将：
+
+- 在你登录时自动启动
+- 崩溃后自动重启
+- 在后台持续运行
+
+旧版说明：如果存在残留的 `com.openclaw.ssh-tunnel` LaunchAgent，请将其删除。
+
+---
+
+## 故障排除
+
+**检查隧道是否正在运行：**
+
+```bash
+ps aux | grep "ssh -N remote-gateway" | grep -v grep
+lsof -i :18789
+```
+
+**重启隧道：**
+
+```bash
+launchctl kickstart -k gui/$UID/bot.molt.ssh-tunnel
+```
+
+**停止隧道：**
+
+```bash
+launchctl bootout gui/$UID/bot.molt.ssh-tunnel
+```
+
+---
+
+## 工作原理
+
+| 组件                                 | 功能说明                                    |
+| ------------------------------------ | ------------------------------------------- |
+| `LocalForward 18789 127.0.0.1:18789` | 将本地端口 18789 转发到远程端口 18789       |
+| `ssh -N`                             | 仅进行端口转发的 SSH 连接（不执行远程命令） |
+| `KeepAlive`                          | 隧道崩溃时自动重启                          |
+| `RunAtLoad`                          | 在代理加载时启动隧道                        |
+
+OpenClaw.app 连接到客户端机器上的 `ws://127.0.0.1:18789`。SSH 隧道将该连接转发到运行 Gateway网关的远程机器的 18789 端口。

package/docs/zh-CN/gateway/remote.md

@@ -0,0 +1,133 @@
+---
+read_when:
+  - 运行或排查远程 Gateway网关设置问题
+summary: 使用 SSH 隧道（Gateway网关 WebSocket）和 tailnet 进行远程访问
+title: 远程访问
+x-i18n:
+  generated_at: "2026-02-01T20:35:58Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 7e00bd2e048dfbd829913bef0f40a791b8d8c3e2f8a115fc0a13b03f136ebc93
+  source_path: gateway/remote.md
+  workflow: 14
+---
+
+# 远程访问（SSH、隧道和 tailnet）
+
+本仓库通过在专用主机（桌面/服务器）上运行单个 Gateway网关（主节点）并让客户端连接到它，来支持"通过 SSH 远程访问"。
+
+- 对于**操作者（你 / macOS 应用）**：SSH 隧道是通用的后备方案。
+- 对于**节点（iOS/Android 及未来设备）**：连接到 Gateway网关的 **WebSocket**（根据需要通过局域网/tailnet 或 SSH 隧道）。
+
+## 核心思路
+
+- Gateway网关 WebSocket 绑定到你配置端口上的**local loopback**（默认为 18789）。
+- 对于远程使用，你通过 SSH 转发该 local loopback 端口（或使用 tailnet/VPN 以减少隧道需求）。
+
+## 常见的 VPN/tailnet 设置（智能体运行的位置）
+
+将 **Gateway网关主机**视为"智能体运行的位置"。它拥有会话、认证配置、渠道和状态。
+你的笔记本/桌面（及节点）连接到该主机。
+
+### 1) 在 tailnet 中常驻运行的 Gateway网关（VPS 或家庭服务器）
+
+在持久化主机上运行 Gateway网关，通过 **Tailscale** 或 SSH 访问。
+
+- **最佳体验：**保持 `gateway.bind: "loopback"` 并使用 **Tailscale Serve** 提供控制界面。
+- **后备方案：**保持 local loopback + 从需要访问的任何机器建立 SSH 隧道。
+- **示例：**[exe.dev](/platforms/exe-dev)（简易虚拟机）或 [Hetzner](/platforms/hetzner)（生产 VPS）。
+
+当你的笔记本经常休眠但希望智能体始终在线时，这是理想方案。
+
+### 2) 家庭桌面运行 Gateway网关，笔记本作为远程控制
+
+笔记本**不**运行智能体。它通过远程连接：
+
+- 使用 macOS 应用的**通过 SSH 远程连接**模式（设置 → 通用 → "OpenClaw 运行位置"）。
+- 应用会打开并管理隧道，因此 WebChat + 健康检查"开箱即用"。
+
+操作指南：[macOS 远程访问](/platforms/mac/remote)。
+
+### 3) 笔记本运行 Gateway网关，从其他机器远程访问
+
+保持 Gateway网关本地运行但安全地暴露它：
+
+- 从其他机器通过 SSH 隧道连接到笔记本，或
+- 通过 Tailscale Serve 提供控制界面并保持 Gateway网关仅绑定 local loopback。
+
+指南：[Tailscale](/gateway/tailscale) 和 [Web 概览](/web)。
+
+## 命令流程（什么在哪里运行）
+
+一个 Gateway网关服务拥有状态和渠道。节点是外围设备。
+
+流程示例（Telegram → 节点）：
+
+- Telegram 消息到达 **Gateway网关**。
+- Gateway网关运行**智能体**并决定是否调用节点工具。
+- Gateway网关通过 Gateway网关 WebSocket（`node.*` RPC）调用**节点**。
+- 节点返回结果；Gateway网关将回复发送回 Telegram。
+
+说明：
+
+- **节点不运行 Gateway网关服务。**每台主机只应运行一个 Gateway网关，除非你有意运行隔离的配置文件（参见[多 Gateway网关](/gateway/multiple-gateways)）。
+- macOS 应用"节点模式"只是通过 Gateway网关 WebSocket 连接的节点客户端。
+
+## SSH 隧道（CLI + 工具）
+
+创建到远程 Gateway网关 WebSocket 的本地隧道：
+
+```bash
+ssh -N -L 18789:127.0.0.1:18789 user@host
+```
+
+隧道建立后：
+
+- `openclaw health` 和 `openclaw status --deep` 现在通过 `ws://127.0.0.1:18789` 访问远程 Gateway网关。
+- `openclaw gateway {status,health,send,agent,call}` 也可以在需要时通过 `--url` 指向转发的 URL。
+
+注意：将 `18789` 替换为你配置的 `gateway.port`（或 `--port`/`OPENCLAW_GATEWAY_PORT`）。
+
+## CLI 远程默认值
+
+你可以持久化远程目标，使 CLI 命令默认使用它：
+
+```json5
+{
+  gateway: {
+    mode: "remote",
+    remote: {
+      url: "ws://127.0.0.1:18789",
+      token: "your-token",
+    },
+  },
+}
+```
+
+当 Gateway网关仅绑定 local loopback 时，保持 URL 为 `ws://127.0.0.1:18789` 并先打开 SSH 隧道。
+
+## 通过 SSH 访问聊天界面
+
+WebChat 不再使用单独的 HTTP 端口。SwiftUI 聊天界面直接连接到 Gateway网关 WebSocket。
+
+- 通过 SSH 转发 `18789`（参见上文），然后将客户端连接到 `ws://127.0.0.1:18789`。
+- 在 macOS 上，建议使用应用的"通过 SSH 远程连接"模式，它会自动管理隧道。
+
+## macOS 应用"通过 SSH 远程连接"
+
+macOS 菜单栏应用可以端到端驱动相同的设置（远程状态检查、WebChat 和语音唤醒转发）。
+
+操作指南：[macOS 远程访问](/platforms/mac/remote)。
+
+## 安全规则（远程/VPN）
+
+简短版本：**保持 Gateway网关仅绑定 local loopback**，除非你确定需要绑定其他地址。
+
+- **local loopback + SSH/Tailscale Serve** 是最安全的默认设置（无公开暴露）。
+- **非 local loopback 绑定**（`lan`/`tailnet`/`custom`，或 local loopback 不可用时的 `auto`）必须使用认证令牌/密码。
+- `gateway.remote.token` **仅**用于远程 CLI 调用——它**不会**启用本地认证。
+- `gateway.remote.tlsFingerprint` 在使用 `wss://` 时固定远程 TLS 证书。
+- **Tailscale Serve** 可以在 `gateway.auth.allowTailscale: true` 时通过身份头进行认证。如果你希望使用令牌/密码，请将其设置为 `false`。
+- 将浏览器控制视为操作者访问：仅限 tailnet + 有意的节点配对。
+
+深入了解：[安全](/gateway/security)。

package/docs/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated.md

@@ -0,0 +1,135 @@
+---
+read_when: 当你遇到 '沙箱隔离' 或看到工具/提权拒绝提示，想要了解需要修改的确切配置键时阅读。
+status: active
+summary: 工具被阻止的原因：沙箱运行时、工具允许/拒绝策略以及提权执行门控
+title: 沙箱 vs 工具策略 vs 提权模式
+x-i18n:
+  generated_at: "2026-02-01T20:38:41Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 863ea5e6d137dfb61f12bd686b9557d6df1fd0c13ba5f15861bf72248bc975f1
+  source_path: gateway/sandbox-vs-tool-policy-vs-elevated.md
+  workflow: 14
+---
+
+# 沙箱 vs 工具策略 vs 提权模式
+
+OpenClaw 有三个相关（但不同的）控制机制：
+
+1. **沙箱** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) 决定**工具在哪里运行**（Docker 还是宿主机）。
+2. **工具策略** (`tools.*`、`tools.sandbox.tools.*`、`agents.list[].tools.*`) 决定**哪些工具可用/被允许**。
+3. **提权模式** (`tools.elevated.*`、`agents.list[].tools.elevated.*`) 是一个**仅限 exec 的逃逸通道**，用于在沙箱环境下在宿主机上运行。
+
+## 快速调试
+
+使用检查器查看 OpenClaw *实际*在做什么：
+
+```bash
+openclaw sandbox explain
+openclaw sandbox explain --session agent:main:main
+openclaw sandbox explain --agent work
+openclaw sandbox explain --json
+```
+
+它会输出：
+
+- 生效的沙箱模式/范围/工作区访问权限
+- 当前会话是否处于沙箱中（主会话 vs 非主会话）
+- 生效的沙箱工具允许/拒绝策略（以及该策略来源于智能体级/全局级/默认级）
+- 提权门控及修复路径
+
+## 沙箱：工具在哪里运行
+
+沙箱由 `agents.defaults.sandbox.mode` 控制：
+
+- `"off"`：所有内容在宿主机上运行。
+- `"non-main"`：仅非主会话被沙箱隔离（对群组/渠道来说常常出乎意料）。
+- `"all"`：所有内容都被沙箱隔离。
+
+完整的配置矩阵（范围、工作区挂载、镜像）请参阅[沙箱隔离](/gateway/sandboxing)。
+
+### 绑定挂载（安全快速检查）
+
+- `docker.binds` 会*穿透*沙箱文件系统：你挂载的任何内容都会以你设置的模式（`:ro` 或 `:rw`）在容器内可见。
+- 如果省略模式，默认为读写；建议对源代码/密钥使用 `:ro`。
+- `scope: "shared"` 会忽略每个智能体的绑定（仅全局绑定生效）。
+- 绑定 `/var/run/docker.sock` 实际上会将宿主机控制权交给沙箱；请仅在有意为之时使用。
+- 工作区访问（`workspaceAccess: "ro"`/`"rw"`）与绑定模式相互独立。
+
+## 工具策略：哪些工具存在/可调用
+
+两个层面需要关注：
+
+- **工具配置文件**：`tools.profile` 和 `agents.list[].tools.profile`（基础允许列表）
+- **提供商工具配置文件**：`tools.byProvider[provider].profile` 和 `agents.list[].tools.byProvider[provider].profile`
+- **全局/每智能体工具策略**：`tools.allow`/`tools.deny` 和 `agents.list[].tools.allow`/`agents.list[].tools.deny`
+- **提供商工具策略**：`tools.byProvider[provider].allow/deny` 和 `agents.list[].tools.byProvider[provider].allow/deny`
+- **沙箱工具策略**（仅在沙箱隔离时适用）：`tools.sandbox.tools.allow`/`tools.sandbox.tools.deny` 和 `agents.list[].tools.sandbox.tools.*`
+
+经验法则：
+
+- `deny` 始终优先。
+- 如果 `allow` 非空，其他所有工具都视为被阻止。
+- 工具策略是硬性限制：`/exec` 无法覆盖被拒绝的 `exec` 工具。
+- `/exec` 仅为授权发送者更改会话默认设置；它不会授予工具访问权限。
+  提供商工具键接受 `provider`（如 `google-antigravity`）或 `provider/model`（如 `openai/gpt-5.2`）格式。
+
+### 工具组（简写）
+
+工具策略（全局、智能体、沙箱）支持 `group:*` 条目，可展开为多个工具：
+
+```json5
+{
+  tools: {
+    sandbox: {
+      tools: {
+        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
+      },
+    },
+  },
+}
+```
+
+可用的组：
+
+- `group:runtime`：`exec`、`bash`、`process`
+- `group:fs`：`read`、`write`、`edit`、`apply_patch`
+- `group:sessions`：`sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`session_status`
+- `group:memory`：`memory_search`、`memory_get`
+- `group:ui`：`browser`、`canvas`
+- `group:automation`：`cron`、`gateway`
+- `group:messaging`：`message`
+- `group:nodes`：`nodes`
+- `group:openclaw`：所有内置 OpenClaw 工具（不包括提供商插件）
+
+## 提权模式：仅限 exec 的"在宿主机运行"
+
+提权模式**不会**授予额外的工具；它仅影响 `exec`。
+
+- 如果你处于沙箱中，`/elevated on`（或带 `elevated: true` 的 `exec`）会在宿主机上运行（审批可能仍然适用）。
+- 使用 `/elevated full` 可跳过当前会话的 exec 审批。
+- 如果你已经在直接运行模式下，提权实际上是无操作（仍然受门控限制）。
+- 提权模式**不是**Skills 范围的，也**不会**覆盖工具允许/拒绝策略。
+- `/exec` 与提权模式是分开的。它仅为授权发送者调整每会话的 exec 默认设置。
+
+门控：
+
+- 启用：`tools.elevated.enabled`（以及可选的 `agents.list[].tools.elevated.enabled`）
+- 发送者允许列表：`tools.elevated.allowFrom.<provider>`（以及可选的 `agents.list[].tools.elevated.allowFrom.<provider>`）
+
+参阅[提权模式](/tools/elevated)。
+
+## 常见"沙箱隔离"修复方法
+
+### "工具 X 被沙箱工具策略阻止"
+
+修复键（任选其一）：
+
+- 禁用沙箱：`agents.defaults.sandbox.mode=off`（或每智能体 `agents.list[].sandbox.mode=off`）
+- 在沙箱内允许该工具：
+  - 从 `tools.sandbox.tools.deny`（或每智能体 `agents.list[].tools.sandbox.tools.deny`）中移除它
+  - 或将其添加到 `tools.sandbox.tools.allow`（或每智能体允许列表）
+
+### "我以为这是主会话，为什么被沙箱隔离了？"
+
+在 `"non-main"` 模式下，群组/渠道键*不是*主会话。请使用主会话键（通过 `sandbox explain` 查看）或将模式切换为 `"off"`。

package/docs/zh-CN/gateway/sandboxing.md

@@ -0,0 +1,196 @@
+---
+read_when: 你想深入了解沙箱机制，或需要调整 agents.defaults.sandbox 配置。
+status: active
+summary: OpenClaw 沙箱的工作原理：模式、作用域、工作区访问和镜像
+title: 沙箱
+x-i18n:
+  generated_at: "2026-02-01T20:38:47Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 184fc53001fc6b2847bbb1963cc9c54475d62f74555a581a262a448a0333a209
+  source_path: gateway/sandboxing.md
+  workflow: 14
+---
+
+# 沙箱
+
+OpenClaw 可以**在 Docker 容器内运行工具**以缩小影响范围。
+此功能是**可选的**，通过配置控制（`agents.defaults.sandbox` 或
+`agents.list[].sandbox`）。如果沙箱未启用，工具将在宿主机上运行。
+Gateway网关始终在宿主机上运行；启用沙箱后，工具执行将在隔离的沙箱中进行。
+
+这并非完美的安全边界，但在模型执行了错误操作时，能有效限制文件系统和进程访问。
+
+## 哪些内容会被沙箱隔离
+
+- 工具执行（`exec`、`read`、`write`、`edit`、`apply_patch`、`process` 等）。
+- 可选的沙箱浏览器（`agents.defaults.sandbox.browser`）。
+  - 默认情况下，沙箱浏览器会在浏览器工具需要时自动启动（确保 CDP 可达）。
+    通过 `agents.defaults.sandbox.browser.autoStart` 和 `agents.defaults.sandbox.browser.autoStartTimeoutMs` 进行配置。
+  - `agents.defaults.sandbox.browser.allowHostControl` 允许沙箱会话显式访问宿主机浏览器。
+  - 可选的允许列表控制 `target: "custom"`：`allowedControlUrls`、`allowedControlHosts`、`allowedControlPorts`。
+
+未被沙箱隔离的内容：
+
+- Gateway网关进程本身。
+- 任何被显式允许在宿主机上运行的工具（例如 `tools.elevated`）。
+  - **提权 exec 在宿主机上运行，会绕过沙箱。**
+  - 如果沙箱未启用，`tools.elevated` 不会改变执行方式（本身已在宿主机上）。参见[提权模式](/tools/elevated)。
+
+## 模式
+
+`agents.defaults.sandbox.mode` 控制**何时**使用沙箱：
+
+- `"off"`：不使用沙箱。
+- `"non-main"`：仅对**非主**会话启用沙箱（如果你希望普通聊天在宿主机上运行，这是默认值）。
+- `"all"`：所有会话都在沙箱中运行。
+  注意：`"non-main"` 基于 `session.mainKey`（默认为 `"main"`），而非智能体 ID。
+  群组/渠道会话使用各自的键，因此它们被视为非主会话，会被沙箱隔离。
+
+## 作用域
+
+`agents.defaults.sandbox.scope` 控制**创建多少个容器**：
+
+- `"session"`（默认）：每个会话一个容器。
+- `"agent"`：每个智能体一个容器。
+- `"shared"`：所有沙箱会话共享一个容器。
+
+## 工作区访问
+
+`agents.defaults.sandbox.workspaceAccess` 控制**沙箱能看到什么**：
+
+- `"none"`（默认）：工具在 `~/.openclaw/sandboxes` 下的沙箱工作区中运行。
+- `"ro"`：以只读方式将智能体工作区挂载到 `/agent`（禁用 `write`/`edit`/`apply_patch`）。
+- `"rw"`：以读写方式将智能体工作区挂载到 `/workspace`。
+
+入站媒体会被复制到活动沙箱工作区中（`media/inbound/*`）。
+Skills 说明：`read` 工具以沙箱为根目录。当 `workspaceAccess: "none"` 时，
+OpenClaw 会将符合条件的 Skills 镜像到沙箱工作区（`.../skills`）中以便读取。当设为 `"rw"` 时，工作区 Skills 可从
+`/workspace/skills` 读取。
+
+## 自定义绑定挂载
+
+`agents.defaults.sandbox.docker.binds` 将额外的宿主机目录挂载到容器中。
+格式：`host:container:mode`（例如 `"/home/user/source:/source:rw"`）。
+
+全局和每个智能体的绑定挂载会被**合并**（而非替换）。在 `scope: "shared"` 下，每个智能体的绑定挂载会被忽略。
+
+示例（只读源码 + Docker 套接字）：
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        docker: {
+          binds: ["/home/user/source:/source:ro", "/var/run/docker.sock:/var/run/docker.sock"],
+        },
+      },
+    },
+    list: [
+      {
+        id: "build",
+        sandbox: {
+          docker: {
+            binds: ["/mnt/cache:/cache:rw"],
+          },
+        },
+      },
+    ],
+  },
+}
+```
+
+安全注意事项：
+
+- 绑定挂载会绕过沙箱文件系统：它们以你设置的模式（`:ro` 或 `:rw`）暴露宿主机路径。
+- 敏感挂载（例如 `docker.sock`、密钥、SSH 密钥）应使用 `:ro`，除非确实需要写入。
+- 如果你只需要对工作区的读取权限，可与 `workspaceAccess: "ro"` 配合使用；绑定模式保持独立。
+- 参见[沙箱 vs 工具策略 vs 提权](/gateway/sandbox-vs-tool-policy-vs-elevated)了解绑定挂载如何与工具策略和提权 exec 交互。
+
+## 镜像 + 设置
+
+默认镜像：`openclaw-sandbox:bookworm-slim`
+
+构建一次即可：
+
+```bash
+scripts/sandbox-setup.sh
+```
+
+注意：默认镜像**不包含** Node。如果 Skills 需要 Node（或
+其他运行时），请构建自定义镜像或通过
+`sandbox.docker.setupCommand` 安装（需要网络出口 + 可写根文件系统 +
+root 用户）。
+
+沙箱浏览器镜像：
+
+```bash
+scripts/sandbox-browser-setup.sh
+```
+
+默认情况下，沙箱容器以**无网络**方式运行。
+可通过 `agents.defaults.sandbox.docker.network` 覆盖。
+
+Docker 安装和容器化 Gateway网关的说明在这里：
+[Docker](/install/docker)
+
+## setupCommand（一次性容器设置）
+
+`setupCommand` 在沙箱容器创建后**仅运行一次**（不会每次运行时都执行）。
+它通过 `sh -lc` 在容器内执行。
+
+路径：
+
+- 全局：`agents.defaults.sandbox.docker.setupCommand`
+- 每个智能体：`agents.list[].sandbox.docker.setupCommand`
+
+常见问题：
+
+- 默认 `docker.network` 为 `"none"`（无出口），因此包安装会失败。
+- `readOnlyRoot: true` 会阻止写入；请设置 `readOnlyRoot: false` 或构建自定义镜像。
+- 包安装需要 root 用户（省略 `user` 或设置 `user: "0:0"`）。
+- 沙箱 exec **不会**继承宿主机的 `process.env`。请使用
+  `agents.defaults.sandbox.docker.env`（或自定义镜像）来设置 Skills API 密钥。
+
+## 工具策略 + 逃逸机制
+
+工具的允许/拒绝策略仍在沙箱规则之前生效。如果某个工具在全局或智能体级别被拒绝，沙箱不会将其恢复。
+
+`tools.elevated` 是一个显式的逃逸机制，在宿主机上运行 `exec`。
+`/exec` 指令仅对授权发送者生效，且在每个会话中持续有效；要彻底禁用
+`exec`，请使用工具策略拒绝（参见[沙箱 vs 工具策略 vs 提权](/gateway/sandbox-vs-tool-policy-vs-elevated)）。
+
+调试：
+
+- 使用 `openclaw sandbox explain` 检查当前生效的沙箱模式、工具策略和修复配置项。
+- 参见[沙箱 vs 工具策略 vs 提权](/gateway/sandbox-vs-tool-policy-vs-elevated)了解"为什么被阻止了？"的思维模型。
+  保持锁定状态。
+
+## 多智能体覆盖
+
+每个智能体可以覆盖沙箱和工具配置：
+`agents.list[].sandbox` 和 `agents.list[].tools`（以及 `agents.list[].tools.sandbox.tools` 用于沙箱工具策略）。
+参见[多智能体沙箱与工具](/multi-agent-sandbox-tools)了解优先级。
+
+## 最小启用示例
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "non-main",
+        scope: "session",
+        workspaceAccess: "none",
+      },
+    },
+  },
+}
+```
+
+## 相关文档
+
+- [沙箱配置](/gateway/configuration#agentsdefaults-sandbox)
+- [多智能体沙箱与工具](/multi-agent-sandbox-tools)
+- [安全](/gateway/security)