关于 GitHub Copilot 的本地沙盒

本地沙盒提供独立的执行环境，让 Copilot 能够在您的本地计算机上安全地与代码、工具、文件系统和网络资源进行交互。

在本文中

Introduction

Copilot本地沙盒是为 GitHub Copilot CLI 和 GitHub Copilot app 提供安全沙盒体验的执行平台。 由于 Copilot 代表你执行更多操作（运行工具、执行命令和修改文件），沙盒提供安全采用代理工作流所需的隔离、可移植性和策略控制。

沙盒功能在 GitHub Copilot CLI 和 GitHub Copilot app 中都可用，但这两个界面对其提供方式不同：

  • 在本文中 Copilot CLI，使用本文所述的命令和设置控制本地沙盒。
  • 在 中，可以对本地存储库和工作树会话使用本地沙盒化。 项目设置决定了新建本地会话的默认设置，你也可以更改当前活动的本地会话的沙盒设置。 有关详细信息，请参阅“在 GitHub Copilot 应用中使用代理会话”。

本地沙盒设置是在 Copilot CLI 和 GitHub Copilot app 中分别配置的。 在一个界面中启用或配置本地沙盒功能，不会更改另一个界面中的相应设置。

通过沙盒机制，你可以选择 Copilot 在何处运行：

  • 本地沙盒：在您自己的计算机上安全运行 Copilot。 运行的命令 Copilot 对文件系统、网络和系统功能具有受限的访问权限。 无需额外付费即可使用本地沙盒。
  • 云沙盒：在由 GitHub 托管的完全隔离的临时 Linux 环境中远程运行整个 Copilot 会话。 云沙盒是根据使用情况计费的。 有关详细信息，请参阅“关于 GitHub Copilot 的云沙盒”。

本地沙盒机制

本地沙盒机制可让 Copilot 直接在您的设备上的沙盒环境中运行，且对文件系统、网络访问和系统功能的访问受到限制。 您可以在 Copilot CLI 或 GitHub Copilot app 中配置本地沙盒。

默认情况下，本地沙盒处于关闭状态。 在你启用它之前，由 Copilot 运行的 shell 命令会直接在你的计算机上执行，并且具有与你的用户账户相同的访问权限：它们可以在你有权限的任何位置读取、写入和删除内容，可以访问你的计算机所能访问的任何网络，并且可以不受限制地使用你的凭据。 启用本地沙盒可将这种访问限制在由你控制的策略范围内。

本地沙盒的工作原理

本地沙盒由 Microsoft eXecution Container （MXC）提供支持，这是一种跨平台技术，它提供每个操作系统上可用的隔离机制的通用接口。 Copilot CLI 声明它想要强制执行的沙盒策略（哪些路径是可读的还是可写的，是允许的网络访问，等等），MXC 使用适用于操作系统的相应隔离后端应用该策略。

隔离技术存在于一个范围中，从强隔离（例如完整虚拟机监控程序或容器）到较轻的隔离（例如 OS 级进程和文件系统包含）。 本地沙盒目前处于这一范围中较轻量的一端：它会限制进程可读取和写入的内容，以及可访问的网络资源，但不会在单独的虚拟机或容器中运行你的命令。 如果要评估此级别的隔离是否符合安全要求，请参阅 microsoft/mxc 存储库 以了解实现详细信息。

有关详细信息，请参阅“了解 GitHub Copilot CLI 中用于本地沙盒的文件系统策略”。

启用本地沙盒机制

若要在 Copilot CLI 会话中启用本地沙盒环境，请运行：

Shell
/sandbox enable

启用本地沙盒后，代理代表您运行的命令和工具会在操作系统级沙盒中运行，用于限制其对系统的访问。 其中包括 shell 命令、文件搜索，以及默认情况下，任何本地 MCP 和语言 （LSP） 服务器。 Copilot 继续使用本地沙盒，包括在未来的会话中，直到运行 /sandbox disable 以禁用它。

如果企业托管设置需要沙盒，则普通设置和启动选项无法将其关闭。 如果有效策略允许绕过沙盒，你仍然可以通过绕过权限提示或运行 /sandbox disable 为当前会话的其余部分禁用沙盒。 这不会更改保存的策略。

CLI 的内置文件工具——即作为 CLI 组成部分的第一方命令，而不是像 sed 这样的 shell 命令——在 CLI 进程内运行。 由于 CLI 本身不是沙盒，因此操作系统沙盒永远不会看到这些工具执行的文件操作，并且无法约束它们。 相反，内置工具被设计为自行检查沙盒策略，并在尽力而为的基础上遵循您已配置的设置。

在存储库 GitHub Copilot app设置中，为新的本地存储库和工作树会话定义本地沙盒默认值。 还可以更改活动本地会话的沙盒隔离设置，而无需更改存储库默认值。

有关在 Copilot CLI 和 Copilot app 中启用本地沙盒的详细信息，请参阅 使用本地沙盒机制。

配置本地沙盒

您可以使用默认的本地沙盒行为，或修改 Copilot 可以访问的内容。 可用控件取决于你使用的表面。

在其中 Copilot CLI，可以控制多个访问维度：

  • 文件系统：授予对特定路径的只读或读/写访问权限，或拒绝路径。
  • 网络：控制出站 Internet 访问和本地网络访问，或允许和拒绝特定主机。 可用的限制取决于你的操作系统。
  • 凭据：启用 Git 和 GitHub CLI （gh） 身份验证，或屏蔽其他环境变量。 沙盒工具接收占位符，本地代理仅向批准的 HTTPS 目标提供真实凭据。
  • 子进程：选择本地 MCP 服务器和语言服务器是否也在沙盒中运行。 远程 MCP 服务器永远不会沙盒化。
  • 密钥链（macOS）：选择是否可从沙盒内部访问系统密钥链。
  • 每个命令例外：在需要更广泛的访问时，允许或阻止单个命令在沙盒外部运行。

