@quantumclaw/quantumclaw 2026.3.22

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

@@ -0,0 +1,164 @@
+---
+read_when: Connecting the macOS app to a remote gateway over SSH
+summary: QuantumClaw.app 连接远程 Gateway 网关的 SSH 隧道设置
+title: 远程 Gateway 网关设置
+x-i18n:
+  generated_at: "2026-02-03T07:48:37Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b1ae266a7cb4911b82ae3ec6cb98b1b57aca592aeb1dc8b74bbce9b0ea9dd1d1
+  source_path: gateway/remote-gateway-readme.md
+  workflow: 15
+---
+
+# 使用远程 Gateway 网关运行 QuantumClaw.app
+
+QuantumClaw.app 使用 SSH 隧道连接到远程 Gateway 网关。本指南向你展示如何设置。
+
+## 概述
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        Client Machine                          │
+│                                                              │
+│  QuantumClaw.app ──► ws://127.0.0.1:18789 (local port)           │
+│                     │                                        │
+│                     ▼                                        │
+│  SSH Tunnel ────────────────────────────────────────────────│
+│                     │                                        │
+└─────────────────────┼──────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────────────┐
+│                         Remote Machine                        │
+│                                                              │
+│  Gateway WebSocket ──► ws://127.0.0.1:18789 ──►              │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 快速设置
+
+### 步骤 1：添加 SSH 配置
+
+编辑 `~/.ssh/config` 并添加：
+
+```ssh
+Host remote-gateway
+    HostName <REMOTE_IP>          # e.g., 172.27.187.184
+    User <REMOTE_USER>            # e.g., 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 QUANTUMCLAW_GATEWAY_TOKEN "<your-token>"
+```
+
+### 步骤 4：启动 SSH 隧道
+
+```bash
+ssh -N remote-gateway &
+```
+
+### 步骤 5：重启 QuantumClaw.app
+
+```bash
+# Quit QuantumClaw.app (⌘Q), then reopen:
+open /path/to/QuantumClaw.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.quantumclaw.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`                          | 代理加载时启动隧道                    |
+
+QuantumClaw.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 WS）和 tailnet 进行远程访问
+title: 远程访问
+x-i18n:
+  generated_at: "2026-02-03T07:48:40Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 7e00bd2e048dfbd829913bef0f40a791b8d8c3e2f8a115fc0a13b03f136ebc93
+  source_path: gateway/remote.md
+  workflow: 15
+---
+
+# 远程访问（SSH、隧道和 tailnet）
+
+本仓库通过在专用主机（桌面/服务器）上运行单个 Gateway 网关（主节点）并让客户端连接到它来支持"SSH 远程"。
+
+- 对于**操作员（你/macOS 应用）**：SSH 隧道是通用的回退方案。
+- 对于**节点（iOS/Android 和未来的设备）**：连接到 Gateway **WebSocket**（LAN/tailnet 或根据需要通过 SSH 隧道）。
+
+## 核心理念
+
+- Gateway WebSocket 绑定到你配置端口的 **loopback**（默认为 18789）。
+- 对于远程使用，你通过 SSH 转发该 loopback 端口（或使用 tailnet/VPN 减少隧道需求）。
+
+## 常见的 VPN/tailnet 设置（智能体所在位置）
+
+将 **Gateway 网关主机**视为"智能体所在的位置"。它拥有会话、身份验证配置文件、渠道和状态。
+你的笔记本电脑/桌面（和节点）连接到该主机。
+
+### 1) tailnet 中始终在线的 Gateway 网关（VPS 或家庭服务器）
+
+在持久主机上运行 Gateway 网关，并通过 **Tailscale** 或 SSH 访问它。
+
+- **最佳用户体验：** 保持 `gateway.bind: "loopback"` 并使用 **Tailscale Serve** 作为控制 UI。
+- **回退方案：** 保持 loopback + 从任何需要访问的机器建立 SSH 隧道。
+- **示例：** [exe.dev](/install/exe-dev)（简易 VM）或 [Hetzner](/install/hetzner)（生产 VPS）。
+
+当你的笔记本电脑经常休眠但你希望智能体始终在线时，这是理想的选择。
+
+### 2) 家庭桌面运行 Gateway 网关，笔记本电脑作为远程控制
+
+笔记本电脑**不**运行智能体。它远程连接：
+
+- 使用 macOS 应用的 **Remote over SSH** 模式（设置 → 通用 → "QuantumClaw runs"）。
+- 应用打开并管理隧道，因此 WebChat + 健康检查"直接工作"。
+
+操作手册：[macOS 远程访问](/platforms/mac/remote)。
+
+### 3) 笔记本电脑运行 Gateway 网关，从其他机器远程访问
+
+保持 Gateway 网关在本地但安全地暴露它：
+
+- 从其他机器到笔记本电脑的 SSH 隧道，或
+- Tailscale Serve 控制 UI 并保持 Gateway 网关仅 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 WS 的本地隧道：
+
+```bash
+ssh -N -L 18789:127.0.0.1:18789 user@host
+```
+
+隧道建立后：
+
+- `quantumclaw health` 和 `quantumclaw status --deep` 现在通过 `ws://127.0.0.1:18789` 访问远程 Gateway 网关。
+- `quantumclaw gateway {status,health,send,agent,call}` 在需要时也可以通过 `--url` 指定转发的 URL。
+
+注意：将 `18789` 替换为你配置的 `gateway.port`（或 `--port`/`QUANTUMCLAW_GATEWAY_PORT`）。
+
+## CLI 远程默认值
+
+你可以持久化远程目标，以便 CLI 命令默认使用它：
+
+```json5
+{
+  gateway: {
+    mode: "remote",
+    remote: {
+      url: "ws://127.0.0.1:18789",
+      token: "your-token",
+    },
+  },
+}
+```
+
+当 Gateway 网关仅限 loopback 时，保持 URL 为 `ws://127.0.0.1:18789` 并先打开 SSH 隧道。
+
+## 通过 SSH 的聊天 UI
+
+WebChat 不再使用单独的 HTTP 端口。SwiftUI 聊天 UI 直接连接到 Gateway WebSocket。
+
+- 通过 SSH 转发 `18789`（见上文），然后让客户端连接到 `ws://127.0.0.1:18789`。
+- 在 macOS 上，优先使用应用的"Remote over SSH"模式，它会自动管理隧道。
+
+## macOS 应用"Remote over SSH"
+
+macOS 菜单栏应用可以端到端驱动相同的设置（远程状态检查、WebChat 和语音唤醒转发）。
+
+操作手册：[macOS 远程访问](/platforms/mac/remote)。
+
+## 安全规则（远程/VPN）
+
+简短版本：**保持 Gateway 网关仅 loopback**，除非你确定需要绑定。
+
+- **Loopback + SSH/Tailscale Serve** 是最安全的默认设置（无公开暴露）。
+- **非 loopback 绑定**（`lan`/`tailnet`/`custom`，或当 loopback 不可用时的 `auto`）必须使用身份验证令牌/密码。
+- `gateway.remote.token` **仅**用于远程 CLI 调用——它**不**启用本地身份验证。
+- `gateway.remote.tlsFingerprint` 在使用 `wss://` 时固定远程 TLS 证书。
+- 当 `gateway.auth.allowTailscale: true` 时，**Tailscale Serve** 可以通过身份标头进行身份验证。如果你想使用令牌/密码，请将其设置为 `false`。
+- 将浏览器控制视为操作员访问：仅限 tailnet + 有意的节点配对。
+
+深入了解：[安全](/gateway/security)。

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

