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

在 `global.json` 文件中，你可以配置全局权限策略，包括文件目录授权、网络目标授权、命令调用规则和 MCP 调用规则。通过这些配置，你可以统一管理智能体对本地文件、网络目标、Shell 命令和 MCP 工具的访问与执行范围。

## 资源授权 {#hTRXAiL2B}

`resourceAuthorization` 对象用于配置资源级授权规则。你可以为指定文件目录设置读写或只读权限，也可以为指定网络目标设置允许或拒绝访问的策略。当智能体访问的资源命中这里的规则时，TRAE 会优先使用资源级规则；未命中时，再回退到自定义权限模式中的默认策略或系统内置的默认资源访问权限。

```JSON
"resourceAuthorization": {
  "filesystem": {
    "readWrite": [],
    "readOnly": []
  },
  "network": {
    "allow": [],
    "deny": []
  }
}
```

### 文件目录授权 {#hfeVa38c3}

`resourceAuthorization.filesystem` 用于精细控制智能体对本地文件系统的访问权限。它通过路径列表为智能体设置指定目录的读写或只读权限。

<!-- @cols-width: 132,116,100,567 -->
| | | | | \
|**字段** |**类型** |**默认值** |**描述** |
|---|---|---|---|
|`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`。
* 对于同一个文件目录，`resourceAuthorization.filesystem` 中的权限配置优先于自定义权限模式中的以及系统内置的文件系统访问权限配置。

### 网络目标授权 {#hcxLS7EsJ}

:::tip 提示
仅 Windows 和 Linux 支持。
:::

`resourceAuthorization.network` 用于管理智能体对特定网络目标的访问策略。该配置可用于允许或阻止特定域名、IP、子网或端口。

可配置的字段如下：

<!-- @cols-width: 100,111,113,524 -->
| | | | | \
|**字段** |**类型** |**默认值** |**描述** |
|---|---|---|---|
|`allow` |`string[]` |`[]` |允许访问的网络目标列表。命中该列表的出站请求将被放行。 |
|`deny` |`string[]` |`[]` |拒绝访问的网络目标列表。命中该列表的出站请求将被拒绝。 |

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

* 网络地址越长、越精确，优先级越高。
* 如果一个网络地址同时被添加至 `allow` 和 `deny` 列表，`deny` 的优先级高于 `allow`。
* 对于同一个网络目标，`resourceAuthorization.network` 中的权限配置优先于自定义权限模式中的以及系统内置的网络访问权限配置。

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

<!-- @cols-width: 200,229,240 -->
| | | | \
|**格式** |**含义** |**示例** |
|---|---|---|
|`[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 服务的访问，降低敏感信息被发送到非预期网络目标的风险。

```JSON
{
  "customProfiles": {
    "defaultCustomProfile": {
      ...
      "network": {
        "default": "deny"
      ...    
      }
    }
  },
  "resourceAuthorization": {
    "network": {
      "allow": ["*.github.com:443"],
      "deny": []
    }
  }
}
```

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

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

```JSON
{
  "customProfiles": {
    "defaultCustomProfile": {
      ...
      "network": {
        "default": "allow"
      ...
      }
    }
  },
  "resourceAuthorization": {
    "network": {
      "allow": [],
      "deny": [
        "[10.0.0.0/8]",
        "[172.16.0.0/12]",
        "[192.168.0.0/16]"
      ]
    }
  }
}
```

## 命令调用规则 {#hCaV4BBW9}

`customProfiles.defaultCustomProfile.approval.commandRules` 用于按命令内容配置审批与执行策略。它适合对特定 Shell 命令设置更精细的控制，例如直接放行常用命令、拒绝高风险命令，或要求用户在执行前确认。

:::tip 提示
`customProfiles.defaultCustomProfile.approval.commandRules` 的优先级高于自定义权限模式配置中的 `commandAstDangerChecker`。如果一个命令同时命中了全局规则和 AST 危险检测，以全局规则为准。
:::

该字段以键值对形式配置，key 为命令匹配模式，value 为对应的审批与执行策略。

**命令匹配模式：**

<!-- @cols-width: 137,156,359 -->
| | | | \
|**模式** |**示例** |**描述** |
|---|---|---|
|精确匹配 |`git status` |命令必须与该字符串完全一致才会匹配。 |
|前缀匹配 |`git add *` |命令以 `git add ` 开头即会匹配，`*` 代表任意后缀。 |
|正则匹配 |`r/rm\s+-rf/` |使用正则表达式匹配命令。 |

**审批与执行策略：**

<!-- @cols-width: 136,117,351 -->
| | | | \
|**字段** |**类型** |**描述** |
|---|---|---|
|`approval` |string |* `allow`：直接放行 |\
| | |* `ask`：触发审批 |\
| | |* `deny`：直接拒绝 |
|`execEnv` |string |命令的执行环境。取值： |\
| | | |\
| | |* `byConfig`：遵循沙箱配置 |\
| | |* `host`：强制在宿主机中执行 |\
| | |* `sandbox`：强制在宿主机中执行 |

**示例：**

```JSON
{
  "commandRules": {
    "git *": { "approval": "allow", "execEnv": "host" },
    "npm *": { "approval": "allow", "execEnv": "host" },
    "r/rm\\s+-rf/": { "approval": "deny" },
    "kill *": { "approval": "ask" }
  }
}
```

## MCP 调用规则 {#hMxrrxwr3}

`customProfiles.defaultCustomProfile.approval.mcpRules` 字段用于按 MCP Server 或 MCP 工具配置审批与执行策略。它适合对来自不同 MCP Server 的工具调用进行精细化管理，例如放行可信工具、拦截高风险工具，或要求用户在调用前确认。

该字段以键值对形式配置，key 为 MCP 工具匹配模式，value 为对应的审批与执行策略。

**MCP 工具匹配模式：**

<!-- @cols-width: 154,265,395 -->
| | | | \
|**格式** |**示例** |**描述** |
|---|---|---|
|精确匹配 |`mcpserver__mcptool` |匹配指定 MCP Server 中的指定 MCP 工具。 |
|Server 通配 |`mcpserver__*` 或 `mcpserver` |匹配指定 MCP Server 中的所有 MCP 工具。 |

**审批与执行策略：**

<!-- @cols-width: 136,117,351 -->
| | | | \
|**字段** |**类型** |**描述** |
|---|---|---|
|`approval` |string |* `allow`：直接放行 |\
| | |* `ask`：触发审批确认 |\
| | |* `deny`：直接拒绝 |

**示例：**

```JSON
{
  "mcpRules": {
    "playwright__playwright_delete": { "approval": "allow" },
    "github__*": { "approval": "ask" },
    "internal-admin": { "approval": "deny" }
  }
}
```