使用本地沙盒机制

Introduction

本地沙盒限制对计算机上的文件、网络资源和凭据的访问。 本文介绍如何在和中启用或禁用本地沙盒。 有关云和本地沙盒 Copilot 的概念概述，请参阅 关于 GitHub Copilot 的云沙盒和本地沙盒。 有关调整沙盒设置的信息，请参阅 配置本地沙盒设置。

有关在Visual Studio Code中使用本地沙盒的信息，请参阅文档中的VS Code。

Prerequisites

• Windows： Windows 上的本地沙盒需要 Windows 11 版本 25H2 且安装更新 KB5124010 或更高版本，或者 Windows 11 版本 26H1 且安装更新 KB5124006 或更高版本，并且支持 ProcessContainer 后端的 BaseContainer 层。
• Linux： Bubblewrap（bwrap）版本 0.5.0 或更高版本，且 slirp4netns 必须已安装并可在 PATH 中找到。

在 Copilot CLI 中使用本地沙盒

启用本地沙盒时， Copilot CLI 在操作系统沙盒中代表你运行大部分命令和工具。 启用本地沙盒后，它将用于所有 Copilot CLI 会话，直到禁用它，或为特定会话关闭它。 如果企业管理设置要求启用沙盒机制，则常规配置和 --no-sandbox 命令行选项都无法将其禁用。 但是，如果生效的策略允许绕过沙盒，您可以通过当前显示的绕过权限提示，或通过运行 /sandbox disable，在当前会话的剩余时间内显式禁用沙盒。 此会话选择退出不会放宽已保存的策略。

默认情况下，沙盒命令和工具可以在当前工作目录和临时文件夹中写入。 在 Git 存储库中，存储库的 Git 元数据也是可写的，而当前工作目录上方的存储库的其余部分是可读的，但不可写。 选定的系统和开发人员工具位置是可读的，某些生成和包缓存是可写的。 这不会授予对整个主目录的访问权限。 其他路径已被阻止，除非您授予访问权限。

默认情况下，出站 Internet 访问处于打开状态。 本地网络访问已关闭。 这些设置如何影响命令取决于操作系统。 请参阅“配置本地沙盒设置”。

默认情况下会启用 Git 和 GitHub CLI（gh）身份验证，但 git push 和 gh pr create 等操作依赖于网络设置和工具兼容性。 沙盒命令和脚本接收占位符 Git 和 gh 凭据。 本地代理仅在已批准的 HTTPS 目标中用您的真实凭据替换这些内容。

Git 凭据保留其原始主机、端口和存储库路径限制。 对于gh，凭据仅用于github.com、api.github.com和uploads.github.com。 可以在 **** 的“/sandbox config”选项卡上关闭身份验证。

还可以屏蔽其他环境变量，例如 API 令牌。 在沙盒中运行的命令、本地 MCP 服务器和语言服务器接收这些变量的占位符。 代理仅向您指定的 HTTPS 主机提供每个真实值。 有关设置的说明，请参阅“配置本地沙盒设置”。

在Windows，这需要支持从沙盒到计算机上的服务（主机环回）的连接的版本。 还必须在**** 中的“网络”选项卡上启用/sandbox config。 这还允许专用网络访问，而不仅仅是对凭据代理的访问。

有关 Copilot CLI 中沙盒机制的概念概述，请参阅 关于 GitHub Copilot 的云沙盒和本地沙盒。

沙盒命令

你可以在 /sandbox 会话中使用 Copilot CLI 斜杠命令管理本地沙盒环境。 它具有以下子命令。

启用本地沙盒机制

若要启用本地沙盒，请在交互式 Copilot CLI 会话中输入以下命令：

/sandbox enable

/sandbox enable

沙盒机制会立即在当前会话中启用。

启用本地沙盒后，它将继续用于当前和将来的交互式会话，以及用于编程会话。

禁用本地沙盒

如果企业托管设置要求使用沙盒，则 /sandbox disable 会被拒绝，除非生效策略允许绕过沙盒限制。 如果允许绕过，那么运行 /sandbox disable——或响应当前显示的绕过权限提示——将仅在当前会话的剩余时间内禁用沙盒隔离，而不会放宽已保存的策略。

若要停止使用本地沙盒，请在交互式 Copilot CLI 会话中输入以下命令：

/sandbox disable

/sandbox disable

除非企业托管设置要求使用沙盒模式，否则这会在当前会话以及新会话和重新启动的会话中关闭沙盒模式。 在允许绕过的托管策略下，它仅对当前会话禁用沙盒隔离。

