# GitHub Copilot CLI 配置目录

查找有关 ~/.copilot 目录的信息，其中 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 集成状态            |

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

## 用户可编辑的文件

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

### `config.json`

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

常见设置包括：

| 密钥                    | 类型     | 说明                                                                                            |
| --------------------- | ------ | --------------------------------------------------------------------------------------------- |
| `model`               | 字符串    | 要使用的 AI 模型（例如，`"gpt-5.2"``"claude-sonnet-4.6"`）。 设置为 `Auto` 允许 Copilot 自动选取最佳可用模型。            |
| `effortLevel`         | 字符串    | 支持该功能的模型的推理复杂程度                                                                               |
| `theme`               | 字符串    | 颜色主题： `"auto"`、 `"dark"`或 `"light"`                                                           |
| `mouse`               | 布尔     | 在替换屏幕模式下启用鼠标支持（默认： `true`                                                                     |
| `banner`              | 字符串    | 动画横幅频率： `"always"`、 `"once"`或 `"never"` （默认值： `"once"`）                                       |
| `renderMarkdown`      | 布尔     | 在响应中呈现 Markdown （默认值： `true`）                                                                 |
| `screenReader`        | 布尔     | 启用屏幕阅读器优化（默认值： `false`                                                                        |
| `autoUpdate`          | 布尔     | 自动下载 CLI 更新（默认值： `true`）                                                                      |
| `stream`              | 布尔     | 逐个令牌地流式传输响应（默认值： `true`）                                                                      |
| `includeCoAuthoredBy` | 布尔     | 在代理创建的提交中添加共同创作者（默认值：`true`）                                                                  |
| `respectGitignore`    | 布尔     | 从 `@` 文件选取器中排除 gitignored 文件（默认值： `true`）                                                     |
| `allowedUrls`         | 字符串\[] | 允许的 URL 或域，无需提示                                                                               |
| `deniedUrls`          | 字符串\[] | 被永久拒绝的 URL 或域                                                                                 |
| `logLevel`            | 字符串    | 日志详细程度：`"none"`、`"error"`、`"warning"`、`"info"`、`"debug"`、`"all"`或`"default"`（默认值：`"default"`） |
| `disableAllHooks`     | 布尔     | 禁用所有挂钩（默认值： `false`）                                                                          |
| `hooks`               | 对象     | 内联用户级别挂钩定义                                                                                    |

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

> \[!TIP]
> 还可以使用命令行标志设置某些设置。 例如， `/model` 斜杠命令将您的模型选择写入到这个文件中，以便在不同会话间保留。

### `mcp-config.json`

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

有关详细信息，请参阅“[为 GitHub Copilot 命令行界面 (CLI) 添加 MCP 服务器](/zh/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers)”。

### `agents/`

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

有关详细信息，请参阅“[为 GitHub Copilot 命令行界面 (CLI) 创建和使用自定义智能体](/zh/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/copilot/how-tos/copilot-cli/customize-copilot/add-skills)”。

### `hooks/`

在此处存储用户级挂钩脚本。 这些挂钩适用于所有会话。 你还可以使用 `config.json` 键在 `hooks` 中以内联方式定义挂钩。 存储库级挂钩（in `.github/hooks/`）与用户级挂钩一起加载。

有关详细信息，请参阅“[与 GitHub Copilot 命令行界面 (CLI) 一起使用挂钩](/zh/copilot/how-tos/copilot-cli/customize-copilot/use-hooks)”。

## 自动管理文件

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

### `permissions-config.json`

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

> \[!NOTE]
> 如果要重置项目的权限，可以从此文件中删除相关条目。 但是，在会话运行时编辑文件可能会导致意外行为。

### `session-state/`

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

### `session-store.db`

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

### `logs/`

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

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

### `installed-plugins/`

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

有关详细信息，请参阅“[GitHub Copilot CLI 插件参考](/zh/copilot/reference/copilot-cli-reference/cli-plugin-reference)”。

### `ide/`

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

## 更改配置目录的位置

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

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

  ```bash copy
  export COPILOT_HOME=/path/to/my/copilot-config
  ```

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

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

## 延伸阅读

* [GitHub Copilot 命令行界面 (CLI)](/zh/copilot/how-tos/copilot-cli)
* [GitHub Copilot CLI 命令参考](/zh/copilot/reference/copilot-cli-reference/cli-command-reference)
* [GitHub Copilot 命令行界面编程参考](/zh/copilot/reference/copilot-cli-reference/cli-programmatic-reference)
* [GitHub Copilot CLI 插件参考](/zh/copilot/reference/copilot-cli-reference/cli-plugin-reference)