GitHub Copilot CLI 命令参考

命令行命令

copilot login 选项

在本地终端或仍可访问浏览器的非 TTY 本地进程（例如，具有显示或浏览器信号的桌面 OS 或 Linux）上，默认身份验证模式是基于浏览器的 Web 流：CLI 将打开浏览器进行授权，然后在本地环回回调上捕获结果。 在远程终端（例如 SSH、 GitHub Codespaces开发容器）或 CI 中，CLI 默认为 OAuth 设备代码流，因为浏览器通常无法访问环回端口。 使用 --web-flow 或 --device-code 替代自动选择的流。

完成后，身份验证令牌安全地存储在系统凭据存储中。 如果未找到凭据存储，令牌将存储在 ~/.copilot/ 下的纯文本配置文件中（如果已设置，则存储在 COPILOT_HOME 指定的目录下）。

或者， Copilot CLI 将使用在环境变量中找到的身份验证令牌。 以下项按优先级顺序进行检查： COPILOT_GITHUB_TOKEN， GH_TOKEN。 GITHUB_TOKEN 此方法最适合无外设使用，例如自动化。

支持的令牌类型包括具有“Copilot 请求”权限的 fine-grained personal access tokens (v2 PATs)，Copilot CLI 应用中的 OAuth 令牌，以及 GitHub CLI (gh) 应用中的 OAuth 令牌。 不支持经典 personal access tokens （ghp_）。

示例：

# Authenticate with github.com
copilot login

# Authenticate with GitHub Enterprise Cloud (data residency)
copilot login --host https://example.ghe.com

# Force the device code flow, for example on a remote terminal
copilot login --device-code

# Force the browser (web) flow, for example on a local terminal
copilot login --web-flow

# Read a token from standard input, bypassing the OAuth flow entirely
copilot login --with-token < mytoken.txt

# Use a fine-grained PAT via environment variable
COPILOT_GITHUB_TOKEN=github_pat_... copilot

使用 copilot completion

该命令 copilot completion SHELL 输出指定 shell（bash、zsh 或 fish）的脚本。

通过执行该脚本（或将其写入 shell 的补全目录），即可在终端中为 copilot 的子命令、命令选项以及命令选项的已知取值，启用 Tab 键自动补全功能。

用法示例

Bash （仅限当前会话）：

source <(copilot completion bash)

source <(copilot completion bash)

Bash （持久性，Linux）：

copilot completion bash | sudo tee /etc/bash_completion.d/copilot

copilot completion bash | sudo tee /etc/bash_completion.d/copilot

Zsh — 将输出写入 $fpath 路径中的一个目录。 运行此命令后重启 shell：

copilot completion zsh > "${fpath[1]}/_copilot"

copilot completion zsh > "${fpath[1]}/_copilot"

鱼：

copilot completion fish > ~/.config/fish/completions/copilot.fish

copilot completion fish > ~/.config/fish/completions/copilot.fish

使用 copilot plugins list

运行 copilot plugins list 来检查在当前工作目录中发现的每个插件、MCP 服务器、技能、指令源和语言服务器。 输出按类型分组，然后按配置范围（用户、存储库、组织、插件参与、内置或未知）分组。

# List everything for the current workspace
copilot plugins list

# Only MCP servers and skills
copilot plugins list --kind mcp --kind skill

# Only user-scoped resources, as JSON
copilot plugins list --scope user --json

自定义智能体和会话范围内的钩子不受 copilot plugins list 影响；两者均需要活跃的会话。

copilot plugins enable / copilot plugins disable

按名称启用或禁用插件、MCP 服务器或技能。 更改会保存到配置中，并在今后的会话中生效。

# Disable an MCP server
copilot plugins disable github --mcp

# Enable a skill
copilot plugins enable my-skill --skill

# Enable a plugin (default kind)
copilot plugins enable spark@copilot-plugins

指令仅在会话范围内有效，无法通过这些命令进行切换。 语言服务器、代理和钩子由别处管理。

copilot plugins remove

卸载插件、删除 MCP 服务器或按名称删除技能。

# Remove an MCP server
copilot plugins remove github --mcp

# Delete a personal or project skill
copilot plugins remove my-skill --skill

# Uninstall a plugin (default kind)
copilot plugins remove spark@copilot-plugins

使用 --skill 传递技能名称或指向添加的自定义技能目录的路径。 技能名称删除该技能的文件;自定义目录路径仅取消注册目录并将其文件保留在磁盘上。 只能删除你添加的个人和项目技能 -- 插件提供的技能或内置集不能以这种方式删除（改为禁用它们）。 指令源从磁盘中发现，无法在此处删除。

会话侧边栏

会话侧边栏是一个停靠在当前对话旁边的面板，可让你快速处理本地 GitHub Copilot CLI 会话。

当边栏具有焦点时，可以使用以下键盘快捷方式。

侧边栏还会响应鼠标操作。

会话状态指示器

侧边栏中的每个会话都会显示其当前状态指示器。

