# GitHub Copilot CLI 配置目录 查找有关 ~/.copilot 目录的信息，其中 Copilot CLI 存储配置、会话数据和自定义项。 Copilot CLI 将其配置、会话历史记录、日志和自定义存储在计算机上的单个目录中。 默认情况下，此目录为 `~/.copilot` （即 `$HOME/.copilot`） 。 本文介绍此目录的内容以及如何使用它们。 ## 目录概述 该 `~/.copilot` 目录包含以下顶级项。 | 路径 | 类型 | 说明 | | ------------------------- | ---- | ------------------------------- | | `agents/` | 目录 | 个人自定义代理定义 | | `config.json` | File | 自动管理的应用程序状态（身份验证、已安装的插件和其他内部数据） | | `copilot-instructions.md` | File | 个人自定义说明（适用于所有会话） | | `extensions/` | 目录 | 由 CLI 加载的个人扩展 | | `hooks/` | 目录 | 用户级挂钩脚本 | | `ide/` | 目录 | IDE 集成状态 | | `installed-plugins/` | 目录 | 已安装的插件文件 | | `instructions/` | 目录 | 其他个人 `*.instructions.md` 文件 | | `logs/` | 目录 | 会话日志文件 | | `lsp-config.json` | File | 用户级 LSP 服务器定义 | | `mcp-config.json` | File | 用户级 MCP 服务器定义 | | `mcp-oauth-config/` | 目录 | MCP OAuth 令牌和注册后备存储 | | `mcp-secrets/` | 目录 | MCP 密钥占位符的本地后备存储和索引 | | `permissions-config.json` | File | 每个项目保存的工具和目录权限 | | `plugin-data/` | 目录 | 已安装插件的持久数据 | | `session-state/` | 目录 | 会话历史记录和工作区数据 | | `command-history-state/` | 目录 | 命令历史记录数据 | | `session-store.db` | File | 用于跨会话数据的 SQLite 数据库 | | `settings.json` | File | 个人配置设置 | | `skills/` | 目录 | 个人自定义技能定义 | > \[!NOTE] > 并非所有项都立即出现。 有些是在首次使用特定功能时按需创建的，例如， `installed-plugins/` 仅在安装第一个插件后显示。 ## 用户可编辑的文件 以下文件旨在由你直接编辑，或通过 CLI 命令进行管理。 ### `settings.json` 这是用于 Copilot CLI 的主配置文件。 在会话中，可以使用交互式 `/settings` 命令更改特定值，或运行 `/settings KEY VALUE` 以设置单个值。 请参阅“[使用 \`/settings\` 命令更改设置](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot/change-settings)”。 或者，可以直接在文本编辑器中编辑 `settings.json` 文件。 该文件支持带有注释的 JSON（JSONC）。 默认情况下，此文件位于 `~/.copilot` 目录（即用户级配置目录）。 它包含所有存储库的全局用户级默认值。 可以通过将环境变量设置为 `COPILOT_HOME` 其他路径来更改此目录的位置。 > \[!NOTE] > 用户可编辑的设置最初存储在 `config.json`. 他们被转移到 `settings.json`了。 启动时存在 `config.json` 的任何用户设置都将自动迁移到 `settings.json`。 如果`settings.json`无法读取、分析或验证，Copilot CLI将忽略无效值（识别`config.json`的值仍在合并中），并在时间线上显示启动警告，指示你进入命令的`/settings`“**问题**”选项卡。 打开该选项卡以查看特定错误，然后修复报告的问题以还原受影响的设置。 如果 `settings.json` 包含某个不是已识别设置的顶级键（例如拼写错误），Copilot CLI 会在 \*\*\*\* 命令的 `/settings` 选项卡中列出它，而不是在时间线或 stderr 中列出。 当任何配置范围出现问题时，该选项卡的标签会显示一个计数（例如 `Problems (2)`）。 `$schema` 可被容忍，且从不报告。 如果 `~/.copilot/settings.json` 是符号链接（例如，为了通过 dotfiles 仓库同步设置），那么使用 `/settings` 命令写入时，会沿着该符号链接更新其目标文件，而不是将该符号链接替换为普通文件。 有关设置的完整列表及其与存储库级配置交互的方式，请参阅本文后面的 [配置文件设置](#configuration-file-settings) 。 > \[!TIP] > 在终端中运行 `copilot help config` 以获取快速参考。 ### `copilot-instructions.md` 适用于所有会话的个人自定义说明，无论你正在使用哪个项目。 此文件的工作方式与存储库级别 `copilot-instructions.md` 相同，但全局应用。 有关详细信息，请参阅“[为GitHub Copilot添加存储库自定义说明](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions)”。 ### `instructions/` 将此处的其他个人说明文件存储为 `*.instructions.md` 文件。 这些内容将与 `copilot-instructions.md` 一起加载，并适用于所有会话。 可以按主题组织说明，例如 `~/.copilot/instructions/code-style.instructions.md`。 ### `mcp-config.json` 定义用户级别可用的 MCP（模型上下文协议）服务器。 无论你处于哪个项目目录，这些服务器都可以在所有会话中使用。 项目级 MCP 配置（在 `.mcp.json` 或 `.github/mcp.json` 中）在当服务器名称冲突时，优先于用户级定义。 有关详细信息，请参阅“[为 GitHub Copilot CLI 添加 MCP 服务器](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers)”。 ### `lsp-config.json` 定义在用户级别提供的语言服务器协议标准（LSP）服务器。 这些服务器向代理提供语言智能（诊断、完成等）。 使用 `/lsp` 斜杠命令管理此文件，或直接对其进行编辑。 有关详细信息，请参阅“[为 GitHub Copilot CLI 添加 LSP 服务器](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers)”。 ### `agents/` 将个人自定义代理定义存储在此处作为 `.agent.md` 文件。 放置在此目录中的代理在所有会话中都可用。 项目级智能体（位于 `.github/agents/` 中）如果与个人智能体同名，将优先使用。 有关详细信息，请参阅“[为 GitHub Copilot CLI 创建和使用自定义智能体](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli)”。 ### `skills/` 在此处存储个人自定义技能定义。 每个技能都位于一个包含 `SKILL.md` 文件的子目录中，例如 `~/.copilot/skills/my-skill/SKILL.md`。 所有会话中均可使用个人技能。 项目级别的技能优先于个人技能（如果两者同名）。 有关详细信息，请参阅“[为 GitHub Copilot CLI 添加代理技能](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot/add-skills)”。 ### `hooks/` 在此处存储用户级挂钩脚本。 这些挂钩适用于所有会话。 还可以使用 `~/.copilot/settings.json` 键在用户配置文件 (`hooks`) 中以内联方式定义挂钩。 存储库级挂钩（in `.github/hooks/`）与用户级挂钩一起加载。 有关详细信息，请参阅“[与 GitHub Copilot CLI 一起使用挂钩](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot/use-hooks)”。 ### `extensions/` 在此处存储用户级扩展文件。 此目录中的扩展可在会话之间使用。 可以手动在此目录中创建文件，或搭建扩展基架，然后编辑生成的文件。 ## 自动管理文件 以下项由 CLI 管理。 通常不应手动编辑它们。 ### `config.json` 存储 CLI 自动管理的内部应用程序状态，包括身份验证数据、已安装的插件元数据和其他运行时信息。 通常不需要编辑此文件。 > \[!NOTE] > 早期版本的Copilot CLI将用户设置和应用程序状态存储在`config.json`中。 用户可编辑的设置现在位于 `settings.json`。 启动时的任何用户设置 `config.json` 都将自动迁移到 `settings.json`。 应用程序状态字段（例如`loggedInUsers`、`installedPlugins`和`firstLaunchAt``staff`）仍保留在其中`config.json`，并且不会迁移。 ### `permissions-config.json` 存储已保存的工具和目录权限决策，按项目位置进行组织。 批准工具或授予对当前位置目录的访问权限时，CLI 会在此处记录决策，这样就不会在同一存储库或目录中再次提示你。 > \[!NOTE] > 如果要重置项目的权限，可以从此文件中删除相关条目。 但是，在会话运行时编辑文件可能会导致意外行为。 CLI 会自动删除磁盘上不再存在其位置路径的条目。 #### 文件位置 Copilot CLI 从配置目录中定位该文件。 | 优先级 | Source | 使用的文件 | | --- | ------------------------ | --------------------------------------- | | 1 | `--config-dir=DIRECTORY` | `DIRECTORY/permissions-config.json` | | 2 | `COPILOT_HOME` | `$COPILOT_HOME/permissions-config.json` | | 3 | Default | `~/.copilot/permissions-config.json` | CLI 仅按此顺序使用第一个适用的配置目录。 它也不会从优先级较低的位置加载 `permissions-config.json` 。 此选项 `--config-dir` 是旧选项。 需要更改配置目录时首选 `COPILOT_HOME` 。 在Windows上，默认文件通常是： ```text C:\Users\YOUR-USER\.copilot\permissions-config.json ``` 较旧的构建版本使用了一个名为 `permissions-config` 的无扩展名文件。 如果 `permissions-config.json` 不存在，但无扩展文件仍然存在，CLI 仍遵循旧文件。 新编辑时请使用 `permissions-config.json`。 当未设置 `~/.copilot` 时，程序会在启动时将先前基于 XDG 的配置位置迁移到 `COPILOT_HOME`。 #### 位置键 顶层 `locations` 对象以绝对路径为键。 * 对于 Git 存储库，请使用用于界定权限范围的 Git 根目录。 * 链接的工作树解析为主存储库根，因此它们与主工作树共享权限。 * 子模块使用自己的工作目录。 * 对于不在 Git 存储库中的目录，请使用规范化当前工作目录。 密钥必须与运行的位置 Copilot CLI 匹配。 如果密钥不匹配，则保存的审批将不适用。 当会话启动和活动工作目录更改时，CLI 会加载匹配位置的批准。 #### Schema 该文件必须包含 JSON 对象。 | 领域 | 类型 | 必需 | Default | 允许的值 | 说明 | | -------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------- | ------- | ----------------- | ------------------------------------ | | `locations` | 对象 | 否 | `{}` | 绝对路径键 | 保存批准的位置键映射。 | | `locations.` | 对象 | 否 | `{}` | 任意绝对位置键 | 针对一个存储库或目录的已保存批准。 | | `locations..tool_approvals` | Array | 否 | `[]` | 审批对象 | 已批准用于此位置的工具。 | | `locations..allowed_directories` | 字符串数组 | 否 | `[]` | 绝对目录路径 | 路径门可以访问此位置的额外目录。 CLI 应用配置时，必须存在每个目录。 | | `locations..tool_approvals[].kind` | String | 是的 | None | | | | `commands`、`read`、`write`、`mcp`、`mcp-sampling`、`memory`、`custom-tool`、`extension-management`、`extension-permission-access` | 选择审批类型。 | | | | | | `commandIdentifiers` | 字符串数组 | 是，对于 `commands` | None | 命令标识符 | 待批准的 Shell 命令标识符。 | | `serverName` | String | 是，对于 `mcp` 和 `mcp-sampling` | None | MCP 服务器名称 | 待批准的 MCP 服务器。 | | `toolName` | 字符串或 `null` | 是，对于 `mcp` | None | MCP 工具名称，或 `null` | 要批准的 MCP 工具。 使用 `null` 批准服务器上的所有工具。 | | `toolName` | String | 是，对于 `custom-tool` | None | 自定义工具名称 | 按确切名称批准的自定义工具。 | | `operation` | String | 否，对于 `extension-management` | 省略 | 扩展操作名称 | 待批准的扩展管理操作。 省略此字段以批准所有扩展管理操作。 | | `extensionName` | String | 是，对于 `extension-permission-access` | None | 扩展名称 | 已批准访问权限门控功能的扩展。 | `permissions-config.json` 不支持拒绝规则、“ask”规则、默认模式、URL 规则、工具筛选或存储库本地共享策略。 对于这些行为，请使用命令行选项，例如`--deny-tool`、`--available-tools`、`--excluded-tools`和`--allow-url``--deny-url`。 保存的 URL 规则存储在其中 `settings.json`，而不是存储在其中 `permissions-config.json`。 未知字段不是架构的一部分。 CLI 可能会忽略它们，以后的写入可能会删除它们。 #### 审批类型 每个项 `tool_approvals` 必须是下列对象之一。 | `kind` | 必填字段 | 可选字段 | Meaning | | ----------------------------- | -------------------- | ------------------------------------------------- | --------------------------------------- | | `commands` | `commandIdentifiers` | None | 批准匹配的 shell 命令标识符。 | | `read` | None | None | 批准读取工具请求。 交互式 CLI 会话已自动批准读取，因此这通常是不必要的。 | | `write` | None | None | 批准创建和修改文件的工具请求。 路径提示仍可应用于允许的目录之外的路径。 | | `mcp` | | | | | `serverName`、`toolName` | None | 批准一个 MCP 工具，或者在 `toolName` 为 `null` 时批准服务器上的所有工具。 | | | `mcp-sampling` | `serverName` | None | 批准针对单个服务器的 MCP 采样请求。 | | `memory` | None | None | 批准内存写入和投票请求。 | | `custom-tool` | `toolName` | None | 按确切名称批准自定义工具。 | | `extension-management` | None | `operation` | 批准扩展管理。 如果 `operation` 省略，则所有扩展管理操作都匹配。 | | `extension-permission-access` | `extensionName` | None | 批准扩展对权限门控功能的访问。 | 对于 MCP 审批， `serverName` 必须与配置的 MCP 服务器名称完全匹配。 使用 MCP 配置中的原始服务器名称，而不是经过规范化处理的工具名称前缀。 #### Shell命令匹配 `permissions-config.json` 不支持正则表达式或常规 glob 模式。 字符串值按字面意义进行匹配，但在 shell 的 `:*` 值中，末尾的 `commandIdentifiers` 会匹配 `:*` 前的文本，既可以仅匹配该文本本身，也可以后跟一个空格及更多内容。 一个普通 `*` 没有特殊的含义，所以 `git*` 不匹配 `git status`。 | 图案 | Matches | 不匹配 | | ----------------------------------- | -------------- | -------------------- | | `git status` | `git status` | `git status --short` | | `git:*` | | | | `git`、`git status`、`git push` | `gitea` | | | `gh pr:*` | | | | `gh pr`、`gh pr view`、`gh pr create` | `gh repo view` | | #### 目录匹配 `allowed_directories` 条目允许 Copilot CLI 在没有单独的路径提示的情况下访问这些目录中的路径。 他们并不批准该工具本身的操作。 例如，在允许的目录中编辑文件仍需要 `write` 审批。 每个 `allowed_directories` 条目必须是绝对的、非空的可访问目录。 CLI 在比较路径之前解析符号链接，阻止 UNC 网络路径，除非它们是扩展长度的本地路径，在 Windows 上不区分大小写地比较路径，在其他平台上区分大小写。 如果无法应用条目，CLI 会记录警告并跳过该条目。 #### Examples 允许所有 Git 子命令并访问额外的本地目录： ```json copy { "locations": { "C:\\src\\my-repo": { "tool_approvals": [ { "kind": "commands", "commandIdentifiers": ["git:*"] } ], "allowed_directories": ["C:\\src\\shared-docs"] } } } ``` 允许在文件写入前仍询问所选命令： ```json copy { "locations": { "/Users/YOUR-USER/src/my-repo": { "tool_approvals": [ { "kind": "commands", "commandIdentifiers": [ "git status", "git diff", "git log", "npm test", "npm run build" ] } ] } } } ``` 批准文件写入和存储库的一个 MCP 服务器： ```json copy { "locations": { "/home/YOUR-USER/src/my-repo": { "tool_approvals": [ { "kind": "write" }, { "kind": "mcp", "serverName": "github-mcp-server", "toolName": null } ] } } } ``` 批准一个 MCP 工具、内存写入和扩展权限访问： ```json copy { "locations": { "C:\\src\\my-repo": { "tool_approvals": [ { "kind": "mcp", "serverName": "github-mcp-server", "toolName": "search_code" }, { "kind": "memory" }, { "kind": "extension-permission-access", "extensionName": "my-extension" } ] } } } ``` ### `session-state/` 包含按子目录中的会话 ID 组织的会话历史记录数据。 每个会话目录存储事件日志（`events.jsonl`）和工作区项目（计划、检查点、跟踪的文件）。 此数据启用会话恢复（`--resume` 或 `--continue`）。 从此目录中删除文件只会删除本地副本。 如果已将会话同步到 GitHub 账户，则同步的数据将单独存储，不受删除本地文件的影响。 您可以从 GitHub.com 删除或隐藏已同步的会话。 有关详细信息，请参阅“[关于 GitHub Copilot CLI 会话数据](/zh/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/chronicle#managing-your-session-data)”。 ### `command-history-state/` 包含用于反向搜索（Ctrl+R）和交互式界面中的历史记录导航的命令历史记录数据。 此目录是自动管理的，不应对其进行编辑。 ### `session-store.db` CLI 使用的 SQLite 数据库，用于存储跨会话数据，例如检查点索引和搜索。 此文件是自动管理的，不应对其进行编辑。 如果删除此文件，可以使用命令重新生成该文件 `/chronicle reindex` 。 重新编入索引还会将您的会话数据同步到您的账户。 ### `logs/` 包含 CLI 会话的日志文件。 每个会话创建一个名为`process-{timestamp}-{pid}.log`的文件。 这些文件可用于调试问题。 CLI 还可能在 `logs/extensions/` 下创建扩展专用日志。 这与 `~/.copilot/extensions/`存储用户创作的扩展代码不同。 > \[!TIP] > 若要查找当前会话的日志文件，请在交互式会话中输入 `/session` 。 输出包括日志文件的完整路径，以及其他会话详细信息，例如会话 ID、持续时间和工作目录。 ### `installed-plugins/` 包含已安装的插件的文件。 从市场安装的插件存储在 `installed-plugins/{marketplace-name}/{plugin-name}/`以下位置。 直接安装的插件存储在 `installed-plugins/_direct/`. 使用 `copilot plugin` 命令管理插件，而不是直接编辑此目录。 有关详细信息，请参阅“[GitHub Copilot CLI 插件参考](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-plugin-reference)”。 ### `plugin-data/` 包含已安装插件的持久性数据，按市场和插件名称进行组织。 此数据由插件本身管理，不应手动编辑。 ### `ide/` 包含 IDE 集成相关的锁定文件和状态（例如，当Copilot CLI与Visual Studio Code连接时）。 此目录会自动管理。 ### `mcp-oauth-config/` 包含 MCP OAuth 令牌、注册信息以及在密钥链存储不可用时的 PKCE 备用文件。 此目录会自动管理。 ### `mcp-secrets/` 包含备用文件存储以及在密钥链存储不可用时 MCP 密钥占位符的索引。 此目录会自动管理。 ## 更改配置目录的位置 若要替代默认 `~/.copilot` 位置，请将 `COPILOT_HOME` 环境变量设置为要使用的目录的路径。 ```bash copy export COPILOT_HOME=/path/to/my/copilot-config ``` ### 要注意的事项 * `COPILOT_HOME` 替换整个 `~/.copilot` 路径。 设置的值应该是要用于配置文件和子目录的目录的完整路径。 * 更改目录意味着不会在新位置找到现有的配置、会话历史记录、已安装的插件和已保存的权限。 如果您想要保留`~/.copilot`的内容，请将其复制或移动到新位置。 * **缓存目录**（用于市场缓存、自动更新包和其他临时数据）遵循平台约定，不受影响`COPILOT_HOME`。 它位于： * macOS：\*\*\*\* * **Linux**： `$XDG_CACHE_HOME/copilot` 或 `~/.cache/copilot` * **Windows**：`%LOCALAPPDATA%/copilot` 若要单独替代缓存目录，请设置 `COPILOT_CACHE_HOME`。 ## 可以安全地删除的内容 | 物品 | 删除是否安全？ | Effect | | ----------------------------------------- | ------- | ----------------------------------------------------------- | | `agents/`、`skills/`、`hooks/` | 不推荐 | 你将丢失个人自定义项。 首先备份。 | | `config.json` | 谨慎 | 重置应用程序状态，包括身份验证。 需要重新进行身份验证，CLI 将在下次启动时重新检测内部状态。 | | `copilot-instructions.md`、`instructions/` | 不推荐 | 你将丢失个人自定义说明。 首先备份。 | | `extensions/` | 不推荐 | 您将丢失个人扩展。 首先备份。 | | `installed-plugins/` | 不推荐 | 请改用 `copilot plugin uninstall` ，确保插件元数据 `config.json` 保持准确。 | | `logs/` | 是的 | 日志文件在每次会话中会被重新创建。 删除它们不会影响功能。 | | `lsp-config.json` | 不推荐 | 你将失去用户级 LSP 服务器定义。 首先备份。 | | `mcp-config.json` | 不推荐 | 你将失去用户级 MCP 服务器定义。 首先备份。 | | `mcp-oauth-config/` | 谨慎 | 清除本地 MCP OAuth 回退状态。 可能需要重新对 MCP 服务器进行身份验证。 | | `mcp-secrets/` | 谨慎 | 清除本地 MCP 机密的后备状态和映射。 机密支持的 MCP 服务器可能需要重新配置。 | | `permissions-config.json` | 谨慎 | 重置所有已保存的权限。 CLI 将再次提示你进行工具和目录审批。 | | `plugin-data/` | 是的 | 插件持久数据会根据需要重新创建。 | | `session-state/` | 谨慎 | 删除会话将清除历史记录。 你将无法再恢复过去的会话。 | | `command-history-state/` | 谨慎 | 删除会清除命令历史记录。 你将无法再使用 Ctrl+R 搜索以前的命令。 | | `session-store.db` | 谨慎 | 删除操作会移除跨会话数据。 该文件会自动重新创建。 | | `settings.json` | 谨慎 | 将所有用户首选项重置为默认值。 需要重新配置设置。 | ## 配置文件设置 设置按此顺序应用（稍后将替代前面）： 1. 内置默认值 2. 移动设备管理（MDM）托管设置 3. 用户设置 （`~/.copilot/settings.json`） 4. 存储库设置 （`.github/copilot/settings.json`） 5. 本地设置 （`.github/copilot/settings.local.json`） 6. 环境变量 7. 命令行标志 MDM 托管设置会在启动时加载，并作为策略基线与用户设置合并。 对于大多数密钥，用户设置可以替代该基线。 对于 `permissions.disableBypassPermissionsMode`，MDM 值 `"disable"` 始终获胜。 有关详细信息，请参阅 [MDM 托管设置](#mdm-managed-settings)。 | Scope | Location | Purpose | | ----- | ------------------------------------- | ------------------------------------------ | | 用户 | `~/.copilot/settings.json` | 所有存储库的全局默认值。 使用 `COPILOT_HOME` 环境变量指定备用路径。 | | 资料库 | `.github/copilot/settings.json` | 共享存储库配置（提交到存储库）。 | | Local | `.github/copilot/settings.local.json` | 个人覆盖（将此添加到 `.gitignore`）。 | CLI 还会读取 `.claude/settings.json` 和 `.claude/settings.local.json`，以获取存储库设置中供各工具共享的那部分子集（例如 `companyAnnouncements`、`disableAllHooks`、`enabledPlugins`、`extraKnownMarketplaces` 和 `hooks`）。 ### 用户设置 （`~/.copilot/settings.json`） 这些设置适用于所有会话和存储库。 可以使用 `/settings` 斜杠命令运行交互式对话，或使用特定的斜杠命令来更新单个值，或直接编辑此文件。 | 密钥 | 类型 | Default | 说明 | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `allowedUrls` | `string[]` | `[]` | 无需提示即允许的 URL 或域。 支持确切的 URL、域模式和通配符子域（例如）。 `"*.github.com"` | | `askUser` | `boolean` | `true` | 允许代理提出澄清问题。 设置为 `false` 可实现完全自主运作。 还可以使用 `--no-ask-user`. | | `autoUpdate` | `boolean` | `true` | 在每个会话开始时自动下载 CLI 更新和更新第一方插件。 | | `autoUpdatesChannel` | | | | | `"stable"` | | | | | \| | | | | | `"prerelease"` | | | | | `"stable"` | 更新通道。 将`"prerelease"`设置为接收预发布更新。 | | | | `banner` | | | | | `"always"` | | | | | \| | | | | | `"once"` | | | | | \| | | | | | `"never"` | | | | | `"once"` | 动画横幅显示频率。 | | | | `bashEnv` | `boolean` | `false` | 启用 `BASH_ENV` 对 bash shell 的支持。 可以用 `--bash-env` 或 `--no-bash-env` 设置。 | | `beep` | `boolean` | `true` | 需要注意时播放一声哔哔音。 | | `beepOnSchedule` | `boolean` | `true` | 在预定的 `/every` 或 `/after` 运行完成后发出蜂鸣提示音。 | | `builtInAgents.rubberDuck` | `boolean` | `true` | 启用“橡皮鸭”子智能体，该子智能体会对智能体计划提供对抗性反馈。 | | `builtInAgents.rubberDuckAutoInvoke` | `boolean` | `false` | 包含主动提示，用于自动调用“橡皮鸭”。 设置为 `true` 以在智能体回合期间选择接收额外的“橡皮鸭”提示。 | | `colorMode` | | | | | `"default"` | | | | | \| | | | | | `"github"` | | | | | \| | | | | | `"dim"` | | | | | \| | | | | | `"high-contrast"` | | | | | \| | | | | | `"colorblind"` | | | | | `"github"` | | | | | `theme` 的已弃用别名。 首选 `theme`。 | | | | | `commandHistoryMaxSize` | `number` | `50` | 为输入历史记录和反向搜索保留的最新命令的最大数目。 必须是介于 `1` 和 `1000` 之间的整数。 | | `compactPaste` | `boolean` | `true` | 将大块粘贴内容（超过 10 行）折叠成紧凑的标记。 | | `companyAnnouncements` | `string[]` | `[]` | 启动时随机显示的自定义消息。 每次启动 CLI 时，都会随机选择一条消息。 适用于团队公告或提醒。 | | `continueOnAutoMode` | `boolean` | `false` | 在速率受限时自动切换到自动模式。 如果为 `true`，那么符合条件的速率限制错误会触发系统自动切换到自动模式并进行重试。 不适用于全局速率限制或 BYOK 提供程序。 | | `copyOnSelect` | `boolean` | | | | `true` （macOS）、 `false` （其他） | 自动将鼠标选择的文本复制到系统剪贴板。 | | | | `customAgents.defaultLocalOnly` | `boolean` | `false` | 仅使用本地自定义代理（无远程组织或企业代理）。 | | `deniedUrls` | `string[]` | `[]` | 始终被拒绝的 URL 或域。 拒绝规则优先于允许规则。 | | `disableAllHooks` | `boolean` | `false` | 禁用所有钩子（包括存储库级别和用户级别）。 | | `disabledMcpServers` | `string[]` | `[]` | 要禁用的 MCP 服务器名称。 列出的服务器已配置，但未启动。 | | `disabledSkills` | `string[]` | `[]` | 要禁用的技能名称。 列出的技能已被发现，但未能加载。 | | `dynamicRetrieval` | `{ skills?: boolean }` | 取消设置 | 按类别控制基于嵌入的动态指令检索。 将 `skills` 设置为 `false` 以禁用技能的检索。 | | `effortLevel` | `string` | `"medium"` | 扩展思维的推理工作水平： `"low"`、 `"medium"`、 `"high"`或 `"xhigh"`。 更高的级别使用更多的计算。 | | `enabledMcpServers` | `string[]` | `[]` | 启用默认禁用的内置 MCP 服务器。 | | `enabledPlugins` | `Record` | `{}` | 声明性插件自动安装。 密钥是插件规格; `true` 值为 （enabled） 或 `false` （disabled）。 | | `experimental` | `boolean` | `false` | 启用实验性功能。 还可以使用 `--experimental` 命令行选项或 `/experimental` 斜杠命令启用。 | | `extraKnownMarketplaces` | `Record` | `{}` | 其他插件市场。 每个键都是一个市场名称；其值指定了必需的 `source`（`"directory"`、`"git"` 或 `"github"`）。 在条目上设置 `autoUpdate: true`，可将该应用市场中已安装的插件设为在会话启动时自动更新，与第一方插件相同。 此选择加入仅适用于交互式会话和 `-p` 会话 - SDK 和服务器会话不会自动更新。 如果在您自己的用户设置或受管理的（MDM/服务器）设置中进行了选择加入设置，该设置就会生效。 在同名冲突时，内置的第一方市场项优先生效，其次是托管条目（它会替换整个同名的用户条目，因此如果托管条目中没有 `"autoUpdate": true`，就会移除用户的选择启用），最后才是用户自己的条目。 | | `footer` | `object` | — | 控制状态行中显示的项。 子键包括`showModelEffort`、`showDirectory`、`showBranch`、`showContextWindow`、`showQuota`、`showAgent`、`showAiUsed`、`showCodeChanges`、`showUsername`、`showSandbox`、`showYolo`和`showCustom`（均为`boolean`）。 由 `/statusline` 斜杠命令管理。 | | `hooks` | `object` | — | 内联用户级挂钩定义，按事件名称进行键控。 使用与 `.github/hooks/*.json` 文件相同的架构。 请参阅“[与 GitHub Copilot CLI 一起使用挂钩](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot/use-hooks)”。 | | `ide.autoConnect` | `boolean` | `true` | 启动时自动连接到 IDE 工作区。 当 `false` 时，你仍然可以使用 `/ide` 命令手动连接。 | | `ide.openDiffOnEdit` | `boolean` | `true` | 在连接的 IDE 中打开文件编辑差异以供批准。 如果为 `false`，文件编辑审批仅显示于终端中。 | | `includeCoAuthoredBy` | `boolean` | `true` | 将 `Co-authored-by` 尾部添加到代理进行的 git 提交。 | | `keepAlive` | | | | | `"on"` | | | | | \| | | | | | `"off"` | | | | | \| | | | | | `"busy"` | | | | | `"off"` | 启动 CLI 时应用保持活动模式。 | | | | `"on"` 始终防止系统进入休眠状态，`"busy"` 仅在智能体运行时防止休眠，而 `"off"` 禁用保持活动状态。 也可以使用 `/keep-alive` 斜杠命令进行配置。 | | | | | `logLevel` | | | | | `"none"` | | | | | \| | | | | | `"error"` | | | | | \| | | | | | `"warning"` | | | | | \| | | | | | `"info"` | | | | | \| | | | | | `"debug"` | | | | | \| | | | | | `"all"` | | | | | \| | | | | | `"default"` | | | | | `"default"` | 日志记录详细程度。 | | | | `mergeStrategy` | | | | | `"rebase"` | | | | | \| | | | | | `"merge"` | | | | | — | | | | | `/pr fix conflicts` 的冲突解决策略。 设置为 `"rebase"` 时，通过变基到基分支来解决冲突。 当设置为 `"merge"`时，将基分支合并到功能分支中。 如果未配置，将显示选取器对话框。 | | | | | `model` | `string` | 变化 | 要使用的 AI 模型。 设置为 `"auto"` 允许 Copilot 自动选取最佳可用模型。 由 `/model` 斜杠命令管理。 | | `mouse` | `boolean` | `true` | 启用鼠标支持。 可以用 `--mouse` 或 `--no-mouse` 设置。 | | `permissions.disableBypassPermissionsMode` | `string` | — | 将其设置为 `"disable"`，以在启动时禁用所有 allow-all 标志（`--allow-all-tools`、`--allow-all-paths`、`--allow-all-urls`、`--allow-all`、`--yolo`），使其无法用于授予提升后的权限。 将其设置为 `"allow-auto-only"`，以继续阻止“全部允许”，同时仍允许 `/allow-all auto`（LLM 辅助的自动批准）。 请参阅“[GitHub Copilot CLI 命令参考](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-command-reference#restricting-the---allow-all-options)”。 | | `pinnedPrompts` | `boolean` | `true` | 滚动时间线时，将当前区段的用户请求固定在顶部栏下方，以便始终清楚当前可见的输出对应的是哪个请求。 仅适用于 CLI UI——对发送给模型的提示词没有影响。 | | `powershellFlags` | `string[]` | `["-NoProfile", "-NoLogo"]` | 启动时传递给 PowerShell 的标志。 在Windows上，CLI 首选 PowerShell 7+ （`pwsh`），并在 `powershell.exe` 不可用时回退到 Windows PowerShell（`pwsh`）。 仅适用于Windows。 | | `proxyKerberosServicePrincipal` | `string` | 取消设置 | 用于 Kerberos/Negotiate 代理身份验证的服务主体名称 (SPN)，会覆盖派生的 `HTTP/`。 | | `proxyUrl` | `string` | 取消设置 | HTTP（S） 请求的代理 URL（例如 `http://proxy.corp.example:3128`）。 可由 `HTTP_PROXY` 或 `HTTPS_PROXY` 环境变量覆盖（不区分大小写）。 | | `remote` | | | | | `"on"` | | | | | \| | | | | | `"off"` | | | | | `"on"` | 控制会话同步和远程访问。 | | | | `"off"`设置为仅保留本地会话数据并禁用远程控制。 可以用 `--remote` 或 `--no-remote` 设置。 | | | | | `renderHexColors` | `boolean` | `true` | 将以内联代码形式编写的六位十六进制颜色代码（例如 `` `#FF0000` ``）显示为颜色色块。 | | `renderMarkdown` | `boolean` | `true` | 在终端输出中呈现 Markdown。 | | `remoteExport` | `boolean` | `true` | 当会话同步可用时远程导出会话。 设置为 `false` 默认退出远程导出。 当 `remoteSessions` 设置设为 `true` 时，或设置了 `--remote` 标志时，无论此设置如何，仍会启用导出和引导。 | | `respectGitignore` | `boolean` | `true` | 从 `@` 文件提及选取器中排除 gitignored 文件。 当 `false`，选取器包含通常被 `.gitignore`排除的文件。 | | `sandbox.allowBypass` | `boolean` | `true` | 允许沙盒中的命令为特定操作请求绕过限制（会弹出权限提示），这样一来，像 `grep` 和 `glob` 这样的工具在原本会被沙盒阻止时也能继续工作。 将其设置为 `false` 以选择退出。 | | `sandbox.enabled` | `boolean` | `false` | 将 shell 命令、MCP/LSP 服务器和内置文件/Web 工具限制为具有有限文件系统和网络访问权限的沙盒环境。 可在 `/sandbox` 对话框中启用它，或使用 `/sandbox enable`。 | | `sandbox.auth.git` | `boolean` | `true` | 将 Git 凭据注入沙盒，以便其内部运行的命令可以使用 Git 进行身份验证。 | | `false`设置为选择退出。已从`sandbox.gitAuth`中重命名;旧密钥没有迁移，无论在何处显示，都将被忽略。 | | | | | `sandbox.auth.gh` | `boolean` | `true` | 将 GitHub CLI（`gh`）凭据注入沙盒中，以便在其中运行的命令能够与 GitHub CLI 进行身份验证。 | | `false`设置为选择退出。已从`sandbox.ghAuth`中重命名;旧密钥没有迁移，无论在何处显示，都将被忽略。 | | | | | `sandbox.userPolicy.network.allowLocalNetwork` | `boolean` | `true` | 允许沙盒命令访问本地网络地址（例如本地开发服务器）。 将其设置为 `false` 以选择退出。 | | `sandbox.userPolicy.network.proxy` | `object` | 取消设置 | 通过 HTTP 代理转发沙盒化网络流量。 字段： `url` （必需）、 `username` （可选）、 `password` （可选）。 从 `/sandbox` 对话框的 **“网络** ”选项卡对其进行配置，该选项卡屏蔽密码字段。 密码本身存储在 OS 密钥链中，而不是存储在 `settings.json`其中，因此无法通过 `/settings`它进行编辑。 在 Linux 和 macOS 上，代理采用协作模式（即不强制执行）；而在 Windows 上则会强制执行。 | | `sandbox.userPolicy.deniedPaths` | `string[]` | `[]` | 沙盒化命令无法访问的路径。 在 Windows 上，ProcessContainer 沙盒后端无法强制执行按路径设置的拒绝规则，因此这些条目不会生效——所以不要依赖 `deniedPaths` 在 Windows 上保护敏感目录。 | | `sandbox.userPolicy.seatbelt.keychainAccess` | `boolean` | `false` | 仅限 macOS。 授予沙盒命令对系统密钥链的访问权限。 也可以从 `/sandbox` 对话框中切换。 | | `screenReader` | `boolean` | `false` | 启用屏幕阅读器优化。 | | `scrollbar` | `boolean` | `true` | 在可滚动视图中显示滚动条。 将其设置为 `false` 以将其隐藏，并使用终端的全部宽度。 | | `shellShortcut` | `boolean` | `true` | 允许在提示符处单独输入 `$`，然后按下 Enter，即可打开一个以该会话工作目录为根目录的交互式 shell（仅当会话是在真实 TTY 上的本地、受信任且当前空闲的会话时才会启用）。 仅限用户或托管范围 - 不可重写存储库。 | | `showTimestamps` | `boolean` | `true` | 在时间线中于用户消息旁显示浅色 `HH:mm` 时间戳。 | | `showTipsOnStartup` | `boolean` | `true` | 在 CLI 启动时显示随机命令提示。 | | `skillDirectories` | `string[]` | `[]` | 用于搜索自定义技能定义的其他目录（除了 `~/.copilot/skills/`）。 | | `statusLine` | `object` | — | 自定义状态行显示。 | | `type`：必须是 `"command"`。 | | | | | `command`：用于接收 stdin 上的会话 JSON 的可执行脚本的路径，并将状态内容输出到 stdout。 | | | | | `padding`：可选数量的左填充空格。 | | | | | `refreshInterval`：可选的整数秒数（`1`–`2147483`）以在计时器上重新运行命令，而不是仅在事件上运行;仅当会话状态发生更改时，省略它以刷新。 如果命令无法启动、以非零状态退出，或 CLI 未能从 stdin 接收到状态 JSON，CLI 会在每次连续失败期间仅记录一次警告，并将状态行留空，而不是静默失败。 使用 `--log-level all` 运行以查看底层错误详情。 | | | | | `stayInAutopilot` | `boolean` | `true` | 在每个任务完成之后，保持 Autopilot 模式。 启用后，在任务完成之后输入的下一个提示也会在 autopilot 模式下进行处理。 有关详细信息，请参阅“[允许 GitHub Copilot CLI 自主工作](/zh/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/autopilot#staying-in-autopilot-mode-between-tasks)”。 | | `storeTokenPlaintext` | `boolean` | `false` | 允许在系统密钥链不可用时以纯文本 `config.json` 形式存储身份验证令牌。 | | `stream` | `boolean` | `true` | 启用流响应。 | | `streamerMode` | `boolean` | `false` | 隐藏预览模型名称、配额详细信息、提示时间戳和可用更新通知。 演示 Copilot CLI 或屏幕共享时非常有用。 | | `subagents.agents` | `object` | `{}` | 各代理的模型配置，以代理名称为键。 每个值都是一个具有可选`model`（字符串）、 `effortLevel` （string）和`contextTier`（`"default"`、或`"long_context"``"inherit"`）字段的对象。 将任意字段设置为 `"inherit"`，以在分派时使用父会话的值。 | | `/subagents`使用斜杠命令以交互方式配置这些设置。 | | | | | `subagents.disabledSubagents` | `string[]` | `[]` | 需防止被调度的智能体名称。 只有 `rubber-duck` 代理无法通过此设置禁用。 可以禁用所有其他内置代理，包括`explore`、`task`、`code-review``general-purpose`、`research`和`security-review`。 | | `subagents.maxConcurrency` | `number` | 基于计划的 | 此会话的最大并发子代理数。 仅对按使用量计费用户生效；对所有其他套餐均不生效。 上限为 `32`。 请参阅“[GitHub Copilot CLI 命令参考](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-command-reference#subagent-limits)”。 | | `subagents.maxDepth` | `number` | `6` | 最大子代理嵌套深度。 仅对按使用量计费用户生效；对所有其他套餐均不生效。 上限为 `256`。 请参阅“[GitHub Copilot CLI 命令参考](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-command-reference#subagent-limits)”。 | | `tabs.enabled` | `boolean` | `true` | 显示主选项卡栏。 将其设为 `false` 以将其完全隐藏。 | | `tabs.hide` | `string[]` | `[]` | 要隐藏的选项卡标识符。 接受的值：`"copilot"`、`"agents"`、`"issues"`、`"pull-requests"`、`"gists"`（匹配时不区分大小写）。 | | `tabs.sort` | `string[]` | `[]` | 选项卡的显示顺序。 未列出的选项卡排在已列出的选项卡之后，并保持其默认的相对顺序。 忽略未知标识符。 | | `terminalProgress` | `boolean` | `true` | 在代理工作时发送 OSC 9;4 终端进度指示器。 支持的终端包括 Windows 终端、iTerm2、Ghostty 和 ConEmu。 | | `theme` | | | | | `"default"` | | | | | \| | | | | | `"github"` | | | | | \| | | | | | `"dim"` | | | | | \| | | | | | `"high-contrast"` | | | | | \| | | | | | `"colorblind"` | | | | | `"github"` | 终端输出的调色板。 由`/settings``/theme`斜杠命令管理。 | | | | `colorMode` 是此设置已弃用的别名。 | | | | | `toolSearch` | `boolean` | 取决于模型和功能 | 控制工具搜索（延迟的工具加载）。 将 `toolSearch: false` 设为不参与工具搜索。 | | `updateTerminalTitle` | `boolean` | `true` | 在终端选项卡或窗口标题中显示当前意向。 | | `worktreeBaseRef` | | | | | `"head"` | | | | | \| | | | | | `"defaultBranch"` | | | | | `"head"` | 由 `/worktree`、`/worktree new` 和 `--worktree` 创建的新工作树的起点。 | | | | `"defaultBranch"` 从远程默认分支而不是当前签出开始。 | | | | > \[!TIP] > 运行 `copilot help sandbox` 以查看完整的沙盒参考文档，其中包括受支持的主机和所有 `sandbox` 设置键。 `/sandbox` 对话框将 `git`、`gh` 和密钥链访问归类到专门的 **身份验证** 选项卡下，并显示用于存储当前沙盒配置的 `settings.json` 路径。 在`/sandbox`对话框中按Ctrl+E，可保存所有待处理的更改，并在编辑器（`VISUAL`、`EDITOR`或`settings.json`）中打开`COPILOT_EDITOR`，与`/settings`中的相同快捷键保持一致。 编辑并保存文件后，对话框会从磁盘重新加载其状态。 沙盒由[Microsoft eXecution 容器（MXC）](https://github.com/microsoft/mxc)提供支持，该容器提供特定于平台的包含后端。 Copilot CLI 在 macOS 上使用 Seatbelt，在 Linux 上使用 Bubblewrap，在 Windows 上使用 ProcessContainer。 ### 存储库设置 （`.github/copilot/settings.json`） 存储库设置适用于在存储库中工作的每个人。 它们将提交到存储库并与协作者共享。 > \[!NOTE] > 存储库配置文件（`enabledPlugins` 和 `extraKnownMarketplaces`）中与插件相关的键也会被 Copilot cloud agent 读取，而不只是被 Copilot CLI 读取。 这样，便可以从单个文件中为两个客户端启用相同的插件。 有关插件的详细信息，请参阅 [关于 GitHub Copilot 插件](/zh/enterprise-cloud@latest/copilot/concepts/agents/about-plugins)。 存储库级别仅支持下表中列出的密钥。 将无提示地忽略任何其他密钥（包括用户配置文件中有效的密钥）。 每个受支持的键都有一种定向合并策略，以确保覆盖操作在发生故障时保持默认关闭并且安全。 | 密钥 | 类型 | 合并行为 | 说明 | | ---------------------------- | ------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `companyAnnouncements` | `string[]` | 已替换 — 存储库优先 | 启动时随机显示的消息。 | | `contextTier` | | | | | `"default"` | | | | | \| | | | | | `"long_context"` | | | | | 已替换 — 存储库优先 | 固定默认上下文层级。 | | | | `deniedUrls` | `string[]` | 联合 - 存储库可以添加条目，从不删除 | URL 或域名已被阻止。 | | `disableAllHooks` | `boolean` | 存储库优先 | 禁用所有挂钩。 | | `disabledMcpServers` | `string[]` | 联合 - 存储库可以添加条目，从不删除 | MCP 服务器已配置但未启动。 | | `disabledSkills` | `string[]` | 联合 - 存储库可以添加条目，从不删除 | 已发现但未加载的技能 | | `effortLevel` | `string` | 已替换 — 存储库优先 | 固定默认推理工作量。 | | `enabledPlugins` | `Record` | 已合并 — 存储库覆盖用户的相同密钥 | 声明性插件自动安装。 | | `extraKnownMarketplaces` | `Record` | 已合并 — 存储库覆盖用户的相同密钥 | 此存储库中提供的插件市场。 每个条目的 `source` 均为必填项。 条目上的 `autoUpdate: true` 在仓库级别会被接受，但目前会被忽略——只有在用户自己的设置或受管控（MDM/服务器）设置中进行配置时，“选择启用自动更新”这一设置才会生效。 | | `hooks` | `object` | 已合并 — 存储库覆盖用户的相同密钥 | 范围限定到此存储库的挂钩定义。 请参阅“[与 GitHub Copilot CLI 一起使用挂钩](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot/use-hooks)”。 | | `includeCoAuthoredBy` | `boolean` | 已替换 — 存储库优先 | | | `Co-authored-by`添加预告片以提交。 | | | | | `mergeStrategy` | | | | | `"rebase"` | | | | | \| | | | | | `"merge"` | | | | | 已替换 — 存储库优先 | | | | | `/pr fix conflicts` 的冲突解决策略。 | | | | | `model` | `string` | 已替换 — 存储库优先 | 将此仓库的默认模型置顶。 | | `respectGitignore` | `boolean` | 仅可收紧——仓库可以启用，但不能禁用 | 从 `@` 文件提及选取器中排除 gitignored 文件。 | `model`、`effortLevel` 和 `contextTier` 覆盖仅在工作目录[受信任](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools)时生效。 仅通过存储库启用的 `enabledPlugins` 插件的范围限定为该存储库：它在声明存储库中自动安装和激活，但全局保持禁用状态，因此它永远不会在无关项目中激活。 离开存储库，或者存储库禁用该插件时，会关闭其 MCP 服务器，并停用该会话中的代理和技能。 ### 存储库级模型允许列表 （`.github/allowed_models.txt`） 通过位于 `.github/allowed_models.txt` 的纯文本允许列表，限制仓库可使用哪些内置模型；该路径相对于当前工作目录所在仓库的根目录解析（如果当前工作目录不在仓库内，则相对于当前工作目录本身解析）。 每一行都是与模型 ID 匹配的 glob 模式，或者是一条 `fallback:` 指令，用于指定当已配置或请求的模型不被允许时应使用的模型： ```text # .github/allowed_models.txt fallback: gpt-5.2 gpt-5.2 gpt-5.4 claude-sonnet-* ``` | 规则 | 说明 | | -------------------- | ------------------------------------------ | | `*` | 允许所有模型（不存在文件时的默认设置）。 | | `MODEL-ID` | 允许指定精确的模型 ID。 | | `GLOB-PATTERN` | 允许与 glob 模式匹配的模型 ID（例如，`claude-sonnet-*`）。 | | `fallback: MODEL-ID` | 必须且只能有一次。 当前模型不被允许时使用的模型 Copilot。 | | `#` | 注释行。 | 不支持否定模式（`!pattern`），回退模型必须是精确 ID（而不是通配模式），并且回退模型本身必须匹配已配置的通配模式之一。 Copilot CLI 重新评估关于 `/cd` 的策略，并在运行前报错并拒绝无效文件。 允许列表仅适用于 Copilot 的内置模型。 它无法筛选出使用自带 API 密钥 （BYOK） 方法添加的自定义模型。 无论配置的模式如何，BYOK 模型都会保持列出和可选择状态，并且 `fallback:` 指令永远不会应用于它们。 有关详细信息，请参阅 [在企业中为 GitHub Copilot 启用自定义模型](/zh/enterprise-cloud@latest/copilot/how-tos/administer-copilot/manage-for-enterprise/enable-custom-models) 和 [在你的组织中为 GitHub Copilot 启用自定义模型](/zh/enterprise-cloud@latest/copilot/how-tos/administer-copilot/manage-for-organization/enable-custom-models)。 ### 本地设置 （`.github/copilot/settings.local.json`） 在存储库中创建 `.github/copilot/settings.local.json`，用于存放那些不应被提交的个人覆盖。 将此文件添加到 `.gitignore`. 本地配置文件使用与存储库配置文件 （`.github/copilot/settings.json`） 相同的架构，并优先于它。 ## MDM 托管设置 IT 管理员可以通过移动设备管理（MDM）托管设置下发基线策略，而不是要求按用户逐一配置。 这些设置对受支持的密钥应用设备级默认值，并在用户设置之前加载。 Copilot CLI 在启动时除了加载 MDM 外，还会加载由服务器管理的设置。 由设备管理（MDM）和服务器管理的设置会**按键分别**确定：对于 MDM 已设置的任意键，均以 MDM 的值为准；对于 MDM 未设置的键，则由服务器的值补充。 这样，组织可以通过 MDM（例如，`permissions`）设置某些策略，同时仍从服务器接收其他托管默认值（例如，`model`）。 长时间运行的会话每小时都会重新获取并重新应用托管设置，因此策略更改（例如某个组织启用 `permissions.disableBypassPermissionsMode`）无需重启会话即可生效。 ### MDM 托管设置源 Copilot CLI 从平台特定的 MDM 或基于文件的位置中读取托管设置。 | Platform | 源类型 | Location | | ----------- | -------- | ------------------------------------------------------------------ | | macOS | MDM 属性列表 | `com.github.copilot` | | macOS | File | `/Library/Application Support/GitHubCopilot/managed-settings.json` | | Windows操作系统 | MDM 注册表 | `HKLM\SOFTWARE\Policies\GitHubCopilot` | | Windows操作系统 | File | `%ProgramFiles%\GitHubCopilot\managed-settings.json` | | Linux | File | `/etc/github-copilot/managed-settings.json` | > \[!NOTE] > 在 POSIX 系统上， Copilot CLI 拒绝基于文件的托管设置，这些设置是符号链接，不是根拥有的，也不是世界可写的。 ### 文件格式 将基于文件的托管设置编写为 JSON。 ```json { "model": "auto", "permissions": { "disableBypassPermissionsMode": "disable" } } ``` > \[!NOTE] > `model` 是顶级密钥。 将其嵌套为 `permissions.model` 的旧配置仍然有效——当缺少顶层 `model` 键时，运行时会回退到该位置——但新配置应将 `model` 写在顶层。 ### 支持的密钥 MDM 托管设置中仅支持以下密钥。 | 密钥 | 说明 | | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `allowedMcpServers` | 用户可加载的 MCP 服务器允许列表，按 `serverUrl`、`serverCommand` 或 `serverName` 匹配。 受信任的第一方服务器（例如内置 GitHub MCP 服务器）始终是豁免的。 将此键留空会允许所有非默认服务器；空数组会拒绝所有这些服务器。 请参阅 [托管 MCP 服务器允许/拒绝列表](#managed-mcp-server-allowdeny-list)。 | | `deniedMcpServers` | 绝不能加载的 MCP 服务器阻止列表，其匹配方式与 `allowedMcpServers` 相同。 匹配的非默认服务器都会被阻止，不受允许名单影响——拒绝规则始终优先。 请参阅 [托管 MCP 服务器允许/拒绝列表](#managed-mcp-server-allowdeny-list)。 | | `enabledPlugins` | 启用或禁用特定插件 | | `extraKnownMarketplaces` | 添加可信的插件市场 | | `forceRemoteSettingsRefresh` | 即使存在最新的缓存策略，也要求在启动时重新获取由服务器管理的设置。 如果获取失败，缓存条目仍会被保留作为后备。 设备 （MDM） 值优先于缓存的服务器值。 | | `model` | 为所有用户设置默认模型（可被 `--model` 标记或恢复会话时使用的模型覆盖） | | `permissions` | 设置托管权限，包括`disableBypassPermissionsMode`和`deny` / `ask` / `allow`规则数组。 请参阅 [托管权限规则](#managed-permission-rules)。 | | `policyHelper` | 注册提供最低优先级托管设置层的可执行文件。 字段： `path` （必需），外加可选 `args`、 `timeoutMs`和 `refreshIntervalMs`。 如果设备（MDM）和服务器策略都注册了一个 `policyHelper`，则设备注册将获胜。 | | `remoteControl` | 控制此设备上的会话是否可以从其他设备进行控制。 | | `mode` 是 `"enabled"`， `"disabled"`或 `"requireSSO"` （在设置时需要 `githubDotComOrganizations` ）。 | | | `shellShortcut` | 为所有用户强制启用或强制禁用 `$` 交互式 shell 的快捷方式。 托管值始终替代用户自己的 `shellShortcut` 设置。 | | `strictKnownMarketplaces` | 将插件限制为已知市场 | | `telemetry` | 推送基线 OpenTelemetry 导出配置：`enabled`、`endpoint`、`protocol`、`headers`、`resourceAttributes`、`captureContent`、`lockCaptureContent`和`serviceName`。 请参阅“[GitHub Copilot CLI 命令参考](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-command-reference#opentelemetry-monitoring)”。 | > \[!NOTE] > `policyHelper.path` 接受绝对路径、相对于主目录的路径（`~/...`）或从 `PATH` 解析得到的不带路径的程序名。 其他相对形式均不被接受。 注册已被接受并通过验证，但运行时尚未调用辅助程序；辅助程序的执行将在未来版本中提供支持。 > \[!NOTE] > 当 `remoteControl.mode` 为 `"requireSSO"` 时，在 `remoteControl.githubDotComOrganizations` 中列出允许的组织。 客户端必须对至少一个列出的 GitHub.com 组织进行 SSO 授权，因此不再需要对所有组织进行授权。 > \[!NOTE] > 在 MDM 托管设置中将 `permissions.disableBypassPermissionsMode` 设为 `"disable"`，以在设备级别强制实施该限制。 帐户切换无法替代此策略。 将其设置为 `"allow-auto-only"`，以阻止完全“全部允许”式的权限提升，同时仍允许 `/permissions assisted`（LLM 辅助权限审批）。 如果设置了无法识别的值，CLI 会记录该问题，并将 `"disable"` 作为故障关闭（fail-closed）的默认值强制执行，因此即使托管策略格式错误，仍会限制 allow-all 选项，而不是在没有任何提示的情况下放行这些选项。 请参阅“[GitHub Copilot CLI 命令参考](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-command-reference#restricting-the---allow-all-options)”。 > \[!NOTE] > 大多数受管理的键会锁定整行：本地编辑会在下次加载时被受管理的值悄然覆盖。 > `enabledPlugins` 和 `extraKnownMarketplaces` 则是例外——托管层会将这些映射与你自己的条目按字段逐一合并，而不是直接将其整体替换。 这意味着该锁是应用于 **每个条目** 的，而不是应用于整个键：由托管策略固定的插件或市场项无法在本地重新启用、禁用或重新指定指向，但同一映射中的其他条目仍完全由用户控制。 ### 受管理的权限规则 在托管`deny`密钥下推送`ask`、`allow`和`permissions`规则列表，以跨所有用户（独立于`permissions.disableBypassPermissionsMode`）强制实施权限策略。 ```json { "permissions": { "deny": ["Shell(rm -rf *)", "Domain(*.evil.example)"], "ask": ["Shell(git push *)"], "allow": ["Read(**)"] } } ``` | 规则族 | Matches | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | `Bash(...)`、`Shell(...)` | Shell 命令。 使用 ` *`（例如 `git push *`）来匹配命令前缀；否则，该规则匹配精确文本。 | | `PowerShell(...)` | PowerShell 命令，匹配方式与 `Shell(...)` 相同。 | | `Read(...)` | 文件读取/查看路径。 支持 glob 模式：`/` 表示工作区根目录，`~/` 表示用户主目录，`./` 表示当前工作目录。 | | `Edit(...)`、`Write(...)` | 文件写入/编辑路径，匹配方式与 `Read(...)` 相同。 | | `Domain(...)` | URL 主机名，与 [URL 规则](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-command-reference#tool-permission-patterns)一样匹配。 | 来自受管源的规则会按固定优先级合并：拒绝始终优先，然后是询问，最后是允许——如果匹配到 `deny` 规则，请求就会被阻止，即使同时也匹配了 `allow` 规则。 `deny` 和 `ask` 会在所有托管来源（服务器、MDM）中合并。 `allow` 要求所有声明了 `allow` 列表的源都必须接受该操作——取交集，而不是并集。 如果设置了 `deny`、`ask` 或 `allow` 中的任意一个，则与它们均不匹配的操作将默认使用 `ask`，而不是静默穿透。 ## 托管 MCP 服务器允许/拒绝列表 管理员可以直接通过 MDM 托管设置（独立于 [企业 MCP 允许列表）来管理 MCP](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-command-reference#enterprise-mcp-allowlist) 服务器。 在托管设置源中设置 `allowedMcpServers` 和/或 `deniedMcpServers` ： ```json { "allowedMcpServers": [ { "serverUrl": "https://mcp.example.com/*" }, { "serverCommand": ["npx", "-y", "@example/mcp-server"] } ], "deniedMcpServers": [ { "serverName": "untrusted-server" } ] } ``` 每个条目通过以下匹配器中的恰好一种来标识服务器。 | 匹配器 | Matches | 备注 | | ------------------- | ------------------------- | -------------------------------------------------- | | `serverUrl` | 通过 URL 指定的远程（HTTP/SSE）服务器 | 支持 `*` 通配符；协议和主机名匹配时不区分大小写，路径匹配时区分大小写。 | | `${VAR}` 引用在匹配之前展开。 | | | | `serverCommand` | 按其确切命令和参数顺序排列的 stdio 服务器 | | | `${VAR}` 引用在匹配之前展开。 | | | | `serverName` | 按已分配标签的服务器 | 允许列表条目限制为 `[A-Za-z0-9_-]+` （无通配符）;拒绝列表条目接受任何非空字符串。 | 规则： * **受信任的第一方服务器** （例如，内置 GitHub MCP 服务器）始终免除这两个列表。 * **未设置 `allowedMcpServers`** 时允许所有非默认服务器；**空数组** 会阻止所有非默认服务器（全部拒绝）。 * **未设置或为空的 `deniedMcpServers`** 不会阻止任何内容。 * **拒绝始终优先**——匹配 `deniedMcpServers` 的服务器即使也匹配 `allowedMcpServers`，也会被阻止。 * 对于远程服务器，匹配结果必须来自 `serverUrl` 条目；仅在不存在 `serverName` 条目的情况下，`serverUrl` 才算有效。 对于 stdio 服务器，匹配必须来自条目 `serverCommand` ; `serverName` 仅当不存在 `serverCommand` 条目时才会进行计数。 ## 延伸阅读 * [GitHub Copilot CLI](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli) * [GitHub Copilot CLI 命令参考](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-command-reference) * [GitHub Copilot 命令行界面编程参考](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-programmatic-reference) * [GitHub Copilot CLI 插件参考](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-plugin-reference) * [GitHub Copilot 挂钩参考](/zh/enterprise-cloud@latest/copilot/reference/hooks-reference)