GitHub Copilot CLI 配置目录

          Copilot 命令行界面（CLI） 将其配置、会话历史记录、日志和自定义存储在计算机上的单个目录中。 默认情况下，此目录为 `~/.copilot` （即 `$HOME/.copilot`） 。

本文介绍此目录的内容以及如何使用它们。

目录概述

该 ~/.copilot 目录包含以下顶级项。

路径	类型	说明
settings.json	File	个人配置设置
copilot-instructions.md	File	个人自定义说明（适用于所有会话）
instructions/	目录	其他个人 *.instructions.md 文件
mcp-config.json	File	用户级 MCP 服务器定义
lsp-config.json	File	用户级 LSP 服务器定义
permissions-config.json	File	每个项目保存的工具和目录权限
agents/	目录	个人自定义代理定义
skills/	目录	个人自定义技能定义
hooks/	目录	用户级挂钩脚本
logs/	目录	会话日志文件
session-state/	目录	会话历史记录和工作区数据
session-store.db	File	用于跨会话数据的 SQLite 数据库
installed-plugins/	目录	已安装的插件文件
plugin-data/	目录	已安装插件的持久数据
ide/	目录	IDE 集成状态

用户可编辑的文件

以下文件旨在由你直接编辑，或通过 CLI 命令进行管理。

settings.json

这是用于 Copilot 命令行界面（CLI） 的主配置文件。 可以直接在文本编辑器中编辑它，或使用类似 /model 和 /theme 更改会话中的特定值等交互式命令。 该文件支持带有注释的 JSON（JSONC）。

有关设置的完整列表及其与存储库级配置交互的方式，请参阅本文后面的 配置文件设置 。

copilot-instructions.md

适用于所有会话的个人自定义说明，无论你正在使用哪个项目。 此文件的工作方式与存储库级别 copilot-instructions.md 相同，但全局应用。

有关详细信息，请参阅“为GitHub Copilot添加存储库自定义说明”。

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 服务器”。

lsp-config.json

定义在用户级别提供的语言服务器协议标准（LSP）服务器。 这些服务器向代理提供语言智能（诊断、完成等）。 使用 /lsp 斜杠命令管理此文件，或直接对其进行编辑。

有关详细信息，请参阅“为 GitHub Copilot 命令行界面 (CLI) 添加 LSP 服务器”。

agents/

将个人自定义代理定义存储在此处作为 .agent.md 文件。 放置在此目录中的代理在所有会话中都可用。 项目级代理（.github/agents/）如果与个人代理同名，则优先于个人代理。

有关详细信息，请参阅“为 GitHub Copilot 命令行界面 (CLI) 创建和使用自定义智能体”。

skills/

在此处存储个人自定义技能定义。 每个技能都位于一个包含 SKILL.md 文件的子目录中，例如 ~/.copilot/skills/my-skill/SKILL.md。 所有会话中均可使用个人技能。 项目级别的技能优先于个人技能（如果两者同名）。

有关详细信息，请参阅“为 GitHub Copilot 命令行界面 (CLI) 添加代理技能”。

hooks/

在此处存储用户级挂钩脚本。 这些挂钩适用于所有会话。 还可以使用~/.copilot/config.json密钥在用户配置文件 （hooks） 中内联定义挂钩。 存储库级挂钩（in .github/hooks/）与用户级挂钩一起加载。

有关详细信息，请参阅“与 GitHub Copilot 命令行界面 (CLI) 一起使用挂钩”。

自动管理文件

以下项由 CLI 管理。 通常不应手动编辑它们。

permissions-config.json

存储已保存的工具和目录权限决策，按项目位置进行组织。 批准工具或授予对目录的访问权限时，CLI 会在此处记录决策，这样就不会在同一项目中再次提示你。

session-state/

包含按子目录中的会话 ID 组织的会话历史记录数据。 每个会话目录存储事件日志（events.jsonl）和工作区项目（计划、检查点、跟踪的文件）。 此数据启用会话恢复（--resume 或 --continue）。

session-store.db

CLI 使用的 SQLite 数据库，用于存储跨会话数据，例如检查点索引和搜索。 此文件是自动管理的，不应对其进行编辑。

logs/

包含 CLI 会话的日志文件。 每个会话创建一个名为process-{timestamp}-{pid}.log的文件。 这些文件可用于调试问题。

installed-plugins/

包含已安装的插件的文件。 从市场安装的插件存储在 installed-plugins/{marketplace-name}/{plugin-name}/以下位置。 直接安装的插件存储在 installed-plugins/_direct/. 使用 copilot plugin 命令管理插件，而不是直接编辑此目录。

有关详细信息，请参阅“GitHub Copilot CLI 插件参考”。

plugin-data/

包含已安装插件的持久性数据，按市场和插件名称进行组织。 此数据由插件本身管理，不应手动编辑。

