企业沙箱用于限制 TRAE 智能体运行命令时可访问的本地文件和网络资源。企业管理员可以分别为 Windows、macOS 和 Linux 配置企业沙箱策略，统一设置智能体在成员客户端上的文件读写范围和网络访问范围。配置后，智能体只能访问策略允许的目录或网络地址，从而降低误读本地文件、泄露敏感数据、访问高风险网络或探测内网服务的风险。 ## 适用客户端 * TRAE IDE * TRAE Work ## 使用限制 * 企业沙箱配置的优先级高于成员的个人沙箱配置。配置下发后，成员本地的个人沙箱配置可能被覆盖或受限，请谨慎启用。 * 同一个操作系统只能启用一个企业沙箱策略。如果为同一操作系统保存并启用了新策略，原策略将失效。 * 网络访问控制目前仅支持 Windows。macOS 和 Linux 仅支持文件系统访问控制。 ## 添加企业沙箱策略 1. 登录 [TRAE 企业版控制台](https://console.enterprise.trae.cn/)。 2. 前往 **企业配置** \> **安全设置**。 3. 在 **企业沙箱** 页签中，点击右上角的 **添加企业沙箱策略** 按钮。你将进入企业沙箱策略配置面板。 ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/99a484494bd449f588a8f64cada4b775) 4. 填写该沙箱策略的名称。建议使用能体现适用范围的名称，例如 “macOS\-文件访问策略” 或 “Windows\-网络访问策略”。 5. 选择该沙箱策略适用的操作系统：Windows、macOS 或 Linux。 6. 填写企业沙箱配置。你可以选择以下任一方式： * **导入配置文件**：点击 **立即导入**，上传已写入 JSON 格式沙箱配置的本地文件。 * **手动输入配置**：在输入框中直接填写 JSON 格式的沙箱配置。 7. 点击 **保存** 按钮。 8. 在确认弹窗中，点击 **确定** 按钮。企业沙箱策略保存后会默认启用，并下发到适用成员的客户端。客户端收到策略后，会优先使用企业沙箱配置。 ## 企业沙箱 JSON 配置说明 ### 配置文件格式企业沙箱策略使用 JSON 格式配置，包含 `filesystem` 和 `network` 两个顶层字段： ```JSON { "filesystem": { "readWrite": [], "readOnly": [] }, "network": { "default": "allow", "allow": [], "deny": [] } } ``` ### 文件访问配置说明 `filesystem` 字段用于精细控制沙箱对本地文件系统的访问权限。 |**字段** |**类型** |**默认值** |**描述** | |---|---|---|---| |`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 沙箱的内置文件访问控制策略（详情参考[此文档](https://www.volcengine.com/ide_sandbox)）。 ### 网络访问配置说明

提示

仅 Windows 支持网络访问控制。

`network` 字段用于管理沙箱内进程的网络请求策略，实现允许或阻止对特定网络的访问。可配置的字段如下： |**字段** |**类型** |**默认值** |**描述** | |---|---|---|---| |`default` |`string` |`allow` |默认的网络访问策略。用于决定未命中 `allow` 或 `deny` 字段中配置的网络请求是允许还是拒绝。可选值：

* `allow`：允许访问

* `deny`：禁止访问 | |`allow` |`string[]` |`[]` |允许访问的网络。 | |`deny` |`string[]` |`[]` |禁止访问的网络。 | 网络目标的匹配规则如下： * 网络的地址越长、越精确，优先级越高。 * 如果一个网络地址同时被添加至 `allow` 和 `deny` 列表，`deny` 的优先级高于 `allow`。 * 如果一个网络地址没有被添加至 `allow` 和 `deny` 列表，则对其采用 `default` 中设置的默认访问策略。支持的网络地址写法如下： |**格式** |**含义** |**示例** | |---|---|---| |`[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]" ] } } ``` ## 关于企业沙箱和个人沙箱的合并当某个操作系统下已存在生效中的企业沙箱策略时，企业沙箱配置会下发至成员的客户端，并与成员的个人沙箱配置逐字段合并。 ### 合并规则企业沙箱与个人沙箱同时存在时，系统会按字段逐一比对，并按以下规则确定最终生效的配置： * 若管理员已在企业沙箱中为该字段配置取值，则覆盖成员个人沙箱中的同名字段的取值。 * 若管理员未在企业沙箱中配置该字段，或该字段为空数组，则沿用成员个人沙箱中的同名字段的取值。 ### 配置合并示例企业沙箱原始配置： ```JSON { "filesystem": { "readWrite": [ "/opt/company/workspace" ], "readOnly": [] }, "network": { "default": "deny", "deny": [] } } ``` 个人沙箱原始配置： ```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" ] } } ``` 合并后，最终生效的沙箱配置： * 个人沙箱中的 `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" ] } } ```

TRAE CN