# 了解本地沙盒的文件系统策略 GitHub Copilot CLI

启用本地沙盒后，在 Copilot CLI 文件系统策略下运行每个沙盒进程或操作，以控制它可以读取和写入的文件和目录。 了解该策略的生成方式以及如何检查它授予的访问权限。

> \[!NOTE]
> 本地沙盒 GitHub Copilot 位于 公开预览 且可能会更改。

> \[!IMPORTANT]
> Windows上的本地沙盒需要Windows预览体验成员版本。

## 介绍

启用本地沙盒时， Copilot CLI 请在操作系统沙盒中代表你运行它调用的命令。 沙盒强制实施 **文件系统策略**：一组规则，用于确定沙盒进程或操作可以读取哪些路径、可以写入哪些路径，以及它根本无法触摸哪些路径。

大部分策略都是自动组装的，以便日常命令在未设置的情况下继续工作。 本文介绍如何 Copilot 到达策略，以及如何检查它在特定目录中授予的访问权限。

有关本地沙盒的概述，包括如何打开和关闭它，请参阅 [关于云和本地沙盒 GitHub Copilot](/zh/copilot/concepts/about-cloud-and-local-sandboxes) 和 [使用本地沙盒](/zh/copilot/how-tos/cloud-and-local-sandboxes/using-local-sandboxing)。

## 策略适用于的内容

文件系统策略涵盖代表你执行的工作 Copilot ，但根据工作类型，它以不同的方式强制执行：

* **Shell 命令和内置搜索** 作为沙盒子进程运行，因此操作系统直接强制实施策略。 例如，这些工具`grep``glob`以沙盒子进程的形式运行 ripgrep。
* **本地 MCP 和语言服务器进程（LSP）** 也可以在沙盒中运行，因此操作系统也会对其强制执行策略。
* **内置文件读取和文件编辑工具** 作为本身的 Copilot CLI 一部分运行，而不是作为沙盒子进程运行。 它们先检查相同的文件系统策略，然后再读取或写入文件，但由于操作系统沙盒永远不会看到这些操作，因此检查是仅软件保护，而不是操作系统强制执行的一种。
* **远程 MCP 服务器** 在计算机外部运行，因此没有沙盒的本地子进程，文件系统策略不会限制它们。
* **子代理** 不直接执行;它们协调其他工具。 策略是否适用以及应用方式取决于子代理调用的工具。

因此，沙盒 **进程** 受操作系统的约束，而进程内 **操作** 在软件中强制实施相同的策略，这就是为什么本文引用沙盒进程或操作，而不仅仅是命令。

## 权限级别

**沙盒默认为拒绝**：除非显式授予路径，否则命令无法使用它。 策略中的每个路径都有三个权限级别之一：

* **读/写** - 命令可以读取和修改此路径上的文件。
* **只读** - 命令可以读取此路径上的文件，但不能更改这些文件。
* **被拒绝** — 命令无法在此路径上读取或写入，即使更广泛的规则将允许它。

由于除非授予访问权限， Copilot 否则必须授予它合法需要的所有内容（项目文件、运行的工具和支持位置（如临时目录）的命令，同时保留其他所有内容不受限制。

> \[!NOTE]
> 这些权限级别适用于每个沙盒进程或操作，但它们以不同的方式强制执行：对于沙盒子进程，操作系统会直接强制实施这些进程，而 CLI 自己的内置文件读取和文件编辑工具会在软件中检查相同的级别，而无需操作系统后退。

## 如何生成策略

在每个沙盒进程启动之前， Copilot CLI 使用当前工作目录、环境、设置和自动授予解析该进程的有效策略。 这会将过程限制为仅需要访问，这意味着你不必自己管理这些常见位置。

### 工作目录

当本地沙盒的文件系统设置中启用了 **Include 工作目录** （默认启用）时，将授予当前工作目录读/写访问权限。 在 Git 存储库中， Copilot 还会添加关联的 Git 授权。 关闭此设置将禁止所有这些自动授予，因此必须手动添加所需项目和 Git 路径的允许规则。 请参阅“[配置本地沙盒设置](/zh/copilot/how-tos/cloud-and-local-sandboxes/configuring-local-sandbox-settings)”。

