GitHub Copilot CLI 配置目录

Copilot CLI 在你的机器上将配置、会话历史、日志和自定义内容存储在单个目录中。默认情况下，该目录为 ~/.copilot（即 $HOME/.copilot）。

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

目录概览

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

路径	类型	描述
config.json	文件	你的个人配置设置
mcp-config.json	文件	用户级别的 MCP 服务器定义
permissions-config.json	文件	按项目保存的工具和目录权限
agents/	目录	个人自定义代理定义
skills/	目录	个人自定义技能定义
hooks/	目录	用户级别的钩子脚本
logs/	目录	会话日志文件
session-state/	目录	会话历史和工作区数据
session-store.db	文件	用于跨会话数据的 SQLite 数据库
installed-plugins/	目录	已安装的插件文件
ide/	目录	IDE 集成状态

用户可编辑的文件

以下文件设计为可直接由你编辑，或通过 CLI 命令进行管理。

config.json

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

常用设置包括

键	类型	描述
model	string	要使用的 AI 模型（例如 "gpt-5.2"、"claude-sonnet-4.6"）
effortLevel	string	支持此功能的模型的推理力度等级
theme	string	颜色主题："auto"、"dark" 或 "light"
mouse	boolean	在 alt screen 模式下启用鼠标支持（默认：true）
banner	string	动画横幅频率："always"、"once" 或 "never"（默认："once"）
renderMarkdown	boolean	在响应中渲染 Markdown（默认：true）
screenReader	boolean	启用屏幕阅读器优化（默认：false）
autoUpdate	boolean	自动下载 CLI 更新（默认：true）
stream	boolean	逐标记流式传输响应（默认：true）
includeCoAuthoredBy	boolean	在代理创建的提交中添加 Co-authored-by（默认：true）
respectGitignore	boolean	从 @ 文件选择器中排除 .gitignore 忽略的文件（默认：true）
trusted_folders	string[]	已授予读取/执行权限的文件夹
allowed_urls	string[]	无需提示即可允许的 URL 或域名
denied_urls	string[]	始终被拒绝的 URL 或域名
logLevel	string	日志冗余度："none"、"error"、"warning"、"info"、"debug"、"all" 或 "default"（默认："default"）
disableAllHooks	boolean	禁用所有钩子（默认：false）
hooks	object	Inline user-level hook definitions

要获取完整的配置设置列表，请在终端中输入 copilot help config。

mcp-config.json

定义用户级别可用的 MCP（模型上下文协议）服务器。这些服务器在所有会话中均可使用，无论你处于哪个项目目录。当服务器名称冲突时，项目级别的 MCP 配置（位于 .mcp.json 或 .github/mcp.json）会优先于用户级别的定义。

欲了解更多信息，请参阅 为 GitHub Copilot CLI 添加 MCP 服务器。

agents/

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

For more information, see 为 GitHub Copilot CLI 创建和使用自定义代理.

skills/

在此处存储个人自定义技能定义。每个技能位于包含 SKILL.md 文件的子目录中，例如 ~/.copilot/skills/my-skill/SKILL.md。个人技能在所有会话中均可用。若与项目级别技能同名，项目级别的技能将覆盖个人技能。

更多信息请参阅 为 GitHub Copilot CLI 创建代理技能。

hooks/

在此处存储用户级别的钩子脚本。这些钩子适用于所有会话。你也可以在 config.json 中使用 hooks 键内联定义钩子。仓库级别的钩子（位于 .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 插件参考。

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_HOME 的优先级又高于默认的 ~/.copilot 位置。

需要注意的事项

• COPILOT_HOME 会替换整个 ~/.copilot 路径。你设置的值应为想要用于存放配置文件和子目录的完整路径。

• 更改目录后，原有的配置、会话历史、已安装插件和已保存的权限将不会出现在新位置。如果想保留它们，请将 ~/.copilot 的内容复制或移动到新位置。

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

  • macOS: ~/Library/Caches/copilot
  • Linux: $XDG_CACHE_HOME/copilot or ~/.cache/copilot
  • Windows: %LOCALAPPDATA%/copilot

  如果想单独覆盖缓存目录，请设置 COPILOT_CACHE_HOME。

可以安全删除的内容

项目	是否安全删除？	效果
logs/	是	日志文件每次会话都会重新创建。删除它们不会产生功能影响。
session-state/	慎重处理	删除后会丢失会话历史。你将无法恢复过去的会话。
session-store.db	慎重处理	删除后会丢失跨会话数据。该文件会自动重新创建。
config.json	慎重处理	将所有配置重置为默认值。你需要重新配置偏好设置。
permissions-config.json	慎重处理	重置所有已保存的权限。CLI 将再次提示你批准工具和目录。
installed-plugins/	不推荐	请改用 copilot plugin uninstall，以确保 config.json 中的插件元数据保持一致。
mcp-config.json	不推荐	你将失去用户级别的 MCP 服务器定义。请先备份。
agents/, skills/, hooks/	不推荐	你将失去个人自定义内容。请先备份。

延伸阅读

• GitHub Copilot CLI
• GitHub Copilot CLI 命令参考
• GitHub Copilot CLI 编程参考
• GitHub Copilot CLI 插件参考