@symerian/symi 3.0.21 → 3.0.22

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

@@ -1,164 +0,0 @@
----
-read_when: Connecting the macOS app to a remote gateway over SSH
-summary: Symi.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 网关运行 Symi.app
-
-Symi.app 使用 SSH 隧道连接到远程 Gateway 网关。本指南向你展示如何设置。
-
-## 概述
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        Client Machine                          │
-│                                                              │
-│  Symi.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 SYMI_GATEWAY_TOKEN "<your-token>"
-```
-
-### 步骤 4：启动 SSH 隧道
-
-```bash
-ssh -N remote-gateway &
-```
-
-### 步骤 5：重启 Symi.app
-
-```bash
-# Quit Symi.app (⌘Q), then reopen:
-open /path/to/Symi.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.symi.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`                          | 代理加载时启动隧道                    |
-
-Symi.app 连接到你的客户端机器上的 `ws://127.0.0.1:18789`。SSH 隧道将该连接转发到运行 Gateway 网关的远程机器的端口 18789。

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

@@ -1,133 +0,0 @@
----
-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** 模式（设置 → 通用 → "Symi 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
-```
-
-隧道建立后：
-
-- `symi health` 和 `symi status --deep` 现在通过 `ws://127.0.0.1:18789` 访问远程 Gateway 网关。
-- `symi gateway {status,health,send,agent,call}` 在需要时也可以通过 `--url` 指定转发的 URL。
-
-注意：将 `18789` 替换为你配置的 `gateway.port`（或 `--port`/`SYMI_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

@@ -1,135 +0,0 @@
----
-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 提权
-
-Symi 有三个相关（但不同）的控制：
-
-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 的逃逸通道**，允许在沙箱隔离时在主机上运行。
-
-## 快速调试
-
-使用检查器查看 Symi *实际*在做什么：
-
-```bash
-symi sandbox explain
-symi sandbox explain --session agent:main:main
-symi sandbox explain --agent work
-symi 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:symi`：所有内置 Symi 工具（不包括提供商插件）
-
-## 提权：仅限 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

@@ -1,188 +0,0 @@
----
-read_when: You want a dedicated explanation of sandboxing or need to tune agents.defaults.sandbox.
-status: active
-summary: Symi 沙箱隔离的工作原理：模式、作用域、工作区访问和镜像
-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
----
-
-# 沙箱隔离
-
-Symi 可以**在 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"`（默认）：工具看到 `~/.symi/sandboxes` 下的沙箱工作区。
-- `"ro"`：以只读方式在 `/agent` 挂载智能体工作区（禁用 `write`/`edit`/`apply_patch`）。
-- `"rw"`：以读写方式在 `/workspace` 挂载智能体工作区。
-
-入站媒体被复制到活动沙箱工作区（`media/inbound/*`）。
-Skills 注意事项：`read` 工具以沙箱为根。使用 `workspaceAccess: "none"` 时，Symi 将符合条件的 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 交互。
-
-## 镜像 + 设置
-
-默认镜像：`symi-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)）。
-
-调试：
-
-- 使用 `symi 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)