> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trae.cn/llms.txt
> Use this file to discover all available pages before exploring further.

沙箱为智能体生成的命令提供受限的执行环境，确保智能体在安全隔离的环境中运行命令，防止未经授权的文件访问。

## 支持的操作系统 {#8eaff6df}

* macOS
* Windows（包括 Windows 原生系统以及 Remote WSL 2）
* Linux：Debian 10 及以上、Ubuntu 20.04 及以上（通过 Remote SSH 和 Bubblewrap 实现）

## 安全策略：文件访问控制 {#9a590c53}

:::tip 提示
* 当前安全策略不涉及网络访问。
* 读写权限继承当前用户权限；当读写与只读权限冲突时，以只读权限为准。
:::

启用沙箱后，TRAE 的文件目录访问权限如下：

<!-- @cols-width: 100,219,528 -->
| | | | \
|**权限类型** |**目录类型** |**目录列表** |
|---|---|---|
| | | | \
|只读 |项目目录中的受保护目录 |`.vscode` |
|^^| | | \
| |根目录 |`/`（默认策略：所有未显式声明为可写的目录均为只读） |
| | | | \
|读写 |项目目录 |除 `.trae`、`.vscode` 和 `.git` 之外的项目文件与目录 |
|^^| | | \
| |临时目录 |* macOS：`/tmp`、`/var/folders`、`TMPDIR` 环境变量路径 |\
| | |* Windows：`~/AppData/Local/Temp`、`~/AppData/LocalLow/Temp` |\
| | |* Linux：`/tmp`、`TMPDIR` 环境变量路径 |
|^^| | | \
| |缓存目录 |* macOS：`~/Library/Caches`、`~/.cache`、`XDG_CACHE_HOME` 环境变量路径 |\
| | |* Linux：`~/.cache`、`XDG_CACHE_HOME` 环境变量路径 |
|^^| | | \
| |通用工具依赖目录 |* macOS & Linux：`~/.local/lib`、`~/.local/bin`、`~/.local/share`（通常用于 pip、uv/uvx、npm/pnpm、cmake 等工具的依赖目录） |\
| | |* Windows：`LOCALAPPDATA` 环境变量路径内的常见工具依赖的路径（pip、uv/uvx、npm/pnpm 等） |
|^^| | | \
| |常用语言的工具链及其依赖目录 |Go、Java、Python、Node.js、Rust 和 C++ 等常用语言的工具链及其依赖目录。 |

## 使用流程 {#40575ce6}

### 第一步：在操作系统中配置环境 {#049a40e3}

使用沙箱前，需要根据你所使用的操作系统，完成相应的环境配置。

::::tabs
@tab macOS
基于 macOS 的 `sandbox-exec` 工具，TRAE 会自动为你创建一个受限的命令执行环境。你无需进行任何额外配置。

@tab Windows
基于自研的沙箱 SDK，TRAE 会自动为你创建一个受限的命令执行环境。你无需进行任何额外配置。

@tab WSL 2 / Linux
沙箱功能需通过 WSL 2 / Remote SSH 和 Bubblewrap 实现。

在远程 Linux 环境中，TRAE 基于 User Namespace 构建沙箱，并在独立的 User Namespace 中结合其他 Linux Namespace，实现对多类系统资源的隔离。

* 关于如何在 Windows 上运行 Linux 环境，参考[使用 WSL 进行远程开发](/ide/wsl)。
* 关于如何使用 Remote SSH 功能连接你的 Linux 远程主机，参考[使用 SSH 进行远程开发](/ide/ssh-remote)。

在远程环境中启用沙箱时，TRAE 会自动完成以下配置：

1. 检查当前系统是否启用 User Namespace。绝大多数 Linux 发行版默认已启用该功能。
2. 完成临时参数配置（仅当前运行周期生效）。
   若系统禁止普通用户创建 User Namespace，或该功能未启用，TRAE 会临时修改内核参数，允许非特权用户创建 User Namespace：
   ```Bash
   sysctl -w kernel.unprivileged_userns_clone=1 # 允许非特权用户（普通用户）创建 User Namespace
   sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 # 关闭 AppArmor 对 “非特权 User Namespace” 的额外限制
   ```