默认 CLI 聊天模式下会话的文本使用默认文本颜色。 在计划模式和 autopilot 模式下使用不同的颜色。

会话边栏设置

/settings sidebar使用交互式 CLI 会话中的斜杠命令调整会话边栏的这些设置。

有关会话边栏的详细信息，请参阅 使用多个 GitHub Copilot CLI 会话。

交互式界面中的全局快捷方式

在本地会话中，您可以将提示词、Shell 命令和受支持的斜杠命令加入队列，以便在当前任务完成后按顺序运行。 按 Ctrl+Q 在代理运行时将当前输入排入队列。 已排队的条目会显示“待处理”标签，并可在运行前逐个取消。

交互式界面中的时间线快捷方式

任务对话框快捷方式

当任务对话框打开时（通过 /tasks 打开）：

会生成自身嵌套子智能体的子智能体将以缩进树形结构显示；您传送到的行将高亮显示为“当前”。 在深入查看子智能体视图时，您可以像对主会话一样，通过编辑器向其发送控制消息。

会话选取器快捷方式

会话选择器打开时（通过 /resume 或 --continue 打开）：

会话按以下模式排序：

已在另一个窗口中打开的会话在所有非相关性排序模式下浮动到顶部。 当没有工作目录上下文可用时，将跳过 relevance 模式。

差异模式快捷键

当打开差异模式时（通过 /diff 进入）：

交互式界面中的导航快捷方式

交互式接口中的斜杠命令

这些是在交互式 CLI 会话中可以使用的斜杠命令。 这些斜杠命令的子集可供通过其 ACP 服务器使用 CLI 的客户端使用。 有关详细信息，请参阅“Copilot CLI ACP 服务器”。

要获取所有可用的斜杠命令的完整列表，请在 CLI 的交互式界面中输入 /help。

在通过单独按下 /every 或 /after 打开的计划管理器中，使用 ↑/↓ 选择一个条目，并按 x 将其删除。 仅可通过在提示符下使用 /every 或 /after 并带参数来添加计划任务 — 对话框本身仅支持读取和删除操作。

/plugin 会在上游有可用新版本时提示已安装的插件或市场项，并在仪表板中提供 更新 操作。

/mcp list / ls 和 /plugin list/ls（包括裸 /plugin）均为只读，并且可在代理忙于处理一轮交互时执行。 所有其他 /mcp 命令和 /plugin 子命令都会被阻止，直到轮次完成。

命令行选项

有关命令和选项的完整列表，请运行 copilot help。

你可以将--remote与--resume <TASK-ID>配合使用，在本地恢复远程任务。 即使任务最初是在 Git 存储库外部创建的，也是如此。

如果会话在 CLI 进程消失时仍然处于打开状态，例如由于崩溃或计算机重启，下次启动 copilot 时，系统会提供还原会话的选项。 您可以查看可用于恢复的会话，或者改为启动一个新会话。 对于智能体正在处理中的恢复会话，系统会自动恢复该项工作。

先规划，后自动执行

Plan-then-autopilot 允许会话在计划模式下启动，并在计划准备就绪后自动继续进入 Autopilot 模式，而无需等待人工批准转换。 可通过 --plan --mode autopilot 启用此功能，或者对于只能注入环境变量而无法注入命令行选项的测试框架，可通过 COPILOT_PLAN_THEN_AUTOPILOT 环境变量启用。 如果同时设置了这两个选项，则显式选项优先，CLI 会显示一条警告，指出环境变量已被忽略。

企业级管理的沙箱底线

企业管理策略可将操作系统级 Shell 沙盒隔离强制设定为最低基线。 换言之，即使您传入 --no-sandbox，策略仍可强制启用沙箱。 这是策略覆盖，而非标志本身失败。 相比之下，--sandbox 不受影响，因为它只会启用沙盒机制，而不会将其移除。 如果有效策略允许绕过沙盒，则您可以在响应当前显示的绕过权限提示时，显式禁用当前会话剩余时间内的沙盒。

当托管策略覆盖了你的设置时，CLI 会在交互式时间线中显示警告（或者在使用 -p 时通过 stderr 显示警告），从而明确表明该行为是由策略强制执行导致的，而不是因为该选项本身不起作用。 如果需要更改策略，请与管理员联系。 每当受管策略强制启用沙盒机制时，/sandbox 命令也会被注册；即使未启用实验性功能，您仍可在该底线生效期间检查当前生效的策略和状态。 仅在实验模式下可用。

将受管理的 sandbox.failIfUnavailable 设置为 true，并同时将 sandbox.enabled 设置为 true，会使得在无法建立沙盒时必须强制使用沙盒。 如果策略无法验证、编译，或无法由可用的沙盒后端执行，Copilot 不会回退为以非沙盒方式运行命令，而是会阻止模型和工具执行。 请参阅“企业管理设置”。