ide/

包含 IDE 集成相关的锁定文件和状态（例如，当Copilot 命令行界面（CLI）与Visual Studio Code连接时）。 此目录会自动管理。

更改配置目录的位置

可以通过两种方式替代默认 ~/.copilot 位置：

•         **环境变量**：设置为 `COPILOT_HOME` 要使用的目录的路径。
  

  Bash

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

•         **命令行选项**：在启动 CLI 时使用 `--config-dir` 。
  

  Bash

  copilot --config-dir /path/to/my/copilot-config
  

该 --config-dir 选项优先于 COPILOT_HOME默认位置，后者又优先于默认 ~/.copilot 位置。

要注意的事项

•         `COPILOT_HOME` 替换整个 `~/.copilot` 路径。 设置的值应该是要用于配置文件和子目录的目录的完整路径。
  

• 更改目录意味着不会在新位置找到现有的配置、会话历史记录、已安装的插件和已保存的权限。 如果您想要保留~/.copilot的内容，请将其复制或移动到新位置。

•         **缓存目录**（用于市场缓存、自动更新包和其他临时数据）遵循平台约定，不受影响`COPILOT_HOME`。 它位于：
  

  • macOS：****

  •       **Linux**： `$XDG_CACHE_HOME/copilot` 或 `~/.cache/copilot`
    

  •       **Windows**：`%LOCALAPPDATA%/copilot`
    

  若要单独替代缓存目录，请设置 COPILOT_CACHE_HOME。

可以安全地删除的内容

物品	删除是否安全？	Effect
agents/、skills/、hooks/	不推荐	你将丢失个人自定义项。 首先备份。
copilot-instructions.md、instructions/	不推荐	你将丢失个人自定义说明。 首先备份。
installed-plugins/	不推荐	请改用 copilot plugin uninstall，以确保 settings.json 中的插件元数据保持一致。
logs/	是的	日志文件在每次会话中会被重新创建。 删除它们不会影响功能。
lsp-config.json	不推荐	你将失去用户级 LSP 服务器定义。 首先备份。
mcp-config.json	不推荐	你将失去用户级 MCP 服务器定义。 首先备份。
permissions-config.json	谨慎	重置所有已保存的权限。 CLI 将再次提示你进行工具和目录审批。
plugin-data/	是的	插件持久数据会根据需要重新创建。
session-state/	谨慎	删除会话将清除历史记录。 你将无法再恢复过去的会话。
session-store.db	谨慎	删除操作会移除跨会话数据。 该文件会自动重新创建。
settings.json	谨慎	将所有配置重置为默认值。 需要重新配置首选项并重新进行身份验证。

配置文件设置

设置逐层下传，从用户到存储库再到本地，更具体的范围会覆盖更泛泛的范围。 命令行选项和环境变量始终优先。

Scope	Location	Purpose
用户	~/.copilot/settings.json	所有存储库的全局默认值。 使用 COPILOT_HOME 环境变量指定备用路径。
资料库	.github/copilot/settings.json	共享存储库配置（提交到存储库）。
Local	.github/copilot/settings.local.json	个人替代（将此替代添加到 .gitignore）。

用户设置 （~/.copilot/settings.json）

这些设置适用于所有会话和存储库。 可以直接编辑此文件，或使用斜杠命令更新各个值。