@@ -0,0 +1,135 @@
+---
+read_when: You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change.
+status: active
+summary: 工具被阻止的原因：沙箱运行时、工具允许/拒绝策略和提权 exec 限制
+title: 沙箱 vs 工具策略 vs 提权
+x-i18n:
+  generated_at: "2026-02-03T07:48:55Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 863ea5e6d137dfb61f12bd686b9557d6df1fd0c13ba5f15861bf72248bc975f1
+  source_path: gateway/sandbox-vs-tool-policy-vs-elevated.md
+  workflow: 15
+---
+
+# 沙箱 vs 工具策略 vs 提权
+
+QuantumClaw 有三个相关（但不同）的控制：
+
+1. **沙箱**（`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`）决定**工具在哪里运行**（Docker vs 主机）。
+2. **工具策略**（`tools.*`、`tools.sandbox.tools.*`、`agents.list[].tools.*`）决定**哪些工具可用/允许**。
+3. **提权**（`tools.elevated.*`、`agents.list[].tools.elevated.*`）是一个**仅限 exec 的逃逸通道**，允许在沙箱隔离时在主机上运行。
+
+## 快速调试
+
+使用检查器查看 QuantumClaw *实际*在做什么：
+
+```bash
+quantumclaw sandbox explain
+quantumclaw sandbox explain --session agent:main:main
+quantumclaw sandbox explain --agent work
+quantumclaw 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:quantumclaw`：所有内置 QuantumClaw 工具（不包括提供商插件）
+
+## 提权：仅限 exec 的"在主机上运行"
+
+提权**不会**授予额外工具；它仅影响 `exec`。
+
+- 如果你被沙箱隔离，`/elevated on`（或带 `elevated: true` 的 `exec`）在主机上运行（审批可能仍然适用）。
+- 使用 `/elevated full` 跳过该会话的 exec 审批。
+- 如果你已经直接运行，提权实际上是空操作（仍然受限）。
+- 提权**不是** skill 范围的，**不会**覆盖工具允许/拒绝。
+- `/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`（或每个智能体 allow）
+
+### "我以为这是主会话，为什么被沙箱隔离了？"
+
+在 `"non-main"` 模式下，群组/渠道键*不是*主会话。使用主会话键（由 `sandbox explain` 显示）或将模式切换为 `"off"`。

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