当受管策略在您未请求的会话中启用沙箱时，CLI 也会发出警告，而不仅仅是在其覆盖 --no-sandbox 时。 这包括策略在启动后才生效的会话，因为服务器管理的设置仅在登录后才可用。 如果你自己的设置或 --sandbox 选项已请求启用沙盒，则会省略此警告，因为此时会话状态属于预期情况。

如果设备存在无法读取的受管策略，CLI 将以安全关闭方式失败，并以最高限制级别强制实施沙盒隔离。 该通知说明无法确定该策略，并告知你等待该问题得到解决。 不受支持的主机的启动警告使用相同的措辞。

限制使用 --allow-all 选项

如果将 permissions.disableBypassPermissionsMode 设置为 "disable"，则所有允许授予全部权限的命令行选项（--allow-all-tools、--allow-all-paths、--allow-all-urls、--allow-all、--yolo）都会在启动时被禁用，且不能用于授予提升后的权限。 /permissions allow-all斜杠命令及其别名/allow-all，/yolo也将被禁止显示。

将permissions.disableBypassPermissionsMode设为"allow-auto-only"，以阻止完全放开所有权限，但允许/permissions assisted（LLM 辅助权限审批）。 辅助批准仍会针对每个请求提示确认，但会附带一条 LLM 安全建议，以便 CLI 能自动批准那些被模型评估为可接受的请求。

如果 permissions.disableBypassPermissionsMode 设置为无法识别的值，CLI 将不再彻底拒绝它。 相反，CLI 会记录该问题，并强制执行 "disable" 作为“失败即关闭”的默认设置，因此格式错误的受管策略仍会限制“允许所有”选项，而非默默允许它们。

有三个来源可以设置此限制，按持久性递增的顺序如下：

有关 MDM 配置详细信息，请参阅 GitHub Copilot CLI 配置目录。

支持的模型

使用 --model=MODEL 或 COPILOT_MODEL 环境变量选择 AI 模型。 传递auto让Copilot自动选择最佳可用模型。

还可以使用斜杠命令在 /model 交互式会话期间切换模型。

工具可用性值

和--available-tools``--excluded-tools选项支持以下值：

Shell 工具

文件操作工具

代理和任务委派工具

其他工具

工具权限模式

--allow-tool和--deny-tool选项接受格式为Kind(argument)的权限模式。 该参数是可选的， 省略它与该类型的所有工具匹配。

对于 shell 规则，:* 后缀与命令主干后跟一个空格匹配，以避免部分匹配。 例如， shell(git:*) 匹配 git push 和 git pull 不匹配 gitea。

即使设置了拒绝规则， --allow-all 拒绝规则始终优先于允许规则。

# Allow all git commands except git push
copilot --allow-tool='shell(git:*)' --deny-tool='shell(git push)'

# Allow a specific MCP server tool
copilot --allow-tool='MyMCP(create_issue)'

# Allow all tools from a server
copilot --allow-tool='MyMCP'

# Deny writes to a specific path (exact or trailing-path-segment match; no glob support yet)
copilot --deny-tool='write(secret.txt)'

--deny-tool='write(PATH)' 将拒绝范围限定为该路径 - 其他写入不受影响。 匹配操作会解析符号链接和 ./.. 段，并在 macOS 和 Windows 上不区分大小写。

环境变量

配置文件设置

有关配置文件设置的详细信息（包括用户设置、存储库设置、本地设置及其级联方式的完整列表），请参阅 GitHub Copilot CLI 配置目录。

Copilot 的项目初始化

使用命令 copilot init或交互式会话中的斜杠命令 /init 时， Copilot 分析代码库并写入或更新 .github/copilot-instructions.md 存储库中的文件。 此自定义说明文件包含特定于项目的指南，可改进将来的 CLI 会话。

当你启动新项目时，或者当你在现有存储库中开始使用 copilot init 时，你通常会使用/init 或 Copilot CLI。

copilot-instructions.md创建或更新的文件通常记录信息：

• 生成、测试和 Lint 命令。
• 高级体系结构。
• 特定于代码库的约定。

如果文件已存在，Copilot 会提议可选择应用或拒绝的改进。

CLI 在启动时查找 copilot-instructions.md 文件，如果缺少该文件，则会显示消息：

💡 未找到副驾指令。 运行 /init 以为此项目生成 copilot-instructions.md 文件。

如果不想创建此文件，可以使用斜杠命令永久隐藏当前存储库的 /init suppress 此启动消息。

有关详细信息，请参阅“为GitHub Copilot添加存储库自定义说明”。

使用 --sandbox 或 --no-sandbox 并配合 copilot init，可仅对初始化会话启用或禁用 OS 级 shell 沙盒，而无需更改已保存的沙盒设置。 这些选项与其他入口一样，受相同的企业管理沙盒下限约束——请参阅企业管理沙盒下限。

自定义指令位置

Copilot CLI 同时从这些位置加载自定义指令（全部合并）：

自定义指令导入

