配置体系

本文你会学到：

• 📂 配置文件与 COPILOT_HOME 环境变量的作用
• 🛡️ 信任目录的安全含义与持久化方式
• 🔧 工具权限的三种审批选项和模式匹配语法
• 📁 路径权限的默认范围与扩展方式
• 🌐 URL 权限的 allow/deny 规则与协议差异
• 🔓 --allow-all / --yolo 组合权限的使用场景
• 💾 权限持久化机制（1.0.37 新增）

配置就像给 Copilot 发放不同级别的门禁卡——你可以精确控制它能在哪些房间走动、能打开哪些抽屉。

📂 配置文件概述¶

Copilot CLI 的行为通过多个配置文件协同控制。除了常见的自定义指令文件外，还有自动管理的 config.json 和 permissions-config.json。

配置方式总览¶

配置目录结构¶

默认配置目录为 ~/.copilot（即 $HOME/.copilot），其中存储了所有配置、会话历史、日志和自定义内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

~/.copilot/
├── config.json                  # 自动管理的内部状态
├── settings.json                # 用户可编辑的全局设置
├── copilot-instructions.md      # 全局自定义指令
├── permissions-config.json      # 保存的权限审批记录
├── mcp-config.json              # 用户级 MCP 服务器定义
├── lsp-config.json              # 用户级 LSP 服务器定义
├── agents/                      # 个人自定义 Agent 定义
├── skills/                      # 个人自定义 Skill 定义
├── hooks/                       # 用户级 Hook 脚本
├── instructions/                # 额外的 *.instructions.md 文件
├── session-state/               # 会话历史数据
├── logs/                        # 会话日志
└── installed-plugins/           # 已安装的插件

1
2
3
4
5
6

%USERPROFILE%\.copilot\
├── config.json
├── settings.json
├── copilot-instructions.md
├── permissions-config.json
└── ...

1

export COPILOT_HOME=/path/to/my/copilot-config

配置优先级¶

配置的优先级从高到低为：命令行选项 > 环境变量 > 本地设置 > 仓库设置 > 用户设置。更具体的范围总是覆盖更通用的范围。

🛡️ 信任目录管理¶

信任目录（Trusted Directories）控制 Copilot CLI 可以在哪些位置读取、修改和执行文件。这就像给 Copilot 划定"工作区域"——只有被信任的目录内的文件，它才有权接触。

单次信任 vs 永久信任¶

启动 Copilot CLI 时，系统会询问你是否信任当前目录。你有两个选择：

编辑信任目录¶

永久信任的目录存储在 config.json 的 trustedFolders 数组中。你可以手动编辑这个数组：

1
2

# 打开配置文件
vi ~/.copilot/config.json

1
2

# 打开配置文件
vi $HOME/.copilot/config.json

编辑 trustedFolders 数组，添加或移除目录路径即可。

🔧 工具权限系统¶

Copilot CLI 使用多种工具来完成你的任务：执行 Shell 命令、读写文件、搜索代码、获取网页内容、调用 MCP 服务器等。只读操作（如搜索、读取文件）默认自动允许，而可能修改系统的操作（如执行 Shell 命令、编辑文件、访问 URL）则需要你的明确审批。

交互式审批¶

当 Copilot 首次需要使用某个可能需要审批的工具时（例如 touch、chmod、node、sed），会弹出审批提示，提供三个选项：

命令行权限控制¶

你可以通过命令行选项在启动时就指定工具权限，避免运行时反复确认。

工具模式匹配语法¶

--allow-tool 和 --deny-tool 的值使用 Kind(argument) 格式。argument 是可选的——省略时匹配该类型下的所有工具。

常见权限配置示例¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

# 允许所有工具免审批（适合 CI/CD 等自动化场景）
copilot -p "任务描述" --allow-all-tools

# 禁止 rm 和 git push，但允许其他所有工具
copilot --allow-all-tools --deny-tool='shell(rm)' --deny-tool='shell(git push)'

# 允许所有 git 命令但禁止 git push
copilot --allow-tool='shell(git:*)' --deny-tool='shell(git push)'

# 允许所有 Shell 命令
copilot --allow-tool='shell'

# 允许编辑文件但禁止写操作中的特定文件
copilot --allow-tool='write' --deny-tool='write(.env)'

# 禁止特定 MCP 服务器工具
copilot --deny-tool='My-MCP-Server(tool_name)'

# 允许 MCP 服务器的所有工具，但排除其中一个
copilot --allow-tool='My-MCP-Server' --deny-tool='My-MCP-Server(tool_name)'

限制可用工具集¶

--available-tools 和 --excluded-tools 从"工具认知"层面控制 AI 模型能看到哪些工具：

1
2

# 只让 Copilot 知道 bash、edit、view、grep、glob 这几个工具
copilot --available-tools='bash,edit,view,grep,glob' --allow-tool='shell(git:*)' --deny-tool='shell(git push)'

如果同时使用两个选项，--available-tools 生效而 --excluded-tools 被忽略。被排除的工具，AI 模型根本无法选择使用，即使你用 --allow-tool 指定了它。

📁 路径权限¶

路径权限控制 Copilot CLI 可以访问哪些目录和文件。这就像给 Copilot 规定"只能在哪些架子上取东西"。

默认范围¶

默认情况下，Copilot CLI 可以访问以下位置：

路径权限应用于 Shell 命令、文件操作（创建、编辑、查看）以及搜索工具（grep、glob）。对于 Shell 命令，路径通过分词命令文本并识别类似路径的 token 来启发式提取。

扩展路径权限¶

1
2
3
4
5
6
7
8

# 允许访问任意路径
copilot -p "任务描述" --allow-all-paths

# 禁止使用临时目录
copilot -p "任务描述" --disallow-temp-dir

# 添加额外的可访问目录
copilot -p "任务描述" --add-dir=/opt/my-project --add-dir=/data/shared

🌐 URL 权限¶

URL 权限控制 Copilot CLI 可以访问哪些外部 URL。这就像控制 Copilot 能拨打哪些外部电话——默认所有电话都需要你的批准。

默认行为¶

默认情况下，所有 URL 在被访问之前都需要你的审批。URL 权限应用于 web_fetch 工具以及网络相关的 Shell 命令（如 curl、wget、fetch）。

配置 URL 权限¶

1
2
3
4
5
6
7
8

# 允许访问所有 URL
copilot -p "任务描述" --allow-all-urls

# 预批准特定域名
copilot -p "任务描述" --allow-url=github.com --allow-url=docs.github.com

# 拒绝特定域名（优先级高于 allow）
copilot -p "任务描述" --allow-url=example.com --deny-url=evil.example.com

1
2
3
4

{
  "allowedUrls": ["github.com", "docs.github.com"],
  "deniedUrls": ["evil.example.com"]
}

🔓 组合权限¶

如果你希望在三个维度（工具、路径、URL）上同时放开所有限制，可以使用组合权限选项。

--allow-all / --yolo¶

1
2
3

# 两种写法等价
copilot -p "任务描述" --allow-all
copilot -p "任务描述" --yolo

--allow-all（别名 --yolo）等价于同时设置以下三个选项：

💾 权限持久化¶

从 1.0.37 版本起，权限持久化默认启用。这就像 Copilot 会记住你之前给过的"通行证"——下次在同一项目中启动时，不需要重复审批。

工作原理¶

当你在某个目录下审批了工具权限后，该审批会自动保存到 ~/.copilot/permissions-config.json 中。保存的审批按项目路径组织，后续在同一目录启动 Copilot 时，之前批准过的权限会自动生效，不再弹出确认提示。

重置权限¶

如果你需要重新审批权限，有以下方式：