GitHub Copilot CLI 配置目录

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

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

目录概述

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

用户可编辑的文件

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

settings.json

这是用于 Copilot 命令行界面（CLI） 的主配置文件。 在会话中，可以使用交互式 /settings 命令更改特定值，或运行 /settings KEY VALUE 以设置单个值。 请参阅“使用 /settings 命令更改设置”。 或者，可以直接在文本编辑器中编辑 settings.json 文件。 该文件支持带有注释的 JSON（JSONC）。

默认情况下，此文件位于 ~/.copilot 目录（即用户级配置目录）。 它包含所有存储库的全局用户级默认值。 可以通过将环境变量设置为 COPILOT_HOME 其他路径来更改此目录的位置。

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

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） 从配置目录中定位该文件。

CLI 仅按此顺序使用第一个适用的配置目录。 它也不会从优先级较低的位置加载 permissions-config.json 。

此选项 --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 会加载匹配位置的批准。

Schema

该文件必须包含 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命令匹配

permissions-config.json 不支持正则表达式或常规 glob 模式。 字符串值按字面意义进行匹配，但在 shell 的 :* 值中，末尾的 commandIdentifiers 会匹配 :* 前的文本，既可以仅匹配该文本本身，也可以后跟一个空格及更多内容。 一个普通 * 没有特殊的含义，所以 git* 不匹配 git status。

目录匹配

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

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

Examples

允许所有 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）

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

存储库级别仅支持下表中列出的密钥。 将无提示地忽略任何其他密钥（包括用户配置文件中有效的密钥）。 每个受支持的键都有一种定向合并策略，以确保覆盖操作在发生故障时保持默认关闭并且安全。

model、effortLevel 和 contextTier 覆盖仅在工作目录受信任时生效。

仅通过存储库启用的 enabledPlugins 插件的范围限定为该存储库：它在声明存储库中自动安装和激活，但全局保持禁用状态，因此它永远不会在无关项目中激活。 离开存储库，或者存储库禁用该插件时，会关闭其 MCP 服务器，并停用该会话中的代理和技能。

存储库级模型允许列表 （.github/allowed_models.txt）

通过位于 .github/allowed_models.txt 的纯文本允许列表，限制仓库可使用哪些内置模型；该路径相对于当前工作目录所在仓库的根目录解析（如果当前工作目录不在仓库内，则相对于当前工作目录本身解析）。

每一行都是与模型 ID 匹配的 glob 模式，或者是一条 fallback: 指令，用于指定当已配置或请求的模型不被允许时应使用的模型：

# .github/allowed_models.txt
fallback: gpt-5.2
gpt-5.2
gpt-5.4
claude-sonnet-*

不支持否定模式（!pattern），回退模型必须是精确 ID（而不是通配模式），并且回退模型本身必须匹配已配置的通配模式之一。 Copilot 命令行界面（CLI） 重新评估关于 /cd 的策略，并在运行前报错并拒绝无效文件。

允许列表仅适用于 Copilot 的内置模型。 它无法筛选出使用自带 API 密钥 （BYOK） 方法添加的自定义模型。 无论配置的模式如何，BYOK 模型都会保持列出和可选择状态，并且 fallback: 指令永远不会应用于它们。 有关详细信息，请参阅 在企业中为 GitHub Copilot 启用自定义模型 和 在你的组织中为 GitHub Copilot 启用自定义模型。

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

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

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

MDM 托管设置

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

Copilot 命令行界面（CLI） 在启动时除了加载 MDM 外，还会加载由服务器管理的设置。 由设备管理（MDM）和服务器管理的设置会按键分别确定：对于 MDM 已设置的任意键，均以 MDM 的值为准；对于 MDM 未设置的键，则由服务器的值补充。 这样，组织可以通过 MDM（例如，permissions）设置某些策略，同时仍从服务器接收其他托管默认值（例如，model）。

长时间运行的会话每小时都会重新获取并重新应用托管设置，因此策略更改（例如某个组织启用 permissions.disableBypassPermissionsMode）无需重启会话即可生效。

MDM 托管设置源

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

文件格式

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

{
    "model": "auto",
    "permissions": {
        "disableBypassPermissionsMode": "disable"
    }
}

支持的密钥

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

托管 MCP 服务器允许/拒绝列表

管理员可以直接通过 MDM 托管设置（独立于 企业 MCP 允许列表）来管理 MCP 服务器。

在托管设置源中设置 allowedMcpServers 和/或 deniedMcpServers ：

{
    "allowedMcpServers": [
        { "serverUrl": "https://mcp.example.com/*" },
        { "serverCommand": ["npx", "-y", "@example/mcp-server"] }
    ],
    "deniedMcpServers": [
        { "serverName": "untrusted-server" }
    ]
}

每个条目通过以下匹配器中的恰好一种来标识服务器。

规则：

• 受信任的第一方服务器 （例如，内置 GitHub MCP 服务器）始终免除这两个列表。
• 未设置 allowedMcpServers 时允许所有非默认服务器；空数组 会阻止所有非默认服务器（全部拒绝）。
• 未设置或为空的 deniedMcpServers 不会阻止任何内容。
• 拒绝始终优先——匹配 deniedMcpServers 的服务器即使也匹配 allowedMcpServers，也会被阻止。
• 对于远程服务器，匹配结果必须来自 serverUrl 条目；仅在不存在 serverUrl 条目的情况下，serverName 才算有效。 对于 stdio 服务器，匹配必须来自条目 serverCommand ; serverName 仅当不存在 serverCommand 条目时才会进行计数。

延伸阅读

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