说明文件支持 @path 导入。 在行首添加 @ 后跟路径，即可内联另一个文件的内容。 路径可以是相对于指令文件的目录或绝对路径。 导入会进行递归解析，受深度限制，并带有循环和大小限制。 AGENTS.md、CLAUDE.md 和 .github/copilot-instructions.md 支持此功能。

挂钩引用

有关挂钩的详细信息（包括挂钩配置格式、挂钩事件、输入有效负载和决策控制），请参阅 GitHub Copilot 挂钩参考。

MCP 服务器配置

MCP 服务器向 CLI 代理提供其他工具。 在~/.copilot/mcp-config.json中配置持久性服务器。 使用 --additional-mcp-config 来为单个会话添加服务器。

在沙盒内启动的本地（stdio）服务器（请参阅 /sandbox 斜杠命令）会在 connected (sandboxed) 和 copilot mcp list 中显示为 /mcp list 状态，因为远程（HTTP/SSE）服务器绝不会在沙盒中运行。 仅在实验模式下可用。

copilot mcp list 和 /mcp list 用于标记已禁用的服务器，在文本输出中以 (disabled) 后缀表示，或在 --json 输出中按服务器分别以 "enabled": false 表示。 copilot mcp get 显示一行 Status: Enabled/Disabled 。

切换 /sandbox 仅会重启本地（stdio）MCP 服务器，因为它们是在沙箱内部启动的。 远程（HTTP/SSE）服务器保持连接状态。

/mcp edit <name> 会拒绝来自工作区的服务器（即在仓库的 .mcp.json 中定义的服务器），而不是打开用户级向导，因为保存时会在无提示的情况下创建一个同名的用户级条目，而该条目仍会被工作区中的条目遮蔽。 错误信息直接给出了要编辑的文件名。 /mcp delete <name> 当系统要求删除工作区源服务器时，报告同一文件。

copilot mcp 子命令

用于 copilot mcp 从命令行管理 MCP 服务器配置，而无需启动交互式会话。

对于本地（stdio）服务器，请在 -- 后提供该命令：

copilot mcp add SERVER-NAME -- COMMAND [ARGS...]

copilot mcp add SERVER-NAME -- COMMAND [ARGS...]

对于远程 HTTP 或 SSE 服务器，请指定传输并提供 URL：

copilot mcp add --transport http SERVER-NAME URL

copilot mcp add --transport http SERVER-NAME URL

** copilot mcp add 选项：**

在 /mcp add//mcp edit 交互式表单中，在 env 字段中输入以逗号分隔的 KEY=VALUE 对，或输入 JSON 对象（例如 {"API_KEY":"secret"}）。 $PATH 默认包含，无需列出。

传输类型

本地服务器配置字段

工具快照缓存

Copilot CLI 会持久化保存每个本地服务器的工具列表快照，以便在启动时工具可立即使用，同时在后台完成实时发现。 实时发现始终运行，并在完成后替换快照。

将服务器上的 disableToolCache: true 设为相应值，以仅对该服务器强制进行实时发现；或者设置 COPILOT_MCP_TOOL_CACHE=false 环境变量，以对整个进程禁用快照加载和持久化。 这两个选择退出都使现有缓存文件保持不变。

专用 npm 注册表

在 --registry 数组中使用 args 从私有 npm 注册表拉取包 — 例如，Artifactory 或 GitHub Packages 源：

{
    "mcpServers": {
        "my-internal-server": {
            "command": "npx",
            "args": [
                "--registry", "https://npm.pkg.github.com",
                "@my-org/internal-mcp-server"
            ],
            "tools": ["*"]
        }
    }
}

在计算服务器标识指纹时，--registry 选项和其他 npm 配置选项（--userconfig、--globalconfig、--prefix、--cache、--node-options、--workspace、-w）会被视为接受值的参数。 这可确保当这些选项出现在包名称之前时，企业允许列表校验和注册表验证能够正常运行。

远程服务器配置字段

OAuth 重新身份验证

使用 OAuth 的远程 MCP 服务器可能会在令牌过期或需要其他帐户时显示 needs-auth 状态。 使用 /mcp auth <server-name> 触发新的 OAuth 流。 这会打开浏览器身份验证提示，允许你登录或切换帐户。 完成流后，服务器会自动重新连接。

在 Windows 上，受 Microsoft Entra ID 保护的远程 MCP 服务器则通过操作系统身份验证代理（Web 帐户管理器）进行身份验证，通常不会出现提示。 在其他平台上，在没有代理库的Windows计算机上，登录会回退到上述浏览器流。 传入 --device-code 会绕过代理程序，并强制使用 OAuth 设备代码流程，而不是浏览器流程。

无外设 OAuth（client_credentials 授权）

对于没有可用的浏览器的 CI 或 cron 用例，请设置 oauthGrantType: "client_credentials"。 这需要：

• oauthClientId— MCP 提供程序颁发的静态客户端 ID。
• oauthPublicClient: false- 客户端是机密的。
• 存储在系统钥匙串中的 client_secret（通过 /mcp UI 配置一次，或写入 OAuth 凭据存储）。

