> ## 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.

企业沙箱用于限制 TRAE 智能体运行命令时可访问的本地文件和网络资源。

企业管理员可以分别为 Windows、macOS 和 Linux 配置企业沙箱策略，统一设置智能体在成员客户端上的文件读写范围和网络访问范围。配置后，智能体只能访问策略允许的目录或网络地址，从而降低误读本地文件、泄露敏感数据、访问高风险网络或探测内网服务的风险。

## 适用客户端 {#hobWHoW5N}

* TRAE IDE
* TRAE Work

## 使用限制 {#hIapwgo6B}

* 企业沙箱配置的优先级高于成员的个人沙箱配置。配置下发后，成员本地的个人沙箱配置可能被覆盖或受限，请谨慎启用。
* 同一个操作系统只能启用一个企业沙箱策略。如果为同一操作系统保存并启用了新策略，原策略将失效。
* 网络访问控制目前仅支持 Windows。macOS 和 Linux 仅支持文件系统访问控制。

## 添加企业沙箱策略 {#hdPPUwiPP}


1. 登录 [TRAE 企业版控制台](https://console.enterprise.trae.cn/)。
2. 前往 **企业配置** > **安全设置**。
3. 在 **企业沙箱** 页签中，点击右上角的 **添加企业沙箱策略** 按钮。
   你将进入企业沙箱策略配置面板。
   ![Image=2544x1607](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/5420791c804e473d99c23fa668fa80e5~tplv-goo7wpa0wc-topic.png)
4. 填写该沙箱策略的名称。建议使用能体现适用范围的名称，例如 “macOS-文件访问策略” 或 “Windows-网络访问策略”。
5. 选择该沙箱策略适用的操作系统：Windows、macOS 或 Linux。
6. 填写企业沙箱配置。你可以选择以下任一方式：
   * **导入配置文件**：点击 **立即导入**，上传已写入 JSON 格式沙箱配置的本地文件。
   * **手动输入配置**：在输入框中直接填写 JSON 格式的沙箱配置。
7. 点击 **保存** 按钮。
8. 在确认弹窗中，点击 **确定** 按钮。
   企业沙箱策略保存后会默认启用，并下发到适用成员的客户端。客户端收到策略后，会优先使用企业沙箱配置。   


## 企业沙箱 JSON 配置说明 {#hPqhkQWu1}

### 配置文件格式 {#hHZIDZlmE}

企业沙箱策略使用 JSON 格式配置，包含 `filesystem` 和 `network` 两个顶层字段：

```JSON
{
  "filesystem": {
    "readWrite": [],
    "readOnly": []
  },
  "network": {
    "default": "allow",
    "allow": [],
    "deny": []
  }
}
```

### 文件访问配置说明 {#htADPhWtB}

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

<!-- @cols-width: 126,100,100,584 -->
| | | | | \
|**字段** |**类型** |**默认值** |**描述** |
|---|---|---|---|
|`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` 列表，则对其采用 TRAE 沙箱的内置文件访问控制策略（详情参考[此文档](/ide_sandbox)）。

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

:::tip 提示
仅 Windows 支持网络访问控制。
:::

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

可配置的字段如下：

<!-- @cols-width: 100,100,100,561 -->
| | | | | \
|**字段** |**类型** |**默认值** |**描述** |
|---|---|---|---|
|`default` |`string` |`allow` |默认的网络访问策略。用于决定未命中 `allow` 或 `deny` 字段中配置的网络请求是允许还是拒绝。可选值： |\
| | | | |\
| | | |* `allow`：允许访问 |\
| | | |* `deny`：禁止访问 |
|`allow` |`string[]` |`[]` |允许访问的网络。 |
|`deny` |`string[]` |`[]` |禁止访问的网络。 |

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

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

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

<!-- @cols-width: 184,202,252 -->
| | | | \
|**格式** |**含义** |**示例** |
|---|---|---|
|`[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]"
        ]
    }
}
```

## 关于企业沙箱和个人沙箱的合并 {#hrwtR0Dza}

当某个操作系统下已存在生效中的企业沙箱策略时，企业沙箱配置会下发至成员的客户端，并与成员的个人沙箱配置逐字段合并。

### 合并规则 {#hqScX0jbz}

企业沙箱与个人沙箱同时存在时，系统会按字段逐一比对，并按以下规则确定最终生效的配置：

* 若管理员已在企业沙箱中为该字段配置取值，则覆盖成员个人沙箱中的同名字段的取值。
* 若管理员未在企业沙箱中配置该字段，或该字段为空数组，则沿用成员个人沙箱中的同名字段的取值。

### 配置合并示例 {#hjTRz2wGP}

::::cols
@col 33
企业沙箱原始配置：

```JSON
{
  "filesystem": {
    "readWrite": [
      "/opt/company/workspace"
    ],
    "readOnly": []
  },
  "network": {
    "default": "deny",
    "deny": []
  }
}
```

@col 33
个人沙箱原始配置：

```JSON
{
  "filesystem": {
    "readWrite": [
      "/Users/alice/project"
    ],
    "readOnly": [
      "/Users/alice/docs",
      "/Users/alice/.ssh"
    ]
  },
  "network": {
    "default": "allow",
    "allow": [
      "api.openai.com",
      "github.com"
    ],
    "deny": [
      "internal.example.com"
    ]
  }
}
```

@col 33
合并后，最终生效的沙箱配置：

* 个人沙箱中的 `filesystem.readWrite` 和 `network.default` 字段的取值被企业沙箱覆盖。
* 个人沙箱中的 `filesystem.readOnly`、`network.allow` 和 `network.deny` 字段的取值被继续使用。

```JSON
{
  "filesystem": {
    "readWrite": [
      "/opt/company/workspace"
    ],
    "readOnly": [
      "/Users/alice/docs",
      "/Users/alice/.ssh"
    ]
  },
  "network": {
    "default": "deny",
    "allow": [
      "api.openai.com",
      "github.com"
    ],
    "deny": [
      "internal.example.com"
    ]
  }
}
```
::::