允许和拒绝工具使用

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

在本文中

介绍

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

根据适用的策略，通常允许自动执行搜索、读取文件和运行只读 shell 命令等只读操作。 其他操作（如运行破坏性 shell 命令、编辑文件或访问 URL）在 Copilot 使用它们之前需要获得权限。 是否提示你取决于现有的权限和权限模式。 这些控件有助于避免意外更改，例如，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 的本地沙盒 和 关于 GitHub Copilot 的云沙盒。

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

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

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

注意

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

减少使用 assisted permissions 的提示

允许所有权限选项无需查看单个操作即可授予广泛的权限。 若要在不授予全面权限的情况下减少审批提示，请改用此选项 assisted permissions 。

若要打开 assisted permissions，请在交互式会话中输入 /permissions assisted 斜杠命令。 大型语言模型评估符合条件的权限请求，并自动批准其判断为安全的请求。 现有权限和企业规则仍适用，仍需要审批的请求将提交给你。 输入 /permissions manual 以返回到手动批准，或 /permissions show 检查当前设置。 还可以输入 /permissions（无参数）从列表中选择模式。

若要在未配置托管默认值时在新的交互式会话中默认使用assisted permissions，请在用户配置文件中将defaultPermissionMode设置为"assisted"。 若要将其用于非交互式运行，例如在 CI/CD 工作流中，请使用 --assisted-approval 命令行选项。 有关详细信息，请参阅“允许安全命令在未经手动批准的情况下运行”。

重置权限

/reset-allowed-tools斜杠命令撤销你在当前交互式会话期间授予的权限。 这同样适用于你通过响应提示给予的授权，以及对/permissions、/allow-all或/yolo斜杠命令的使用。 它还将权限模式返回到手动模式，如果其中任一项已启用，则关闭“全部允许”权限或 assisted permissions。

使用/reset-allowed-tools会将权限恢复为默认值，或恢复为你启动Copilot CLI时使用的基于规则和 URL 的命令行选项所定义的基线，例如--allow-tool、--deny-tool、--allow-url以及--deny-url。

该命令还会从 permissions-config.json 中清除当前所在位置的所有已保存审批，包括已保存的工具审批和所有已保存的目录权限。 此外，它还会重新启用 Autopilot 权限对话框，因此如果需要，Copilot 将再次提示你授予 Autopilot 权限。

例如，如果使用此选项Copilot CLI启动--allow-tool='shell(git:*)'交互式会话，然后在会话期间通过响应提示来允许和拒绝进一步的权限，则在使用该/reset-allowed-tools命令时，CLI 的权限将返回到原始--allow-tool='shell(git:*)'状态，而不允许或拒绝其他权限。 继续在会话中工作时，如果Copilot需要申请额外的权限，系统会再次提示你。

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

延伸阅读