配置后，CLI 将完全跳过浏览器、回调服务器、PKCE 和动态客户端注册。 每次遇到 401 错误时，会将 grant_type=client_credentials 直接发送至服务器检测到的令牌端点。

{
    "mcpServers": {
        "headless-api": {
            "type": "http",
            "url": "https://api.example.com/mcp",
            "tools": ["*"],
            "oauthClientId": "YOUR-CLIENT-ID",
            "oauthPublicClient": false,
            "oauthGrantType": "client_credentials"
        }
    }
}

筛选器映射

控制如何使用服务器配置中的filterMapping字段来处理 MCP 工具输出。

内置 MCP 服务器

CLI 包括内置 MCP 服务器，这些服务器在没有其他设置的情况下可用。

用于 --disable-builtin-mcps 禁用所有内置服务器，或 --disable-mcp-server SERVER-NAME 禁用特定服务器。

GitHub MCP 服务器工具

github-mcp-server 提供以下工具。

MCP 服务器命名

服务器名称可以包含任何可打印字符，包括空格、Unicode 字符和标点符号。 不允许控制字符（U+0000–U+001F、U+007F）和右大括号（}）。 服务器名称用作工具名称的前缀，例如，名为 my-server 的服务器生成类似 my-server-fetch 的工具名称，而名为 My Server 的服务器生成类似 My Server-fetch 的工具名称。

MCP 工具名称清理

MCP 服务器名称和工具名称在发送到模型之前进行过滤。 工具名称中无效的字符（除了 a-z、A-Z、0-9、-、_ 之外的任何字符）都将被 - 替换。 Unicode 字符是 Punycode 编码的。 符号 @ 也替换为 - ，以避免与 Punycode 编码冲突。

组合名称 （serverName-toolName） 上限为 64 个字符。 截断将创建名称冲突时，将追加数字后缀（例如，my-server-tool2``my-server-tool3），以确保唯一性。

MCP 服务器信任级别

MCP 服务器从多个源加载，每个源具有不同的信任级别。

所有 MCP 工具调用都需要显式权限。 这甚至适用于对外部服务的只读操作。

MCP 服务器加载优先级

来自不同源的 MCP 服务器按优先级顺序合并（第一个最高）。 当服务器共享名称时，优先级较高的源优先。

1. --additional-mcp-config 选项（最高）
2. 插件提供的服务器
3. 工作区服务器 — .mcp.json 和 .github/mcp.json 从工作目录向上加载到 Git 根目录；要求该文件夹受信任
4. ~/.copilot/mcp-config.json （最低）

企业 MCP 允许列表

GitHub Enterprise 组织可以强制实施允许的 MCP 服务器白名单。 处于活动状态时，CLI 会根据企业策略评估每个非默认服务器，然后再连接。

检测到 GitHub Enterprise 注册表策略（或启用 MCP_ENTERPRISE_ALLOWLIST 实验性功能标志）时，CLI：

1. 根据每个配置的非默认服务器的命令、参数和远程 URL 计算指纹。
2. 将指纹发送到企业白名单评估端点。
3. 仅允许指纹已获批准的服务器；所有其他服务器都将被阻止，并收到一个包含企业名称的消息。

此检查为“失效关闭”模式：如果评估终结点不可访问或返回错误，则会阻止非默认服务器，直至策略可以被验证。

当企业允许列表阻止服务器时，CLI 会显示：

MCP server "SERVER-NAME" was blocked by your enterprise "ENTERPRISE-NAME".
Contact your enterprise administrator to add this server to the allowlist.

内置默认服务器始终不受允许列表强制实施的约束。

迁移自 .vscode/mcp.json

如果项目使用 .vscode/mcp.json（VS Code 的 MCP 配置格式），请迁移到 .mcp.json 以便于 GitHub Copilot CLI。 迁移会将密钥servers重新映射到 mcpServers 。

POSIX Shell（bash、zsh、fish 和其他）：

jq '{mcpServers: .servers}' .vscode/mcp.json > .mcp.json

需要 jq。

PowerShell：

pwsh -NoProfile -Command "`$json = Get-Content '.vscode/mcp.json' -Raw | ConvertFrom-Json; `$content = ([pscustomobject]@{ mcpServers = `$json.servers } | ConvertTo-Json -Depth 100); [System.IO.File]::WriteAllText('.mcp.json', `$content, (New-Object System.Text.UTF8Encoding `$false))"

在Windows，如果使用 Windows PowerShell 而不是 PowerShell Core，请将 pwsh 替换为 powershell。

Stdio 服务器输出

MCP stdio 传输协议将 stdout 专用于以换行符分隔的 JSON-RPC 帧。 在将输出传递到协议分析器之前，CLI 会自动筛选出任何非 JSON 行（纯文本日志、异常堆栈跟踪或仅空格行）。

将所有诊断输出写入 stderr，而不是 stdout。 将日志或错误消息写入 stdout 的服务器可以触发分析错误反馈循环，该循环会停止初始化握手;筛选器通过静默删除非 JSON 帧来阻止此情况。