3. 持久化参数配置。
   为确保系统重启后，沙箱依然可用，TRAE 会将以下参数配置写入 `/etc/sysctl.d/trae-sandbox.conf` 文件。
   ```Bash
   kernel.unprivileged_userns_clone=1
   kernel.apparmor_restrict_unprivileged_userns=0
   ```
::::

### 第二步：在 TRAE 中启用沙箱 {#a9668487}

在 TRAE 中启用沙箱后，智能体将自动在沙箱中运行命令。启用沙箱的步骤如下：

1. 在 IDE 模式界面中，点击界面右上角的 **设置** 图标，进入设置中心。
   或
   在 SOLO 模式界面中，点击对话面板右上角的 **设置** 图标，进入设置中心。
2. 在左侧导航栏中，选择 **对话流**，进入 **对话流** 面板。
3. 在 **自动运行** 部分的 **自动运行命令** 处，为 IDE 和/或 SOLO 模式选择 **沙箱运行（支持白名单）** 模式。
4. 在 **白名单作用于 IDE / SOLO** 处，按需将命令前缀加入白名单。
   白名单中的命令将跳过沙箱，直接在沙箱外执行。   


![Image=600x146](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/cfe233ecd4f547fd92658313a829a892~tplv-goo7wpa0wc-image.image)

## 自定义沙箱配置 {#a0e30a72}

通过 `sandbox.json` 文件，你可以为当前项目自定义沙箱内进程的文件和网络访问范围。

### sandbox.json 文件的位置 {#a85e4ae7}

* Windows：`%USERPROFILE%\.trae-cn\sandbox.json`
* macOS & Linux：`~/.trae-cn/sandbox.json`

### 创建并编辑 sandbox.json 文件 {#d1ac1cb0}


1. 前往 **设置** > **对话流**。
2. 在 **沙箱自定义配置** 处，点击 **打开配置** 按钮。
   ![Image=600x211](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/a255bb75139d47ae9e7db6bf80a200d5~tplv-goo7wpa0wc-image.image)
   TRAE 将在你的本地用户目录中创建 `sandbox.json` 文件，并在编辑器内打开它。
   该文件的初始结构如下：
   ```JSON
   {
       "filesystem": {
           "readWrite": [],
           "readOnly": []
       },
       "network": {
           "default": "allow",
           "allow": [],
           "deny": []
       }
   }
   ```
3. 在打开的 `sandbox.json` 文件中，填入你的自定义沙箱配置。
4. 保存文件以使配置生效。

### 文件访问配置说明 {#082df684}

`filesystem` 字段用于精细控制沙箱对本地文件系统的访问权限。

<!-- @cols-width: 122,116,100,511 -->
| | | | | \
|**字段** |**类型** |**默认值** |**描述** |
|---|---|---|---|
| | | | | \
|`readWrite` |`string[]` |`[]` |读写路径列表。沙箱内进程对列表中的路径拥有读写权限（继承自当前用户）。 |
| | | | | \
|`readOnly` |`string[]` |`[]` |只读路径列表。沙箱内进程对列表中的路径仅有只读权限。 |

**支持的路径格式：**

* 绝对路径：例如 `/usr/local/bin` 或 `C:\Program Files`；
* Home 目录：使用 `~` 表示用户主目录，如 `~/Documents`；
* 环境变量：使用 `$VAR` 引用环境变量，如 `$HOME/.config`；
* 工作区变量：使用 `$WORKSPACE_FOLDER` 引用当前工作区目录。

**针对各个操作系统的注意事项：**

* Windows：系统会自动忽略 Unix 风格的绝对路径（如 `/usr/lib`），并将 Git Bash 风格的路径（如 `/c/Users`）转换为标准 Windows 路径（如 `C:\Users`）。
* macOS / Linux：系统会自动忽略 Windows 风格的盘符路径（如 `C:\Users`）。

**路径匹配规则：**

系统会合并你的自定义配置和系统内置的文档访问控制策略，并根据以下优先级规则确定最终生效的权限：