密钥	类型	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 | 当需要注意时播放一声提示音。 | | colorMode | "default" | "dim" | "high-contrast" | "colorblind" | "default" | 颜色对比度模式。 由 /theme 斜杠命令管理。 | | compactPaste | boolean | true | 将大块粘贴内容（超过 10 行）折叠成紧凑的标记。 | | companyAnnouncements | string[] | [] | 启动时随机显示的自定义消息。 每次启动 CLI 时，都会随机选择一条消息。 适用于团队公告或提醒。 | | continueOnAutoMode | boolean | false | 在速率受限时自动切换到自动模式。 当true符合条件的速率限制错误时，将自动切换到自动模式并重试。 不适用于全局速率限制或自带密钥（BYOK）提供商。 | | copyOnSelect | boolean | true （macOS）、 false （其他） | 在Alt屏幕模式下自动将鼠标选择的文本复制到系统剪贴板。 | | customAgents.defaultLocalOnly | boolean | false | 仅使用本地自定义代理（无远程组织或企业代理）。 | | deniedUrls | string[] | [] | 始终被拒绝的 URL 或域。 拒绝规则优先于允许规则。 | | disableAllHooks | boolean | false | 禁用所有钩子（包括存储库级别和用户级别）。 | | disabledMcpServers | string[] | [] | 要禁用的 MCP 服务器名称。 列出的服务器已配置，但未启动。 | | disabledSkills | string[] | [] | 要禁用的技能名称。 列出的技能已被发现，但未能加载。 | | effortLevel | string | "medium" | 扩展思维的推理工作水平： "low"、 "medium"、 "high"或 "xhigh"。 更高的级别使用更多的计算。 | | enabledMcpServers | string[] | [] | 启用默认情况下被禁用的内置 MCP 服务器（例如，"computer-use"）。 | | enabledPlugins | Record<string, boolean> | {} | 声明性插件自动安装。 密钥是插件规格; true 值为 （enabled） 或 false （disabled）。 | | experimental | boolean | false | 启用实验性功能。 还可以使用 --experimental 命令行选项或 /experimental 斜杠命令启用。 | | extraKnownMarketplaces | Record<string, {...}> | {} | 其他插件市场。 每个密钥都是市场名称;值指定源（"directory"或"git"``"github"）。 | | footer | object | — | 控制状态行中显示的项。 子键：showModelEffort、showDirectory、showBranch、showContextWindow、showQuota（全部 showAgent``boolean）。 由 /statusline 斜杠命令管理。 | | hooks | object | — | 内联用户级挂钩定义，按事件名称进行键控。 使用与 .github/hooks/*.json 文件相同的架构。 请参阅“与 GitHub Copilot 命令行界面 (CLI) 一起使用挂钩”。 | | ide.autoConnect | boolean | true | 启动时自动连接到 IDE 工作区。 当 false 时，你仍然可以使用 /ide 命令手动连接。 | | ide.openDiffOnEdit | boolean | true | 在连接的 IDE 中打开文件差异编辑以供审核。 当进行false文件编辑审批时，仅显示于终端中。 | | includeCoAuthoredBy | boolean | true | 向 Co-authored-by 代理提交的 git 提交添加预告片。 | | 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设置。 | | powershellFlags | string[] | ["-NoProfile", "-NoLogo"] | 启动时传递给 PowerShell 的pwsh标志。 仅适用于Windows。 | | renderMarkdown | boolean | true | 在终端输出中呈现 Markdown。 | | respectGitignore | boolean | true | 从 @ 文件提及选取器中排除 gitignored 文件。 当 false，选取器包含通常被 .gitignore排除的文件。 | | screenReader | boolean | false | 启用屏幕阅读器优化。 | | skillDirectories | string[] | [] | 用于搜索自定义技能定义的其他目录（除了 ~/.copilot/skills/）。 | | statusLine | object | — | 自定义状态行显示。 type：必须是 "command"。 command：用于接收 stdin 上的会话 JSON 的可执行脚本的路径，并将状态内容输出到 stdout。 padding：可选的左填充空格数值。 | | storeTokenPlaintext | boolean | false | 当没有系统密钥链可用时，在配置文件中以纯文本形式存储身份验证令牌。 | | stream | boolean | true | 启用流响应。 | | streamerMode | boolean | false | 隐藏预览模型名称和配额详细信息。 演示 Copilot 命令行界面（CLI） 或屏幕共享时非常有用。 | | theme | "auto" | "dark" | "light" | "auto" | 终端颜色主题。 "auto" 检测终端背景并相应地选择。 | | updateTerminalTitle | boolean | true | 在终端选项卡或窗口标题中显示当前意向。 |

存储库设置 （.github/copilot/settings.json）

存储库设置适用于在存储库中工作的每个人。 它们将提交到存储库并与协作者共享。

存储库级别仅支持下表中列出的密钥。 将无提示地忽略任何其他密钥（包括用户配置文件中有效的密钥）。

密钥	类型	合并行为	说明
companyAnnouncements	string[]	已替换 — 存储库优先	启动时随机显示的消息。
disableAllHooks	boolean	存储库优先	禁用所有挂钩。
enabledPlugins	Record<string, boolean>	合并 - 存储库覆盖同一密钥的用户	声明性插件自动安装。
extraKnownMarketplaces	Record<string, {...}>	合并 - 存储库覆盖同一密钥的用户	此存储库中提供的插件市场。
hooks	object	串联 - 存储库挂钩在用户挂钩后运行	为此存储库设置的钩子定义。 请参阅“与 GitHub Copilot 命令行界面 (CLI) 一起使用挂钩”。
mergeStrategy

          `"rebase"`
          \|
          `"merge"`
         | 存储库优先 | 冲突解决策略。`/pr fix conflicts` |

本地设置 （.github/copilot/settings.local.json）

          `.github/copilot/settings.local.json`在存储库中创建不应提交的个人替代。 将此文件添加到 `.gitignore`.

本地配置文件使用与存储库配置文件 （.github/copilot/settings.json） 相同的架构，并优先于它。

延伸阅读

• GitHub Copilot 命令行界面 (CLI)
• GitHub Copilot CLI 命令参考
• GitHub Copilot 命令行界面编程参考
• GitHub Copilot CLI 插件参考