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

支持的操作系统

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

系统内置安全策略：文件访问控制

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

使用流程

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

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

第二步：在 TraeCode 中启用沙箱

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

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. 在 沙箱自定义配置 处，点击 打开配置 按钮。 TraeCode 将在你的本地用户目录中创建 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 列表，则对其采用上文安全策略：文件访问控制中的规则。

网络访问配置说明

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} 到白名单：将该命令的前缀添加到白名单，之后可在沙箱外运行相关命令。
• 运行：本次在沙箱内运行该命令。