GitHub Copilot CLI 配置目录

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

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

目录概述

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

用户可编辑的文件

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

settings.json

这是用于 Copilot 命令行界面（CLI） 的主配置文件。 在会话中，可以使用交互式 /settings 命令更改特定值，或运行 /settings KEY VALUE 以设置单个值，或直接在文本编辑器中编辑文件。 该文件支持带有注释的 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/settings.json 键在用户配置文件 (hooks) 中以内联方式定义挂钩。 存储库级挂钩（in .github/hooks/）与用户级挂钩一起加载。

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

extensions/

在此处存储用户级扩展文件。 此目录中的扩展可在会话之间使用。

可以手动在此目录中创建文件，或搭建扩展基架，然后编辑生成的文件。

自动管理文件

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

config.json

存储 CLI 自动管理的内部应用程序状态，包括身份验证数据、已安装的插件元数据和其他运行时信息。 通常不需要编辑此文件。

permissions-config.json

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

文件位置

Copilot 命令行界面（CLI） 从配置目录中定位该文件。

此选项 --config-dir 是旧选项。 需要更改配置目录时首选 COPILOT_HOME 。

在Windows上，默认文件通常是：

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 会在会话启动时以及活动工作目录变更时加载对应位置中的审批配置。

架构

该文件必须包含 JSON 对象。

permissions-config.json 不支持拒绝规则、“ask”规则、默认模式、URL 规则、工具筛选或存储库本地共享策略。 对于这些行为，请使用命令行选项，例如--deny-tool、--available-tools、--excluded-tools和--allow-url``--deny-url。 保存的 URL 规则存储在其中 settings.json，而不是存储在其中 permissions-config.json。

未知字段不是架构的一部分。 CLI 可能会忽略它们，以后的写入可能会删除它们。

审批类型

每个项 tool_approvals 必须是下列对象之一。

对于 MCP 审批， serverName 必须与配置的 MCP 服务器名称完全匹配。 使用 MCP 配置中的原始服务器名称，而不是经过规范化处理的工具名称前缀。

Shell命令匹配

commandIdentifiers 匹配从 shell 请求中提取的命令标识符。 匹配完全一致，但不包括 :* 后缀。

:* 后缀不是通用的 glob 模式。 它匹配完全相同的词干，或者匹配后面跟一个空格和更多文本的词干。

目录匹配

allowed_directories 条目允许 Copilot 命令行界面（CLI） 在没有单独的路径提示的情况下访问这些目录中的路径。 他们并不批准该工具本身的操作。 例如，在允许的目录中编辑文件仍需要 write 审批。

每个 allowed_directories 条目必须是绝对的、非空的可访问目录。 CLI 在比较路径之前会解析符号链接，禁止使用 UNC 网络路径，除非其属于扩展长度本地路径；在 Windows 上比较路径时不区分大小写，而在其他平台上则区分大小写。 如果无法应用条目，CLI 会记录警告并跳过该条目。

示例

允许所有 Git 子命令并访问额外的本地目录：

{
  "locations": {
    "C:\\src\\my-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": ["git:*"]
        }
      ],
      "allowed_directories": ["C:\\src\\shared-docs"]
    }
  }
}

{
  "locations": {
    "C:\\src\\my-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": ["git:*"]
        }
      ],
      "allowed_directories": ["C:\\src\\shared-docs"]
    }
  }
}

允许所选命令，同时在写入文件前仍先询问：

{
  "locations": {
    "/Users/YOUR-USER/src/my-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": [
            "git status",
            "git diff",
            "git log",
            "npm test",
            "npm run build"
          ]
        }
      ]
    }
  }
}

{
  "locations": {
    "/Users/YOUR-USER/src/my-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": [
            "git status",
            "git diff",
            "git log",
            "npm test",
            "npm run build"
          ]
        }
      ]
    }
  }
}

批准存储库的文件写入和一台 MCP 服务器：

{
  "locations": {
    "/home/YOUR-USER/src/my-repo": {
      "tool_approvals": [
        {
          "kind": "write"
        },
        {
          "kind": "mcp",
          "serverName": "github-mcp-server",
          "toolName": null
        }
      ]
    }
  }
}

{
  "locations": {
    "/home/YOUR-USER/src/my-repo": {
      "tool_approvals": [
        {
          "kind": "write"
        },
        {
          "kind": "mcp",
          "serverName": "github-mcp-server",
          "toolName": null
        }
      ]
    }
  }
}

批准一个 MCP 工具、内存写入和扩展权限访问：

{
  "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"
        }
      ]
    }
  }
}

{
  "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) 会话数据”。

command-history-state/

包含用于反向搜索（Ctrl+R）和交互式界面中的历史记录导航的命令历史记录数据。 此目录是自动管理的，不应对其进行编辑。

session-store.db

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

如果删除此文件，可以使用命令重新生成该文件 /chronicle reindex 。 重新编入索引还会将您的会话数据同步到您的账户。

logs/

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

CLI 还可能在 logs/extensions/ 下创建扩展专用日志。

这与 ~/.copilot/extensions/存储用户创作的扩展代码不同。

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连接时）。 此目录会自动管理。

mcp-oauth-config/

包含 MCP OAuth 令牌、注册信息以及在密钥链存储不可用时的 PKCE 备用文件。 此目录会自动管理。

mcp-secrets/

包含备用文件存储以及在密钥链存储不可用时 MCP 密钥占位符的索引。 此目录会自动管理。

更改配置目录的位置

若要替代默认 ~/.copilot 位置，请将 COPILOT_HOME 环境变量设置为要使用的目录的路径。

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

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。

可以安全地删除的内容

配置文件设置

设置按此顺序应用（稍后将替代前面）：

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 托管设置。

CLI 还会读取 .claude/settings.json 和 .claude/settings.local.json，以获取存储库设置中供各工具共享的那部分子集（例如 companyAnnouncements、disableAllHooks、enabledPlugins、extraKnownMarketplaces 和 hooks）。

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

这些设置适用于所有会话和存储库。 可以使用 /settings 斜杠命令运行交互式对话，或使用特定的斜杠命令来更新单个值，或直接编辑此文件。

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

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

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

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

在存储库中创建 .github/copilot/settings.local.json，用于存放那些不应被提交的个人覆盖。 将此文件添加到 .gitignore.

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

MDM 托管设置

IT 管理员可以通过移动设备管理（MDM）托管设置下发基线策略，而不是要求按用户逐一配置。 这些设置对受支持的密钥应用设备级默认值，并在用户设置之前加载。

MDM 托管设置源

Copilot 命令行界面（CLI） 从平台特定的 MDM 或基于文件的位置中读取托管设置。

文件格式

将基于文件的托管设置编写为 JSON。

{
    "permissions": {
        "disableBypassPermissionsMode": "disable"
    }
}

支持的密钥

MDM 托管设置中仅支持以下密钥。

延伸阅读

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