GitHub Copilot CLI 配置目录

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

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

目录概述

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

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

注意

并非所有项都立即出现。有些是在首次使用特定功能时按需创建的，例如， installed-plugins/ 仅在安装第一个插件后显示。

用户可编辑的文件

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

`config.json`

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

常见设置包括：

密钥	类型	说明
`model`	字符串	要使用的 AI 模型（例如， "gpt-5.2"``"claude-sonnet-4.6"）
`effortLevel`	字符串	支持该功能的模型的推理复杂程度
`theme`	字符串	颜色主题： `"auto"`、 `"dark"`或 `"light"`
`alt_screen`	布尔	使用备用屏幕缓冲区（默认值： `true`
`mouse`	布尔	在替换屏幕模式下启用鼠标支持（默认： `true`
`banner`	字符串	动画横幅频率： `"always"`、 `"once"`或 `"never"` （默认值： `"once"`）
`render_markdown`	布尔	在响应中呈现 markdown （默认值： `true`）
`screen_reader`	布尔	启用屏幕阅读器优化（默认值： `false`
`auto_update`	布尔	自动下载 CLI 更新（默认值： `true`）
`stream`	布尔	逐个令牌地流式传输响应（默认值： `true`）
`includeCoAuthoredBy`	布尔	在代理创建的提交中添加“由共同创作的”（默认值：`true`）
`respectGitignore`	布尔	从 `@` 文件选取器中排除 gitignored 文件（默认值： `true`）
`trusted_folders`	字符串[]	已授予读取/执行权限的文件夹
`allowed_urls`	字符串[]	允许的 URL 或域，无需提示
`denied_urls`	字符串[]	被永久拒绝的 URL 或域
`log_level`	字符串	日志详细程度：`"none"`、`"error"`、`"warning"`、`"info"`、`"debug"`、`"all"`或`"default"`（默认值：`"default"`）
`disableAllHooks`	布尔	禁用所有挂钩（默认值： `false`）
`hooks`	对象	内联用户级挂钩定义

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

提示

还可以使用命令行标志设置某些设置。例如，--alt-screen和--no-alt-screen设置alt_screen值并将其保存到config.json。 /model 斜杠命令将您的模型选择写入此文件，以便在各个会话之间保持。

`mcp-config.json`

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

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

`agents/`

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

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

`skills/`

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

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

`hooks/`

在此处存储用户级挂钩脚本。这些挂钩适用于所有会话。您还可以使用hooks键在config.json中内联定义挂钩。存储库级挂钩（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的文件。这些文件可用于调试问题。

提示

若要查找当前会话的日志文件，请在交互式会话中输入 /session 。输出包括日志文件的完整路径，以及其他会话详细信息，例如会话 ID、持续时间和工作目录。

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

Bash

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

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

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

Bash

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

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
`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/` | 不推荐 | 你将丢失个人自定义项。 首先备份。 |

延伸阅读

        [AUTOTITLE](/copilot/how-tos/copilot-cli)

        [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference)

        [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-programmatic-reference)

        [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-plugin-reference)

在本文中