超过 1 MB 的行会绕过结构检查，并按原样转发，以避免拆分或丢弃超大但有效的协议帧（例如，一个较大的 tools/list 响应）。

技能指南

技能是可扩展 CLI 功能的 Markdown 文件。 每个技能都位于其自己的目录中，其中包含一个 SKILL.md 文件。 调用（通过 /SKILL-NAME 或自动由代理调用）时，技能的内容将注入到会话中。

技能前页字段

技能位置

系统将按照优先顺序从这些位置加载技能（对于重复名称，以首次找到项为准）。

当本地技能具有相同名称时，远程技能与本地技能一起投影，并遵循相同的基于名称的优先级。

当两个插件提供具有相同名称的技能时，两个插件都使用插件限定的调用名称（例如 /my-plugin/search 和 /other-plugin/search） 共存。 仅名称会路由到优先级更高的插件。 这仅适用于技能；命令仍保持标准的基于层级的去重机制，其中优先级更高的来源优先。

非交互式安装技能

使用 copilot plugins install --skill 可从文件、URL 或目录安装技能，而无需打开交互式会话：

# Install for your user account (default scope)
copilot plugins install --skill ./my-skill/SKILL.md

# Install into the current project (.github/skills; file or URL skills only)
copilot plugins install --skill --scope project ./my-skill/SKILL.md

安装一个目录时，系统会将其注册为自定义技能源，而不是复制该目录。 安装文件或 URL 会将技能的内容复制到个人或项目技能目录中。 等效的交互式命令为 /skills add [--project] <FILE|URL|DIRECTORY>. 有关完整选项参考，请参阅 GitHub Copilot CLI 插件参考。

命令（可选技能格式）

命令是 .md 中存储为单个 .claude/commands/ 文件的技能的替代项。 命令名称派生自文件名。 命令文件使用简化格式（无需 name 字段），并支持 argument-hint、description、allowed-tools 和 disable-model-invocation。 命令的优先级低于具有相同名称的技能。

自定义代理参考

自定义代理是在 Markdown 文件中定义的专用 AI 代理。 文件名（减扩展名）将成为代理 ID。 使用 .agent.md 或 .md 用作文件扩展名。

内置代理

code-review 和 security-review 绝不会将完整审查转发给另一个审查代理：因为启动某个审查者本身就已经满足了“使用”或“调用”审查者的请求，所以它会自行完成审查，而不会在整个委托链中递归地将整个任务委托给嵌套的 code-review 或 security-review 子代理。 code-review 仍会将请求中侧重安全的部分交由专门的 security-review 专家处理，并且这两个代理都可以将范围较窄且可独立界定的事实查证工作委托给非审查代理，例如 explore。

只有根代理才能调用 store_memory 或 vote_memory 来保存某条记忆或对其进行投票。 子代理通过对存储的 read_memories记忆保持读取访问权限，但无法对它们进行写入或投票。

自定义代理程序前端字段

无论代理是通过 task 工具调度，还是直接启动（例如，通过 SDK 的 session.startSubagent），model 和 reasoningEffort 都适用。 它们按以下优先级确定，优先级从高到低依次为：每次调用时显式指定的值、model中的subagents覆盖值、代理定义中的/reasoningEffort``~/.copilot/settings.json字段，最后是父会话的值。 若声明的模型或操作无法被满足，系统将回退到会话的默认值，而非导致分派失败。

自定义代理位置

对于项目作用域的代理，CLI 会从当前工作目录开始，逐级向上遍历直到 Git 根目录，并在沿途每一级父目录中加载 .github/agents/ 和 .claude/agents/ 目录。 这意味着 monorepo 中的每个包或子目录都可以贡献自己的代理。 当路径中存在多个 .github/agents/ 目录时，将加载所有目录，其中最深的目录具有最高优先级。 在同一级别中，.github/agents/ 约定优先于 .claude/agents/。 用户级代理的优先级低于项目级代理。 插件代理的优先级最低。

代理通信

在自定义代理中使用 list_agents 和 write_agent，以检查附近的代理并在多代理会话中协调工作。

list_agents中的关系标签

关系标签标识可见代理与当前代理的关系。 当子代理在启用了共享同级通信的父会话内运行时，将显示标签。

作用域列表

在scope上使用list_agents，以便在选择目标之前缩小列表范围。

在单代理会话中，默认视图以子代理为中心。 在多代理会话中，默认视图显示即时本地上下文，而不是整个树。

list_agents(scope="siblings")
list_agents(scope="children")
list_agents(scope="all")

作用域内消息传送

在scope上使用write_agent，将一条消息广播给多个相关代理。

仅可在启用了共享同级通信的父会话内运行的子智能体中使用作用域内消息传送。 在顶级会话中，应改为以具有显式 agent_id 值的代理为目标。

如果某个作用域匹配的智能体过多，write_agent 会返回错误，并要求改为从 agent_id 提供明确的 list_agents 值。