普通的启用或禁用命令将你的选择作为 sandbox.enabled 保存在你的个人设置文件中（默认为 ~/.copilot/settings.json）。 受管理的仅限会话的退出选择不会更改此文件。 运行 /sandbox enable 以还原该会话中的沙盒隔离。

对单个会话使用沙盒隔离

可以使用 --sandbox 命令行选项为单个会话使用沙盒，而无需为其他会话启用沙盒。 如果已启用沙盒，则可以使用 --no-sandbox 选项仅对单次会话将其禁用。 --no-sandbox 选项无法覆盖要求使用沙盒机制的企业管理设置。

您可以将这些选项与 -p 命令行选项结合使用，以在以编程方式使用 CLI 时控制沙盒机制。 例如：

copilot --sandbox -p "PROMPT"

copilot --sandbox -p "PROMPT"

在沙盒外部运行单个命令

当沙盒阻止命令时， Copilot 可以要求你批准具有更广泛访问权限的另一次尝试。 提示描述命令和建议的重试。 可以批准它、保留阻止的结果，或为当前会话的其余部分禁用沙盒。 仅当有效策略允许绕过沙盒时，才可为该会话禁用沙盒。 允许时，还可以随时通过运行 /sandbox disable来执行此操作。

默认情况下启用绕过请求，可以在沙盒设置中关闭。

经批准的命令绕过会跳过凭据掩码和沙盒代理。 该命令使用其普通环境运行，该环境可以包含真正的机密值。 掩码变量主机限制不会保护在沙盒外部运行的命令。

沙盒只是命令失败的原因之一。 仅当沙盒很可能是原因，且在沙盒外运行确实可能有帮助时，Copilot 才会提供一次具有更广泛访问权限的重试。 其他故障情况下不会显示绕过提示。 有关特定于平台的重试行为，请参阅 配置本地沙盒设置。

检查是否正在使用沙盒

若要检查本地沙盒是否用于当前会话，请输入：

/sandbox status

/sandbox status

Copilot CLI 指示当前会话是否已启用沙盒。 如果你的组织的托管设置要求启用沙盒，状态中也会注明这一点。 由于该状态反映的是会话实际强制执行的内容，因此它是确认 Copilot 运行的命令是否沙盒化的可靠方式。

若要不仅查看沙盒是否处于打开状态，而且确切地查看哪些路径是可读、可写还是被阻止，请输入 /sandbox policy。 有关详细信息，请参阅“了解 GitHub Copilot CLI 中用于本地沙盒的文件系统策略”。

你还可以在状态行中一眼看出沙盒状态；启用沙盒时，状态行中会显示 sandbox enabled。 默认情况下，状态行中沙盒信息的显示处于打开状态。 如果它已关闭，则可以将其重新打开：

1. 输入 /statusline。
2. 将选项列表下移至 沙盒。
3. 按 Enter 键切换该设置，使其显示勾选标记。

Troubleshooting

使用以下指南排查 Windows 上被阻止的命令、PowerShell 和 Git 问题以及身份验证失败。

排查被阻止的命令

如果命令无法访问文件、使用工具或连接到主机，请在授予更广泛的访问权限之前检查沙盒策略。

1. 运行 /sandbox status 以确认沙盒是否为当前会话启用。

2. 运行 /sandbox policy 以检查有效策略。 若要查看某命令所使用工具的其他可用路径，请在 /sandbox policy 后加上该命令。 例如：

   Shell

   /sandbox policy npm install
   

   这会预览策略而不运行 npm install。 查看列出的路径和网络设置。 检查说明，查看无法应用的设置。

3. 如果策略阻止你希望允许的访问，则使用 /sandbox config 更新所需的路径或主机规则。 仅授予命令所需的访问权限。 有关缺少的路径和符号链接，请参阅 了解 GitHub Copilot CLI 中用于本地沙盒的文件系统策略。 通过 /add-dir 添加目录不会授予沙盒访问权限。

4. 如果设置由组织管理，请联系管理员。 如果错误提示提到缺少某个操作系统功能或 Linux 依赖项，请解决该要求，然后在重试之前重启 Copilot CLI。

5. 请 Copilot 再次运行该命令。 如果提供了单命令绕过，则仅当你能接受所述的更广泛的访问权限时，才批准它。 为整个会话禁用沙盒可让后续命令获得更广泛的访问权限，而不仅仅是被阻止的命令。

对不存在的被阻止的路径进行故障排除

沙盒设置可以阻止访问特定文件或目录。 如果计算机上不存在被阻止的路径，Copilot CLI 会在启动沙盒命令之前在该位置创建一个目录。 它还会创建任何缺失的父目录。 之后不会自动删除这些目录。

