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

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

## TraeWork 桌面版 {#hIFrZ5csT}

### 沙箱策略概览 {#hQG2nECmC}

<!-- @cols-width: 124,119,251,421 -->
| **操作系统**  | **模式**  | **沙箱形态**  | **描述**  |
| --- | --- | --- | --- |
| macOS  | * Code | * 本地：本机受限执行环境。 | * 本地任务：项目目录可写；受保护目录和未显式声明为可写的目录只读。 | \
| | * Work | * 云端：独立的云端沙箱容器。  | * 云端任务：仅可访问当前云端会话内的工作目录、临时目录和缓存目录。  | \
| | * Design  | | |
| Windows  | * Code  | * 本地：本机受限执行环境。 | * 本地任务：项目目录可写；受保护目录和未显式声明为可写的目录只读。 | \
| | | * 云端：独立的云端沙箱容器。  | * 云端任务：仅可访问当前云端会话内的工作目录、临时目录和缓存目录。  |
|^^| * Work | 隔离的虚拟化运行环境。  | 仅能读写当前项目目录。  | \
| | * Design  | | |

:::tip 提示
自 0.1.20 版本起，TraeWork 桌面版在 macOS 上的 Work 模式采用与 Code 模式一致的沙箱策略。Windows 上的 Work 模式仍使用独立虚拟化运行环境。
:::

### (macOS) Work / Code / Design 模式 + (Windows) Code 模式 {#d29b0b41}

#### 安全策略 {#hNaEpSNoJ}

* **云端任务**
   在 macOS 系统中，TraeWork 桌面版的 Work、Code 和 Design 模式，以及 Windows 系统中的 Code 模式，所有云端任务均运行于独立的安全沙箱容器内。每个云端会话拥有隔离的运行环境（包括磁盘、缓存等资源），以确保会话之间互不干扰。
   在云端会话中，智能体执行命令时的文件访问权限默认遵循 “自动运行”（Auto-Run）模式的策略。
   启用沙箱后，智能体的文件访问范围将被严格限制在当前会话对应的沙箱容器内，无法访问宿主机或其他会话的数据。这种隔离机制确保了各会话的工作目录、临时文件、缓存及运行环境彼此独立，从而提升整体安全性与稳定性。
   文件访问权限如下：
   <!-- @cols-width: 100,283,449 -->
   | **权限类型**  | **目录类型**  | **权限范围**  |
   | --- | --- | --- |
   | 读写  | 当前会话的工作目录  | 仅当前项目或当前会话内创建、同步的文件与目录。  |
   | 读写  | 沙箱容器内的临时与缓存目录  | 仅当前会话运行所需的临时文件及依赖缓存路径。  |
   | 不可访问  | 宿主机的文件系统  | 无法访问用户本地设备或平台宿主机上的任何目录。  |
   | 不可访问  | 其他会话的数据目录  | 无法访问其他会话的文件、缓存、磁盘及运行环境资源。  |
* **本地任务**
   :::tip 提示
   * 当前安全策略不涉及网络访问。
   * 读写权限继承当前用户权限；当读写与只读权限冲突时，以只读权限为准。
   :::   


在 macOS 系统中，TraeWork 桌面版的 Work、Code 和 Design 模式，以及 Windows 系统中的 Code 模式，在执行本地任务时，对文件的访问权限如下：

<!-- @cols-width: 100,219,528 -->
| **权限类型**  | **目录类型**  | **目录列表**  |
| --- | --- | --- |
| 只读  | 项目目录中的受保护目录  | `.vscode`  |
|^^| 根目录  | `/`（默认策略：所有未显式声明为可写的目录均为只读）  |
| 读写  | 项目目录  | 除 `.trae`、`.vscode` 和 `.git` 之外的项目文件与目录  |
|^^| 临时目录  | * macOS：`/tmp`、`/var/folders`、`TMPDIR` 环境变量路径 | \
| | | * Windows：`~/AppData/Local/Temp`、`~/AppData/LocalLow/Temp`  |
|^^| 缓存目录  | macOS：`~/Library/Caches`、`~/.cache`、`XDG_CACHE_HOME` 环境变量路径  |
|^^| 通用工具依赖目录  | * macOS：`~/.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++ 等常用语言的工具链及其依赖目录。  |

#### 配置沙箱的运行环境 {#d67f69ca}

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

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

#### 在 TraeWork 中启用沙箱 {#86d04aa7}

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

1. 在界面左下角，点击 **头像** > **设置**。
   你将进入设置中心。
2. 在左侧导航栏中，选择 **对话流**。
   你将进入对话流设置面板。
3. 在 **自动运行** 部分，将 **命令运行方式** 设置为 **沙箱运行（支持白名单）**。
4. (可选) 在 **白名单列表** 处，按需将命令前缀加入白名单。
   白名单中的命令将跳过沙箱，直接在沙箱外执行。   


![Image=1720x288](https://p16-arcosite-sg.ibyteimg.com/tos-alisg-i-k9wyc2ijk0-sg/80a7bf62925b455a802d04ea586e28df~tplv-k9wyc2ijk0-image.image)

### (Windows) Work / Design 模式 {#0d4e6351}

在 Windows 系统中，TraeWork 桌面版的 Work 和 Design 模式为你提供了一个安全、隔离的虚拟化运行环境，具有以下特点：

* **完全隔离**：AI 生成的所有代码和命令都在沙箱内执行，与你的主机系统完全分离，确保主机安全。
* **开箱即用**：沙箱镜像预装了完整的 Skills 工具链，你无需手动配置环境，即可立即使用。
* **安全共享**：你的项目文件通过受控方式挂载到沙箱中，既方便了文件使用，又有效保障了数据安全。

沙箱默认启用，且无法关闭。项目内的文件写入会同步到本地项目目录，因此可在本地环境中查看；对项目目录之外路径的读写将写入沙箱隔离区，不会影响系统环境，也不会在本地环境中可见。

## TraeWork 网页版 {#ffc6315b}

在 TraeWork 网页版的 Work、Code 与 Design 模式中，所有云端任务均运行于独立的安全沙箱容器内。每个云端会话拥有隔离的运行环境（包括磁盘、缓存等资源），以确保会话之间互不干扰。

在云端会话中，智能体执行命令时的文件访问权限默认遵循 “自动运行”（Auto-Run）模式的策略。

启用沙箱后，智能体的文件访问范围将被严格限制在当前会话对应的沙箱容器内，无法访问宿主机或其他会话的数据。这种隔离机制确保了各会话的工作目录、临时文件、缓存及运行环境彼此独立，从而提升整体安全性与稳定性。

文件访问权限如下：

<!-- @cols-width: 100,283,449 -->
| **权限类型**  | **目录类型**  | **权限范围**  |
| --- | --- | --- |
| 读写  | 当前会话的工作目录  | 仅当前项目或当前会话内创建、同步的文件与目录。  |
| 读写  | 沙箱容器内的临时与缓存目录  | 仅当前会话运行所需的临时文件及依赖缓存路径。  |
| 不可访问  | 宿主机的文件系统  | 无法访问用户本地设备或平台宿主机上的任何目录。  |
| 不可访问  | 其他会话的数据目录  | 无法访问其他会话的文件、缓存、磁盘及运行环境资源。  |

## 高风险命令的运行策略 {#f5263bae}

### 普通命令 {#d1119566}

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

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

### 高风险命令 {#b917a7c8}

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

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

![Image=1700x299](https://p16-arcosite-sg.ibyteimg.com/tos-alisg-i-k9wyc2ijk0-sg/952d9f7934384ab6b464b30e42302653~tplv-k9wyc2ijk0-image.image)