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 其他路径来更改此目录的位置。

如果 settings.json 无法读取、解析或验证，Copilot CLI 将忽略无效值，并在时间线上显示启动警告，引导你前往 **** 命令的 /settings 选项卡。 打开该选项卡以查看特定错误，然后修复报告的问题以还原受影响的设置。

如果 settings.json 包含某个不是已识别设置的顶级键（例如拼写错误），Copilot CLI 会在 **** 命令的 /settings 选项卡中列出它，而不是在时间线或 stderr 中列出。 当任何配置范围出现问题时，该选项卡的标签会显示一个计数（例如 Problems (2)）。 $schema 可被容忍，且从不报告。

如果 ~/.copilot/settings.json 是符号链接（例如，通过 dotfiles 存储库同步设置），则 /settings 命令的写入操作将沿用该符号链接并更新其目标，而非将符号链接替换为普通文件。

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

在会话外部的 shell 中使用 copilot config，以非交互方式读取或更改设置；它是 /settings 斜杠命令对应的脚本方式。 将.github/copilot/settings.local.json或--local添加到目标.github/copilot/settings.json或--repo，而不是用户设置文件；只能在那里写入可由存储库重写的键。 有关完整命令参考，请参阅 GitHub Copilot CLI 命令参考 。

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 服务器”。

providers.json

将自带密钥（BYOK）提供程序和模型的注册表定义为一个包含 models 和 providers 键的 JSON 对象。 当此文件声明任何提供程序或模型时，它优先于旧 COPILOT_PROVIDER_* 环境变量。

默认情况下，此文件位于 ~/.copilot/providers.json. 使用 COPILOT_PROVIDERS_CONFIG 环境变量替代其位置。

此文件中的模型可与您的Copilot订阅提供的模型一起使用。 手动编辑文件后，重启 Copilot CLI 以加载更改。 有关设置的说明，请参阅“将 LLM 模型添加到 GitHub Copilot CLI”。

提供程序配置结构

使用 JSON 对象，而不使用注释或尾随逗号。 该文件包含两个数组。 每个提供程序定义一个连接，每个模型按名称引用其中一个提供程序。 在下表中， [] 表示数组中的条目。 例如，models[].capabilities.supports.vision 是模型条目内的 vision 内的 capabilities 中的 supports 设置。

缺少文件或文件为空，或者文件中没有提供程序或模型条目时，CLI 将回退为使用 COPILOT_PROVIDER_* 环境变量。 任一数组的 null 值都被视为空数组。 包含无效 JSON 或无效提供程序或模型条目的文件，而是会导致配置错误。

若要在启动 CLI 时使用配置的模型，请向 --model 选项传递 PROVIDER-NAME/MODEL-ID。 PROVIDER-NAME 是提供程序的 name 值，而 MODEL-ID 是模型的 id 值。 例如，运行 copilot --model local/qwen3:8b。 或者，在交互式会话期间，可以输入 /model，然后从选取器中选择模型。

此文件配置在 Copilot CLI 中使用的连接、模型功能和模型说明。 此文件中的 JSON 不是提供程序 API 请求正文。 将设置添加到此文件时，设置不会传递给提供程序。

提供程序设置

在 providers 中的每个条目都接受以下字段。 只有 name 和 baseUrl ，总是必须的。 身份验证要求取决于提供程序。

命名提供程序文件不支持 apiKeyCommand。 请勿在 metadata 或 localModel.args 中放入凭据或令牌刷新命令。

本地模型服务器设置

这些设置仅在 "local_model" 为 baseUrl 且 .gguf 是指向 providers[].type 文件的路径时适用。 首次使用模型时，CLI 会启动 llama-server。 可执行文件必须已安装，并可在 PATH 上使用。 使用绝对模型路径以避免依赖于启动 CLI 时所在的目录。

如果 baseUrl 为 HTTP 或 HTTPS URL，CLI 将连接到该现有服务器，并且不使用这些启动设置。 它们也未配置 Ollama 或其他与 OpenAI 兼容的服务器。

内部 providers[].localModel 的所有字段都是可选的。

CLI 管理服务器的模型路径、主机和端口。 不能将--model、-m、--host或--port传递给args，包括--port=8080等形式。

模型设置

在 models 中的每个条目都接受以下字段。 仅 id 必需且 provider 是必需的。

三个令牌限制字段接受从 0 到 4294967295 的整数。 使用适合您的部署环境的正值，而不是依赖 0 作为禁用限制的方法。 这些设置告知 CLI 要使用的限制，但不会增加模型的实际容量。

模型功能