例如，如果在该文件存在之前阻止对 .env 的访问，Copilot CLI 则创建一个名为 .env 的目录，而不是文件。

• 如果被阻止的路径应作为文件使用，请在运行沙盒命令之前在沙盒外部创建该文件。
• 如果看到 Failed to prepare denied sandbox path，该命令尚未启动。 检查配置的路径是否正确，并且帐户是否有权在那里创建目录。 使用 /sandbox config 更正错误路径，或者，如果该设置由管理员管理，请与管理员联系。

运行 /sandbox policy 不会创建这些目录。 在 Linux 上，预览中显示的有效策略将不会包含尚不存在的路径。 它们保留在您已配置的设置中。

在 Windows 上对 PowerShell 和 Git 进行故障排除

在缺少所需更新的 Windows 安装上，沙盒 PowerShell 可能会将驱动器根目录（如 C:\）报告为其当前目录。 Set-Location 和依赖于当前目录的 Git 命令可能会失败，即使 PowerShell 能够启动。

1. 为受支持的 Windows 版本安装 2026 年 9 月或之后的更新。 如果你的组织管理 Windows 更新，请联系你的管理员。

2. 如果无法立即更新，请要求 Copilot 对 Git 命令使用绝对存储库路径。 例如：

   Shell

   git -C "C:\PATH\TO\REPOSITORY" status
   

   这可以避免依赖 PowerShell 的当前目录。 沙盒仍必须允许访问存储库。 它不会修复其他文件系统或身份验证失败。

身份验证故障排除

启用凭据掩码后， Copilot CLI 使用本地代理将真实凭据添加到传出请求。 使用这些凭据的工具必须支持代理并信任其安全证书。

Copilot CLI 自动向沙盒工具提供临时证书捆绑包。 某些工具不使用此捆绑包，可能会报告证书或身份验证错误。

在 macOS 和Windows上，可以选择在操作系统的信任存储中安装代理的证书颁发机构，以提高兼容性。 在Copilot CLI会话中，运行/sandbox ca create，然后运行/sandbox ca trust。 在Windows，安装证书需要管理员批准。 这还会更改 Copilot CLI 之外的应用程序的证书信任。

安装证书并不能解决每个兼容性问题。 需要 HTTP/2、仅接受特定服务器证书（证书固定）、使用客户端证书或使用凭据对请求进行签名的工具可能仍然失败。

对于已掩码处理的环境变量，请检查该变量是否可用于 CLI，目标与其注入主机匹配，并且网络设置允许连接。 工具必须在 HTTPS 请求标头中将占位符作为凭据发送，例如 Authorization 或 X-Api-Key。 当占位符为密码时，HTTP 基本身份验证也有效。 纯文本 HTTP、请求正文、URL 和签名请求都不会包含真实值。

掩码仅保护配置的环境变量和已启用的 Git 和 gh 身份验证。 它不会在凭据文件、其他环境变量或远程 MCP 身份验证中隐藏机密。

在 Copilot app 中使用本地沙盒

根据可能应用的任何企业托管设置，可以使用斜杠命令来启用或禁用当前活动会话的本地沙盒。

为会话启用和禁用沙盒

若要打开本地沙盒，请输入：

/sandbox on

若要关闭沙盒，请输入：

/sandbox off

除非企业托管设置阻止更改，否则这些命令会立即打开或关闭沙盒。 你的选择适用于当前会话，包括重启后，优先于项目默认值。 它不会更改项目在其他会话中的默认值。

本地沙盒关闭时，代理运行命令可以访问与用户帐户相同的文件、网络和凭据。

不能对云沙盒会话或远程主机上运行的会话使用本地沙盒。

在沙盒外运行工具

如果某个工具需要沙盒策略不允许的访问权限，应用可以在 沙盒外部显示“运行” 提示。 根据有效策略，可以：

• 取消操作。
• 在沙盒外部运行该操作一次。
• 在当前会话的剩余时间内禁用沙盒并运行该操作。

若要从此提示中禁用沙盒，请单击“更多选项”，然后单击 “禁用沙盒并运行”，然后确认选择。

如果您在此提示中禁用沙盒隔离，应用将显示 此会话的沙盒已关闭。 单击“ 重新启用沙盒 ”将其重新打开。

暂时禁用沙盒不会更改项目默认值或会话的已保存设置。 会话重启或重新附加时，它将结束。

企业所有者可以阻止用户在沙盒外部运行工具。 有关详细信息，请参阅“企业管理设置”。

延伸阅读

• 关于 GitHub Copilot 的云沙盒和本地沙盒
• 配置本地沙盒设置