> \[!NOTE]
> 如果从企业拥有的组织获取 Copilot ，管理员可以关闭 **“包括工作目录** ”设置并锁定它，因此无法将其重新打开。 请参阅“[企业管理设置](/zh/copilot/reference/enterprise-administrators/enterprise-managed-settings#sandbox)”。

### PATH 上的工具

若要运行程序，或者`python``git`，沙盒必须让命令查看程序所在的目录。
`PATH`环境变量列出这些目录，并向其授予**只读**访问权限，以及Copilot相关工具变量（例如`GOPATH`，`CARGO_HOME`和`PYTHONPATH`）命名的目录。 只读是外部工具的正确级别：命令需要运行 `git`，而不是对其进行修改。 有关沙盒检查的工具链环境变量的完整列表 `PATH` 以及每个环境变量的解释方式，请参阅 [GitHub Copilot CLI 命令参考](/zh/copilot/reference/copilot-cli-reference/cli-command-reference#sandbox-tool-directory-grants)。

### 系统和配置文件位置

标准系统位置和用户配置文件（主页）目录是只读的，因此命令可以读取配置文件和共享库，而无需更改它们。

### 包管理器缓存

若要让安装和生成在沙盒中运行， Copilot 还授予对常见包管理器和工具链使用的缓存和注册表的访问权限，即注册表和工具链的只读，以及生成缓存的读/写。 在报表中 `/sandbox policy` ，这显示为 **开发工具访问权限**。

### Git 存储库

在 Git 存储库的子目录中工作时，Copilot授予对整个存储库的**读取**访问权限，以便命令可以查看完整的项目，同时限制对当前工作目录和存储库的 Git 元数据（其`.git`目录）的**写入**。 这样，命令就可以跨存储库进行读取，但将更改集中在你工作的位置上。

由于读取访问权限跨越整个存储库，沙盒命令可以读取当前子目录之外的文件，包括项目中其他位置存储的任何敏感内容。 若要使特定路径无法访问，可以添加拒绝规则。 请参阅“[配置本地沙盒设置](/zh/copilot/how-tos/cloud-and-local-sandboxes/configuring-local-sandbox-settings)”。

## 访问规则重叠时

由于 Copilot 授予多个位置，你可以添加自己的位置，因此规则可以重叠。 当他们这样做时， **更具体的路径会赢**。 例如，如果`/project`可写但标记为`/project/secrets`只读，则除以下情况外`/project/secrets`，所有`/project`内容都保持可写状态。 这是保护敏感子文件夹的有用方法。

当方便授予会妨碍你时，也会解决重叠问题。 请考虑一个Python项目，其中包含显示在你的`PATH`本地虚拟环境 （`.venv`） 上。 将该目录视为普通的只读工具位置会使它处于只读状态（即使它位于可写项目内），并且这样的命令在 `pip install` 尝试更新环境时可能会失败。
Copilot 为你解决此问题：它自动添加的授权（例如工具目录） `PATH`为已涵盖它的更广泛的读/写授权提供了一种途径。 因此，作为工作区的一部分，项目本地`.venv``node_modules/.bin`目录或类似的目录保持可写性。

**配置**的规则始终保留。 如果将路径标记为只读，或者拒绝该路径，则即使会自动发现并授予相同的路径，该决定也是如此。 这为你提供了一种可靠的方法来保护敏感位置，例如，拒绝 `.env` 文件，以便没有沙盒命令可以读取机密。

## 检查当前策略允许的内容

由于策略是针对每个目录和命令进行组合的，因此查看访问的最简单方法是询问 Copilot CLI。 在会话中，输入：

```shell copy
/sandbox policy
```

Copilot 打印当前目录 **的有效** 策略：从此处启动的命令实际接收的读/写、只读和拒绝路径，以及有效网络访问和开发工具访问。 这是自动授予和你自己的设置合并后解析的结果，并且解析了任何重叠，而不仅仅是已保存设置的副本。

阅读报表时要记住的一些事项：

* 它反映 **当前目录**。 由于每个目录都发现授予，因此根据运行位置，相同的设置可以解析为不同的路径。
* 如果磁盘上不存在你配置的路径，则会将其排除在策略外，并在 **“说明”** 部分中注明。 这解释了添加的规则为何可能不起作用。
* 如果沙盒已关闭， `/sandbox policy` 请告知你，而不是打印策略，因为没有任何限制。

若要仅检查沙盒当前是否处于打开状态，请使用 `/sandbox status`。 有关这些命令的详细信息，请参阅 [使用本地沙盒](/zh/copilot/how-tos/cloud-and-local-sandboxes/using-local-sandboxing)。

## 自定义策略

你可以从对话框或设置文件中授予额外的读/写或只读路径、拒绝路径和更改其他文件系统行为 `/sandbox config` 。 进行更改后，运行 `/sandbox policy` 以确认结果。 有关分步说明，请参阅 [配置本地沙盒设置](/zh/copilot/how-tos/cloud-and-local-sandboxes/configuring-local-sandbox-settings)。

## 企业管理的策略

如果 Copilot 通过企业拥有的组织，管理员可以通过托管设置强制实施文件系统策略。 托管设置充当无法松动的基线：它们可能需要沙盒、添加被拒绝的路径，以及限制允许授予的路径。 应用托管设置时， `/sandbox config` 对话框将其显示为锁定 **的（托管）** 值，并将其 `/sandbox policy` 反映在解析的策略中。

与大多数设置不同，其中单个源获胜，沙盒策略由每次生效的每个源组成。 托管设置可以同时通过多个通道（服务器托管、MDM 和基于文件的通道）到达，这些设置彼此结合，并与你自己的设置组合在 **一** 起，而不是一个替代另一个源：所需的切换保持打开状态，拒绝来自所有源的路径相加，并且允许授予的路径只能缩小。 有关详细信息，请参阅“[企业管理设置](/zh/copilot/reference/enterprise-administrators/enterprise-managed-settings#sandbox)”。

## 延伸阅读

* [关于云和本地沙盒 GitHub Copilot](/zh/copilot/concepts/about-cloud-and-local-sandboxes)
* [使用本地沙盒](/zh/copilot/how-tos/cloud-and-local-sandboxes/using-local-sandboxing)
* [配置本地沙盒设置](/zh/copilot/how-tos/cloud-and-local-sandboxes/configuring-local-sandbox-settings)