* 路径越长、越精确，优先级越高。
* 如果一个路径被同时添加至 `readWrite` 和 `readOnly` 列表，`readOnly` 的优先级高于 `readWrite`。
* 如果一个路径未被添加至 `readWrite` 和 `readOnly` 列表，则对其采用上文[安全策略：文件访问控制](/ide/sandbox#9a590c53)中的规则。

### 网络访问配置说明 {#b0726909}

:::tip 提示
仅 Windows 操作系统支持此功能。
:::

`network` 字段用于管理沙箱内进程的网络请求策略，实现允许或阻止对特定网络的访问。

可配置的字段如下：

<!-- @cols-width: 100,111,113,524 -->
| | | | | \
|**字段** |**类型** |**默认值** |**描述** |
|---|---|---|---|
| | | | | \
|`default` |`string` |`allow` |默认的网络访问策略。可选值： |\
| | | | |\
| | | |* `allow`：允许访问 |\
| | | |* `deny`：禁止访问 |
| | | | | \
|`allow` |`string[]` |`[]` |允许访问的网络。 |
| | | | | \
|`deny` |`string[]` |`[]` |禁止访问的网络。 |

网络目标的匹配规则如下：

* 网络的地址越长、越精确，优先级越高。
* 如果一个网络地址同时被添加至 `allow` 和 `deny` 列表，`deny` 的优先级高于 `allow`。
* 如果一个网络地址没有被添加至 `allow` 和 `deny` 列表，则对其采用 `default` 中设置的默认访问策略。

支持的网络地址写法如下：

<!-- @cols-width: 200,229,240 -->
| | | | \
|**格式** |**含义** |**示例** |
|---|---|---|
| | | | \
|`[ip]` |单个 IP（所有端口） |`"[192.168.1.100]"` |
| | | | \
|`[ip/mask]` |CIDR 子网（所有端口） |`"[192.168.1.0/24]"` |
| | | | \
|`[ipv6/mask]` |CIDR 子网（所有端口） |`"[ff::01/64]"` |
| | | | \
|`[ip]:port` |单个 IP:单个端口 |`"[192.168.1.100]:443"` |
| | | | \
|`[ip]:port,port` |单个 IP:多个端口 |`"[192.168.1.100]:80,443"` |
| | | | \
|`[ip/mask]:port` |CIDR 子网:单个端口 |`"[10.0.0.0/8]:22"` |
| | | | \
|`domain` |域名（所有端口） |`"example.com"` |
| | | | \
|`domain:port` |域名:单个端口 |`"api.example.com:443"` |
| | | | \
|`*.domain` |通配符域名（所有端口） |`"*.example.com"` |
| | | | \
|`*.domain:port` |通配符域名:单个端口 |`"*.example.com:443"` |

**示例 1： 仅允许访问 GitHub**

此配置将禁止所有网络请求，仅放行对 GitHub (HTTPS) 的访问，避免 AI 泄露敏感信息。

```JSON
{
    "network": {
        "default": "deny",
        "allow": ["*.github.com:443"],
        "deny": []
    }
}
```

**示例 2：禁止访问内部网络**

此配置将放行所有网络请求，但明确禁止访问常见的内网地址段，防止 AI 访问或攻击内网服务。

```JSON
{
    "network": {
        "default": "allow",
        "allow": [],
        "deny": [
            "[10.0.0.0/8]",
            "[172.16.0.0/12]",
            "[192.168.0.0/16]"
        ]
    }
}
```

## 命令的运行策略 {#8041ae18}

### 普通命令 {#62459bd7}

启用沙箱后，系统将根据命令是否在白名单内，决定其执行方式：

* **在白名单内**：命令会自动在沙箱外运行。
* **不在白名单内**：命令会自动在沙箱内运行。如果运行失败，系统会询问你是否需要在沙箱外重试。

### 高风险命令 {#8f43cf11}

为了防范系统风险，当智能体生成 `rm -rf` 等高风险命令时，系统会拦截该操作并向你弹出提示。你可以选择：

* **跳过**：跳过该命令，不运行。
* **添加 { runningCommandList} 到白名单**：将该命令的前缀添加到白名单，之后可在沙箱外运行相关命令。
* **运行**：本次在沙箱内运行该命令。

![Image=600x190](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/8f7b6505f8344c6885079c70b6e7a7f1~tplv-goo7wpa0wc-image.image)