该 models[].capabilities 对象描述模型。 将某项功能设置为 true 不会将该功能添加到不支持它的模型中。

所有功能字段都是可选的。 对象与模型的默认值合并，数组替换相应的默认数组。

支持的模型功能

以下字段应位于 models[].capabilities.supports 内部。

这些 adaptive_thinking 值具有以下含义。

对于reasoning_effort，CLI 识别"none"、"minimal"、"low"、"medium"、"high"、"xhigh"和"max"。 仅列出模型支持的级别，例如 ["low", "medium", "high"]。 省略列表或空列表会让 CLI 使用其特定于模型的默认值。 在可用时，使用 --reasoning-effort 或模型选取器选择级别。

模型功能限制

以下字段应位于 models[].capabilities.limits 内。 所有选项都是可选的。

手动设置令牌预算时，首选使用模型的maxPromptTokens、maxContextWindowTokens和maxOutputTokens字段。 Discovery 可以在这两个位置保存限制设置。 保持重复值一致，因为不同的 CLI 操作读取两种表示形式。 对于 CLI 管理的本地服务器，经评估的上下文限制可以优先于配置的值。

对令牌计数和图像大小使用非负整数，为图像计数使用正整数。 令牌计数和图像计数必须在 0 到 4294967295 的范围内。 图像大小以字节为单位，而不是令牌进行度量。

模型系统消息

models[].systemMessage 控制 CLI 为此模型生成标准提示时所使用的系统指令，也包括供通用子代理使用的系统指令。 它优先于这些路径上的会话范围的系统消息配置。 它不会替换所选自定义代理或专用子代理的说明。

仅当需要其他说明时首选 "mode": "append" 。 替换或删除内置说明可以更改 CLI 的工具使用和其他预期行为。 省略 systemMessage 以保留标准指令，而不是将其设置为 null。

仅接受某一模式下列出的字段。 例如，添加 sections 而不设置 "mode": "customize" 会导致配置错误。

在替换内容中， {{copilot:memories}} 插入 CLI 的内存指令和上下文（如果可用）。

系统消息部分

在 customize 模式下，models[].systemMessage.sections 将节名称映射到对象。 每个对象指定一个action，并在需要时指定一个content。 例如， models[].systemMessage.sections.tone 更改音调部分。

可用操作包括:

在 providers.json 中，不支持执行 transform 操作，因为它需要应用程序回调，而不是保存的 JSON 配置。

在 sections 中使用以下部分或组名称作为键。

在组更改之前，将应用单个节更改。 组替换将替换其所有成员部分，包括已单独自定义的分区。

系统消息内容块

在 replace 模式下， models[].systemMessage.contentBlocks 提供替换指令，而不是纯 content 字符串。 保留 content，因为配置格式要求保留它。 所有块都必须有一个 content 字符串。

模型元数据

models[].metadata 是一个对象，其值可以是任何有效的 JSON 值。 它是描述性数据，而不是提供 API 请求参数或凭据的方法。 无需手动添加元数据。

模型发现可以保存以下字符串字段。 保留现有发现结果不变。

提供程序配置示例

此示例连接到现有的 Ollama 服务器，并演示如何嵌套模型功能和系统指令。 假定已安装 qwen3:8b。 令牌限制是示例预算，并不表示模型的最大容量。 调整它们以匹配服务器上配置的上下文。

{
  "providers": [
    {
      "name": "local",
      "type": "openai",
      "baseUrl": "http://127.0.0.1:11434/v1",
      "modelProvider": "ollama"
    }
  ],
  "models": [
    {
      "id": "qwen3:8b",
      "provider": "local",
      "name": "Qwen 3 8B",
      "maxPromptTokens": 6144,
      "maxContextWindowTokens": 8192,
      "maxOutputTokens": 2048,
      "capabilities": {
        "supports": {
          "vision": false,
          "toolCalls": true
        }
      },
      "systemMessage": {
        "mode": "customize",
        "sections": {
          "tone": {
            "action": "append",
            "content": "\nUse concise explanations."
          }
        }
      }
    }
  ]
}

{
  "providers": [
    {
      "name": "local",
      "type": "openai",
      "baseUrl": "http://127.0.0.1:11434/v1",
      "modelProvider": "ollama"
    }
  ],
  "models": [
    {
      "id": "qwen3:8b",
      "provider": "local",
      "name": "Qwen 3 8B",
      "maxPromptTokens": 6144,
      "maxContextWindowTokens": 8192,
      "maxOutputTokens": 2048,
      "capabilities": {
        "supports": {
          "vision": false,
          "toolCalls": true
        }
      },
      "systemMessage": {
        "mode": "customize",
        "sections": {
          "tone": {
            "action": "append",
            "content": "\nUse concise explanations."
          }
        }
      }
    }
  ]
}

