TraeWork 的沙箱：任务在什么环境里跑、能碰到你哪些文件

一、你真正担心的不是「它会不会写错代码」

让一个智能体替你跑命令，最让人不敢按下确认键的从来不是它写得对不对，而是这一条命令的作用范围到哪儿。它要装依赖，那 pip、npm 的缓存目录算不算它能碰的？它说要清理一下产物，清的是项目目录里的，还是顺手把上一层也清了？你在同一台机器上还开着别的活儿，另一个会话的临时文件会不会被它读走？

这些问题的答案不该靠「应该不会吧」来兜底，而应该有一份可以逐条对照的清单。TraeWork 官方文档里的《沙箱》一页就是这份清单，它把「哪些目录读写、哪些只读、哪些完全不可访问」写成了表格。这篇文章做的事情很简单：把那一页拆开，指出几处容易读反的地方，以及文档明确没有覆盖的部分。

需要先说清楚：TraeWork 仍在快速迭代，官方文档的 changelog 更新频繁，功能与计费口径都可能变动，下面复述的每一条都请以官方最新文档为准。文中提到的所有内容都来自官方文档原文，我们没有开通账号，也没有实际操作过这个产品。

二、官方文档写明的形态与开关

第一件要分清的事：沙箱不是一种形态，而是按「操作系统 + 模式 + 本地/云端」切出来的几种。

官方文档的沙箱策略概览表是这么划的：

系统	模式	沙箱形态
macOS	Work / Code / Design	本地：本机受限执行环境；云端：独立的云端沙箱容器
Windows	Code	本地：本机受限执行环境；云端：独立的云端沙箱容器
Windows	Work / Design	隔离的虚拟化运行环境，仅能读写当前项目目录

文档在这张表下面挂了一条提示：自 0.1.20 版本起，TraeWork 桌面版在 macOS 上的 Work 模式采用与 Code 模式一致的沙箱策略；Windows 上的 Work 模式仍使用独立虚拟化运行环境。 这句话对读者的实际意义是：你在网上看到的关于「Work 模式沙箱怎样怎样」的说法，得先问一句是哪个系统、哪个版本，跨系统直接搬结论会搬错。

运行环境本身不需要你配置。文档写明，macOS 侧基于系统的 sandbox-exec 工具自动创建受限执行环境，Windows 侧基于自研的沙箱 SDK 自动创建，两边都写着「你无需进行任何额外配置」。至于这个自研 SDK 具体是怎么实现的，官方文档没有说明这一点，我们也不做任何推测。

启用的入口在设置里。官方文档给出的路径是：界面左下角的头像 > 设置，进入设置中心后在左侧导航栏选择对话流，在自动运行部分把命令运行方式设置为沙箱运行（支持白名单）。下面还有一个可选项，叫白名单列表，可以按需把命令前缀加进去。菜单名照抄自官方文档，具体呈现以你自己那一版为准。

三、边界在哪：五处值得逐条对照的地方

这一段是本文的重点。沙箱这类功能，真正会咬到人的不是它能做什么，而是它在哪儿停下来。

1. 白名单的语义跟直觉相反

很多人看到「白名单」下意识以为是「批准它在沙箱里跑」。官方文档的原文不是这个意思：白名单中的命令将跳过沙箱，直接在沙箱外执行。

在「高风险命令的运行策略」一节里，文档把这条规则展开得更明确——启用沙箱后，在白名单内的命令自动在沙箱外运行；不在白名单内的命令自动在沙箱内运行，如果运行失败，系统会询问你是否需要在沙箱外重试。也就是说，白名单是一个豁免列表，不是许可列表。往里加一条，等于给这个前缀开了一个绕过受限环境的口子。这一点如果读反了，加白名单的动作方向就完全颠倒了。

2. 高风险命令拦截后的三个选项，含义各不相同

文档写明，当智能体生成 rm -rf 等高风险命令时，系统会拦截该操作并弹出提示，你可以选择：跳过（不运行）、添加 {runningCommandList} 到白名单（将该命令的前缀加入白名单，之后可在沙箱外运行相关命令）、运行（本次在沙箱内运行该命令）。

把这三项和上一条的白名单语义放在一起读，会发现一个需要留神的组合：第三项「运行」的范围是本次、在沙箱内，而第二项「添加到白名单」按文档口径，是让该前缀之后可在沙箱外运行。两个选项一个是单次受限执行，一个是长期豁免。这是两处文档原文并置得出的关系，说到这里就停，我们不推测产品这么设计的意图。

3. 只读与读写的冲突规则，以及一处需要对照着看的差异

本地任务这一段，文档给了两条前置提示：当前安全策略不涉及网络访问；读写权限继承当前用户权限；当读写与只读权限冲突时，以只读权限为准。