write_agent(scope="children", message="Re-check your findings against the updated schema.")
write_agent(scope="siblings", message="Post status when your current check completes.")
write_agent(agent_id="explore-auth", message="Focus on token refresh flow and report only confirmed issues.")

子代理限制

CLI 强制实施深度和并发限制以防止生成失控代理。

深度 计数彼此嵌套的代理数。 达到深度限制时，最内部的代理无法生成进一步的子代理。 并发 计数在整个会话树中同时运行的子代理数。 达到限制后，将拒绝新的子代理请求，直到活动代理完成。

默认并发限制取决于您所用的 Copilot 套餐：

按使用量计费的用户可通过 subagents.maxConcurrency 和 subagents.maxDepth 设置覆盖这些限制：

{
    "subagents": {
        "maxConcurrency": 16,
        "maxDepth": 10
    }
}

超出有效范围的值会被限制：maxConcurrency 的上限为 32，maxDepth 的下限为 256。 对于不使用基于使用情况的计费的计划，将忽略这些设置。 请参阅 配置文件设置。

Sidekick 智能体

Sidekick 代理在后台自动运行，并将上下文发布到会话收件箱中。 它们响应会话事件，而不是被显式调用。

在任何代理定义中添加 sidekick: 块，使其成为辅助代理：

---
name: Context Gatherer
description: Gathers relevant context when the working directory changes
sidekick:
    triggers:
        - session.context_changed
        - event: user.message
          limit: 1
    behavior: persistent
    maxSendsPerTurn: 2
---

Gather useful context about the current repository and working directory.
Summarize recent changes and any relevant project structure.

Sidekick 触发器

triggers 中的每个条目要么是一个纯事件名称字符串，可触发无限次；要么是一个包含 event 和可选的 limit 的对象。

Sidekick 配置字段

"restart" 的行为模式适合用于收集上下文的无状态代理。 "persistent" 行为适用于跨轮次累积状态的智能体。

权限审批结果

当 CLI 提示执行作的权限时，可以使用以下键进行响应。

显示完整对话框后，还可以从以下选项中进行选择：

当 CLI 可以确定位置密钥（Git 根目录或当前目录）时，将显示 “此位置 ”选项。 它将审批保存到磁盘，以便在下次在该目录中工作时自动授予相同的权限，而无需再次提示。

使用 /permissions reset 清除当前会话的内存中授权。

安全性

计划模式

/plan 启动规划会话，在该会话中，Copilot CLI 可以浏览和分析你的代码库，但无法编辑你的项目文件。 Specifically:

• 项目文件受到保护。 任何试图编辑、修补文件，或运行会更改工作区中文件的 Shell 命令的行为，都会被自动阻止——这不只是给模型的一条建议，而是直接强制执行的，因此并不取决于模型是否选择遵守。
• 计划本身仍可编写。 Copilot 需要一个位置来保留笔记和起草计划，因此允许在自己的专用规划工作区中创建和编辑文件（包括要审阅和批准的计划文件）。
• 委派的子任务也受到保护。 如果 Copilot 启动一个辅助会话来研究你的问题中的一部分，该辅助会话也同样受到这些限制，无法编辑你的项目。
• 这是一个安全网，不是保证。 此保护机制旨在拦截明显、直接的文件修改尝试 — 并非万无一失的封锁。 某些事情是有意允许的，因此研究没有过度限制：例如，无法提前明确确定其效果的 shell 命令，以及对已连接的外部/MCP 工具的调用。 在实践中，这很少是个问题，但计划模式应该被视为“更改需要你在应用之前进行评审”，而不是绝对保证磁盘上没有任何内容可以更改。

当您对计划满意后，请批准该计划以退出计划模式，并让 Copilot 执行实际更改。

命令安全分析

在执行之前会分析 Shell 命令，以确定潜在的危险模式：

• 文件删除 （rm -rf）
• 系统修改 （sudo， chmod 777）
• 网络渗漏（带有敏感路径的 curl）
• 凭据访问（读取 .env、SSH 密钥）
• 用于覆盖危险变量的内联环境变量赋值（例如，PATH=...、LD_PRELOAD=...）

高风险命令显示其他警告，并需要显式确认。

当启用沙箱且允许绕过沙箱设置为开启（默认）时，若同步 shell 命令被沙箱的文件系统或网络策略阻止，系统会提示您在沙箱外重新运行该命令 — 无需进行模型往返处理。 确认该提示后，将重新运行该命令并返回其输出结果。 拒绝后将保留沙箱中的（被阻止的）结果。

有关详细信息，请参阅“配置本地沙盒设置”。

环境变量拒绝列表

CLI 会阻止内联分配环境变量，这些环境变量可以被利用以执行任意代码，即使在其他只读命令中也是如此。 阻止的类别包括：

web_fetch SSRF 防护

该工具 web_fetch 在发出任何 HTTP 请求之前强制实施服务器端请求伪造（SSRF）保护：

