允许和拒绝工具使用

控制可以使用哪些工具 Copilot CLI 以避免意外更改。

在本文中

介绍

Copilot CLI 使用各种工具为你完成任务。 它可以执行 shell 命令、读取和写入文件、搜索代码库、提取 Web 内容并将任务委托给专用子代理。

虽然允许自动执行搜索、读取文件和运行只读 shell 命令等只读操作，但可以修改系统的工具（例如运行破坏性 shell 命令、编辑文件或访问 URL）需要显式批准才能 Copilot 使用它们。 这有助于避免使用 CLI 导致你不打算进行的更改，例如，shell 命令可以执行用户帐户可以执行的任何操作：安装包、删除文件、推送代码或发出网络请求。

可以在启动 CLI 或交互式会话期间允许或拒绝工具的权限。 如果在启动会话之前尚未授予权限，则每次需要执行潜在的破坏性操作时， Copilot CLI 都会提示你提供权限。 你可以选择允许使用一次该工具，或允许在会话剩余时间内使用该工具。

持久化权限

某些提示选项会保存你的同意，以便你不会再次被问及。 审批的存储位置取决于你批准的内容。

当你为当前位置批准某个工具时，批准信息会保存到你的配置目录中的 permissions-config.json。 默认情况下，此文件为 ~/.copilot/permissions-config.json. 例如，对于 shell 命令、文件写入、MCP 工具或内存更新，可以选择“不要在此存储库中再次询问”（或“在此目录中”）。 审批的范围限定为当前位置：Git 存储库根目录或工作目录（如果不在存储库中）。 授予访问权限的任何目录将保存到同一文件。

URL 审批的工作方式不同。 当您永久批准某个 URL 时，其域名会被添加到您 allowedUrls 中的 settings.json 列表。 默认情况下，此文件为 ~/.copilot/settings.json. 此审批适用于所有会话，而不是绑定到单个位置。

例如 --allow-tool 和 --deny-tool 这样的命令行选项仅适用于当前会话，不会写入 permissions-config.json。 拒绝规则仍然优先于已保存的审批。

有关存储已保存审批的位置、位置匹配方式和完整 permissions-config.json 架构的详细信息，请参阅 GitHub Copilot CLI 配置目录。

工具控制的层次

在命令行选项中指定工具权限时，可以使用两层控制。 您可以：

  • 限制可用于 AI 模型的工具选择。
  • 允许或拒绝特定工具的权限。

限制可用于 AI 模型的工具选择

和--available-tools``--excluded-tools选项限制 AI 模型知道的工具集，因此可以在确定如何完成任务时从中进行选择。

  • --available-tools 禁用除指定工具以外的所有工具。
  • --excluded-tools 仅禁用指定的工具。

如果将这两个选项一起使用，CLI 将应用指定的 --available-tools 允许列表并忽略指定的 --excluded-tools拒绝列表。

如果工具不在可用集中，则即使使用选项指定它 --allow-tool ，AI 模型也无法使用它。 在未指定可用工具集的交互式会话中，AI 模型可能会尝试使用工具，但只能拒绝。 --available-tools和--excluded-tools选项可以防止你以这种方式浪费与模型的交互。

示例用例

你正在启动一个 CLI 会话来对你的项目进行基准测试，并想阻止 AI 模型尝试使用 Web 搜索。

copilot --excluded-tools='web_fetch, web_search'

注意

有关本文中提到的这些和其他命令行选项语法的完整详细信息，请参阅 GitHub Copilot CLI 命令参考。

允许或拒绝特定工具的使用权限

和--allow-tool``--deny-tool选项允许或拒绝特定工具或工具子命令的权限。

每个选项的值都是一个逗号分隔的工具类型列表，可以选择指定确切的工具和子命令模式。

如果使用指定工具 --allow-tool，AI 模型可以选择使用该工具，而无需提示你提供权限。 如果指定了一个工具 --deny-tool，则 AI 模型根本无法使用该工具，即使它是完成任务的最佳选择。

拒绝规则始终优先于允许规则，即使已设置 --allow-all 或已在 permissions-config.json 中保存匹配的审批。

例子

选项Effect
--allow-tool=shell允许所有 shell 命令。
--allow-tool='shell(git commit)'允许执行git commit命令。
--allow-tool='shell(git:*)' --deny-tool='shell(git push)'允许所有git命令，除git push以外。
--deny-tool=write拒绝所有文件写入操作。
--allow-tool='read, write(.github/copilot-instructions.md)'允许所有读取操作，并允许对特定文件执行写入操作。
--allow-tool='MyMCP(create_issue), MyMCP(delete_issue)'允许使用来自 create_issue MCP 服务器的 delete_issue 和 MyMCP 工具。
--available-tools='bash,edit,view,grep,glob' --allow-tool='shell(git:*)' --deny-tool='shell(git push)'合并受限 CLI 会话的这两个控制层。
Copilot 可以浏览代码、进行编辑和提交更改，但无法访问 Internet、运行任意子代理或推送到 Git 历史记录。

有关支持的工具类型的详细信息，请参阅 GitHub Copilot CLI 命令参考。

宽松选项

以下命令行选项授予 Copilot CLI 使用所有可用工具的权限。

如果您拥有 Copilot Business 或 Copilot Enterprise 许可证，这些命令可能会被企业管理员阻止。

在使用“允许”选项授予 Copilot 各种权限之前，请考虑使用本地沙盒或在云沙盒中运行会话，以限制可以访问的内容 Copilot 。 有关详细信息，请参阅“关于云端和本地沙盒 GitHub Copilot”。

  • --allow-all-tools — 对可用工具的完全访问权限。

  • --allow-all或 --yolo — 等效于在启动 CLI 时使用所有--allow-all-tools和--allow-all-paths``--allow-all-urls选项。

    在交互式会话中，可以使用 /allow-all 斜杠命令 /yolo 来启用所有工具，而无需重启会话。

注意

强烈建议仅在独立环境中使用这些选项。 你应该永远不要使用别名来自动应用其中一个选项每次启动 Copilot CLI，因为这样做会允许 Copilot 在每次使用 CLI 时无需你的明确许可而使用任何工具，这可能会导致不可预料的后果。

重置权限

/reset-allowed-tools斜杠命令撤销在当前交互式会话期间授予的所有权限。 这同样适用于通过响应提示信息授予的权限，以及使用 /allow-all 或 /yolo 斜杠命令。

使用 /reset-allowed-tools 将权限重置为默认值，或重置启动 Copilot CLI时使用的任何命令行选项定义的状态。 它还会从 permissions-config.json 中清除在当前位置保存的工具审批。 例如，如果使用此选项Copilot CLI启动--allow-tool='shell(git:*)'交互式会话，然后在会话期间通过响应提示来允许和拒绝进一步的权限，则在使用该/reset-allowed-tools命令时，CLI 的权限将返回到原始--allow-tool='shell(git:*)'状态，而不允许或拒绝其他权限。 继续在会话中工作时，如果Copilot需要申请额外的权限，系统会再次提示你。

若要删除其他位置的已保存审批，请编辑或删除相关位置条目 permissions-config.json。 有关详细信息，请参阅“GitHub Copilot CLI 配置目录”。

延伸阅读