注意
本地沙盒 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 这样的程序，沙盒必须让该命令能够看到该程序所在的目录。 启用 “允许开发工具访问 ”（如默认情况下）时，Copilot 将 授予对 环境变量中列出的 PATH 目录的只读访问权限，以及相关工具变量（例如 GOPATH， JAVA_HOME和 PYTHONPATH）命名的目录。 只读是外部工具的正确级别：命令需要运行 git，而不是对其进行修改。 如果关闭 “允许开发工具访问” ，则不再自动授予这些目录，并且必须来自你自己的允许规则。 有关沙盒检查的 PATH 环境变量和工具链环境变量的完整列表，以及对每个变量如何解释的说明，请参阅 GitHub Copilot CLI 命令参考。
系统和配置文件位置
在 macOS 上，标准系统位置是只读的，因此命令可以加载共享库和读取系统配置，而无需更改它们。 启用 “允许开发工具访问” 时，用户配置文件中的应用程序目录也被授予只读权限，以便命令可以读取已安装的工具，而无需修改它们。
包管理器缓存
为了让安装和构建能够在沙盒内进行，Copilot 还允许访问常见包管理器和工具链使用的缓存及软件包注册表——大多数位置为只读，而选定的可写位置（例如构建缓存和包管理器的依赖存储）则为读写。 在 /sandbox policy 报告中，此项显示为 开发工具访问权限。
Git 存储库
在 Git 存储库的子目录中工作时，Copilot授予对整个存储库的读取访问权限，以便命令可以查看完整的项目，同时限制对当前工作目录和存储库的 Git 元数据（其.git目录）的写入。 这样，命令就可以跨存储库进行读取，但将更改集中在你工作的位置上。
由于读取访问权限跨越整个存储库，沙盒命令可以读取当前子目录之外的文件，包括项目中其他位置存储的任何敏感内容。 若要使特定路径无法访问，可以添加拒绝规则。 请参阅“配置本地沙盒设置”。
访问规则重叠时
由于 Copilot 授予多个位置，你可以添加自己的位置，因此规则可以重叠。 当他们这样做时， 更具体的路径会赢。 例如，如果 /project 可写，但你将 /project/secrets 标记为只读，则 /project/secrets 中除 /project 外的所有内容都将保持可写。 这是保护敏感子文件夹的有用方法。
当为方便起见授予的许可可能造成阻碍时，重叠部分也会按对你有利的方式解决。 假设有一个 Python 项目，其中有一个显示在你的 .venv 上的本地虚拟环境（PATH）。 将该目录视为普通的只读工具位置会使它处于只读状态（即使它位于可写项目内），并且这样的命令在 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 对话框会将其显示为已锁定的 (managed) 值，且 /sandbox policy 会在已解析的策略中反映这一点。 如果有效策略允许绕过沙盒，则用户可以通过当前显示的绕过权限提示，明确禁用当前会话剩余时间内的沙盒。 此会话选择退出不会松动已保存的策略。
与大多数设置不同，后者通常由单一来源决定，而沙盒策略则由所有同时生效的来源共同构成。 托管设置可以同时通过多个渠道下发——服务器托管、MDM 和基于文件——这些设置会彼此叠加，也会与你自己的设置一起按 最严格 的方向生效，而不是由某一个来源覆盖另一个来源：要求开启的开关会保持开启，所有来源拒绝的路径会累加，而你被允许授予的路径范围只能进一步收窄。 有关详细信息，请参阅“企业管理设置”。