AI 助手
TRAE 智能问答助手
你好,我是 TRAE 文档问答助手 🎉 你在阅读当前文档的过程中,无论对文档概念的解释,还是文档内容方面的疑问,都可以随时向我提问,我会全力为你解答
推荐问题
TRAE IDE 里最热门的 Skill 是哪些?
如何创建自定义智能体?
如何配置 Rules?
文档反馈
TRAE 企业版介绍
产品动态
计费说明
订阅管理
组织管理
用量管理
AI 配置
自动化
成员个人设置
问题排查
帮助与支持
相关协议

企业沙箱

复制页面

企业沙箱用于限制 TRAE 智能体运行命令时可访问的本地文件和网络资源。

企业管理员可以分别为 Windows、macOS 和 Linux 配置企业沙箱策略,统一设置智能体在成员客户端上的文件读写范围和网络访问范围。配置后,智能体只能访问策略允许的目录或网络地址,从而降低误读本地文件、泄露敏感数据、访问高风险网络或探测内网服务的风险。

适用客户端

  • TRAE
  • TRAE CLI

使用限制

  • 企业沙箱配置的优先级高于成员的个人沙箱配置。配置下发后,成员本地的个人沙箱配置可能被覆盖或受限,请谨慎启用。
  • 同一个操作系统只能启用一个企业沙箱策略。如果为同一操作系统保存并启用了新策略,原策略将失效。
  • 网络访问控制目前仅支持 Windows。macOS 和 Linux 仅支持文件系统访问控制。

添加企业沙箱策略

  1. 登录 TRAE 企业版控制台。
  2. 前往 企业配置 > 安全设置。
  3. 在 企业沙箱 页签中,点击右上角的 添加企业沙箱策略 按钮。
    你将进入企业沙箱策略配置面板。
    Image
  4. 填写该沙箱策略的名称。建议使用能体现适用范围的名称,例如 “macOS-文件访问策略” 或 “Windows-网络访问策略”。
  5. 选择该沙箱策略适用的操作系统:Windows、macOS 或 Linux。
  6. 填写企业沙箱配置。你可以选择以下任一方式:
    • 导入配置文件:点击 立即导入,上传已写入 JSON 格式沙箱配置的本地文件。
    • 手动输入配置:在输入框中直接填写 JSON 格式的沙箱配置。
  7. 点击 保存 按钮。
  8. 在确认弹窗中,点击 确定 按钮。
    企业沙箱策略保存后会默认启用,并下发到适用成员的客户端。客户端收到策略后,会优先使用企业沙箱配置。

企业沙箱 JSON 配置说明

配置文件格式

企业沙箱策略使用 JSON 格式配置,包含 filesystem 和 network 两个顶层字段:

{
  "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 沙箱的内置文件访问控制策略(详情参考此文档)。

网络访问配置说明

提示

仅 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 泄露敏感信息。

{
    "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]"
        ]
    }
}

关于企业沙箱和个人沙箱的合并

当某个操作系统下已存在生效中的企业沙箱策略时,企业沙箱配置会下发至成员的客户端,并与成员的个人沙箱配置逐字段合并。

合并规则

企业沙箱与个人沙箱同时存在时,系统会按字段逐一比对,并按以下规则确定最终生效的配置:

  • 若管理员已在企业沙箱中为该字段配置取值,则覆盖成员个人沙箱中的同名字段的取值。
  • 若管理员未在企业沙箱中配置该字段,或该字段为空数组,则沿用成员个人沙箱中的同名字段的取值。

配置合并示例

企业沙箱原始配置:

{
  "filesystem": {
    "readWrite": [
      "/opt/company/workspace"
    ],
    "readOnly": []
  },
  "network": {
    "default": "deny",
    "deny": []
  }
}

个人沙箱原始配置:

{
  "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 字段的取值被继续使用。
{
  "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"
    ]
  }
}