重新启动 CLI 后，使用 copilot --model local/qwen3:8b 或 /model 选择器选择此模型。 将更多对象添加到任一数组，以配置其他提供程序和模型。

agents/

将个人自定义代理定义存储在此处作为 .agent.md 文件。 放置在此目录中的代理在所有会话中都可用。 如果个人代理和项目级代理具有相同的 ID（例如，如果两个顶级文件都命名 reviewer.agent.md），则个人代理优先。 可选的 name frontmatter 字段不控制重复数据删除，因此具有相同 name 但不同的 ID 的代理会同时加载重复数据。

有关详细信息，请参阅“为 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 会话数据”。

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" 始终获胜。 受管理的 sandbox 设置是另一个例外。 每个托管的 sandbox 值都不可覆盖，而是设置一个无法放宽的下限。 如果自己的设置更宽松，则托管值将获胜。 该 sandbox.failIfUnavailable 设置只能由管理员设置。 有关详细信息，请参阅 MDM 托管设置。

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

存储库默认值是可选的：在存储库本地设置中将 false 条目设为 enabledPlugins，以覆盖存储库默认值。 托管的必需或阻止的插件条目始终优先。 请参阅“查找并安装插件适用于GitHub Copilot CLI”。

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

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

对话框将 /sandbox Git 身份验证、 gh 身份验证和掩码环境变量分组到专用 凭据 选项卡下，并显示 settings.json 存储当前沙盒配置的路径。 在 “文件系统” 选项卡上，配置的路径列表在 2 read/write, 1 read-only 行后面按权限汇总显示（例如，****）。 在该行按下 Enter 键可打开完整列表，该列表会占用光标和标签栏，直到你按下 Esc 键。配置的路径显示为绝对路径，而不是 ./ 相对形式或 ~ 缩略形式。 添加路径时输入 ~/path，仍会将其扩展为你的主目录路径。 在/sandbox对话框中按Ctrl+E，可保存所有待处理的更改，并在编辑器（VISUAL、EDITOR或settings.json）中打开COPILOT_EDITOR，与/settings中的相同快捷键保持一致。 编辑并保存文件后，对话框会从磁盘重新加载其状态。

使用主机规则和 sandbox.userPolicy.network.proxy 内置的本地代理。 配置两者后，本地代理会在将流量转发到上游代理之前应用主机规则。 上游凭据位于沙盒化子进程之外。 当出站访问关闭时，主机规则和代理设置处于非活动状态。

当沙盒设置中未设置代理时，本地代理会按以下顺序从主机上的第一个非空环境变量中选择其上游代理：HTTPS_PROXY、HTTP_PROXY、ALL_PROXY。 仅支持 http:// 和 https:// 代理，不支持 socks5。

与主机 NO_PROXY 匹配的目标仅绕过此继承的上游代理。 沙盒的本地代理仍处理这些连接并应用其主机规则。 沙盒设置中配置的代理会忽略 NO_PROXY。

在 macOS 和 Linux 上，沙盒会限制直接连接，以便程序无法避免代理。 在 Windows 上，沙盒依赖于会遵循代理设置的程序。 因此，忽略 Windows 上的代理设置的程序可以直接连接并绕过针对主机的规则。 Windows代理和主机规则还需要受支持的主机以及允许专用网络访问的 allowLocalNetwork: true。 在 Linux 上，代理设置拒绝除 [::] 双堆栈通配符以外的 IPv6 地址字面量。 使用 IPv4 终结点或支持 IPv4 的主机名。

沙盒设置是用户级或企业管理的。 它们不能被存储库级别覆盖。 有关配置步骤和网络限制，请参阅 配置本地沙盒设置。

沙盒由Microsoft eXecution 容器（MXC）提供支持，该容器提供特定于平台的包含后端。 Copilot CLI 在 macOS 上使用 Seatbelt，在 Linux 上使用 Bubblewrap，在 Windows 上使用 ProcessContainer。

存储库设置 （.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-6-astra
gpt-6-astra
gpt-6-sol
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）托管设置下发基线策略，而不是要求按用户逐一配置。 这些设置对受支持的密钥应用设备级默认值，并在用户设置之前加载。

托管设置在每个会话托管模式（交互式、-p、--acp、以及--ahp-host``--server）中统一应用，因此，通过不同的入口点启动会话，无法绕过企业 MCP、权限和插件策略。