第一条很关键——沙箱这一页讲的是文件访问，网络不在这套策略的覆盖范围内，别把它当成网络层面的限制来用。第二条则说明沙箱不是在给你加权限，而是在你自己的用户权限之上再做减法，冲突时向更严格的一侧收敛。

具体目录清单，文档是这样写的。只读一侧：项目目录中的受保护目录 .vscode；根目录 /，并注明「默认策略：所有未显式声明为可写的目录均为只读」。读写一侧：项目目录，范围是「除 .trae、.vscode 和 .git 之外的项目文件与目录」。

这里有一处需要对照着读：只读那一栏把受保护目录列为 .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++ 等

注意「缓存目录」那一行只给了 macOS 的路径，Windows 侧的缓存目录官方文档没有单列说明这一点。Windows 用户想确认某个缓存路径算不算可写，只能落到「LOCALAPPDATA 环境变量路径内常见工具依赖的路径」这条更笼统的表述上。

4. Windows 的 Work / Design 模式是另一套，而且关不掉

这是最容易被前面那份目录表误导的地方。Windows 上的 Work 和 Design 模式走的不是本机受限执行环境，而是隔离的虚拟化运行环境。官方文档列了三个特点：AI 生成的所有代码和命令都在沙箱内执行、与主机系统分离；沙箱镜像预装了完整的 Skills 工具链，无需手动配置环境；项目文件通过受控方式挂载到沙箱中。

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

翻成日常场景就是：在这个组合下，如果智能体把某个东西写到了项目目录以外，你在本机是找不到那个文件的——它落在隔离区里了。这不是出错，是文档写明的既定行为。另外，前面那套「在对话流设置里把命令运行方式改成沙箱运行」的开关，与这里的「默认启用、无法关闭」是两个不同前提下的表述，别把 macOS 那套开关经验直接套到 Windows 的 Work / Design 上。

5. 云端任务的可访问范围

macOS 的 Work / Code / Design 模式、Windows 的 Code 模式，其云端任务都运行于独立的安全沙箱容器内，文档写明每个云端会话拥有隔离的运行环境（包括磁盘、缓存等资源）。网页版的 Work、Code 与 Design 三个模式，云端任务同样如此。两处给出的文件访问权限表是一致的四行：

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

文档还写明，在云端会话中，智能体执行命令时的文件访问权限默认遵循「自动运行」（Auto-Run）模式的策略。这句话意味着云端的实际行为跟你在自动运行那一栏的配置是挂钩的，不是一个孤立的开关。至于云端会话的数据保留多久、容器的资源规格是多少，官方文档的这一页没有说明这一点。

四、什么时候你会真的用到它

值得认真读一遍这份清单的场景，大致是这么几类。

一是让智能体装依赖、跑构建的时候。你要判断的是它拉包时写的那些缓存路径在不在上面那份可写清单里——文档只把 macOS 的缓存目录和两边的通用工具依赖目录列了出来，清单之外的路径按「默认策略：所有未显式声明为可写的目录均为只读」这一条走。至于命令实际会不会因此中断，官方文档没有说明这一点；文档写明的只是：不在白名单内的命令在沙箱内运行，如果运行失败，系统会询问你是否需要在沙箱外重试。真被问到的时候，你需要知道自己是在同意什么。

二是同一台机器上并行开多个会话。云端那张表里「不可访问其他会话的数据目录」这一行，是你判断会不会互相踩踏的依据。

三是Windows 上用 Work 或 Design 模式。你至少要记住两件事：沙箱关不掉；项目目录之外的写入你在本地看不见。找不到文件的时候先想起这一条，能省掉不少排查时间。

四是你打算往白名单里加东西之前。搞清楚加进去的效果是「跳过沙箱、在沙箱外执行」，再决定加不加、加什么前缀。

反过来，什么情况下不必特别去折腾它：如果你的任务全程只在项目目录内读写文本、不装依赖、不跑清理类命令，那按默认策略走就行，文档写明的可写范围已经覆盖了项目目录本身（除去前面提到的那几个被排除的子目录）；Windows 的 Work / Design 模式本来也没有关闭选项，不存在「要不要开」的决策。

最后提醒一句必要的分寸：这套机制限定的是文件访问，而且文档自己写了「当前安全策略不涉及网络访问」。文档还写明「读写权限继承当前用户权限」，而白名单与「沙箱外重试」这两条路径按文档口径都是跳过这套受限环境执行的。它不能替代你自己对命令内容的审阅，也不能替代备份和版本控制。请结合自身环境评估，并以官方文档最新版本为准。

---

本文依据 TraeWork 官方文档（docs.trae.cn）于 2026-08-17 的公开内容整理。 我们没有开通付费账号，也没有实际操作过该产品，因此不涉及界面外观、操作手感与生成质量的任何描述。 该产品仍在快速迭代，功能与计费口径随版本变动，文中涉及积分与套餐的表述均为复述官方文档原文， 请以官方最新公告与定价页为准。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。