@@ -0,0 +1,188 @@
+---
+read_when: You want a dedicated explanation of sandboxing or need to tune agents.defaults.sandbox.
+status: active
+summary: QuantumClaw 沙箱隔离的工作原理：模式、作用域、工作区访问和镜像
+title: 沙箱隔离
+x-i18n:
+  generated_at: "2026-02-03T07:49:29Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 184fc53001fc6b2847bbb1963cc9c54475d62f74555a581a262a448a0333a209
+  source_path: gateway/sandboxing.md
+  workflow: 15
+---
+
+# 沙箱隔离
+
+QuantumClaw 可以**在 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"`（默认）：工具看到 `~/.quantumclaw/sandboxes` 下的沙箱工作区。
+- `"ro"`：以只读方式在 `/agent` 挂载智能体工作区（禁用 `write`/`edit`/`apply_patch`）。
+- `"rw"`：以读写方式在 `/workspace` 挂载智能体工作区。
+
+入站媒体被复制到活动沙箱工作区（`media/inbound/*`）。
+Skills 注意事项：`read` 工具以沙箱为根。使用 `workspaceAccess: "none"` 时，QuantumClaw 将符合条件的 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 交互。
+
+## 镜像 + 设置
+
+默认镜像：`quantumclaw-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` 或构建自定义镜像。
+- `user` 必须是 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)）。
+
+调试：
+
+- 使用 `quantumclaw sandbox explain` 检查生效的沙箱模式、工具策略和修复配置键。
+- 参见[沙箱 vs 工具策略 vs 提权](/gateway/sandbox-vs-tool-policy-vs-elevated)了解"为什么被阻止？"的心智模型。
+  保持锁定。
+
+## 多智能体覆盖
+
+每个智能体可以覆盖沙箱 + 工具：
+`agents.list[].sandbox` 和 `agents.list[].tools`（加上 `agents.list[].tools.sandbox.tools` 用于沙箱工具策略）。
+参见[多智能体沙箱与工具](/tools/multi-agent-sandbox-tools)了解优先级。
+
+## 最小启用示例
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "non-main",
+        scope: "session",
+        workspaceAccess: "none",
+      },
+    },
+  },
+}
+```
+
+## 相关文档
+
+- [沙箱配置](/gateway/configuration#agentsdefaults-sandbox)
+- [多智能体沙箱与工具](/tools/multi-agent-sandbox-tools)
+- [安全](/gateway/security)