Copilot CLI 在启动时除了加载 MDM 外，还会加载由服务器管理的设置。 设备管理（MDM）和服务器管理的设置按 ** 每个键 ** 进行解析：对于 MDM 设置的任何键，其值优先；对于 MDM 未设置的键，由服务器的值填充。 这样，组织可以通过 MDM（例如，permissions）设置某些策略，同时仍从服务器接收其他托管默认值（例如，model）。

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

MDM 托管设置源

Copilot CLI 从平台特定的 MDM 或基于文件的位置中读取托管设置。

文件格式

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

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

支持的密钥

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

sandbox.learningMode 仅适用于 Windows，只能通过原生 MDM（例如，通过 Intune 或注册表）设置——managed-settings.json 文件值将被忽略。 在具有拒绝捕获的主机上，将其设置为 "allow"，以在记录和允许模式下启动沙盒 shell 命令，而不是默认的记录和拒绝模式，记录每个文件系统或进程访问并允许它，而不是拒绝它（仍强制执行网络策略）。 这允许管理员在锁定群组之前观察群组的命令需要哪些权限；它不是隔离模式。 状态行显示 sandbox relaxed ，shell 调用在应用时显示 (sandbox relaxed) 。 deny 值（默认值），或删除该键，会使该群组返回到普通的强制沙盒；并且，来自任何托管通道的 deny 始终优先于 allow。 用户设置和 SDK 主机无法设置此密钥。

受管理的权限规则

在托管permissions密钥下添加deny和ask``allow规则列表，以强制每个人实施权限策略。 无论是否设置了 permissions.disableBypassPermissionsMode，这都能正常工作。

{
    "permissions": {
        "deny": ["Shell(rm -rf *)", "Domain(*.evil.example)"],
        "ask": ["Shell(git push *)"],
        "allow": ["Read(**)"]
    }
}

来自受管源的规则会按固定优先级合并：拒绝始终优先，然后是询问，最后是允许——如果匹配到 deny 规则，请求就会被阻止，即使同时也匹配了 allow 规则。 deny 和 ask 会在所有托管来源（服务器、MDM）中合并。 allow 要求每个声明 allow 列表的源都必须允许该操作 — 这是交集，而非并集。 如果设置了 deny、ask 或 allow 中的任意一个，则与它们均不匹配的操作将默认使用 ask，而不是静默穿透。

Edit(...) 和 Write(...) 规则适用于多个内置文件工具。 它们还涵盖由 shell 命令直接编写的文件。 Copilot CLI 可识别一组固定的这类写入操作。 它涵盖 Bash 输出重定向（>、>>、>|、&>>、&>）、PowerShell 输出重定向（>、>>、*>、*>>），以及少量原地 sed 编辑（sed -i 或 --in-place，以及 BSD 形式 -i '' 和 -I ''）。 当 Copilot CLI 可以从命令中识别出目标文件时，匹配的 deny 规则会阻止写入，而匹配的 ask 规则会先提示你。 即使像 Shell(*) 这样的宽泛规则原本会允许该命令，这一点也同样适用。 有时无法预先确定目标文件，例如，当路径来自某个变量时。 在这种情况下，这些路径规则不适用，并且命令由普通 shell 命令规则检查。

域边界 （limitTo）

在托管的permissions键下，与deny、ask和allow一起添加一个limitTo数组，以强制实施封闭式域允许列表：

{
    "permissions": {
        "limitTo": ["github.com", "*.github.com"]
    }
}

limitTo 中仅支持 Domain(...) 条目。 在未提示的情况下，任何对列表外域名的代理网络请求都会被拒绝，并且用户规则、保存的审批和允许所有模式都无法放宽这一范围。 在 shell 请求中检测到的 URL 被视为 Domain 请求，并且还必须满足边界条件。 limitTo不会自行限制shell、read或write操作。

空 limitTo 列表拒绝每个域请求。 无效列表或无效条目会被视为空列表（并报告为配置错误），而不是丢弃该托管策略的其余部分。

deny 仍然优先于 limitTo。 ask 并 allow 仅细化已位于边界内的请求。 同样 allow， limitTo 是跨托管源的交集，每个声明 limitTo 列表的托管源都必须允许该请求。

托管 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 不会阻止任何内容。
• “拒绝”规则始终优先 — 只要也匹配 allowedMcpServers，服务器匹配 deniedMcpServers 就会被阻止。
• 对于远程服务器，匹配结果必须来自 serverUrl 条目；仅在不存在 serverName 条目的情况下，serverUrl 才算有效。 对于 stdio 服务器，匹配必须来自条目 serverCommand ; serverName 仅当不存在 serverCommand 条目时才会进行计数。

延伸阅读

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