TRAE 沙箱

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

支持的操作系统

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

安全策略：文件访问控制

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

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

使用流程

第一步：在操作系统中配置环境

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

macOS

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

Windows

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

WSL2 & Linux

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

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

• 关于如何在 Windows 上运行 Linux 环境，参考使用 WSL 进行远程开发。
• 关于如何使用 Remote SSH 功能连接你的 Linux 远程主机，参考使用 SSH 进行远程开发。

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

1. 检查当前系统是否启用 User Namespace。绝大多数 Linux 发行版默认已启用该功能。

2. 完成临时参数配置（仅当前运行周期生效）。
   若系统禁止普通用户创建 User Namespace，或该功能未启用，TRAE 会临时修改内核参数，允许非特权用户创建 User Namespace：

   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 文件。

   kernel.unprivileged_userns_clone=1
   kernel.apparmor_restrict_unprivileged_userns=0

第二步：在 TRAE 中启用沙箱

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

1. 在 IDE 模式界面中，点击界面右上角的 设置 图标，进入设置中心。

   或

   在 SOLO 模式界面中，点击对话面板右上角的 设置 图标，进入设置中心。

2. 在左侧导航栏中，选择 ，进入 面板。
3. 在 部分的 处，为 IDE 和/或 SOLO 模式选择 模式。

4. 在 IDE / SOLO 处，按需将命令前缀加入白名单。

   白名单中的命令将跳过沙箱，直接在沙箱外执行。
   

自定义沙箱配置

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

sandbox.json 文件的位置

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

创建并编辑 sandbox.json 文件

1. 前往 设置 > 对话流。

2. 在 沙箱自定义配置 处，点击 打开配置 按钮。

   

   TRAE 将在你的本地用户目录中创建 sandbox.json 文件，并在编辑器内打开它。

   该文件的初始结构如下：

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

3. 在打开的 sandbox.json 文件中，填入你的自定义沙箱配置。
4. 保存文件以使配置生效。

文件访问配置说明

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

支持的路径格式：

• 绝对路径：例如 /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 列表，则对其采用上文安全策略：文件访问控制中的规则。

网络访问配置说明

💡提示

仅 Windows 操作系统支持此功能。

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

可配置的字段如下：

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

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

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

示例 1： 仅允许访问 GitHub

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

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

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

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

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

命令的运行策略

普通命令

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

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

高风险命令

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

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