注意
本地沙盒 GitHub Copilot 位于 公开预览 且可能会更改。
重要
Windows上的本地沙盒需要Windows预览体验成员版本。
介绍
启用本地沙盒时， Copilot 命令行界面（CLI） 请在操作系统沙盒中代表你运行它调用的命令。 沙盒强制实施 文件系统策略：一组规则，用于确定沙盒进程或操作可以读取哪些路径、可以写入哪些路径，以及它根本无法触摸哪些路径。
大部分策略都是自动组装的，以便日常命令在未设置的情况下继续工作。 本文介绍如何 Copilot 到达策略，以及如何检查它在特定目录中授予的访问权限。
有关本地沙盒的概述，包括如何打开和关闭它，请参阅 关于云和本地沙盒 GitHub Copilot 和 使用本地沙盒。
策略适用于的内容
文件系统策略涵盖代表你执行的工作 Copilot ，但根据工作类型，它以不同的方式强制执行：
- Shell 命令和内置搜索 作为沙盒子进程运行，因此操作系统直接强制实施策略。 例如，这些工具
grep``glob以沙盒子进程的形式运行 ripgrep。 - 本地 MCP 和语言服务器进程（LSP） 也可以在沙盒中运行，因此操作系统也会对其强制执行策略。
- 内置文件读取和文件编辑工具 作为本身的 Copilot 命令行界面（CLI） 一部分运行，而不是作为沙盒子进程运行。 它们先检查相同的文件系统策略，然后再读取或写入文件，但由于操作系统沙盒永远不会看到这些操作，因此检查是仅软件保护，而不是操作系统强制执行的一种。
- 远程 MCP 服务器 在计算机外部运行，因此没有沙盒的本地子进程，文件系统策略不会限制它们。
- 子代理 不直接执行;它们协调其他工具。 策略是否适用以及应用方式取决于子代理调用的工具。
因此，沙盒 进程 受操作系统的约束，而进程内 操作 在软件中强制实施相同的策略，这就是为什么本文引用沙盒进程或操作，而不仅仅是命令。
权限级别
沙盒默认为拒绝：除非显式授予路径，否则命令无法使用它。 策略中的每个路径都有三个权限级别之一：
- 读/写 - 命令可以读取和修改此路径上的文件。
- 只读 - 命令可以读取此路径上的文件，但不能更改这些文件。
- 被拒绝 — 命令无法在此路径上读取或写入，即使更广泛的规则将允许它。
由于除非授予访问权限， Copilot 否则必须授予它合法需要的所有内容（项目文件、运行的工具和支持位置（如临时目录）的命令，同时保留其他所有内容不受限制。
注意
这些权限级别适用于每个沙盒进程或操作，但它们以不同的方式强制执行：对于沙盒子进程，操作系统会直接强制实施这些进程，而 CLI 自己的内置文件读取和文件编辑工具会在软件中检查相同的级别，而无需操作系统后退。
如何生成策略
在每个沙盒进程启动之前， Copilot 命令行界面（CLI） 使用当前工作目录、环境、设置和自动授予解析该进程的有效策略。 这会将过程限制为仅需要访问，这意味着你不必自己管理这些常见位置。
工作目录
当本地沙盒的文件系统设置中启用了 Include 工作目录 （默认启用）时，将授予当前工作目录读/写访问权限。 在 Git 存储库中， Copilot 还会添加关联的 Git 授权。 关闭此设置将禁止所有这些自动授予，因此必须手动添加所需项目和 Git 路径的允许规则。 请参阅“配置本地沙盒设置”。
注意
如果从企业拥有的组织获取 Copilot ，管理员可以关闭 “包括工作目录 ”设置并锁定它，因此无法将其重新打开。 请参阅“企业托管设置”。
PATH 上的工具
若要运行程序，或者python``git，沙盒必须让命令查看程序所在的目录。
PATH环境变量列出这些目录，并向其授予只读访问权限，以及Copilot相关工具变量（例如GOPATH，CARGO_HOME和PYTHONPATH）命名的目录。 只读是外部工具的正确级别：命令需要运行 git，而不是对其进行修改。 有关沙盒检查的工具链环境变量的完整列表 PATH 以及每个环境变量的解释方式，请参阅 GitHub Copilot CLI 命令参考。
系统和配置文件位置
标准系统位置和用户配置文件（主页）目录是只读的，因此命令可以读取配置文件和共享库，而无需更改它们。
包管理器缓存
若要让安装和生成在沙盒中运行， Copilot 还授予对常见包管理器和工具链使用的缓存和注册表的访问权限，即注册表和工具链的只读，以及生成缓存的读/写。 在报表中 /sandbox policy ，这显示为 开发工具访问权限。
Git 存储库
在 Git 存储库的子目录中工作时，Copilot授予对整个存储库的读取访问权限，以便命令可以查看完整的项目，同时限制对当前工作目录和存储库的 Git 元数据（其.git目录）的写入。 这样，命令就可以跨存储库进行读取，但将更改集中在你工作的位置上。
由于读取访问权限跨越整个存储库，沙盒命令可以读取当前子目录之外的文件，包括项目中其他位置存储的任何敏感内容。 若要使特定路径无法访问，可以添加拒绝规则。 请参阅“配置本地沙盒设置”。
访问规则重叠时
由于 Copilot 授予多个位置，你可以添加自己的位置，因此规则可以重叠。 当他们这样做时， 更具体的路径会赢。 例如，如果/project可写但标记为/project/secrets只读，则除以下情况外/project/secrets，所有/project内容都保持可写状态。 这是保护敏感子文件夹的有用方法。
当方便授予会妨碍你时，也会解决重叠问题。 请考虑一个Python项目，其中包含显示在你的PATH本地虚拟环境 （.venv） 上。 将该目录视为普通的只读工具位置会使它处于只读状态（即使它位于可写项目内），并且这样的命令在 pip install 尝试更新环境时可能会失败。
Copilot 为你解决此问题：它自动添加的授权（例如工具目录） PATH为已涵盖它的更广泛的读/写授权提供了一种途径。 因此，作为工作区的一部分，项目本地.venv``node_modules/.bin目录或类似的目录保持可写性。
配置的规则始终保留。 如果将路径标记为只读，或者拒绝该路径，则即使会自动发现并授予相同的路径，该决定也是如此。 这为你提供了一种可靠的方法来保护敏感位置，例如，拒绝 .env 文件，以便没有沙盒命令可以读取机密。
检查当前策略允许的内容
由于策略是针对每个目录和命令进行组合的，因此查看访问的最简单方法是询问 Copilot 命令行界面（CLI）。 在会话中，输入：
/sandbox policy
/sandbox policy
Copilot 打印当前目录 的有效 策略：从此处启动的命令实际接收的读/写、只读和拒绝路径，以及有效网络访问和开发工具访问。 这是自动授予和你自己的设置合并后解析的结果，并且解析了任何重叠，而不仅仅是已保存设置的副本。
阅读报表时要记住的一些事项：
- 它反映 当前目录。 由于每个目录都发现授予，因此根据运行位置，相同的设置可以解析为不同的路径。
- 如果磁盘上不存在你配置的路径，则会将其排除在策略外，并在 “说明” 部分中注明。 这解释了添加的规则为何可能不起作用。
- 如果沙盒已关闭，
/sandbox policy请告知你，而不是打印策略，因为没有任何限制。
若要仅检查沙盒当前是否处于打开状态，请使用 /sandbox status。 有关这些命令的详细信息，请参阅 使用本地沙盒。
自定义策略
你可以从对话框或设置文件中授予额外的读/写或只读路径、拒绝路径和更改其他文件系统行为 /sandbox config 。 进行更改后，运行 /sandbox policy 以确认结果。 有关分步说明，请参阅 配置本地沙盒设置。
企业管理的策略
如果 Copilot 通过企业拥有的组织，管理员可以通过托管设置强制实施文件系统策略。 托管设置充当无法松动的基线：它们可能需要沙盒、添加被拒绝的路径，以及限制允许授予的路径。 应用托管设置时， /sandbox config 对话框将其显示为锁定 的（托管） 值，并将其 /sandbox policy 反映在解析的策略中。
与大多数设置不同，其中单个源获胜，沙盒策略由每次生效的每个源组成。 托管设置可以同时通过多个通道（服务器托管、MDM 和基于文件的通道）到达，这些设置彼此结合，并与你自己的设置组合在 一 起，而不是一个替代另一个源：所需的切换保持打开状态，拒绝来自所有源的路径相加，并且允许授予的路径只能缩小。 有关详细信息，请参阅“企业托管设置”。