在存储库设置中，GitHub Copilot app 提供了这些控件的一个子集：

  • 文件系统：为特定路径授予额外的只读或读写访问权限，或拒绝访问某些路径。
  • 网络：允许或阻止出站 Internet 和本地网络访问。
  • 凭据：选择 Git 和 GitHub CLI 凭据是否在沙盒中可用。

该应用还可以要求你批准单个命令以在沙盒外部运行。 无法在存储库设置中配置是否允许绕过申请。 有关在应用或 CLI 中配置本地沙盒的详细信息，请参阅 配置本地沙盒设置。

跨平台支持

本地沙盒适用于 macOS、Linux 和最近Windows 11版本。 每个操作系统使用不同的隔离后端，因此要求不同：

  • macOS 使用 Seatbelt 作为后端。 Copilot CLI 会为每个沙盒命令应用进程范围的配置文件。 使用 macOS 15 （Sequoia） 或更高版本。 Copilot CLI 不会阻止你在较旧版本的 macOS 上使用，但后端尚未在该系统上经过测试。
  • Linux 使用 Bubblewrap 后端。 安装 bubblewrap 0.5.0 或更高版本，并确保 bwrap 在你的 PATH 中。 如果 /sandbox 提示你的 bwrap 版本过旧，请升级该软件包。 当沙盒策略允许出站流量时，还必须满足以下条件：
    • 你的 PATH 上的 slirp4netns。
    • 来自 util-linux 2.35 或更高版本、支持 --map-current-user 和 --keep-caps 的 unshare 和 nsenter。
    • iptables、ip6tables 及其还原二进制文件。 使用nf_tables后端。 旧版后端也可运行，但前提是你可以写入 /run/xtables.lock。
    • 访问 /dev/net/tun。
  • Windows需要支持沙盒的较新Windows 11更新。 对拒绝路径、localhost 连接和代理等功能的支持也取决于Windows版本。 如果主机不支持所请求的功能，Copilot CLI 会报告该要求，而不是在限制较弱的情况下运行该命令。 请参阅有关 Copilot 沙盒化的 Windows 更新信息。

代理支持

在 Copilot CLI 中，主机规则和 HTTP 代理设置使用内置的本地代理。 它们的执行方式因操作系统而异：

  • macOS 和 Linux：沙盒限制到本地代理的出站连接。 忽略代理设置的程序也无法改为直接连接。 配置代理时， 跨平台支持 中列出的出站流量的 Linux 要求也适用。
  • Windows：代理和主机规则需要受支持的 Windows 版本，并且需要开启允许本地网络。 在 Windows 上，沙盒依赖程序遵守代理设置。 因此，这些控制措施无法像在 macOS 和 Linux 上那样，针对直接连接提供相同的保护。

在 GitHub Copilot app 中，可以在存储库设置中保存被拒绝的路径。 如果当前启用的 BaseContainer 功能无法对被拒绝访问的路径实施强制限制，沙盒化命令将直接失败，而不会在较弱的策略下运行，也不会在没有沙盒的情况下运行。

在 Linux 上，bubblewrap 无法单独控制所启动进程对本地网络的访问，包括 shell 命令和本地 MCP 或 LSP 服务器。 本地网络设置仍适用于 CLI 和应用中的进程内操作，例如 Web 请求和远程 MCP 连接。

如果主机不支持本地沙盒

在 Copilot CLI 中，如果主机不支持沙盒，则会为当前会话关闭已保存的启用沙盒用户首选项。 通知说明 shell 命令和服务将在没有沙盒的情况下运行。 您保存的sandbox.enabled设置保持不变。 不允许在不支持的主机上运行 /sandbox enable。

企业设置可以更改此行为。 在不受支持的主机上，除非有效的托管设置也将sandbox.failIfUnavailable设置为true，否则拒绝启用沙盒的服务器管理的请求。 即使在不受支持的主机上，设备管理的设置也可能需要进行沙盒隔离。 需要沙盒的命令和服务随后会失败，而不是在没有沙盒的情况下运行。 当有效的托管设置同时设置 sandbox.enabled 和 sandbox.failIfUnavailable 设置为 true时，CLI 会阻止会话的模型请求和工具执行（如果无法强制实施沙盒）。 这些要求可能来自服务器管理的设置、设备管理的设置或两者的组合。

对于不支持本地沙盒的主机，配置为使用本地沙盒的会话可能会正常启动，但当 Copilot 尝试启动 shell 命令和其他沙盒进程时，它们会失败。 GitHub Copilot app 保留已保存的首选项，失败的操作会提示该平台不支持沙盒化。 设备管理的设置可能需要此故障时关闭行为，并且可以阻止模型和工具执行。

企业策略强制实施

企业可以通过服务器托管、MDM 托管或基于文件的托管设置来要求本地沙盒并强制实施其配置。 请参阅“企业管理设置入门”。

身份验证和访问

沙盒环境使用您现有的 Copilot 身份验证机制。 如果你可以登录到 Copilot CLI 或 GitHub Copilot app，并且有权访问 Copilot，则无需为该界面中提供的沙盒选项单独配置身份验证。 无需配置单独的云提供商、管理 API 密钥或设置基础结构。

计费

标准 GitHub Copilot 席位中包含本地沙盒机制，无需额外付费。

延伸阅读