• 协议允许列表：仅允许 http:// 和 https:// URL。 file:// 和其他方案均被拒绝。
• IP 阻止列表：IP 文本检查和 DNS 预解析阻止了对环回地址127.x.x.x（、 ::1）、RFC-1918 专用范围（10.x、 172.16–31.x、 192.168.x）和云元数据终结点（例如） 169.254.169.254的请求。
• 已验证的重定向： web_fetch 遵循 3xx 重定向（最多 10 个跃点，在 60 秒的网络预算内），在遵循该重定向之前，针对同一 IP 阻止列表重新验证每个跃点的目标。 重定向到与原始 URL 不同的源需要权限审批，这与任何其他跨域提取相同;遵循同源重定向，无需额外提示。 最终结果会注明内容何时为 (redirected from <original URL>)。

若要允许 web_fetch 在开发期间访问 localhost （例如，对于本地文档服务器），请设置以下环境变量：

export COPILOT_WEB_FETCH_ALLOW_LOCALHOST=1

沙箱工具目录授权

启用本地沙盒后， Copilot CLI 发现沙盒命令可能需要的工具目录并授予每个 只读 访问权限，因此命令可以运行已安装的工具链，而无需修改它。 在进程启动之前，发现会针对每个命令运行，并从命令环境读取两种类型的源。

• PATH（在 Windows 上为 Path）。 列表中的每个目录都是授予候选项。
• 命名工具链变量。 CLI 在每个操作系统上检查下表中的变量。 保存单个目录的变量会将该目录授予访问权限；保存路径列表的变量会按操作系统的路径分隔符进行拆分（Windows 上为 ;，其他系统上为 :），并且每个条目都会成为一个候选授权项。

只有当候选项为真实存在的绝对路径且解析为目录时，才会被授予。 当候选项为相对路径、不存在、解析为文件系统根目录（如 / 或 C:\），或解析到系统关键位置（Windows 上的 %WINDIR%；/bin、/sbin、/usr/bin、/usr/sbin、/boot、/proc、/sys 和 /dev 在 Linux 及 macOS 上），候选项将被移除，并记录原因至 sandbox_spawn 日志目标。 在进行这些检查之前，会先解析符号链接，并移除重复目录（在 Windows 上按不区分大小写的方式处理）。

每个变量在所有平台上都会被读取；通常设置在列显示了每个变量的常规填充位置，而非 CLI 强制执行的限制。 未设置的变量不会产生任何影响。

这些并非唯一的只读权限。 Copilot CLI 还授予对用户配置文件应用程序目录的访问权限（Linux 和 macOS 上的 ~/.local/bin 和 ~/.local/lib；Windows 上 %LOCALAPPDATA%\Programs 的直接子目录）、标准系统和配置文件位置，以及常用包管理器和工具链使用的缓存和注册表（在 /sandbox policy 报告中显示为 dev-tool 访问）。 若要查看当前目录（读/写、只读和拒绝路径）的完全解析策略，请在会话中运行 /sandbox policy 。 有关如何组合策略的概念，请参阅 了解 GitHub Copilot CLI 中用于本地沙盒的文件系统策略。

OpenTelemetry 监视

Copilot CLI 可以通过 OpenTelemetry（OTel ）导出跟踪和指标，从而了解代理交互、LLM 调用、工具执行和令牌使用情况。 所有信号名称和属性都遵循 OTel GenAI 语义约定。

默认情况下，OTel 处于关闭状态，开销为零。 当满足以下任一条件时，它将激活：

• COPILOT_OTEL_ENABLED=true
• OTEL_EXPORTER_OTLP_ENDPOINT 已设置
• COPILOT_OTEL_FILE_EXPORTER_PATH 已设置

OTel 配置也可以在 VS Code 中设置，或者在企业范围内的 managed-settings.json 文件中设置。 请参阅 文档中的 VS Code 和 企业管理设置。

OTel 环境变量

Traces

运行时为每个智能体交互发出分层跨度树。 每个树都包含根invoke_agent范围，以及chat``execute_tool子范围。

invoke_agent span 属性

包装整个智能体调用：一个用户消息的所有 LLM 调用和工具执行。

• 无论是顶级会话还是子智能体调用（例如 explore、task），都使用 span 类型 INTERNAL（进程内）；面向提供者的推断则由子 CLIENT``chat span 表示。
• 顶层会话还会携带server.address和server.port；子代理调用则不会携带。

chat span 属性

每个 LLM 请求一个跨度。 范围类型： CLIENT.

execute_tool span 属性

为每个工具调用指定一个跨度。 范围类型： INTERNAL.

Metrics

GenAI 约定指标

特定于供应商的指标

跨度事件

在活动 chat 或 invoke_agent 跨度上记录的生命周期事件。

资源属性

所有信号都携带这些资源属性。

内容捕获

默认情况下，不会捕获提示内容、响应或工具参数，仅捕获模型名称、令牌计数和持续时间等元数据。 若要捕获完整内容，请设置 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true。

启用内容捕获后，将填充以下属性。

延伸阅读

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