# GitHub Copilot CLI 命令参考 查找有助于有效使用的 Copilot CLI 命令和键盘快捷方式。 ## 命令行命令 | 命令 | Purpose | | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `copilot` | 启动交互式用户界面。 | | `copilot app` | 打开当前目录中的 GitHub Copilot app，并通过深层链接直接进入新会话。 如果深度链接无法处理，则改为在浏览器中打开该应用的下载页面；如果没有可用的浏览器，则输出该 URL 以供手动打开。 | | `copilot completion SHELL` | 生成一份适用于所选 Shell 的 shell 脚本，你可以利用该脚本来为 Copilot CLI 启用 Tab 键补全功能。 支持的 shell： `bash`、 `zsh`、 `fish`。 请参阅[使用 `copilot completion`](#using-copilot-completion)。 | | `copilot config [KEY] [VALUE]` | 在交互式会话之外，从命令行读取或更改 Copilot 设置。 请参阅[使用 `copilot config`](#using-copilot-config)。 | | `copilot help [TOPIC]` | 显示帮助信息。 帮助主题包括：`billing`、`config`、`commands`、`environment`、`logging`、`monitoring`、`permissions`、`providers`和`sandbox`。 | | `copilot init` | 初始化 Copilot 此存储库的自定义说明。 | | `copilot login [OPTION]` | 使用 OAuth 通过 Copilot 进行身份验证。 请参阅 [`copilot login` 选项](#copilot-login-options)。 | | `copilot mcp` | 从命令行管理 MCP 服务器配置。 | | `copilot plugin` | 管理插件和插件市场，包括列出、启用、禁用和卸载它们。 | | `copilot plugins` （plural） 是一个旧别名。 请参阅“[GitHub Copilot CLI 插件参考](/zh/copilot/reference/copilot-cli-reference/cli-plugin-reference)”。 | | | `copilot instruction` | 以非交互方式列出在当前工作目录中发现的自定义指令源。 请参阅[使用 `copilot instruction`](#using-copilot-instruction)。 | | `copilot lsp` | 以非交互方式列出已配置的语言服务器。 请参阅[使用 `copilot lsp`](#using-copilot-lsp)。 | | `copilot sandbox ca` | 从交互式会话外部管理沙盒的代理证书颁发机构。 请参阅[使用 `copilot sandbox ca`](#using-copilot-sandbox-ca)。 | | `copilot skill` | 从命令行管理代理技能（列出、添加、删除、启用和禁用技能）。 请参阅 [非交互方式管理技能](#managing-skills-non-interactively)。 | | `copilot update` | 下载并安装最新版本。 | | `copilot version` | 显示版本信息并检查更新。 | | `copilot workflow run WORKFLOW-NAME` | 直接运行现有的动态工作流，而无需发送聊天提示。 等待运行完成或停止。 请参阅[使用 `copilot workflow run`](#using-copilot-workflow-run)。 | ### `copilot login` 选项 | 选项 | Purpose | | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `--host HOST` | | | GitHub 主机 URL （默认值： `https://github.com`） 。 使用此方法向使用数据驻留（例如 GitHub Enterprise Cloud）的 `https://example.ghe.com` 实例进行身份验证。 | | | `--web-flow` | 强制基于浏览器的 （Web） 身份验证流，这是本地终端上的默认值。 | | `--device-code` | 强制使用 OAuth 设备代码流程，该流程在远程终端或 CI 中默认使用。 | | `--with-token` | 从标准输入读取身份验证令牌，而不是启动 OAuth 流。 当标准输入为终端时，提示符不会回显输入内容。 与 `--web-flow` 和 `--device-code`. | 在本地终端或仍可访问浏览器的非 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_`）。 **示例：** ```shell # 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 键自动补全功能。 对于 `copilot config`，完成还包括设置键、布尔值和枚举值，以及路径值设置的文件或目录。 #### 用法示例 Bash （仅限当前会话）： ```bash copy source <(copilot completion bash) ``` Bash （持久性，Linux）： ```bash copy copilot completion bash | sudo tee /etc/bash_completion.d/copilot ``` Zsh — 将输出写入 $fpath 路径中的一个目录。 运行此命令后重启 shell： ```shell copy copilot completion zsh > "${fpath[1]}/_copilot" ``` 鱼： ```shell copy copilot completion fish > ~/.config/fish/completions/copilot.fish ``` ### 以非交互方式管理插件 用于 `copilot plugin` 从命令行安装、列出、更新、启用、禁用和卸载插件，而无需打开交互式会话。 `copilot plugins` （plural） 是同一命令的旧别名。 有关完整命令和选项参考，请参阅 [GitHub Copilot CLI 插件参考](/zh/copilot/reference/copilot-cli-reference/cli-plugin-reference)。 ### 使用 `copilot config` 运行 `copilot config` 以在交互式会话外部从命令行读取和更改 Copilot 设置。 这是 `/config`（或 `/settings`）斜杠命令的非交互式对应项。 有关设置文件及其键的详细信息，请参阅 [GitHub Copilot CLI 配置目录](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#settingsjson)。 ```bash # Print a setting copilot config theme # Set a nested value (dot notation) copilot config footer.showQuota off # Append an item to a list setting (added only if not already present) copilot config allowedUrls github.com # Append an item that starts with a dash copilot config powershellFlags -- -NoProfile # Remove a key, or one list item copilot config --rm theme copilot config --rm allowedUrls github.com # List settings as key=value lines, or as JSON copilot config --list copilot config --repo --list --json ``` | 选项/参数 | 说明 | | ---------- | ---------------------------------------------------------------------- | | `KEY` | 以点表示法设置键（例如 `footer.showQuota`）。 | | `VALUE` | 要使用 `--rm` 设置、追加或删除列表中的值。 | | `--list` | 将设置显示为 `key=value` 行；与/`KEY``VALUE`/`--rm`冲突。 | | `--json` | 输出 `--list` 为 JSON;需要 `--list`。 | | `--rm` | 删除键，或仅从列表中删除给定项;要求 `KEY`。 | | `--global` | 使用用户设置文件（默认值）；与 `--repo`/`--local` 冲突。 | | `--repo` | 使用存储库的 `--global`；与 /`--local``.github/copilot/settings.json` 冲突。 | | `--local` | 使用存储库的 `--global`；与 /`--repo``.github/copilot/settings.local.json` 冲突。 | 值必须与设置的类型匹配：对于布尔值，使用 `on`/`off` 或 `true`/`false`；对于数值设置，使用数字；对于枚举，使用可接受的选项。 读取列表每行打印一个项目;读取组会打印 JSON。 未设置的键以 `1` 状态退出。 机密值会从输出中被隐藏。 默认情况下，命令使用用户设置文件（`settings.json` 位于 `~/.copilot` 中，或在已设置时位于 `$COPILOT_HOME` 中）。 `--repo` 和 `--local` 仅接受存储库可以覆盖的设置——请参阅 [GitHub Copilot CLI 配置目录](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#repository-settings-githubcopilotsettingsjson)。 运行 `copilot help config` 以查看可用设置。 ### 使用 `copilot instruction` 运行 `copilot instruction list` 以非交互方式列出在当前工作目录中发现的自定义指令源。 这将取代已停用的 `copilot plugins list --kind instruction`。 ```bash copilot instruction list copilot instruction list --json ``` | 选项 | 说明 | | | ------------------------ | ----------------------------------- | ----------------------------------------- | | `--json` | 发出 JSON 而不是文本。 | | | `--config-dir=DIRECTORY` | 配置目录的路径。 此选项已弃用。 改用 `COPILOT_HOME`。 | | 每个 `--json` 条目的形式为 `{ id, label, description?, location, type, sourcePath, defaultDisabled, applyTo? }`。 此列表仅根据你的全局用户设置解析插件提供的指令——即使当前活动会话正在应用这些指令，由受信任的存储库或受管理的设置启用的指令也可能不会显示在此处。 ### 使用 `copilot lsp` 运行 `copilot lsp list` 以非交互方式列出已配置的语言服务器。 这将取代已停用的 `copilot plugins list --kind lsp`。 此命令仅检查; `/lsp` 在交互式会话中使用斜杠命令启动、停止或重新加载语言服务器。 ```bash copilot lsp list copilot lsp list --json ``` | 选项 | 说明 | | | ------------------------ | ----------------------------------- | ----------------------------------------- | | `--json` | 发出 JSON 而不是文本。 | | | `--config-dir=DIRECTORY` | 配置目录的路径。 此选项已弃用。 改用 `COPILOT_HOME`。 | | 每个 `--json` 条目的形式为 `{ id, fileExtensions?, sourcePlugin? }`。 自定义智能体和会话作用域钩子不在 `copilot instruction`、`copilot lsp`、`copilot plugin`、`copilot mcp` 或 `copilot skill` 的涵盖范围内。 所有这些都需要实时会话。 ### 使用 `copilot workflow run` 运行扩展提供的动态工作流，而无需打开交互式会话： ```shell copy copilot workflow run WORKFLOW-NAME [OPTIONS] ``` `WORKFLOW-NAME` 是扩展注册的名称，而不是扩展文件的路径。 该命令启动运行并等待它完成、暂停或其他停止。 | 选项 | 说明 | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | `--args JSON` 或 `--args @PATH` | 提供工作流的输入。 将此处的“JSON”替换为内联 JSON，或将“PATH”替换为 UTF-8 JSON 文件的路径。 省略时，默认为 `{}`。 接受的输入取决于工作流。 | | `--result-file PATH` | 将返回的值作为 JSON 写入文件，而不是将其包含在标准输出中。 仅在工作流完成并返回结果时写入。 只有在成功写入新结果后，才会替换现有文件。 | | `-s`、`--silent` | 取消进度输出。 除非定向到文件，否则仍会发出最终结果。 错误和状态诊断可能仍显示在标准错误上。 | | `--output-format FORMAT` | 将标准输出格式设置为 `text` （默认值）或 `json` （JSONL，每行一条 JSON 记录）。 结合`json``--silent`以仅接收最终工作流记录。 不更改 . 的 `--result-file`JSON 格式。 | 从工作目录中解析相对自变量文件和结果文件路径。 如果没有 `--silent`，输出包括工作流报告的阶段和进度消息。 该命令使用 CLI 的身份验证、模型、权限和沙盒设置。 权限选项，例如 `--allow-tool` 并 `--allow-url` 应用于工作流的代理。 它不显示权限审批提示。 提示和会话模式选项不能与此命令结合使用。 示例包括 `-p`、 `-i`、 `--agent`、 `--fleet`、 `--autopilot`、 `--resume`和 `--continue`。 管道标准输入不用作提示或工作流参数。 有关详细信息，请参阅 [使用动态工作流](/zh/copilot/how-tos/use-copilot-agents/use-dynamic-workflows#running-a-dynamic-workflow-from-the-command-line) 和 [GitHub Copilot 命令行界面编程参考](/zh/copilot/reference/copilot-cli-reference/cli-programmatic-reference#running-dynamic-workflows)。 ### 使用 `copilot sandbox ca` 运行 `copilot sandbox ca` 以从交互式会话外部管理沙盒的代理证书颁发机构，例如，在预配没有 TTY 的托管设备时。 这反映了 `/sandbox ca` 斜杠命令（`create`、`trust`、`rotate`、`remove`），以及一个 `status` 检查。 ```bash copilot sandbox ca status copilot sandbox ca create copilot sandbox ca trust copilot sandbox ca rotate copilot sandbox ca remove ``` | 子命令 | 说明 | | ----------------------------------- | ------------------------------ | | `copilot sandbox ca status` | 在不更改任何内容的情况下报告信任状态。 | | `copilot sandbox ca create` | 根据需要创建证书颁发机构，而无需信任它。 | | `copilot sandbox ca trust [CA.PEM]` | 将颁发机构（默认值：你自己的）添加到操作系统信任存储。 | | `copilot sandbox ca rotate` | 替换证书颁发机构，保留其当前信任状态。 | | `copilot sandbox ca remove` | 从 OS 信任中删除证书颁发机构；基于捆绑包的路径仍然有效。 | 以运行 `SYSTEM` 的用户身份运行这些命令，而不是以提升权限、`root` 或 Copilot CLI 身份运行，因为证书颁发机构存储在该用户的 Copilot CLI 主目录中。 运行 `copilot sandbox ca trust --help` 以获取无人值守设置指南。 `--config-dir`（或 `COPILOT_HOME`）将这些命令的主目录设为非默认 Copilot CLI 主目录，与 CLI 的其余部分相同。 ## 会话侧边栏 会话侧边栏是一个停靠在当前对话旁边的面板，可让你快速处理本地 GitHub Copilot CLI 会话。 当边栏具有焦点时，可以使用以下键盘快捷方式。 | Shortcut | Purpose | | -------------------------------- | --------------------------------------------------------------------------------- | | ← | 在对话中，打开侧边栏并将焦点移入其中（Vim：`h`）。 | | → | 将焦点移回对话;再次按关闭边栏 （Vim： `l`） 。 | | ↑/↓ | 在侧边栏中切换会话（也可使用 `k`/`j`）。 | | 输入 | 打开所选会话并将焦点返回到对话。 | | `n` | 启动新会话。 | | `x` 两次 | 关闭所选会话。 | | → 然后 按 Tab | 从会话列表顶部， → 移动到标题按钮（**←** 关闭边栏， **+** 新会话）。 按 Tab 键可在它们之间切换。 | | `?` | 显示侧边栏帮助。 | 侧边栏还会响应鼠标操作。 | 手势 | Purpose | | ------------------------- | ------------------------------------- | | 单击会话 | 切换到该会话并返回对话。 | | 双击该会话 | 切换到该会话并停留在侧边栏中。 | | 拖动分隔符 | 调整边栏的大小。 | | 将鼠标悬停在侧边栏上并滚动 | 滚动会话列表。 | | 单击标题按钮 | | | **←** 关闭边栏， **+** 以启动新会话。 | | | 将鼠标悬停在会话右侧 | 显示关闭按钮（需要 `sidebar.showCloseButton`）。 | ### 会话状态指示器 侧边栏中的每个会话都会显示其当前状态指示器。 | 指示器 | Meaning | | ----------- | ------------------------------------------------ | | 绿色 `●` （稳定） | 会话处于空闲状态。 它正在等待下一个提示。 | | 紫色 `●`（闪烁） | 轮次处于飞行状态。 代理正在积极工作。 | | 蓝色 `●` （稳定） | 当你在另一个会话中时，代理已完成一轮交互，而你此后一直未打开该会话。 打开会话会清除此未读状态。 | | 黄色 `●` （稳定） | 代理因错误而停止，或因其他原因需要你关注。 | | 灰色 `○` （稳定） | 可恢复会话。 它已保存，但当前未运行。 | | 黄色 `!` | 会话需要权限才能继续。 | | 黄色 `?` | 会话正在等待你回答问题或做出选择。 | 上面的颜色名称是指南。 确切的色调取决于终端的配色方案以及你通过 `/theme` 设置的主题。 例如，主题 `github` 使用自己的固定颜色， `colorblind` 主题使用蓝色和黄色代替绿色和红色。 在不支持完整颜色的终端上，这些点会使用终端自身的绿色、蓝色和黄色。 上面命名的颜色与默认聊天模式相关。 计划模式和自动驾驶模式会以不同颜色显示某些点。 会话名称的文本颜色也会在这些模式下更改。 由于颜色可以随终端、主题和模式而变化，因此稳定或脉动形状以及`!``?``○`标记是最可靠的提示。 ### 会话边栏设置 `/settings sidebar`使用交互式 CLI 会话中的斜杠命令调整会话边栏的这些设置。
设置 说明 默认
sidebar.enabled 允许显示会话边栏。 开启
sidebar.showResumableSessions 侧边栏包含你可以继续的先前会话。 当设置为 off 时，仅列出活动会话。 对此设置所做的更改将在下次启动 Copilot CLI 时生效。 开启
sidebar.showHeaderButtons 显示侧边栏顶部的一排按钮，用于折叠侧边栏（←）并开始新会话（+）。 开启
sidebar.showCloseButton 作为单击 X 的替代方法，将鼠标悬停在侧栏中会话右侧会显示 关闭会话 按钮。 单击此项，然后再次单击以确认。 无论会话是否仍在运行，会话都将被永久删除。 无法恢复以这种方式删除的会话。 关闭
sidebar.hoverFocus 焦点根据鼠标指针的位置从主 CLI 选项卡更改为边栏。 关闭
sidebar.coloredHints 当边栏打开且当前对话处于聚焦状态时，以边栏的主题色显示使用边栏提示，以吸引用户注意。 关闭时，将使用与其他提示相同的颜色。 关闭边栏时，始终使用与其他提示相同的颜色。 开启
sidebar.accentActiveSession 更改侧栏中突出显示的会话选择。 开启后，你当前对话中打开的会话将被重点高亮显示。 处于关闭状态时，通过键盘的上下箭头键（或鼠标）选中的会话将获得主要高亮显示。 开启
有关会话边栏的详细信息，请参阅 [使用多个 GitHub Copilot CLI 会话](/zh/copilot/how-tos/copilot-cli/use-copilot-cli/work-with-multiple-sessions)。 ## 交互式界面中的全局快捷方式 | Shortcut | Purpose | | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `@ FILENAME` | 将文件内容包含在上下文中。 | | `# NUMBER` | 在上下文中包含 GitHub 问题或拉取请求。 | | `! COMMAND` | 在本地 shell 中执行命令，绕过 Copilot。 在空提示符下单独输入 `!` ，以按顺序输入运行多个 shell 命令的 shell 模式。 在空提示符上按 Esc 或 Ctrl+C 退出 shell 模式。 | | `$` | 在提示符处单独输入 `$`，然后按 Enter，即可将终端切换到真正的交互式 shell（Unix 上为 `$SHELL`，Windows 上为 `%COMSPEC%`），并以会话的工作目录作为当前工作目录。 与 `!` 壳模式不同，此模式会完全暂停 CLI 用户界面，因此任务控制、全屏应用、标签补全和颜色功能均可原生运行。 退出 shell（`exit`或 Unix 上的 Ctrl+D ）以返回到 CLI。 仅在真实的 TTY 上针对本地、受信任且空闲的会话生效。 可以在企业托管设置中禁用。 默认启用。 使用 `shellShortcut` 设置禁用它 - 请参阅 [GitHub Copilot CLI 配置目录](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings)。 | | `?` | 打开快速帮助（在空白提示中）。 再次按下可取消并插入字面值 `?`。 | | Esc | 取消当前操作。 双按即可中断当前运行中的回合，或在主代理空闲时停止后台代理。 在本地会话中，如果模型尚未开始回复当前轮次，那么第二次按下时，会在提示框中再次显示你的提示词，以便进行编辑。 | | Ctrl+C | 取消操作/清除输入。 按两次退出。 | | Ctrl+D | 关闭。 | | Ctrl+G | 在外部编辑器中编辑提示（`$EDITOR`）。 | | Ctrl+L | 清除屏幕。 | | Ctrl+Enter 或 Ctrl+Q | 将消息排队，以在智能体繁忙时发送。 | | Ctrl+R | 反向搜索命令历史记录。 | | Ctrl+空格 | 开启或关闭语音输入（即 Ctrl+X 然后 `v` 的别名）。 只有在终端和操作系统都能将其透传时，这才会起作用。 可能需要在 OS 或终端密钥绑定中释放此值。 可改用 `v`+，然后 | | Ctrl+V | 从剪贴板粘贴为附件。 | | AltV | 将剪贴板中的图像粘贴为附件。 | | Ctrl+然后 X`/` | 开始键入提示后，这样就可以运行斜杠命令，例如，如果要更改模型，而无需重新键入提示。 | | Ctrl+然后 X`e` | 在外部编辑器中编辑提示（`$EDITOR`）。 | | Ctrl+然后 X`b` | 将正在运行的任务或 shell 命令提升到后台。 | | Ctrl+然后 X`g` | 折叠或展开自动驾驶目标面板。 | | Ctrl+然后 X`h` | 隐藏当前会话边栏。 | | Ctrl+然后 X`o` | 从时间线打开最新的链接。 | | Ctrl+然后 X`v` | 打开或关闭语音听写。 | | Ctrl+然后 X`x` | 关闭当前会话。 | | Ctrl+Z | 将进程挂起到后台 (Unix)。 | | Shift+Enter 或 Option+Enter （Mac） / Alt+Enter （Windows/Linux） | 在输入中插入换行符。 | | Shift键+Tab键 | 在标准模式、计划和 Autopilot 模式之间循环。 | 在本地会话中，您可以将提示词、Shell 命令和受支持的斜杠命令加入队列，以便在当前任务完成后按顺序运行。 按 Ctrl+Q 在代理运行时将当前输入排入队列。 已排队的条目会显示“待处理”标签，并可在运行前逐个取消。 当提示框为空时，按 ↑ 可将最近排队的提示词或引导提示词调回提示框中，以便在重新提交前进行编辑。 当此功能可用时，“召回”提示会出现在队列旁边。 请改用 Ctrl+P，以非破坏方式浏览已提交的命令历史记录。 在本地会话中，如果某条已提交的提示对应的那一轮模型尚未开始作答，按两次 Esc 会将你的提示内容放回输入框中，并将其从对话中移除。 如果模型已经开始回答，再次按下 Esc 则会中断当前正在进行的轮次。 之后，在提示框为空时，按下 ↑ 可将提示词恢复到提示框中。 ## 交互式界面中的时间线快捷方式 | Shortcut | Purpose | | ------------------------------- | ------------------------------------------------- | | Ctrl+F | 打开时间线搜索。 | | Ctrl+O | 虽然提示输入中没有任何内容，但这会扩展 Copilot 回复时间线中的最近项目以显示更多详细信息。 | | Ctrl+E | 虽然提示输入中没有任何内容，但这会展开Copilot的响应时间轴中的所有项。 | | Ctrl+T | 在响应中展开/折叠推理显示。 | | 向上翻页/向下翻页 | 将当前时间线视图向上或向下翻动一页。 | ## 任务对话框快捷方式 当任务对话框打开时（通过 `/tasks` 打开）： | Shortcut | Purpose | | ------------------------- | -------------------------------- | | ↑/K | 将所选内容上移。 | | ↓/J | 向下移动所选内容。 | | 输入 | 查看任务详情，或“传送”至所选子智能体的会话视图中。 | | `a` | 切换显示所有嵌套子代理层级，或仅显示当前层级的任务。 | | `f` | 切换是否显示已完成的子智能体和 shell，而不仅限于活动中的。 | | X | 终止所选的活动任务。 | | R | 删除所选已完成的任务。 | | B | 将所选同步任务转为后台运行。 | | Esc | 关闭对话框（或返回列表）。 | 会生成自身嵌套子智能体的子智能体将以缩进树形结构显示；您传送到的行将高亮显示为“当前”。 当你进入子代理视图时，可以像在主会话中一样，从提示框向其发送指导消息。 ## 还原中断的会话 如果某个会话在其 CLI 进程终止时仍处于打开状态——例如因崩溃或计算机重启——那么下次启动 `copilot` 时，系统可提示恢复该会话，让您选择要恢复哪些会话，或者直接重新开始。 其代理处于某次交互进行中的会话，在恢复后会自动继续该项工作。 在重新设计其启动对话框期间，此还原行为暂时需要选择启用。 将 `COPILOT_ENABLE_INTERRUPTED_SESSION_RESTORE` 环境变量设置为 `1` 以启用此功能。 请参阅[环境变量](#environment-variables)。 ## 会话选取器快捷方式 会话选择器打开时（通过 `/resume` 或 `--continue` 打开）： | Shortcut | Purpose | | ------------------------- | ---------------------------- | | ↑/↓ | 向上或向下移动所选内容。 | | 输入 | 打开所选会话。 | | `s` | 在以下排序顺序中循环：相关性→创建时间→名称→上次使用。 | | Tab | 在本地选项卡和远程选项卡之间切换。 | | `x` | 删除所选会话。 | | Esc | 关闭选取器。 | 会话按以下模式排序： | 模式 | 说明 | | ----------- | -------------------------- | | `relevance` | 根据与当前工作目录的匹配度对会话进行排序（默认）。 | | `last used` | 最近修改的会话优先。 | | `created` | 最近创建的会话优先。 | | `name` | 按会话名称按字母顺序排列;未命名的会话将排序到末尾。 | 已在另一个窗口中打开的会话在所有非相关性排序模式下浮动到顶部。 当没有工作目录上下文可用时，将跳过 `relevance` 模式。 ## 对话前环境选择器 在新会话中发送第一条消息之前，请在空提示框中按 Ctrl+E ，选择对话将在本地计算机上或云环境中运行的位置。 发送第一条消息时，会完成环境预配。 > \[!NOTE] > 环境选取器要求您的帐户中可用云会话，这与 `--no-remote`、`--remote-export`、`--no-remote-export`、`--connect` 和 `--remote` 选项的要求相同。 请参阅 [命令行选项](#command-line-options)。 对话启动后， Ctrl+E 将恢复为其其他行为：在键入时将光标移动到行尾，或在空提示框中展开时间线中的所有项。 请参阅 [交互式界面中的导航快捷方式](#navigation-shortcuts-in-the-interactive-interface) 和 [交互式界面中的时间线快捷方式](#timeline-shortcuts-in-the-interactive-interface)。 ## 边栏和会话选项卡快捷方式 当前会话侧边栏可让你在不离开当前所在会话的情况下浏览并切换不同会话。 当提示框为空时，←/→ 会在三种焦点状态间循环切换：关闭、焦点位于时间线，以及焦点位于侧边栏。 通过 `sidebar` 设置可完全禁用侧边栏——请参阅 [GitHub Copilot CLI 配置目录](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings)。 | Shortcut | Purpose | | ---------------------------------------------- | ---------------------------- | | ← （当前选项卡，已关闭） | 打开侧边栏；时间线保持焦点。 | | ←（以时间线为重点） | 将焦点移动到侧栏中。 | | →（焦点位于侧边栏） | 将焦点返回到时间线。 | | → （以时间线为重点） | 关闭边栏。 | | Tab/Shift+Tab | 切换选项卡（**当前**、 **会话**等）。 | | ↑/↓ （侧边栏聚焦） | 移动选择光标; `j`/`k` 是别名。 | | Enter （侧边栏聚焦） | 将前台会话切换到所选卡片。 | | `n` （侧边栏聚焦） | 生成新的后台会话并将其引入前台。 | | `s` （侧边栏聚焦） | 循环切换排序顺序：最近 → 创建时间 → 名称 → 无。 | | `x`， `x` （侧边栏聚焦） | 关闭所选卡片（一个击键，在关闭前显示为红色）。 | 可以拖动边栏的分隔线来调整其大小，并自动折叠到最小可用宽度以下。 每张卡片都会显示一个状态圆点、会话名称，以及其 Git 分支（如果没有分支，则显示工作目录）。 前景会话的标题以主题色突出显示，其卡片具有持久的微妙填充。 点表示会话的状态。 有关每个点的含义，请参阅 [会话状态指示器](#session-status-indicators)。 当前排序顺序（`recent`、`created`、`name`，或表示插入顺序的 `none`）在重启后仍会保留。 鼠标操作与键盘操作对应：单击卡片可切换前台会话，双击卡片或轨道空白区域可聚焦侧栏；当侧栏获得焦点时，单击时间线窗格可将焦点移回时间线。 “ **会话** ”选项卡列出了当前会话以及“可恢复”分隔符下的完整可恢复会话历史记录： | Shortcut | Purpose | | ------------------------------------------ | --------------------------------------------------------------------------- | | ↑/↓ | 浏览各行。 | | Shift+↑/↓ | 向上或向下翻页。 | | 输入 | 恢复所选会话。 | | `n` | 启动新会话。 | | `a` | 循环筛选范围：所有→本地→远程（云）。 | | `/` | 跨名称、分支或工作目录、存储库和会话 ID 实时搜索。 | | `x`、`x` | 关闭或删除所选行（进入单键触发状态；执行前会显示为红色）；Ctrl+`x` 然后 仍可作为双键别名使用。 | | ←/→ | 切换选项卡。 | **“会话**”选项卡中的远程（云）行还会显示联机或脱机状态和存储库。 在一行上按 `x` 两次会关闭正在运行的会话，或者对于本地可恢复行，将永久删除该会话的存储历史记录。 按下 Esc、按下任何其他键、移动高亮，或等待超时，都会取消等待确认的操作。 ## 差异模式快捷键 当打开差异模式时（通过 `/diff` 进入）： | Shortcut | Purpose | | --------------------------------------------- | ----------------- | | ↑ / `k` | 将所选内容向上移动一行。 | | ↓ / `j` | 将所选内容向下移动一行。 | | ← / `h` | 跳转到上一个文件。 | | → / `l` | 跳转到下一个文件。 | | 家 / `g` | 跳到第一行。 | | 结束 / `G` | 跳到最后一行。 | | 向上翻页 | 向上滚动一页。 | | 向下翻页 | 向下滚动一页。 | | Ctrl+U | 向上滚动半页。 | | Ctrl+D | 向下滚动半页。 | | `Click` | 选择点击的差异行（需要鼠标支持）。 | | 鼠标滚动 | 向上或向下滚动。 | | Alt/Option+滚动 | 每次滚动一行，以实现更精细的控制。 | | `c` | 在所选行上添加或编辑批注。 | | `s` | 显示批注摘要（当存在批注时）。 | | `b` | 在未暂存更改和分支差异之间切换。 | | `w` | 切换是否隐藏仅空白字符的更改。 | | 输入 | 提交所有注释（如果存在批注）。 | | `r` | 刷新差异（仅限远程会话）。 | | Esc / Ctrl+C | 退出差异模式。 | ## 交互式界面中的导航快捷方式 | Shortcut | Purpose | | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | Ctrl+A | 移动到行首（输入时）。 | | Ctrl+B | 移到上一个字符。 | | Ctrl+E | 移动到行的末尾（键入时）。 | | Ctrl+F | 移动到下一个字符。 | | Ctrl+H | 删除上一个字符。 | | Ctrl+K | 从光标删除到行尾。 如果光标位于行的末尾，请删除换行符。 | | Ctrl+U | 从光标删除到行首。 | | Ctrl+W | 删除上一个单词。 | | 主页 | 跳转至当前可视化行首。 | | 结束 | 跳转至当前可视化行尾。 | | Ctrl+主页 | 移动到文本的开头。 | | Ctrl+结束 | 移动到文本的末尾。 | | Alt+←/→ （Windows/Linux）
选项+←/→ （Mac） | 按单词移动光标。 | | ↑/↓ | 浏览命令历史。 当提示框为空时，↑会改为调出最近加入队列的提示或引导提示（如果有）。 | | Ctrl+P | 以非破坏性的方式浏览已提交的命令历史记录，而不触发排队提示符召回行为。 | | Tab键 / Ctrl+Y | 接受当前的内联补全建议。 | ## 交互式接口中的斜杠命令 这些是在交互式 CLI 会话中可以使用的斜杠命令。 这些斜杠命令的子集可供通过其 ACP 服务器使用 CLI 的客户端使用。 有关详细信息，请参阅“[Copilot CLI ACP 服务器](/zh/copilot/reference/copilot-cli-reference/acp-server)”。 | 命令 | Purpose | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/add-dir PATH` | 允许文件访问某个目录，并将其 `.github/skills` 和 `.github/agents` 加载为受信任配置。 | | `/after [DELAY PROMPT]`、`/after` | 为当前会话安排一个仅执行一次的提示、技能或可安排执行的斜杠命令（例如 `/after 30m remind me the time` 或 `/after 1h /chronicle standup`）。 在没有参数的情况下，将显示计划管理器。 仅在实验模式下可用。 | | `/agent` | 浏览并选择可用代理（如果有）。 请参阅“[关于自定义代理](/zh/copilot/concepts/agents/copilot-cli/about-custom-agents)”。 | | `/app` | 在 GitHub Copilot app 中打开当前会话（需要 1.1.3 或更高版本），如果未安装该应用，则显示下载链接。 | | `/ask QUESTION`、`/btw QUESTION` | 在不添加到对话历史记录的情况下提出一个快速的附带问题。 请参阅“[在 中提出一个附带问题](/zh/copilot/how-tos/copilot-cli/use-copilot-cli/ask-a-side-question)”。 | | `/allow-all [off\|auto\|show]`、`/yolo [off\|auto\|show]` | 启用所有权限（工具、路径和 URL）。 这是 `/permissions allow-all` 的别名；请参阅 `/permissions` 所在的行，了解其规范命令及其子命令。 | | `/autopilot [OBJECTIVE]`、`/goal [OBJECTIVE]` | 启动或重新聚焦自动驾驶模式，并可选择指定明确目标（例如，`/goal Refactor the auth module`）。 如果没有目标，Autopilot 会从上下文推断意向，状态面板将显示最后一个提示作为推断目标。 您可以使用 `/goal Refactor the auth module --max-ai-credits 5` 为目标设置 AI 积分支出上限（例如，`--max-ai-credits N`）。 达到上限后，Autopilot 会暂停并打开一个面板，报告针对上限使用的信用额度。 输入新金额以使用新的信用额度窗口恢复，或关闭面板以保持暂停状态。 还可以自行恢复暂停的目标，而无需面板，方法是自行运行选项，而不使用客观文本，例如 `/goal --max-ai-credits 5`。 这与面板执行的操作相同：它会打开一个新的窗口，其中包含您指定的积分（完整的新的上限，而非增量），并继续执行目标。 `/goal on` 和 `/goal off` 用于切换自动驾驶模式，无需设置目标，且不支持 `--max-ai-credits`。 当前目标会显示为提示输入框上方的置顶面板，其中显示目标内容、已用积分和待办事项进度。 面板会在短终端高度不足 30 行时自动折叠为单个标识行，并在超过该阈值时展开；按 Ctrl+X，然后按 `g`，即可手动替代自动大小调整。 | | `/changelog [summarize] [VERSION\|last N\|since VERSION]`、`/release-notes [summarize] [VERSION\|last N\|since VERSION]` | 显示 CLI 更改日志。 可选地指定一个版本、最近发布的版本数量或起始版本。 请为 AI 生成的摘要添加关键字 `summarize` 。 | | `/chronicle ` | 会话历史工具和分析。 | | `skills` 子命令用于起草、审查和跟踪根据观察到的使用情况生成的仓库技能提案的状态。 请参阅“[使用 GitHub Copilot CLI 会话数据](/zh/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle#using-the-chronicle-slash-command)”。 | | | `/clear [PROMPT]`、`/new [PROMPT]`、`/reset [PROMPT]` | 启动新对话。 `/new worktree` 在新 Git 工作树中启动空会话，而不是清除当前会话，使当前会话及其工作目录保持不变。 | | `/clikit [COMPONENT]` | 预览 CLI 业务组件（例如配额信息）。 | | `/collect-debug-logs [file\|gist\|share] [PATH]` | 将调试日志收集到存档、 GitHub gist 或将其上传到 GitHub （`share`）。 请参阅 [收集和共享调试日志](#collecting-and-sharing-debug-logs)。 | | `/compact [FOCUS-INSTRUCTIONS]` | 汇总对话历史记录以减少上下文窗口使用情况。 （可选）提供焦点说明来引导摘要，例如 `/compact focus on the auth module`。 请参阅“[在 GitHub Copilot CLI 中管理上下文](/zh/copilot/concepts/agents/copilot-cli/context-management#compaction)”。 | | `/context` | 显示上下文窗口令牌使用情况和可视化效果。 请参阅“[在 GitHub Copilot CLI 中管理上下文](/zh/copilot/concepts/agents/copilot-cli/context-management#checking-your-context-usage)”。 | | `/copy` | 将最后一个响应复制到剪贴板。 | | `/cwd`、`/cd [PATH]` | 更改工作目录或显示当前目录。 | | `/delegate [PROMPT]` | 使用 AI 生成的拉取请求提交更改到远程存储库。 请参阅“[将任务委派给 Copilot](/zh/copilot/how-tos/copilot-cli/use-copilot-cli/delegate-tasks-to-cca)”。 | | `/diagnose [PROMPT]`、`/diagnose` | 分析当前会话日志中出现的错误、意外行为和其他问题。 （可选）包括自定义提示，以便将诊断重点放在特定问题上。 | | `/diff` | 查看当前目录中的更改；当工作树干净时自动切换到分支差异（实验性）。 | | `/downgrade VERSION` | 下载并重启到特定 CLI 版本。 可用于团队帐户。 | | `/env` | 显示加载的环境详细信息（说明、MCP 服务器、技能、代理、挂钩、插件、LSP、扩展）。 | | `/every [INTERVAL] PROMPT`、`/every` | 为当前会话安排周期性提示、技能或可安排的斜杠命令（例如 `/every 1h run tests` 或 `/every 1d /chronicle standup`）。 在没有参数的情况下，将显示计划管理器。 仅在实验模式下可用。 | | `/exit`、`/quit` | 关闭当前会话。 如果还有其他会话正在运行，此操作会将最新的剩余会话置于前台，而不是退出。 仅当它是最后一个打开的会话时，才会退出 CLI。 `/exit print` 始终会关闭 CLI 并提示是否导出对话记录。 `/exit` 和 `/quit`（包括其 `print` 变体）也可以在代理运行期间通过 Ctrl+Q 加入队列——CLI 会在当前轮次以及排在它前面的任何已排队 shell 命令完成后关闭会话。 | | `/extensions [manage\|mode]`、`/extension` | 管理 CLI 扩展。 仅在实验模式下可用。 | | `/experimental [on\|off\|show]` | 切换、设置或显示实验性功能。 | | `/feedback`、`/bug` | 提供有关 CLI 的反馈。 可以提供反馈并附带日志的方式；请参阅 [收集和共享调试日志](#collecting-and-sharing-debug-logs)。 | | `/fleet [PROMPT]` | 支持对任务的某些部分进行并行子代理执行。 请参阅“[使用 \`/fleet\` 命令并行运行任务](/zh/copilot/concepts/agents/copilot-cli/fleet)”。 | | `/help` | 显示交互式命令的帮助。 | | `/ide` | 连接到 IDE 工作区。 请参阅“[连接GitHub Copilot CLI到VS Code](/zh/copilot/how-tos/copilot-cli/use-copilot-cli/connecting-vs-code#managing-the-connection-with-the-ide-slash-command)”。 | | `/init` | 初始化此存储库的 Copilot 自定义说明和智能体功能。 请参阅 [项目初始化Copilot](#project-initialization-for-copilot)。 | | `/instructions` | 查看和切换自定义指令文件。 | | `/keep-alive [on\|off\|busy\|DURATION]`、`/caffeinate [on\|off\|busy\|DURATION]` | 防止计算机进入睡眠状态：当命令行界面（CLI）会话处于活动状态，或者软件代理繁忙，或者在设定的时间段内。 接受持续时间，例如`30`、`30m`、`2h`、`1d`（裸数默认为分钟）。 | | `/limits` | 打开交互式响应限制对话框。 | | `/limits set max-ai-credits VALUE` | 为每个响应允许的 AI 信用额度设置软最大值。 响应限制是针对每个用户消息重置的软限制。 请参阅“[在 AI credit 中设置 GitHub Copilot CLI 会话限制](/zh/copilot/how-tos/copilot-cli/use-copilot-cli/set-session-limit)”。 | | `/limits unset [max-ai-credits\|all]` | 删除特定的响应限制或所有响应限制。 | | `/list-dirs` | 显示允许访问文件的所有目录。 | | `/login` | 登录到 Copilot。 | | `/logout` | 注销 Copilot。 | | `/lsp [show\|test\|reload\|logs\|help] [SERVER-NAME]` | 管理语言服务器配置。 子 `logs` 命令打开实时 LSP 服务日志面板。 | | `/mcp [config\|list\|show\|add\|edit\|delete\|disable\|enable\|auth\|reload\|search] [SERVER-NAME]` | 管理 MCP 服务器配置。 如果不带子命令，或者使用 `config`，插件仪表板打开时会固定在 MCP 服务器列表；添加、编辑和身份验证表单也会在该仪表板内打开，因此关闭表单后会返回服务器列表。 使用 `show` 或 `show SERVER-NAME` 显示所有配置的服务器或直接打开一个服务器的详细信息，包括其可用工具，以及启用或禁用它。 对于插件提供的服务器，`show SERVER-NAME`还显示源属性（例如）。 `Source: Plugin my-plugin (1.2.0)` | | `list` （别名 `ls`）打印具有连接状态和实时状态的已配置服务器的纯文本列表。 单独使用的 `/mcp`、`config`、`show` 和 `list`（别名为 `ls`）要么是只读操作，要么会打开仪表板，因此即使代理正忙于处理一轮交互，它们也可以运行。 会更改状态的子命令（`add`、`delete`、`edit`、`disable`、`enable`、`auth`、`reload` 和 `search`）在该轮结束前将被阻止执行。 | | | `edit ` 会拒绝来自工作区的服务器（即在仓库的 `.mcp.json` 中定义的服务器），而不是打开用户级向导，因为保存时会在未提示的情况下创建一个同名的用户条目，但该条目仍会被工作区中的条目遮蔽。 错误信息直接给出了要编辑的文件名。 当被要求移除来自工作区的服务器时，`delete ` 会报告同一个文件。 沙盒化的本地服务器显示为 `connected (sandboxed)` 状态。 请参阅“[为 GitHub Copilot CLI 添加 MCP 服务器](/zh/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers#managing-mcp-servers)”。 | | | `/model [--session\|--global\|--repo\|--local] [MODEL\|auto TIER]`、`/models` | 选择要使用的 AI 模型，或选择 **自动**。默认情况下（或者使用 `--session`，别名为 `-s` 时），仅更改当前会话的模型、推理强度或上下文窗口，不会更改已保存的设置。 `--repo`/`--local` 而是在存储库设置中固定默认模型; `--global` （或 `/config model`） 设置将来会话的默认值。 在具有长上下文变体的模型上按 Tab ，在默认窗口和长上下文窗口之间切换其上下文列。 选择器会将模型分到不同分区中——按 Shift+Tab 可在推荐分组（最近使用、推荐、新增和其他模型）、提供方和类别之间循环切换分组方式。 具有特定于供应商的数据保留条款的模型显示数据保留警告横幅，其中包含供应商策略的链接。 可在轮次处理中使用：在代理运行期间提出的更改请求会作为可取消的（Ctrl+C）命令加入队列，并在当前轮次结束后生效，而不是在请求处理中途切换当前实时模型。 使用 `/model auto TIER`（`efficiency`、`balance` 或 `intelligence`）可直接选择特定的自动路由层级，包括通过自动层级推荐提示上的“切换”操作进行选择。 当自动选取模型时，时间线会显示该选择的原因，只要 API 提供原因。 请参阅“[关于 Copilotauto model selection](/zh/copilot/concepts/models/auto-model-selection)”。 | | `/permissions [default\|assisted\|allow-all\|show]` | 在权限模式（`default`、、 `assisted`或 `allow-all`）之间切换，或显示当前模式（`show`）。 这是权限模式更改的规范命令; `/allow-all` 并 `/yolo` 保留为别名。 | | `/permissions reset` | 重置当前会话中所有内存中的工具和路径授权（下次使用时再次提示）。 | | `/plan [PROMPT]` | 在编码之前创建实现计划。 | | `/plugin` | 打开插件仪表板，其中显示您已安装的插件。 选择插件并按 Enter 了解其详细信息以及启用、禁用、更新或卸载插件等操作。 使用 ← 和 → 密钥在 **“已安装**”、“ **联机**”和 **“市场** ”视图之间切换。 仪表板仅显示插件；MCP 服务器请使用 `/mcp`，技能请使用 `/skills`。 请参阅“[关于 GitHub Copilot 插件](/zh/copilot/concepts/agents/about-plugins)”。 | | `/plugin install SOURCE` | 从市场规范、GitHub 仓库、git URL 或本地路径安装插件。 | | `/plugin update PLUGIN[@MARKETPLACE]` | 更新已安装的插件。 | | `/plugin uninstall PLUGIN[@MARKETPLACE]`（别名 `remove`、`rm`） | 卸载插件。 | | `/plugin list` （别名 `ls`） | 列出已安装的插件。 | | `/plugin marketplace add SOURCE` | 添加应用市场。 | | `/plugin marketplace remove NAME` | 移除商城。 | | `/plugin marketplace list` | 列出已注册的市场。 | | `/plugin marketplace browse NAME` | 在应用市场中浏览插件。 | | `/plugin marketplace update [NAME]` （别名 `refresh`） | 重新获取某个应用市场的插件目录；如果未指定名称，则重新获取所有已注册应用市场的插件目录。 | | `/pr [view\|create\|fix\|auto\|automerge]` | 管理当前分支的拉取请求。 | | `auto` 将拉取请求驱动为绿色并停止; `automerge` （别名： `agentmerge`） 将拉取请求驱动为绿色并合并请求。 如果存储库具有拉取请求模板（`.github/pull_request_template.md` 或下面的 `.github/PULL_REQUEST_TEMPLATE/`文件）， `create` 则默认遵循该模板，保留标题、批注和清单项，并填写准确的详细信息，而不是编写通用正文。 如果你不想应用该模板，请让 Copilot 跳过它。 请参阅“[使用 /pr 命令管理拉取请求](/zh/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests)”。 | | | `/refine TEXT` | 将大致撰写的提示重写为明确的提示以供审阅。 不带参数运行（通过 Ctrl+X 然后 `/refine`），以清理当前输入框。 对于通过语音输入的提示词尤其有用。 | | `/remote [on\|off]` | 显示远程控制状态（如果未提供任何参数）、启用远程转向（`on`）或结束远程连接（`off`）。 请参阅“[通过其他设备控制 GitHub Copilot CLI 会话](/zh/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely)”。 | | `/rename [NAME]` | 重命名当前会话（如果省略，将自动生成名称；这是`/session rename`的别名）。 | | `/research TOPIC` | 使用 GitHub 搜索和 Web 源进行深入调查。 请参阅“[使用GitHub Copilot CLI进行研究](/zh/copilot/concepts/agents/copilot-cli/research)”。 | | `/reset-allowed-tools` | 重置允许的工具列表。 | | `/restart` | 重启 CLI，还原当前进程的所有实时会话，而不仅仅是前台会话。 如果目标 CLI 版本无法还原多个会话，系统会提示你仅继续使用前台会话或取消。 | | `/resume [SESSION-ID]`、`/continue [SESSION-ID]` | 通过从列表中选择（可选指定会话 ID）切换到其他会话。 | | `/review [PROMPT]` | 运行代码评审代理以分析更改。 请参阅“[使用 GitHub Copilot CLI 请求代码评审](/zh/copilot/how-tos/copilot-cli/use-copilot-cli/agentic-code-review)”。 | | `/rubber-duck [PROMPT]` | 咨询橡皮鸭智能体，以获取关于计划、代码和测试的第二种意见。 请参阅“[关于橡皮鸭智能体](/zh/copilot/concepts/agents/copilot-cli/rubber-duck)”。 | | `/sandbox [config\|status\|policy [COMMAND]\|enable\|disable]` | 管理文件系统和网络访问的沙盒限制。 | | `config`（或仅 `/sandbox`）打开设置对话框。 | | | `status` 显示是否为当前会话启用了沙盒。 启用沙盒后， `policy` 显示按源和访问类型、网络设置、开发人员工具访问和沙盒功能分组的路径授予和限制。 （可选）添加命令，例如 `/sandbox policy npm install`，在不运行命令的情况下检查其开发人员工具访问权限。 | | | `enable` 和 `disable` 通常会更新您保存的设置。 如果你的组织要求启用沙盒隔离，除非允许绕过，否则将拒绝 `disable`。 在这种情况下，禁用仅适用于当前会话。 | | | `/sandbox ca [create\|trust\|rotate\|remove]` | 管理沙盒的代理证书颁发机构。 | | `create` 在不信任它的情况下写入。 | | | `trust` 会将其添加到 OS 信任存储。 | | | `rotate` 在保留其信任状态的同时替换它。 | | | `remove` 移除 OS 信任。 请参阅[使用`copilot sandbox ca`](#using-copilot-sandbox-ca)在会话外运行相同的操作，例如在托管设备上运行。 | | | `/search [QUERY]`、`/find [QUERY]` | 搜索对话时间线。 | | `/security-review [PROMPT]` | 对当前本地代码改动进行有针对性的安全审查，并返回按优先级排序的漏洞发现及修复建议。 此命令不是完整的存储库安全审核。 | | `/session [info\|checkpoints [n]\|files\|plan\|rename [NAME]\|cleanup\|prune\|delete [ID]\|delete-all]`、`/sessions [info\|checkpoints [n]\|files\|plan\|rename [NAME]\|cleanup\|prune\|delete [ID]\|delete-all]` | 显示会话信息和管理会话。 子 `info` 命令显示会话详细信息，包括会话链接（如果可用）。 子命令：`info`、、、`checkpoints`、`files``plan``rename``cleanup`、`prune`、。 `delete``delete-all` | | `/settings [--repo\|--local] [show KEY\|KEY\|KEY VALUE]`,
`/config [--repo\|--local] [show KEY\|KEY\|KEY VALUE]` | 打开设置对话框，打开时将焦点置于特定设置上（`KEY`），以内联方式设置某项设置（`KEY VALUE`），或显示某项设置的当前值（`show KEY`）。 `show` 会屏蔽名为“secret”的值（例如，嵌套在设置下的令牌或 API 密钥），而不是以明文形式显示它们。 对话框显示 **用户**、**仓库**、**仓库（本地）** 和 **问题** 标签页 — 使用 Tab/ 进行切换 Shift+Tab 切换；在另一个作用域中被覆盖的设置会显示一个标记，注明哪个作用域的设置生效。 **问题**选项卡是一个显示需要关注的设置的跨作用域视图（例如，未知或无效的键）；当任一作用域存在问题时，其标签会显示计数，例如 `Problems (2)`，否则仅显示 `Problems`。 将 `--repo` 或 `--local` 添加到目标 `.github/copilot/settings.json` 或 `.github/copilot/settings.local.json` 中，而不是添加到用户设置文件中——例如 `/settings --repo model gpt-6-astra`。 只有[可由仓库覆盖的键](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#repository-settings-githubcopilotsettingsjson)才能通过此方式设置。 受有效组织或 MDM 管理策略约束的行会显示为只读，并带有 `(managed)` 标记。 请参阅“[使用 \`/settings\` 命令更改设置](/zh/copilot/how-tos/copilot-cli/customize-copilot/change-settings)”。 | | `/share [link\|off\|file\|html\|gist\|research] [...]`、`/export [...]` | 共享当前会话。 未指定子命令时，如果你已登录并完成同步，则会生成可共享的 GitHub 链接（否则会退回为 Markdown 文件导出）。 `off` 停止共享。 `link` 是默认链接流的显式别名; `link off` 停止链接共享。 `file [session\|research] [PATH]` 导出为 Markdown 文件。 `html [session\|research] [PATH]` 导出到 HTML 文件。 `gist [session\|research]` 创建 GitHub gist。 `research [PATH]` 导出研究报告。 | | `/skills` | 打开“技能”选项卡上的插件仪表板。 | | `/skills list` | 列出所有可用的技能。 | | `/skills info NAME` | 显示特定技能的详细信息。 | | `/skills add [--project] ` | 从文件、URL 或目录添加技能；`--project` 会将文件或 URL 安装的范围限定到此存储库，而不是你的用户帐户。 | | `/skills remove ` | 按名称删除技能，或取消注册自定义技能目录。 | | `/skills reload` | 从所有目录重新加载技能。 请参阅“[为 GitHub Copilot CLI 添加代理技能](/zh/copilot/how-tos/copilot-cli/customize-copilot/add-skills)”。 | | `/statusline`、`/footer` | 配置状态行中显示的项。 | | `/subagents`、`/agents` | 配置默认子代理模型和每个代理的子代理模型。 对于具有 `modelPolicy: "required"` 的代理，无论该项是在代理自身定义中设置，还是在 `subagents` 设置覆盖中设置，选择器都会显示一个已锁定的 **模型** 条目，以及一行 **模型强制**，其内容为“必需 - 无法覆盖”（如果策略是由代理定义本身设置，则显示“由代理定义要求”）。 将策略从选取器切换回 `"preferred"` 以允许再次替代，除非代理定义需要它。 请参阅“[GitHub Copilot CLI 配置目录](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings)”。 | | `/tasks` | 查看和管理任务（子代理和 shell 命令）。 | | `/terminal-setup` | 为多行输入支持配置终端（Shift+Enter 和 Ctrl+Enter）。 | | `/theme [default\|github\|dim\|high-contrast\|colorblind]` | 查看或设置颜色模式。 | | `/tuikit [colors\|icons\|select\|tabbar]` | 预览 TUIkit 设计系统组件和颜色令牌。 | | `/undo`、`/rewind` | 打开回溯选择器，将会话回滚到较早的用户操作。 请选择：**仅对话**（回退对话，文件保持原样）或 **对话 + 文件**（同时将该轮次以及之后被放弃的轮次中更改过的文件 Copilot 恢复到更改前的内容，但会跳过此后你自行编辑过的文件）。 文件更改是跨编辑工具、shell 命令和子代理的轮次跟踪的，因此不需要 Git。 | | `/update`、`/upgrade` | 将 CLI 更新到最新版本。 | | `/usage` | 显示会话使用情况指标和统计信息，包括每模型令牌总计。 对于基于令牌计费的账户，每个模型所在的行还会显示各自的 AI credit 用量（例如，`1 AIC`）。 没有令牌计数的计费模型仅显示额度。 | | `/user [show\|list\|switch]` | 管理已登录账户。 | | `/version` | 显示版本信息并检查更新。 | | `/vim` | 切换提示框的 Vim 模式，启用 Vim 风格的模态编辑：移动命令（例如 `hjkl`、`$`、`0`、`w`、`G`、`gg`、`e`、`b`）、字符搜索（`f``t`//`T``F`/`,`/`;`/）、插入命令（`o`//`a``i`）、编辑命令（`y`//`~``J`//`c``d`//）、运算符（/`r``D``C``x`）、复制与粘贴（`.``y`/`p`/）、重复操作（`P`）、撤销和重做（`u`/Ctrl+R）、计数前缀，以及按 Esc 返回普通模式。 还可以通过 `editorMode` 设置进行配置。 请参阅“[GitHub Copilot CLI 配置目录](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#user-settings-copilotsettingsjson)”。 | | `/voice [on\|off\|models\|devices]` | 切换语音模式、浏览可用的语音模型或选择输入设备（麦克风）。 | | `/workflows` | 查看工作流运行、阶段、智能体和进度。 需要基于令牌的计费计划。 请参阅 [使用 `copilot workflow run`](#using-copilot-workflow-run) 直接运行已注册的工作流。 | | `/fork [NAME]`、`/branch [NAME]` | 将当前会话复制到新会话中，并可选择为其命名。 在代理运行期间仍可使用——源会话会继续在后台运行。 `/fork worktree` 会复刻当前会话，保留其对话上下文，并在从 `HEAD` 分出的新 Git 工作树中创建该会话。 | | `/worktree [branch\|task]` | 创建新的 Git 工作区副本并切换到该工作区副本，同时将未提交的更改留在当前工作区中。 传入分支名称、任务描述（支持多行，用作新工作树中的初始提示），或者省略该参数，以根据对话自动生成分支名称。 默认情况下，从当前检出分支进行分支（`HEAD`）；将 `worktreeBaseRef` 设置设为 `"defaultBranch"` 即可改为从远程默认分支进行分支。 请参阅“[GitHub Copilot CLI 配置目录](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#user-settings-copilotsettingsjson)”。 需要 Git 存储库。 | | `/worktree new [PROMPT]` | 已弃用 - 请改用 `/new worktree` 。 在新的 Git 工作树中启动新对话，使当前对话及其工作目录保持不变。 （可选）提供第一个提示。 | | `new` 保留为子命令关键字，不能用作文本分支名称。 遵循与 `/worktree` 相同的 `worktreeBaseRef` 设置。 | | | `/move [branch\|task]` | 将未提交的更改移动到新的 Git 工作树并切换到它。 传入分支名称、任务描述（支持多行，用作新工作树中的初始提示），或者省略该参数，以根据对话自动生成分支名称。 需要 Git 存储库。 | 要获取所有可用的斜杠命令的完整列表，请在 CLI 的交互式界面中输入 `/help`。 在通过单独按下 `/every` 或 `/after` 打开的计划管理器中，使用 ↑/↓ 选择一个条目，并按 `x` 将其删除。 仅可通过在提示符下使用 `/every` 或 `/after` 并带参数来添加计划任务 — 对话框本身仅支持读取和删除操作。 只要该会话存在活动计划，页脚就会默认显示“已计划 N 项”指示器，即使系统尚未为你启用 `/every` 和 `/after`。 `/plugin` 会在上游有可用新版本时提示已安装的插件或市场项，并在仪表板中提供 **更新** 操作。 `/mcp list` / `ls` 和 `/plugin list`/`ls`（包括裸 `/plugin`）均为只读，并且可以在智能体忙于处理一轮对话时运行。 所有其他 `/mcp` 命令和 `/plugin` 子命令都会被阻止，直到轮次完成。 > \[!NOTE] > 实验性 `/plugins` 命令已被移除。 其资源已被转移到 `/plugin`， `/mcp`以及 `/skills`。 使用 `/subagents` 和 `/instructions` 用于代理和说明。 ### 收集和共享调试日志 用于 `/collect-debug-logs [file|gist|share] [PATH]` 收集调试日志进行故障排除： | 目标 | 说明 | | ------- | ------------------------------------------ | | `file` | 将日志保存到位于 `PATH` 的本地存档（省略 `PATH` 时使用的默认位置）。 | | `gist` | 将日志上传到机密 GitHub gist。 | | `share` | 保存本地存档，然后将其上传到 GitHub。 | `/collect-debug-logs share`，以及从 `/feedback` 提供的附带日志的反馈流程，首先保存本地存档，然后在上传到 \*\*\*\* 之前请求新的同意（默认为 GitHub）。 上传目前仅适用于 GitHub 员工和内部用户，但尚未正式发布。 在 GitHub 之外的用户继续使用现有的存档和 gist 路由，以及现有的公共反馈路由。 ## 命令行选项 | 选项 | Purpose | | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- | | `--add-dir=PATH` | 允许访问某个目录中的文件，并将其 `.github/skills` 和 `.github/agents` 加载为受信任的配置（可多次使用）。 无论选项顺序如何，相对路径都会相对于会话工作目录（即 `--resume`、`--worktree` 或 `-C` 目录）进行解析。 该路径必须是一个已存在的目录——如果路径缺失或该路径指向的是普通文件，都会导致启动立即失败，并报出与该标志相关的特定错误；在所有模式下都是如此。 | | | `--add-github-mcp-tool=TOOL` | 添加工具以启用 GitHub MCP 服务器，而不是默认 CLI 子集（可多次使用）。 将 `*` 用于所有工具。 | | | `--add-github-mcp-toolset=TOOLSET` | 添加工具集以启用 GitHub MCP 服务器，而不是默认 CLI 子集（可多次使用）。 对所有工具集使用 `all`。 | | | `--additional-mcp-config=JSON` | 仅为此会话添加 MCP 服务器。 服务器配置可以作为 JSON 字符串或文件路径（前缀） `@`提供。 无论选项的顺序如何，相对 `@file` 路径都会相对于会话工作目录（即 `--worktree`、`--resume` 或 `-C` 目录）进行解析。 从 `~/.copilot/mcp-config.json` 扩充配置。 覆盖任何已安装的同名 MCP 服务器配置。 请参阅“[为 GitHub Copilot CLI 添加 MCP 服务器](/zh/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers)”。 | | | `--agent=AGENT` | 指定要使用的值 custom agent 。 请参阅“[关于自定义代理](/zh/copilot/concepts/agents/copilot-cli/about-custom-agents)”。 | | | `--allow-all` | 启用所有权限（等效于 `--allow-all-tools --allow-all-paths --allow-all-urls`）。 | | | `--allow-all-mcp-server-instructions` | 在系统提示符中包含来自所有 MCP 服务器的初始化指令。 默认情况下，只有列入允许列表的服务器指令会预先加载；其他服务器的指令则按需获取。 | | | `--allow-all-paths` | 禁用文件路径验证并允许访问任何路径。 | | | `--allow-all-tools` | 允许所有工具在不确认的情况下自动运行。 以编程方式使用 CLI 时是必需的（env： `COPILOT_ALLOW_ALL`）。 | | | `--allow-all-urls` | 允许在没有确认的情况下访问所有 URL。 | | | `--allow-tool=TOOL ...` | CLI 有权使用的工具。 不会提示输入权限。 对于多个工具，请使用带引号的逗号分隔列表。 请参阅“[允许和拒绝工具使用](/zh/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools#allowing-or-denying-permission-for-specific-tools)”。 | | | `--allow-url=URL ...` | 允许访问特定的网址或域。 对于多个 URL，请使用带引号的逗号分隔列表。 | | | `--acp` | 以代理客户端协议服务器身份启动。 | | | `--attachment PATH` | 将文件附加到初始提示（可以多次使用）。 可以接受图像文件，但要成功发送这些文件，前提是所选模型和组织策略允许视觉输入。 | | | `--autopilot` | 启用自动驾驶连续运行模式——代理会持续运行，直到调用 `task_complete`，然后返回交互模式。 请参阅“[允许 GitHub Copilot CLI 自主工作](/zh/copilot/concepts/agents/copilot-cli/autopilot)”。 | | | `--available-tools=TOOL ...` | 只有这些工具可供模型使用。 对于多个工具，请使用带引号的逗号分隔列表。 请参阅“[允许和拒绝工具使用](/zh/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools)”。 | | | `--banner`、`--no-banner` | 显示或隐藏启动横幅。 | | | `--bash-env` | 启用 `BASH_ENV` 对 bash shell 的支持。 | | | `-C DIRECTORY` | 在执行任何其他操作之前，请更改工作目录。 | | | `--connect[=SESSION-ID]` | 直接连接到远程会话（可选）指定会话 ID 或任务 ID。 与 `--resume` 和 `--continue`. | | | `--context TIER`。 | 设置分级定价模型的上下文窗口层级（该设置将覆盖已保存的配置，并在新的交互式会话中生效）。 选项：“default”、“long\_context”。 | | | `--config-dir=DIRECTORY` | 用于设置配置目录的选项已弃用。 请改用 `COPILOT_HOME` 环境变量。 | | | `--continue` | 恢复当前工作目录中的最新会话，回退到全局最新会话。 与 `--resume` 冲突 | | | `--deny-tool=TOOL ...` | CLI 没有使用权限的工具。 不会提示输入权限。 对于多个工具，请使用带引号的逗号分隔列表。 | | | `--deny-url=URL ...` | 拒绝访问特定 URL 或域，优先于 `--allow-url`。 对于多个 URL，请使用带引号的逗号分隔列表。 | | | `--disable-builtin-mcps` | 禁用所有内置 MCP 服务器（当前： `github-mcp-server`）。 | | | `--disable-mcp-server=SERVER-NAME` | 禁用特定的 MCP 服务器（可以多次使用）。 | | | `--disallow-temp-dir` | 防止自动访问系统临时目录。 | | | `--effort=LEVEL`、`--reasoning-effort=LEVEL` | 设置推理工作量级别（`low`、、`medium``high`、`xhigh``max`）。 `max`是Anthropic模型中深度最高的层级。 | | | `--enable-all-github-mcp-tools` | 启用所有 GitHub MCP 服务器工具，而不是默认 CLI 子集。 | | | `--add-github-mcp-toolset`和`--add-github-mcp-tool`选项被覆盖。 | | | | `--enable-mcp-server=SERVER-NAME` | 为此会话重新启用在设置中禁用的 MCP 服务器（只能多次使用）。 此更改不会保存到您的配置中。 | | | `--enable-memory` | 在提示模式下启用内存（默认禁用）。 | | | `--enable-reasoning-summaries` | 已弃用的兼容性选项（已接受但忽略）。 默认情况下会显示支持 OpenAI 模型的详细推理摘要。 使用 Ctrl+T 切换它们。 | | | `--excluded-tools=TOOL ...` | 这些工具将不适用于模型。 对于多个工具，请使用带引号的逗号分隔列表。 | | | `--experimental` | 启用实验性功能（使用 `--no-experimental` 进行禁用）。 | | | `--extension-sdk-path DIRECTORY` | 使用本地 `@github/copilot-sdk` 文件夹覆盖注入到扩展子进程中的捆绑 `copilot-sdk/`。 无效路径将回退到随附的 SDK。 | | | `--fleet` | 在集群模式下运行提示词（并行子代理编排）。 与 `-i`、`-p` 或管道标准输入结合使用。 这需要由这些来源之一触发，其本身不会产生任何作用。 这相当于使用 `/fleet` 斜杠命令为交互式提示添加前缀。 使用 `-p` 或管道输入时，它会以非交互方式调度相同的机群编排。 请参阅“[使用 \`/fleet\` 命令并行运行任务](/zh/copilot/concepts/agents/copilot-cli/fleet)”。 | | | `-h`、`--help` | 显示帮助。 | | | `-i PROMPT`、`--interactive=PROMPT` | 启动交互式会话并自动执行此提示。 | | | `--log-dir=DIRECTORY` | 设置日志文件目录（默认值： `~/.copilot/logs/`）。 | | | `--log-level=LEVEL` | 设置日志级别（选项：`none`、、`error``warning`、`info`、`debug`、`all``default`）。 | | | `--max-ai-credits=CREDITS` | 为每个响应允许的 AI 信用额度设置软最大值。 该限制会在每条用户消息后重置，并且可在会话中途通过 `/limits` 进行调整。 请参阅“[在 AI credit 中设置 GitHub Copilot CLI 会话限制](/zh/copilot/how-tos/copilot-cli/use-copilot-cli/set-session-limit)”。 | | | `--max-autopilot-continues=COUNT` | Autopilot 模式下的最大延续消息数（默认值：无限制）。 必须是非负整数。 格式不正确的值（`NaN`负、小数或科学表示法）将被拒绝。 请参阅“[允许 GitHub Copilot CLI 自主工作](/zh/copilot/concepts/agents/copilot-cli/autopilot)”。 | | | `--mode=MODE` | 设置初始代理模式（选项：`interactive`、、`plan``autopilot`）。 与 `--plan --mode autopilot` 结合使用（作为 `--plan`），即可实现“先计划后自动驾驶”：会话将以计划模式启动，并在计划就绪后自动进入 Autopilot 模式，而不是等待人工批准。 拒绝任何其他 `--plan --mode MODE` 配对。 | | | `--model=MODEL` | 设置要使用的 AI 模型。 作为值传递 `auto` ，以便 Copilot 自动选取最佳可用模型。 请参阅“[关于 Copilotauto model selection](/zh/copilot/concepts/models/auto-model-selection)”。 | | | `--mouse[=VALUE]` | 在交互式界面中启用或禁用鼠标支持。 VALUE 可以是 `on` （默认值） 或 `off`。 启用后，CLI 捕获鼠标事件（滚轮、单击等）以导航其自己的界面，例如滚动时间线或单击选项卡。 禁用后，将保留终端的本机鼠标行为，例如文本选择和滚动回退。 显式设置此选项时，该值将保存到配置文件中。 | | | `-n NAME`、`--name=NAME` | 设置新会话的名称。 供 `--resume` 和 `/resume` 用于按名称查找会话。 | | | `--no-ask-user` | | | | `ask_user`禁用该工具（代理在不提出问题的情况下自主工作）。 | | | | `--no-auto-update` | 禁用自动下载 CLI 更新。 | | | `--no-bash-env` | 禁用 `BASH_ENV` 对 bash shell 的支持。 | | | `--no-color` | 禁用所有颜色输出。 | | | `--no-custom-instructions` | 禁止从 `AGENTS.md` 相关文件中加载自定义指令。 | | | `--no-experimental` | 禁用实验性功能。 | | | `--no-mouse` | 禁用鼠标支持。 | | | `--no-remote` | 禁用此会话的远程访问。 | | | `--no-remote-export` | 禁止将您的会话导出到 GitHub.com 和 GitHub Mobile（也会禁用远程控制）。 | | | `--output-format=FORMAT` | FORMAT 可以是 `text` （默认值）或 `json` （输出 JSONL：每行一个 JSON 对象）。 | | | `-p PROMPT`、`--prompt=PROMPT` | 以编程方式执行提示（完成后退出）。 退出摘要包含一个用于继续会话的 `copilot --resume=SESSION-ID` 提示。 请参阅“[以编程方式运行GitHub Copilot CLI](/zh/copilot/how-tos/copilot-cli/automate-copilot-cli/run-cli-programmatically)”。 | | | `--plan` | 在计划模式下启动。 | | | `--mode plan` 的速记。 不能与 `--autopilot` 组合。 可与 `--mode autopilot` 结合使用，以实现“先规划后自动驾驶”；任何其他 `--mode` 值都会被拒绝。 | | | | `--plain-diff` | 禁用富差异渲染（通过 Git 配置指定的差异工具进行语法高亮）。 | | | `--plugin-dir=DIRECTORY` | 从本地目录加载插件（可以多次使用）。 无论选项顺序如何，相对路径都会相对于会话工作目录（即 `--resume`、`--worktree` 或 `-C` 目录）进行解析。 由 `--plugin-dir` 插件提供的代理可用于服务器模式（`--server`）会话，以及交互式会话和 `-p` 会话。 | | | `--remote` | 启用从GitHub.com和GitHub Mobile远程访问此会话。 请参阅“[通过其他设备控制 GitHub Copilot CLI 会话](/zh/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely)”。 | | | `--remote-export` | 将您的会话导出到 GitHub.com 和 GitHub Mobile（只读；不会启用远程控制）。 | | | `-r`、`--resume[=VALUE]` | 通过从列表中选择来恢复以前的交互式会话。 （可选）指定会话 ID、ID 前缀或会话名称。 名称匹配精确且不区分大小写;当没有显式名称匹配时，回退到自动生成的摘要。 与 `--continue` 冲突 空写 `--resume`（无值）将显示交互式会话选择器，该操作需要 TTY 支持。 如果存在多个会话且无法显示选择器（例如在 `-p` 模式下、非 TTY 的 `-i` 模式下，或标准输入被管道重定向时），CLI 将报错退出，而非静默启动新会话——请显式传递 `--resume=SESSION-ID` 或使用 `--continue`。 | | | `-s`、`--silent` | 仅输出代理响应（不使用使用情况统计信息），对于使用 `-p`脚本编写非常有用。 | | | `--screen-reader` | 启用屏幕阅读器优化。 | | | `--secret-env-vars=VAR ...` | 从 shell 和 MCP 服务器环境（可以多次使用）中修订环境变量。 对于多个变量，请使用带引号的逗号分隔列表。 默认情况下， `GITHUB_TOKEN` 和 `COPILOT_GITHUB_TOKEN` 环境变量中的值会从输出中隐藏。 | | | `--session-id ID` | 如果您不希望 `--resume` 通过 ID 前缀或会话名称进行更宽泛的匹配，请使用精确的会话或任务 ID。 如果 ID 与现有会话或任务匹配，则会恢复该会话或任务。 如果没有任何匹配项，则仅当该值是有效的 UUID 时，才会创建新会话。 名称和 ID 前缀不会创建新会话。 不要将此选项与其他会话选择或会话启动选项（例如 `--resume`， `--continue`或 `--connect`）合并，因为它们争先决定要打开或创建哪个会话。 | | | `--sandbox` | 仅为此会话启用 OS 级 shell 沙盒，而无需更改保存的沙盒设置。 与 `-p` 搭配使用很有用。 | | | `--no-sandbox` | 仅对此次会话禁用本地沙盒，而不更改已保存的沙盒设置。 如果已配置了企业管理策略以强制启用沙盒，则会忽略此选项。 | | | `--share=PATH` | 程序化会话结束后，将会话共享到 Markdown 文件（默认路径：`./copilot-session-.md`）。 | | | `--share-gist` | 在编程会话完成后，将会话共享给机密 GitHub gist。 | | | `--stream=MODE` | 启用或禁用流模式，该模式在生成时逐渐显示 Copilot其响应，而不是等待完整响应到达（模式选项： `on` 或 `off`，默认值： `on`） 。 | | | `-v`、`--version` | 显示版本信息。 | | | `-w`、`--worktree[=NAME]` | 默认情况下，创建或重复使用独立的 Git 工作树 `.worktrees/` ，并在其中启动会话。 使用 `worktreePathTemplate` 设置来配置位置。 `NAME` 是可选的，省略后将自动生成分支名称。 默认情况下，从当前检出分支进行分支（`HEAD`）；将 `worktreeBaseRef` 设置设为 `"defaultBranch"` 即可改为从远程默认分支进行分支。 与 `--resume`、`--continue` 和 `--connect` 冲突 | | | `--yolo` | 启用所有权限（等效于 `--allow-all`）。 | | 有关命令和选项的完整列表，请运行 `copilot help`。 > \[!NOTE] > `--remote`、`--no-remote`、`--remote-export``--no-remote-export`和`--connect`选项要求在帐户上提供远程会话功能。 你可以将`--remote`与`--resume `配合使用，在本地恢复远程任务。 即使任务最初是在 Git 存储库外部创建的，也是如此。 如果会话在 CLI 进程消失时仍然处于打开状态，例如由于崩溃或计算机重启，下次启动 `copilot` 时，系统会提供还原会话的选项。 您可以查看可用于恢复的会话，或者改为启动一个新会话。 对于智能体正在处理中的恢复会话，系统会自动恢复该项工作。 ### 先规划，后自动执行 Plan-then-autopilot 允许会话在计划模式下启动，并在计划准备就绪后自动继续进入 Autopilot 模式，而无需等待人工批准转换。 可通过 `--plan --mode autopilot` 启用此功能，或者对于只能注入环境变量而无法注入命令行选项的测试框架，可通过 `COPILOT_PLAN_THEN_AUTOPILOT` 环境变量启用。 如果同时设置了这两个选项，则显式选项优先，CLI 会显示一条警告，指出环境变量已被忽略。 ### 企业级管理的沙箱底线 企业管理策略可将操作系统级 Shell 沙盒隔离强制设定为最低基线。 换言之，即使您传入 `--no-sandbox`，策略仍可强制启用沙箱。 这是策略覆盖，而不是选项本身的失败。 相比之下，`--sandbox` 不受影响，因为它只会启用沙盒机制，而不会将其移除。 如果有效策略允许绕过沙盒，则您可以在响应当前显示的绕过权限提示时，显式禁用当前会话剩余时间内的沙盒。 当托管下限通过将 `sandbox.allowBypass` 的有效值设为 `true` 来强制启用沙盒时（如果策略仅将 `sandbox.enabled` 设为 `true`，这是默认行为），请运行 `/sandbox disable`，以在当前会话的剩余时间内退出沙盒——无需先显示绕过提示。 选择退出仅在当前会话中有效：不会有任何内容保存到 `settings.json`，新会话将再次在沙盒中启动，并且 `/sandbox enable` 会立即恢复沙盒隔离，而无需等待新会话。 如果 `false` 是 `allowBypass`，`/sandbox disable` 会拒绝，并提示沙盒机制由托管策略强制实施，无法禁用。 当托管策略覆盖了你的设置时，CLI 会在交互式时间线中显示警告（或者在使用 `-p` 时通过 stderr 显示警告），从而明确表明该行为是由策略强制执行导致的，而不是因为该选项本身不起作用。 如果需要更改策略，请与管理员联系。 使用 `/sandbox status` 或 `/sandbox policy` 检查会话的有效限制。 将托管设置 `sandbox.failIfUnavailable` 设为 `true`，并将 `sandbox.enabled` 设为 `true`，会使得在无法建立沙盒时必须强制使用沙盒。 如果策略无法由可用的沙盒后端验证、编译或强制执行，Copilot 会阻止模型和工具执行，而不是回退到在无沙盒环境下运行命令。 请参阅“[企业管理设置](/zh/copilot/reference/enterprise-administrators/enterprise-managed-settings#sandbox)”。 当受管策略在您未请求的会话中启用沙箱时，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"` 作为“失败即关闭”的默认设置，因此格式错误的受管策略仍会限制“允许所有”选项，而非默默允许它们。 有三个来源可以设置此限制，按持久性递增的顺序如下： | 来源 | Scope | 因切换帐户而被清除？ | | --------------------------------- | ----- | -------------------------------- | | 用户设置 （`~/.copilot/settings.json`） | 机器 | 否 - 适用于所有帐户 | | 托管设置（按账户从服务器获取） | 客户 | 是 — 切换到未禁用“允许所有”选项的其他账户时，该状态将被清除 | | MDM 策略（plist/注册表/文件） | 设备 | 从不 — 不可被帐户切换覆盖的设备级策略 | 有关 MDM 配置详细信息，请参阅 [GitHub Copilot CLI 配置目录](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#mdm-managed-settings)。 ## 支持的模型 使用 `--model=MODEL` 或 `COPILOT_MODEL` 环境变量选择 AI 模型。 传递`auto`让Copilot自动选择最佳可用模型。 | 型号 | 最适用于 | | ------------------- | ------------------- | | `claude-sonnet-5.5` | 常规用途编码（默认值） | | `gpt-5.4` | 复杂的推理任务 | | `gpt-6.1-sol` | 建议，选择启用（并非自动默认选项） | | `gpt-6-astra` | 建议，选择启用（并非自动默认选项） | | `gpt-6-luna` | 建议，选择启用（并非自动默认选项） | | `claude-opus-5.5` | 建议的高能力复杂任务 | | `claude-haiku-4.5` | 快速、轻量的操作 | | `gpt-5.3-codex` | 以代码为中心的任务 | | `gemini-3.7-flash` | 快速 Google Gemini 响应 | | `gemini-3.8-flash` | 快速 Google Gemini 响应 | 还可以使用斜杠命令在 `/model` 交互式会话期间切换模型。 ## 工具可用性值 和`--available-tools``--excluded-tools`选项支持以下值： ### Shell 工具 | 工具名称 | 说明 | | --------------------------------- | --------------- | | `bash` / `powershell` | 执行命令 | | `list_bash` / `list_powershell` | 列出活动 shell 会话 | | `read_bash` / `read_powershell` | 从 shell 会话中读取输出 | | `stop_bash` / `stop_powershell` | 终止 shell 会话 | | `write_bash` / `write_powershell` | 将输入发送到 shell 会话 | ### 文件操作工具 | 工具名称 | 说明 | | ------------- | -------------------------------------- | | `apply_patch` | 应用修补程序（某些模型使用修补程序，而不是 `edit`/`create`） | | `create` | 创建新文件 | | `edit` | 通过字符串替换编辑文件 | | `view` | 读取文件或目录 | ### 代理和任务委派工具 | 工具名称 | 说明 | | ------------- | ------------ | | `list_agents` | 列出可用的代理 | | `read_agent` | 检查后台代理状态 | | `task` | 运行子代理 | | `write_agent` | 向正在运行的代理发送消息 | ### 其他工具 | 工具名称 | 说明 | | -------------- | ------------ | | `ask_user` | 向用户提问 | | `glob` | 查找匹配模式的文件 | | `grep`（或 `rg`） | 搜索文件中的文本 | | `skill` | 调用自定义技能 | | `web_fetch` | 提取和分析 Web 内容 | ## 工具权限模式 `--allow-tool`和`--deny-tool`选项接受格式为`Kind(argument)`的权限模式。 该参数是可选的， 省略它与该类型的所有工具匹配。 | 种类 | 说明 | 示例模式 | | ------------------------------------------ | ----------------------- | -------- | | `memory` | 将事实存储到代理内存 | `memory` | | `read` | 文件或目录读取 | | | `read`、`read(.env)` | | | | `shell` | Shell 命令执行 | | | `shell(git push)`、`shell(git:*)`、`shell` | | | | `url` | 通过 web 抓取或 shell 访问 URL | | | `url(github.com)`、`url(https://*.api.com)` | | | | `write` | 文件创建或修改 | | | `write`、`write(src/*.ts)` | | | | SERVER-NAME | MCP 服务器工具调用 | | | `MyMCP(create_issue)`、`MyMCP` | | | 对于 `shell` 规则，`:*` 后缀与命令主干后跟一个空格匹配，以避免部分匹配。 例如， `shell(git:*)` 匹配 `git push` 和 `git pull` 不匹配 `gitea`。 即使设置了拒绝规则， `--allow-all` 拒绝规则始终优先于允许规则。 ```shell # 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 上不区分大小写。 ## 环境变量 | Variable | 说明 | | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `COPILOT_ALLOW_ALL` | 自动允许所有权限（等效于 `--allow-all`）。 接受`true`、`1`、`yes``on`、或`y`（忽略大小写、忽略周围空格）将其打开;`false``0`、、`no`、`off`或`n`空值将其关闭。 将其精确设置为 `true` 还会在不提示的情况下信任工作目录，并加载该目录的技能、插件、MCP 服务器和钩子（包括运行 shell 命令的钩子）。 其他表示 true 的拼写形式只会自动批准工具。 | | `COPILOT_AUTO_UPDATE` | 设置为 `false` 禁用 CLI 和第一方插件的自动更新。 | | `COPILOT_CACHE_HOME` | 替代缓存目录（用于市场缓存、自动更新包和其他临时数据）。 有关平台默认值，请参阅 [GitHub Copilot CLI 配置目录](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#changing-the-location-of-the-configuration-directory) 。 | | `COPILOT_CHILD_OOM_SCORE_ADJ` | 仅限 Linux。 覆盖应用于 CLI 所生成 shell 命令进程树的 `oom_score_adj` 偏差，使内核的内存不足 (OOM) 终止程序优先回收失控的子进程树（例如构建任务），而不是 CLI 本身。 默认值：`300`。 范围： `-1000`–`1000`. 将其设置为 `off` 以禁用偏置。 | | `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` | 自定义说明中额外目录的逗号分隔列表。 | | `COPILOT_EDITOR` | 用于交互式编辑的编辑器命令（在 `$VISUAL` 和 `$EDITOR` 后检查）。 如果未设置，则默认为`vi`。 | | `COPILOT_ENABLE_HTTP2` | 将其设置为 `1` 或 `true` 以启用 HTTP/2 传输。 HTTP/1.1 是默认值。 | | `COPILOT_ENABLE_INTERRUPTED_SESSION_RESTORE` | 将其设置为 `1`，以启用恢复在 CLI 进程终止时仍处于打开状态的会话，例如由于崩溃或计算机重启。 在重新设计其启动对话框期间，此还原行为暂时需要选择启用。 请参阅 [还原中断的会话](#restoring-an-interrupted-session)。 | | `COPILOT_GH_HOST` | | | GitHub 仅用于 Copilot CLI 的主机名，覆盖 `GH_HOST`。 适用于以下场景：`GH_HOST` 的目标是 GitHub Enterprise Server，但 Copilot 却需要针对 GitHub.com 或 GitHub Enterprise Cloud 主机名来进行身份验证。 | | | `COPILOT_GITHUB_TOKEN` | 身份验证令牌。 优先于 `GH_TOKEN` 和 `GITHUB_TOKEN`。 | | `COPILOT_HOME` | 覆盖配置和状态目录。 默认值：`$HOME/.copilot`。 | | `COPILOT_LARGE_OUTPUT_THRESHOLD_BYTES` | 直接返回给模型的工具输出的最大 UTF-8 字节大小。 默认值： `20480` （20 KiB）。 请参阅“[在 GitHub Copilot CLI 中管理上下文](/zh/copilot/concepts/agents/copilot-cli/context-management#managing-large-tool-output)”。 | | `COPILOT_MCP_TOOL_CACHE` | 设置为 `false` 禁用整个进程的加载和保留本地 MCP 服务器工具快照。 请参阅 [工具快照缓存](#tool-snapshot-caching)。 | | `COPILOT_MODEL` | 设置 AI 模型。 | | `COPILOT_PLAN_THEN_AUTOPILOT` | 对于只能注入环境变量的测试框架，请设置为 `1`、`true`、`yes` 或 `on` 以请求“先规划后自动执行”（等同于 `--plan --mode autopilot`）。 当传入显式的 `--mode`、`--autopilot` 或 `--plan` 选项时，将被忽略，并发出警告。 请参阅 [Plan-then-autopilot](#plan-then-autopilot)。 | | `COPILOT_PROMPT_FRAME` | | | `1`设置为在输入提示周围启用装饰性 UI 框架，或`0`将其禁用。 替代当前会话的 `PROMPT_FRAME` 实验性功能标志。 | | | `COPILOT_PROVIDER_API_KEY_COMMAND` | Shell 命令，用于在每个提供程序请求之前打印全新的自带密钥 （BYOK） API 密钥。 优先于 `COPILOT_PROVIDER_API_KEY` 环境变量。 其输出会替换匹配的凭据请求头，即使通过 `COPILOT_PROVIDER_HEADERS` 设置的自定义请求头原本会与之冲突。 | | `COPILOT_PROVIDERS_CONFIG` | JSON 文件的路径；该文件将自带密钥 (BYOK) 提供程序和模型注册表定义为包含 `providers` 和 `models` 键的对象。 默认值：`/providers.json`。 当此文件声明任何提供程序或模型时，它优先于旧 `COPILOT_PROVIDER_*` 环境变量。 请参阅 [`providers.json`](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#providersjson)。 | | `COPILOT_SKILLS_DIRS` | 技能附加目录的逗号分隔列表。 | | `PLUGINS_DASHBOARD` | 将其设置为`false`，以禁用通过单独使用 `/mcp`、`/plugin` 和 `/skills` 打开的插件仪表板，并禁用非交互式 `copilot plugin`/`copilot plugins` 命令。 | | `COPILOT_STRIP_REASONING_ON_RESUME` | 将其设置为 `0` 或 `false`，以在会话恢复时保留 BYOK 推理令牌，而不是将其剥离。 默认行为是移除它们。 | | `COPILOT_SUBAGENT_MAX_CONCURRENT` | 每个会话的最大并发子代理数（默认值： `32`，范围： `1`–`256`）。 | | `COPILOT_SUBAGENT_MAX_DEPTH` | 最大子代理嵌套深度（默认值： `4`，范围： `1`–`128`）。 | | `COPILOT_TASK_WAIT_TIMEOUT_SECONDS` | 在退出前，等待待处理的后台智能体或 shell 命令完成的最大秒数 `-p`（以及 `-p --autopilot`）（默认：`600`；`0` 则不等待，立即退出）。 | | `GH_HOST` | | | GitHub 和 GitHub CLI 的 Copilot CLI 主机名（默认值：`github.com`）。 将其设置为带有数据驻留主机名的 GitHub Enterprise Cloud。 仅替代为 `COPILOT_GH_HOST` 的 Copilot CLI。 | | | `GH_TOKEN` | 身份验证令牌。 优先于 `GITHUB_TOKEN`. | | `GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS` | 设置为 `true` 加载项目扩展并允许在提示模式下使用扩展管理工具（`-p`）。 默认情况下禁用以防止运行存储库控制的扩展代码，而无需交互式信任。 | | `GITHUB_COPILOT_PROMPT_MODE_REPO_HOOKS` | 设置为 `true` 以在提示模式 (`-p`)下加载存储库挂钩。 如果该文件夹已受信任或已设置 `COPILOT_ALLOW_ALL`，仓库钩子也会自动加载。 | | `GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP` | 将其设置为 `true` 以在提示模式下加载工作区 MCP 源（`-p`）。 默认情况下禁用以防止启动存储库控制的 MCP 服务器，而无需交互式信任。 | | `GITHUB_TOKEN` | 身份验证令牌。 | | `PLAIN_DIFF` | 设置为 `true` 以禁用多差异呈现。 | | `USE_BUILTIN_RIPGREP` | 设置为 `false` 以使用系统 ripgrep，而不是捆绑的版本。 | | `USE_TGREP` | 设置为 `true` 可始终使用[tgrep](https://github.com/microsoft/tgrep)（一种采用三元组索引的搜索引擎），即使在 Git 存储库之外或虚拟化或网络文件系统上也是如此（例如用于 Git 签出的 VFS 或 SMB/9p 挂载）；设置为 `false` 则始终使用 ripgrep。 当 tgrep 被强制在 Git 仓库之外运行时，它会对当前工作目录本身建立索引，因此请避免强制它在较大的目录中运行，例如你的主目录。 Windows 云同步文件夹（例如 OneDrive）始终使用 ripgrep，即使将此项设置为 `true` 也是如此。 未设置时，Copilot CLI 仅会在位于 Git 仓库中、使用非虚拟化文件系统，且文件数达到由 `TGREP_FILE_COUNT_THRESHOLD` 设置的阈值时，自动从 ripgrep 切换到 tgrep。 设置 `USE_TGREP=true` 完全绕过此阈值。 | | `USE_TGREP=false` 仍然禁用 tgrep。 | | | `TGREP_FILE_COUNT_THRESHOLD` | 自动 tgrep 索引搜索的最小文件数（非负整数；默认值：Windows 上为 `10000`，其他平台为 `50000`）。 无效值回退到平台默认值。 | | `0` 仅移除文件数量要求——其他自动启动检查仍然适用。 | | ## 配置文件设置 有关配置文件设置的详细信息（包括用户设置、存储库设置、本地设置及其级联方式的完整列表），请参阅 [GitHub Copilot CLI 配置目录](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings)。 ## 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添加存储库自定义说明](/zh/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions)”。 使用 `--sandbox` 或 `--no-sandbox` 并配合 `copilot init`，可仅对初始化会话启用或禁用 OS 级 shell 沙盒，而无需更改已保存的沙盒设置。 这些选项与其他入口一样，受相同的企业管理沙盒下限约束——请参阅[企业管理沙盒下限](#enterprise-managed-sandbox-floor)。 ### 自定义指令位置 Copilot CLI 同时从这些位置加载自定义指令（全部合并）： | 位置 | 备注 | | -------------------------------------------------- | ----------------- | | `CLAUDE.md` | 在 Git 根目录和当前工作目录中 | | `GEMINI.md` | 在 Git 根目录和当前工作目录中 | | `AGENTS.md` | 在 Git 根目录和当前工作目录中 | | `.github/instructions/**/*.instructions.md` | 在 Git 根目录和当前工作目录中 | | `.claude/rules/**/*.md` | 在 Git 根目录和当前工作目录中 | | `.github/copilot-instructions.md` | 在 Git 根目录和当前工作目录中 | | `$HOME/.copilot/copilot-instructions.md` | — | | `$HOME/.copilot/instructions/**/*.instructions.md` | — | | `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` | 通过环境变量指定的附加目录。 | Copilot CLI 读取 Claude Code 规则文件的方式，与其从 `.claude/rules/**/*.md` 读取 `.github/instructions/**/*.instructions.md` 文件的方式相同。 将规则范围限定为将文件与 `paths` （或 `applyTo`） frontmatter 键匹配： ```markdown --- paths: "src/api/**/*.ts" description: API layer conventions --- Use the shared `ApiError` type for all thrown errors in this directory. ``` ### 自定义指令导入 说明文件支持 `@path` 导入。 在行首添加 `@` 后跟路径，即可内联另一个文件的内容。 路径可以是相对于指令文件的目录或绝对路径。 导入会进行递归解析，受深度限制，并带有循环和大小限制。 `AGENTS.md`、`CLAUDE.md` 和 `.github/copilot-instructions.md` 支持此功能。 ## 挂钩引用 有关挂钩的详细信息（包括挂钩配置格式、挂钩事件、输入有效负载和决策控制），请参阅 [GitHub Copilot 挂钩参考](/zh/copilot/reference/hooks-reference)。 ## MCP 服务器配置 MCP 服务器向 CLI 代理提供其他工具。 在`~/.copilot/mcp-config.json`中配置持久性服务器。 使用 `--additional-mcp-config` 来为单个会话添加服务器。 在沙盒内部生成的本地（stdio）服务器（请参阅`/sandbox`斜杠命令）在`copilot mcp list`和`/mcp list`中显示`connected (sandboxed)`状态。 远程（HTTP/SSE）服务器未在本地沙盒中运行，尽管其来自 CLI 的连接可以受到沙盒网络策略的限制。 `copilot mcp list` 和 `/mcp list` 用于标记已禁用的服务器，在文本输出中以 `(disabled)` 后缀表示，或在 `--json` 输出中按服务器分别以 `"enabled": false` 表示。 `copilot mcp get` 显示一行 `Status: Enabled`/`Disabled` 。 切换 `/sandbox` 仅会重启本地（stdio）MCP 服务器，因为它们是在沙箱内部启动的。 远程（HTTP/SSE）服务器保持连接状态。 `/mcp edit ` 会拒绝来自工作区的服务器（即在仓库的 `.mcp.json` 中定义的服务器），而不是打开用户级向导，因为保存时会在无提示的情况下创建一个同名的用户级条目，而该条目仍会被工作区中的条目遮蔽。 错误信息直接给出了要编辑的文件名。 当被要求移除来自工作区的服务器时，`/mcp delete ` 会报告同一个文件。 ### `copilot mcp` 子命令 用于 `copilot mcp` 从命令行管理 MCP 服务器配置，而无需启动交互式会话。 | 子命令 | 说明 | | ---------------------------------- | ---------------------------------------------- | | `list [--json]` | 列出按源分组的所有已配置的 MCP 服务器，包括插件提供的服务器。 | | `get [--json]` | 显示特定服务器的配置和工具。 对于插件提供的服务器，还显示源插件名称和版本。 | | `add [options] [url]` | 将服务器添加到用户配置。 写入到 `~/.copilot/mcp-config.json`。 | | `enable ` / `disable ` | 按名称启用或禁用服务器。 更改将持续到用户配置，并适用于将来的会话。 | | `remove ` | 删除用户级服务器。 工作区服务器必须直接在其配置文件中进行编辑。 | 对于本地（stdio）服务器，请在 `--` 后提供该命令： ```shell copy copilot mcp add SERVER-NAME -- COMMAND [ARGS...] ``` 对于远程 HTTP 或 SSE 服务器，请指定传输并提供 URL： ```shell copy copilot mcp add --transport http SERVER-NAME URL ``` \*\* `copilot mcp add` 选项：\*\* | 选项 | 说明 | | -------------------------- | ----------------------------------------------------------------------------------- | | `-- [args...]` | 本地 （stdio） 服务器的命令和参数。 | | `` | 远程服务器的 URL。 | | `--transport ` | 传输类型： `stdio`、 `http`或 `sse`。 默认值为 `stdio`。 | | `--env KEY=VALUE` | 环境变量（可重复）。 | | `--header "HEADER: VALUE"` | 远程服务器的 HTTP 标头（可重复）。 | | `--tools ` | 工具筛选器： `"*"` 表示全部，逗号分隔列表，或 `""` 表示无。 | | `--timeout ` | 工具发现和工具调用的超时时间（以毫秒为单位）。 默认值：`30000`。 必须是一个正整数，不带小数部分、单位后缀、符号或指数，从到 `1``4294967295`。 | | `--json` | 将添加的配置输出为 JSON 格式。 | | `--show-secrets` | 显示完整的环境变量和标头值。 | 在 `/mcp add`/`/mcp edit` 交互式表单中，在 `env` 字段中输入以逗号分隔的 `KEY=VALUE` 对，或输入 JSON 对象（例如 `{"API_KEY":"secret"}`）。 `$PATH` 默认包含，无需列出。 > \[!CAUTION] > `--show-secrets` 可以将敏感的环境变量和标头值输出到终端或日志。 仅在受信任的环境中使用此选项，避免在共享日志或历史记录中复制、粘贴或其他捕获输出。 ### 传输类型 | 类型 | 说明 | 必填字段 | | ------------------------------------------ | ---------------------------------------- | ----- | | `local` / `stdio` | 本地进程通过 stdin/stdout 进行通信。 | | | `command`、`args` | | | | `http` | 使用可流式 HTTP 传输的远程服务器。 | | | `"streamable-http"` 也接受为别名，并规范化为 `"http"`。 | `url` | | | `sse` | 使用服务器发送事件 (Server-Sent Events) 传输的远程服务器。 | `url` | ### 本地服务器配置字段 | 领域 | 必需 | 说明 | | ---------------------------------------------------------------------------- | -- | -------------------------------------------------------------------------------------------------- | | `command` | 是的 | 用于启动服务器的命令。 | | `args` | 是的 | 命令参数（数组）。 | | `tools` | 是的 | 要启用的工具：`["*"]`，可以是所有工具或特定工具名称的列表。 | | `env` | 否 | 环境变量。 支持`$VAR`和`${VAR}``${VAR:-default}`扩展。 | | `cwd` | 否 | 服务器的工作目录。 | | `timeout` | 否 | 工具发现和工具调用的超时时间（以毫秒为单位）。 默认值：`30000`。 | | `type` | 否 | | | `"local"` 或 `"stdio"`。 默认值：`"local"`。 | | | | `deferTools` | 否 | | | `"auto"` （default） 或 `"never"`. 将其设为 `"never"`，即可始终显示此服务器的工具，即使在启用工具搜索时也是如此。 | | | | `disableToolCache` | 否 | 将其设置为 `true` 以跳过加载和持久保存此服务器的工具快照。 | | `slowConnectionThresholdMs` | 否 | 在 Copilot CLI 警告此服务器连接时间超出预期之前的毫秒数。 默认值：`10000`。 此设置仅影响显示警告时 ， 它不会更改连接超时。 必须是不大于 `2147483647`的正整数。 | `slowConnectionThresholdMs` 和 `timeout` 是相互独立的：`timeout` 设置实际的连接预算（下限为 `60000` 毫秒），而 `slowConnectionThresholdMs` 仅控制 Copilot CLI 何时针对仍在进行中的连接打印警告。 提高 `slowConnectionThresholdMs` 以静音预期缓慢的握手，例如对于位于身份验证流后面的服务器，而不扩展工具调用允许的耗时。 ### 工具快照缓存 Copilot CLI 会持久化保存每个本地服务器的工具列表快照，以便在启动时工具可立即使用，同时在后台完成实时发现。 实时发现始终运行，并在完成后替换快照。 将服务器上的 `disableToolCache: true` 设为相应值，以仅对该服务器强制进行实时发现；或者设置 `COPILOT_MCP_TOOL_CACHE=false` 环境变量，以对整个进程禁用快照加载和持久化。 这两个选择退出都使现有缓存文件保持不变。 ### 专用 npm 注册表 在 `--registry` 数组中使用 `args` 从私有 npm 注册表拉取包 — 例如，Artifactory 或 GitHub Packages 源： ```json { "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`）会被视为接受值的参数。 这可确保当这些选项出现在包名称之前时，企业允许列表校验和注册表验证能够正常运行。 ### 远程服务器配置字段 | 领域 | 必需 | 说明 | | ---------------------------------------------------------------------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | 是的 | | | `"http"` 或 `"sse"` （`"streamable-http"` 也接受为别名 `"http"`）。 | | | | `url` | 是的 | 服务器 URL。 | | `tools` | 是的 | 要启用的工具。 | | `headers` | 否 | HTTP 标头。 支持变量扩展。 | | `oauthClientId` | 否 | 静态 OAuth 客户端 ID（跳过动态注册）。 | | `oauthScopes` | 否 | 要请求的 OAuth 范围令牌的非空数组。 需要 `oauthClientId`。 服务器的 `WWW-Authenticate` 质询中的非空范围仍然具有优先权；否则，这将覆盖已发现的 `scopes_supported` 元数据。 | | `oauthPublicClient` | 否 | OAuth 客户端是否为公共客户端。 默认值：`true`。 将其设置为`false`，适用于具有存储机密的机密客户端。 | | `oauthGrantType` | 否 | OAuth 授权类型：`"authorization_code"`（默认，基于浏览器的流程）或 `"client_credentials"`（完全无外设，无需浏览器或回调）。 | | `oidc` | 否 | 启用 OIDC 令牌注入。 当`true`，CLI 会为服务器`GITHUB_COPILOT_OIDC_MCP_TOKEN`块（本地服务器）中引用的任何`GITHUB_COPILOT_OIDC_MCP_TOKEN_`或`env`变量注入 OIDC 令牌，或将令牌作为`Bearer``Authorization`标头（远程服务器）发送。 对于本地服务器，首选后缀变体（例如）， `${GITHUB_COPILOT_OIDC_MCP_TOKEN_MY_SVC}`为每个服务器分配唯一的变量名称。 | | `timeout` | 否 | 工具发现和工具调用的超时时间（以毫秒为单位）。 默认值：`30000`。 | | `deferTools` | 否 | | | `"auto"` （default） 或 `"never"`. 将其设为 `"never"`，即可始终显示此服务器的工具，即使在启用工具搜索时也是如此。 | | | | `slowConnectionThresholdMs` | 否 | 在 Copilot CLI 警告此服务器连接时间超出预期之前的毫秒数。 默认值：`10000`。 此设置仅影响显示警告时 ， 它不会更改连接超时。 必须是不大于 `2147483647`的正整数。 | ### OAuth 重新身份验证 使用 OAuth 的远程 MCP 服务器可能会在令牌过期或需要其他帐户时显示 `needs-auth` 状态。 使用 `/mcp auth ` 触发新的 OAuth 流。 这会打开浏览器身份验证提示，允许你登录或切换帐户。 完成流后，服务器会自动重新连接。 在 Windows 上，受 Microsoft Entra ID 保护的远程 MCP 服务器则通过操作系统身份验证代理（Web 帐户管理器）进行身份验证，通常不会出现提示。 在 Linux 和 macOS 上，不存在 OS 代理，CLI 会以无提示方式从通过 `/login` → Microsoft Entra 建立的 Entra 帐户中静默生成每个资源的令牌。 如果该帐户无法无提示地满足请求（例如，没有登录的 Entra 标识、不明确帐户或针对其他客户端预先授权的资源），登录将回退到上述浏览器流。 传递 `--device-code` 会绕过 broker，并强制使用 OAuth 设备代码流而不是浏览器流，并且没有 broker 库的 Windows 计算机也会回退到浏览器流。 ### 账户衍生的 WorkIQ 使用 Microsoft Entra 帐户登录可使托管的 WorkIQ MCP 服务器在 `/mcp` 中可用。 此项默认禁用。 仅靠发现功能无法建立连接、获取令牌或暴露工具——请通过正常的 MCP 控件（`/mcp enable WorkIQ` 或 `copilot mcp enable WorkIQ`）启用它，以先尝试无提示身份验证。 `/mcp auth WorkIQ` 仍可用于恢复。 服务器使用绑定到已登录的 Entra 帐户的凭据，而不是为另一个服务颁发的令牌，其是否启用取决于该 Entra 标识，而不是转移到其他帐户。 显式服务器配置和禁用以及组织允许列表或拒绝列表策略仍优先。 未将 WorkIQ 条目写入 `mcp-config.json`。 这与将 `npx @microsoft/workiq mcp` 作为经过独立身份验证的 stdio 服务器运行无关。 ### 无外设 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` 直接发送至服务器检测到的令牌端点。 ```json { "mcpServers": { "headless-api": { "type": "http", "url": "https://api.example.com/mcp", "tools": ["*"], "oauthClientId": "YOUR-CLIENT-ID", "oauthPublicClient": false, "oauthGrantType": "client_credentials" } } } ``` ### 筛选器映射 控制如何使用服务器配置中的`filterMapping`字段来处理 MCP 工具输出。 | 模式 | 说明 | | ------------------- | ----------------- | | `none` | 无筛选。 | | `markdown` | 将输出格式化为 Markdown。 | | `hidden_characters` | 删除隐藏或控制字符。 违约。 | ### 内置 MCP 服务器 CLI 包括内置 MCP 服务器，这些服务器在没有其他设置的情况下可用。 | 服务器 | 说明 | | ------------------------------------------------- | -------------------------------------------- | | `github-mcp-server` | | | GitHub API 集成：问题、拉取请求、标签、提交、代码搜索和 GitHub Actions。 | | | `playwright` | 浏览器自动化：导航、单击、键入、屏幕截图和表单处理。 | | `fetch` | 通过 `fetch` 工具发送的 HTTP 请求。 | | `time` | 时间实用工具： `get_current_time` 和 `convert_time`。 | 用于 `--disable-builtin-mcps` 禁用所有内置服务器，或 `--disable-mcp-server SERVER-NAME` 禁用特定服务器。 内置服务器会显示在 `copilot mcp list`、`copilot mcp get` 和交互式 `/mcp` 视图中，并与用户、工作区和插件服务器一同显示。 #### GitHub MCP 服务器工具 `github-mcp-server` 提供以下工具。 | 工具 | 说明 | | ---------------------------------------------------------------- | --------------- | | `get_file_contents`、`search_code` | 浏览存储库文件。 | | `list_issues`、`issue_read`、`search_issues` | 问题跟踪。 | | `get_pull_request`、`list_pull_requests`、`get_pull_request_files` | 拉取请求。 | | `list_commits`、`get_commit` | 提交历史记录。 | | `list_workflow_runs`、`get_workflow_run_logs` | GitHub Actions。 | | `get_label`、`list_label`、`label_write` | 标签管理。 | ### 资源发现 仅在实验模式下可用。 缺少本地功能时，代理可以使用内置 `discover-resources` 技能搜索远程目录，查找要添加的公共 MCP 服务器和技能。 技能查询目录，查找相关性排名的 MCP 服务器和与抽象功能匹配的技能（例如“数据库访问”或“体系结构关系图”），然后提供候选项供你选择。 技能本身永远不会安装任何内容。 `/mcp`、`/skills` 和 `/plugin` 仪表板还包含一项可输入的目录搜索功能，可将相同的远程结果整合到本地资源列表中。 ### 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 服务器从多个源加载，每个源具有不同的信任级别。 | 来源 | 信任级别 | 需评审 | | ---------------------------------- | ------------ | ---- | | 内置 | 高 | 否 | | 存储库 （`.github/mcp.json`） | 中等 | 推荐 | | 工作区 （`.mcp.json`） | 中等 | 推荐 | | 用户配置（`~/.copilot/mcp-config.json`） | User-defined | 用户责任 | | 远程服务器 | 低 | 始终 | 所有 MCP 工具调用都需要显式权限。 这甚至适用于对外部服务的只读操作。 ### MCP 服务器加载优先级 来自不同源的 MCP 服务器按优先级顺序合并（第一个最高）。 当服务器共享名称时，优先级较高的源优先。 1. `--additional-mcp-config` 选项（最高） 2. 插件提供的服务器 3. 工作区服务器 — `.mcp.json` 和 `.github/mcp.json` 从工作目录向上加载到 Git 根目录；要求该文件夹受信任 4. `~/.copilot/mcp-config.json` （最低） > \[!NOTE] > 工作区 MCP 服务器（`.mcp.json` 和 `.github/mcp.json`）在交互式会话和 SDK 服务器模式会话中都会被加载，前提是工作目录已受信任。 有关文件夹信任的详细信息，请参阅 [允许和拒绝工具使用](/zh/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools)。 如果工作区配置文件包含无效的服务器条目，CLI 将仅跳过该条目，并不断加载其有效的同级，为每个跳过的条目打印 `Warning: workspace MCP config "": ` 。 格式不正确或不可读的文件（JSON 无效或顶级结构无效）仍完全跳过。 ### 企业 MCP 允许列表 GitHub Enterprise 组织可以强制实施允许的 MCP 服务器白名单。 处于活动状态时，CLI 会根据企业策略评估每个非默认服务器，然后再连接。 检测到 GitHub Enterprise 注册表策略（或启用 `MCP_ENTERPRISE_ALLOWLIST` 实验性功能标志）时，CLI： 1. 根据每个配置的非默认服务器的命令、参数和远程 URL 计算指纹。 2. 将指纹发送到企业白名单评估端点。 3. 仅允许指纹已获批准的服务器；所有其他服务器都将被阻止，并收到一个包含企业名称的消息。 此检查为“失效关闭”模式：如果评估终结点不可访问或返回错误，则会阻止非默认服务器，直至策略可以被验证。 当企业允许列表阻止服务器时，CLI 会显示： ```text 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 和其他）：** ```shell jq '{mcpServers: .servers}' .vscode/mcp.json > .mcp.json ``` 需要 [`jq`](https://jqlang.github.io/jq/)。 PowerShell： ```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` 或自动由代理调用）时，技能的内容将注入到会话中。 ### 技能前页字段 | 领域 | 类型 | 必需 | 说明 | | -------------------------- | ------------------ | -- | -------------------------------------------------------------------------------------------------- | | `name` | 字符串 | 是的 | 技能的唯一标识符。 必须以字母或数字开头，并且仅包含字母、数字、连字符、下划线、点、冒号和空格。 最多 64 个字符。 冒号允许使用带命名空间的名称（例如 `my-plugin:search`）。 | | `description` | 字符串 | 是的 | 技能的作用以及何时使用它。 最多 1024 个字符。 | | `argument-hint` | 字符串 | 否 | 在技能选取器中显示的、用于描述预期参数的自由格式提示（例如 `"[target] [mode]"`）。 | | `allowed-tools` | String 或 String\[] | 否 | 技能处于活动状态时自动允许的工具的逗号分隔列表或 YAML 数组。 将 `"*"` 用于所有工具。 | | `user-invocable` | 布尔 | 否 | 用户是否可以使用 `/SKILL-NAME` 调用技能。 默认值：`true`。 | | `disable-model-invocation` | 布尔 | 否 | 阻止代理自动调用此技能。 默认值：`false`。 | ### 技能位置 系统将按照优先顺序从这些位置加载技能（对于重复名称，以首次找到项为准）。 | 位置 | Scope | 说明 | | --------------------------------------------------------------------------------------------------------------------- | ----- | ----------------------------------------- | | `.github/skills/` | 项目 | 项目特定技能 | | `.agents/skills/` | 项目 | 替代项目位置。 | | `.claude/skills/` | 项目 | 与 Claude 兼容的位置。 | | 父 `.github/skills/` | 继承 | Monorepo 父目录支持。 | | `~/.copilot/skills/` | 个人 | 适用于所有项目的个人技能。 | | `~/.agents/skills/` | 个人 | 跨所有项目共享的代理技能。 | | 插件目录 | 插件 | 已安装插件中的技能。 | | `COPILOT_SKILLS_DIRS` | 自定义 | 其他目录（逗号分隔）。 | | `--add-dir ` | 添加了根 | | | `.github/skills/` 位于通过 `--add-dir`、`/add-dir` 或 SDK 的 `additionalDirectories` 添加的目录下。 这是一项信任决策：添加的技能会以与项目技能相同的信任级别运行。 | | | | （与 CLI 捆绑） | 内置 | CLI 附带的技能。 最低优先级 - 可以被任何其他来源替代。 | | （组织/企业） | 远程 | 由你的组织或企业托管、通过 AHP 中继提供的技能。 调用技能时，会按需提取内容。 | 当本地技能具有相同名称时，远程技能与本地技能一起投影，并遵循相同的基于名称的优先级。 使用 `ignoredSkillsLocations` 设置可排除特定目录（及其所有子目录），使其不被发现，无论按照上述哪个位置规则原本会发现它们。 请参阅“[GitHub Copilot CLI 配置目录](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings)”。 当两个插件提供具有相同名称的技能时，两个插件都使用插件限定的调用名称（例如 `/my-plugin/search` 和 `/other-plugin/search`） 共存。 仅名称会路由到优先级更高的插件。 这仅适用于技能；命令仍保持标准的基于层级的去重机制，其中优先级更高的来源优先。 ### 以非交互方式管理技能 使用 `copilot skill` 从命令行管理技能，无需打开交互式会话。 | 子命令 | 说明 | | ---------------------------------- | ----------------------- | | `list [--json]` | 列出所有发现的技能。 | | `add [--project]` | 从文件路径、URL 或目录添加技能。 | | `remove ` | 删除个人或项目技能，或取消注册自定义技能目录。 | | `enable ` / `disable ` | 按名称启用或禁用技能。 | ```bash # Install a skill for your user account (default) copilot skill add ./my-skill/SKILL.md # Install a skill into the current project (.github/skills; file or URL skills only) copilot skill add --project ./my-skill/SKILL.md # Enable, disable, or remove a skill by name copilot skill enable my-skill copilot skill disable my-skill copilot skill remove my-skill ``` 安装一个目录时，系统会将其注册为自定义技能源，而不是复制该目录。 安装文件或 URL 会将技能的内容复制到个人或项目技能目录中。 等效的交互式命令为 `/skills add [--project] `. `copilot skill list --json` 行的形状为 `{ name, description, source, path, enabled }`。 使用 `remove` 传递技能名称或指向添加的自定义技能目录的路径—技能名称会删除该技能的文件，而自定义目录路径仅注销目录并将其文件保留在磁盘上。 只能删除添加的个人和项目技能;插件或内置集提供的技能不能以这种方式删除（请改为禁用它们）。 这将取代已停用的 `copilot plugins install --skill [--scope project]` 和 `copilot plugins remove/enable/disable --skill`。 ### 命令（可选技能格式） 命令是 `.md` 中存储为单个 `.claude/commands/` 文件的技能的替代项。 命令名称派生自文件名。 命令文件使用简化格式（无需 `name` 字段），并支持 `argument-hint`、`description`、`allowed-tools` 和 `disable-model-invocation`。 命令的优先级低于具有相同名称的技能。 ## 自定义代理参考 自定义代理是在 Markdown 文件中定义的专用 AI 代理。 对于用户、项目和添加根代理，代理 ID 派生自文件相对于 `agents` 目录的路径。 CLI 会移除 `.md` 或 `.agent.md` 扩展名，并将目录分隔符替换为 `--`。 例如，`agents/team/reviewer.agent.md` 的 ID 为 `team--reviewer`。 ### 内置代理 | 代理人 | 默认模型 | 说明 | | ----------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `code-review` | claude-sonnet-4.6 | 高信噪比代码审查。 分析代码差异中的缺陷、安全问题和逻辑错误。 不会修改代码。 | | `explore` | gpt-5.4-mini | 快速代码库浏览。 搜索文件、读取代码和回答问题。 提供不超过300字的简明答案。 可以安全地并行运行。 | | `general-purpose` | claude-sonnet-4.6 | 支持复杂多步骤任务的全功能代理。 在单独的上下文窗口中运行。 | | `research` | claude-haiku-4.5 | 根据说明执行全面搜索。 使用引文搜索 GitHub 存储库、提取文件、验证声明和报告详细发现。 | | `rubber-duck` | 互补模型 | 使用互补模型来对提案、设计、实现或测试进行建设性的批评。 标识薄弱点并建议改进。 请参阅“[关于橡皮鸭智能体](/zh/copilot/concepts/agents/copilot-cli/rubber-duck)”。 | | `security-review` | claude-sonnet-4.6 | 以安全为中心的代码评审。 分析 11 个类别中的高置信度漏洞变化。 仅标记可利用性置信度超过 80% 的问题。 报告严重程度和置信度评分。 不会修改代码。 | | `task` | gpt-5.6-luna（回退到 gpt-5.4-mini，然后回退到 claude-haiku-4.5） | 命令执行（测试、构建、代码检查）。 成功时返回简要摘要，失败时返回全部输出。 | `code-review` 和 `security-review` 绝不会将完整审查转发给另一个审查代理：因为启动某个审查者本身就已经满足了“使用”或“调用”审查者的请求，所以它会自行完成审查，而不会在整个委托链中递归地将整个任务委托给嵌套的 `code-review` 或 `security-review` 子代理。 `code-review` 仍会将请求中侧重安全的部分交由专门的 `security-review` 专家处理，并且这两个代理都可以将范围较窄且可独立界定的事实查证工作委托给非审查代理，例如 `explore`。 只有根代理才能调用 `store_memory` 或 `vote_memory` 来保存某条记忆或对其进行投票。 子代理通过对存储的 `read_memories`记忆保持读取访问权限，但无法对它们进行写入或投票。 ### 自定义代理程序前端字段 | 领域 | 类型 | 必需 | 说明 | | ---------------------------------------------------------------------------------------------------------- | ------ | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `description` | 字符串 | 是的 | 说明显示在代理列表和`task` 工具中。 | | `include-custom-instructions` | 布尔 | 否 | 当此代理作为子代理运行时，请包含存储库指令文件（`copilot-instructions.md`，`AGENTS.md`）。 `CLAUDE.md` 默认值：`false`。 请参阅 [子代理的存储库自定义说明](#repository-custom-instructions-for-subagents)。 | | `infer` | 布尔 | 否 | 允许主代理自动委派。 默认值：`true`。 | | `mcp-servers` | 对象 | 否 | 要连接的 MCP 服务器。 使用与`~/.copilot/mcp-config.json`相同的模式。 | | `model` | 字符串 | 否 | 此代理的 AI 模型。 未设置时，继承外部代理的模型。 当会话模型设置为 `Auto` （服务器选择）时，子代理始终继承解析的会话模型，而不考虑此字段。 | | `models` | 字符串\[] | 否 | 按优先级顺序创作的模型。 运行时使用用户计划可以访问的第一个模型;如果没有解析，则调度会回退到会话的模型。 当两者都设置时，会覆盖 `model`。 | | `modelPolicy` | 字符串 | 否 | | | `"preferred"`（默认值）允许通过 `~/.copilot/settings.json` 中的 `subagents` 覆盖或 `/subagents` 选择器来覆盖 `model`/`models`。 | | | | | `"required"` 将调度锁定到已编写的模型之一——覆盖设置会被拒绝，并且选择器中的 **Model** 条目会被禁用。 | | | | | `name` | 字符串 | 否 | 显示名称。 还可以使用此值来选择代理，例如使用 `--agent`。 默认值为代理 ID。 | | `reasoningEffort` | 字符串 | 否 | 该代理的默认推理强度（例如，`"low"`、`"medium"` 或 `"high"`）。 当未设置时，继承外部智能体的努力值。 | | `tools` | 字符串\[] | 否 | 代理可用的工具。 默认值： `["*"]` （所有工具）。 在列表中的任意位置包含 `*` 即可授予对所有工具的完全访问权限——例如，`["view", "*"]` 会授予对所有工具的访问权限，而不只是 `view`。 | `model`、`models`、`modelPolicy` 和 `reasoningEffort` 在代理通过 `task` 工具分派还是直接启动时都同样适用——例如，通过 SDK 的 `session.startSubagent`。 模型和工作量按以下优先顺序解析（从高到低）：每次调用显式指定的值、/ 中的 `subagents` 覆盖值、代理定义中的 `reasoningEffort``model``models`/`~/.copilot/settings.json` 字段，最后是父会话的值。 如果已声明的模型或工作量无法兑现，系统会回退到会话中的设置值，而不是让调度失败；但如果代理声明了 `modelPolicy: "required"`，则会拒绝调度，而不是静默替换为一个未声明的模型。 ### 自定义代理位置 CLI 按以下优先级顺序加载自定义代理。 当代理具有相同 ID 时，将使用加载的第一个代理。 | Priority | Scope | 位置 | | --------------------------------------------------------------------------------------------------------------------- | ----- | -------------------- | | 1 （最高） | 用户 | `~/.copilot/agents/` | | 2 | 项目 | | | `.github/agents/`，从当前工作目录向上到 Git 根 | | | | 3 | 项目 | | | `.claude/agents/`，从当前工作目录向上到 Git 根 | | | | 4 | 添加了根 | | | `.github/agents/` 位于通过 `--add-dir`、`/add-dir` 或 SDK 的 `additionalDirectories` 添加的目录下。 添加该目录是一项信任决策：其中的代理会作为受信任的配置被加载。 | | | | 5 | 插件 | `/agents/` | | 6 （最低） | 远程 | 组织或企业代理 | 在每个项目行中，CLI 首先检查当前工作目录，然后检查每个父目录到 Git 根目录，因此最深层目录具有最高优先级。 每个项目的 `.github/agents/` 目录都会先于任何项目的 `.claude/agents/` 目录加载。 这意味着 monorepo 中的每个包或子目录都可以贡献自己的代理。 可选的 `name` frontmatter 字段不控制重复数据删除。 具有相同 `name` 但不同 ID 的代理同时加载。 如果传递给 `--agent` 的值与多个代理的 ID 匹配，或者 `name`CLI 使用上述优先级顺序中的第一个匹配代理。 ### 面向子代理的仓库自定义说明 默认情况下，通过 `task` 工具或 SDK 生成为子代理的 `session.startSubagent`自定义代理不会接收存储库指令文件 （`copilot-instructions.md`， `AGENTS.md`， `CLAUDE.md`）。 在其前置元数据中设置 `include-custom-instructions: true` 以启用： ```markdown --- name: RepoAwareReviewer description: Reviews a change against this repository's conventions tools: ["*"] include-custom-instructions: true --- Review the change and flag anything that violates the repository's conventions. ``` | 代理人 | 接收存储库指令 | | --------------------------------------- | --------------------------------------- | | 会话代理（默认代理或选择的 `--agent`自定义代理） | 是的 | | `general-purpose` 子代理 | 是的 | | 内置 `explore`、`task` 和 `code-review` 子代理 | 否 | | 作为子代理生成的自定义代理 | 仅使用 `include-custom-instructions: true` | 当子代理具有`include-custom-instructions: true`时，它会读取存储库自己的指令文件（`copilot-instructions.md`、、`AGENTS.md``CLAUDE.md`）。 它不会继承任何仅为主会话加载的额外指令目录，例如你使用 `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` 为该会话指定的个人目录。 使用 `--no-custom-instructions` 启动会话始终具有最高优先级：使用该选项时，任何代理都不会收到仓库指令，即使是设置了 `include-custom-instructions: true` 的代理也不例外。 仅对需要遵循存储库约定的代理（例如评审或编辑代码的代理）启用设置。 存储库说明会增加代理每次运行时需要处理的内容，因此，对于不需要这些说明的代理——例如仅搜索文件或汇总文本的代理——将该设置关闭可以让这些代理运行得更快、成本更低。 有关详细信息，请参阅“[为 GitHub Copilot CLI 创建和使用自定义智能体](/zh/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli)”。 ### 代理通信 在自定义代理中使用 `list_agents` 和 `write_agent`，以检查附近的代理并在多代理会话中协调工作。 #### `list_agents`中的关系标签 关系标签标识可见代理与当前代理的关系。 当子代理在启用了共享同级通信的父会话内运行时，将显示标签。 | 标签 | Meaning | 使用它来 | | ----------- | ------------ | ------------------------ | | `"self"` | 当前代理 | 确认哪个条目表示活动智能体 | | `"sibling"` | 由同一父级启动的智能体 | 通过 `write_agent` 与对等代理协调 | | `"child"` | 由当前智能体启动的智能体 | 跟踪当前智能体委派的后续工作 | #### 作用域列表 在`scope`上使用`list_agents`，以便在选择目标之前缩小列表范围。 | `scope` 值 | Returns | 使用它来 | | ------------ | ------------ | ---------------- | | 省略 | 当前上下文中的邻近智能体 | 请参阅当前工作流的默认工作集 | | `"siblings"` | 仅同级代理 | 查找同一父级启动的对等智能体 | | `"children"` | 仅限当前智能体的子智能体 | 查看当前智能体委派的工作 | | `"all"` | 所有可见代理 | 检查完整会话树而不使用它进行协调 | 在单代理会话中，默认视图以子代理为中心。 在多代理会话中，默认视图显示即时本地上下文，而不是整个树。 ```text list_agents(scope="siblings") list_agents(scope="children") list_agents(scope="all") ``` #### 作用域内消息传送 在`scope`上使用`write_agent`，将一条消息广播给多个相关代理。 仅可在启用了共享同级通信的父会话内运行的子智能体中使用作用域内消息传送。 在顶级会话中，应改为以具有显式 `agent_id` 值的代理为目标。 | `scope` 值 | 发送到 | 使用它来 | | ------------ | ---------- | --------------- | | `"siblings"` | 所有可见的同级代理 | 在共享会话中协调协作工作 | | `"children"` | 当前代理的所有子代理 | 向委派的工作发送相同的后续工作 | 如果某个作用域匹配的智能体过多，`write_agent` 会返回错误，并要求改为从 `agent_id` 提供明确的 `list_agents` 值。 ```text 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 强制实施深度和并发限制以防止生成失控代理。 | Limit | 默认 | 麦克斯 | | ----- | ----- | ----- | | 最大深度 | `6` | `256` | | 最大并发数 | 基于计划的 | `32` | **深度** 计数彼此嵌套的代理数。 达到深度限制时，最内部的代理无法生成进一步的子代理。 **并发** 计数在整个会话树中同时运行的子代理数。 达到限制后，将拒绝新的子代理请求，直到活动代理完成。 默认并发限制取决于您所用的 Copilot 套餐： | Plan | 最大并发数 | | ---------- | ----- | | 免费/教育 | `2` | | Pro/ Pro+ | `4` | | 麦克斯 | `8` | | 商业 | `16` | | Enterprise | `32` | | 基于使用量的计费 | `32` | 按使用量计费的用户可通过 `subagents.maxConcurrency` 和 `subagents.maxDepth` 设置覆盖这些限制： ```json { "subagents": { "maxConcurrency": 16, "maxDepth": 10 } } ``` 超出有效范围的值会被限制：`maxConcurrency` 的上限为 `32`，`maxDepth` 的下限为 `256`。 对于不使用基于使用情况的计费的计划，将忽略这些设置。 请参阅 [配置文件设置](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings)。 ## Sidekick 智能体 Sidekick 代理在后台自动运行，并将上下文发布到会话收件箱中。 它们响应会话事件，而不是被显式调用。 在任何代理定义中添加 `sidekick:` 块，使其成为辅助代理： ```yaml --- 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` 的对象。 | 事件 | 说明 | | ------------------------- | -------------------------------------------- | | `user.message` | 在每次用户发送消息时触发。 | | `session.context_changed` | 在工作目录、仓库或分支发生变化时触发（例如，在 `cd` 之后或切换 Git 分支后）。 | | 触发器字段 | 类型 | 默认 | 说明 | | ------- | -------- | --- | ---------------------------- | | `event` | `string` | 必需 | 启动此代理的会话事件类型。 | | `limit` | `number` | 无限制 | 此触发器每个会话可触发的最大次数。 设置时必须是正整数。 | ### Sidekick 配置字段 | 领域 | 类型 | 默认 | 说明 | | ------------------------------------------------------- | -------- | ------------------------ | -------------------------------------------------------- | | `triggers` | | | | | `string[]` 或 object\[] | 必需 | 启动此代理的会话事件类型。 至少需要一个触发器。 | | | `behavior` | `string` | `"restart"` | | | `"restart"`：每次触发时取消之前的运行并重新开始。 | | | | | `"persistent"`：保持同一个长时间运行的进程持续运行，并将新消息投递到现有循环中，而不是重新启动。 | | | | | `maxSendsPerTurn` | `number` | `1` | 每个触发器允许的最大收件箱发送量。 在 `"persistent"` 模式下，每个传递的用户消息都会重置此预算。 | `"restart"` 的行为模式适合用于收集上下文的无状态代理。 `"persistent"` 行为适用于跨轮次累积状态的智能体。 ## 权限审批结果 当 CLI 提示执行作的权限时，可以使用以下键进行响应。 | 密钥 | Effect | | --- | ----------------- | | `y` | 允许此特定请求一次。 | | `n` | 拒绝此特定请求一次。 | | `!` | 在会话剩余时段允许所有类似的请求。 | | `#` | 在会话剩余时段拒绝所有类似的请求。 | | `?` | 显示有关请求的详细信息。 | 显示完整对话框后，还可以从以下选项中进行选择： | 选项 | Scope | 持久性 | | --- | ------- | -------- | | 一旦 | 单一使用 | 没有 | | 此位置 | 在手动清除之前 | 按位置保存到磁盘 | | 始终 | 永久 | 配置文件 | 当 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 命令被沙箱的文件系统或网络策略阻止，系统会提示您在沙箱外重新运行该命令 — 无需进行模型往返处理。 确认该提示后，将重新运行该命令并返回其输出结果。 拒绝后将保留沙箱中的（被阻止的）结果。 沙盒绕过提示还提供一个 **“是，并在本次会话的剩余时间内禁用沙盒”** 选项。 选择此项会关闭当前会话中所有剩余命令的沙盒机制，而不只是当前正在批准的命令。 这仅适用于当前会话 - 再次使用 `/new` 沙盒命令启动新会话，并且该选项对保存 `sandbox` 的配置设置或其他正在运行的会话没有影响。 分离（在后台运行）的命令根本无法置于沙盒中，因为沙盒无法封装在工具调用结束后仍继续运行的进程。 启用 **“允许沙盒绕过** ”设置时，会在命令启动之前提示审批，而不是完全拒绝。 批准后，该命令将从一开始就在非沙盒环境中运行。 在沙盒策略支持拒绝捕获的 Windows 主机上，被阻止的交互式 shell 命令会通过一个步骤升级，而不会直接跳转到完全绕过沙盒。 选择批准后，会在将文件和进程限制设为“记录”而非“阻止”的情况下重新运行该命令（网络策略仍然适用）；仅当该命令仍被阻止时，才会回退到已说明的完全绕过模式。 在整个升级过程中，只会显示一个提示。 被拒绝的环回或本地网络套接字操作（例如绑定或连接到 `127.0.0.1`）也会触发相同的升级，而不是静默失败。 当网络策略仍然强制执行时，重试结果标记为“沙盒已放宽”；完全取消沙盒限制时，则标记为“沙盒已绕过”。 如果重试仍然失败，消息将说明主机级权限仍然适用。 如果某个命令因一条提及被沙盒阻止路径的 `EPERM` 或 `EACCES` 诊断信息而失败，系统现在会提供在沙盒外运行该命令的选项，即使该命令行本身并未提及该路径。 当拒绝是由符号链接引起，且该链接的目标超出了沙盒策略授予的范围时，拒绝信息会说明：已授予路径中的链接指向了授权范围之外，并指出其实际目标，从而让你确切知道应将哪个路径添加到沙盒策略中。 有关详细信息，请参阅“[配置本地沙盒设置](/zh/copilot/how-tos/cloud-and-local-sandboxes/configuring-local-sandbox-settings#allowing-sandbox-bypass)”。 #### 环境变量拒绝列表 CLI 会阻止内联分配环境变量，这些环境变量可以被利用以执行任意代码，即使在其他只读命令中也是如此。 阻止的类别包括： | 类别 | 示例 | | ------------------------------------------------------------------------------------------------------------------- | -- | | 动态链接器注入 | | | `LD_*`、 `DYLD_*` （所有前缀） | | | Git 索引配置覆盖 | | | `GIT_CONFIG_COUNT`、`GIT_CONFIG_KEY_*`、`GIT_CONFIG_VALUE_*`（所有`GIT_CONFIG_`前缀） | | | Git 外部程序钩子 | | | `GIT_EXTERNAL_DIFF`、`GIT_PROXY_COMMAND` | | | Git 配置文件覆盖 | | | `GIT_CONFIG`、`GIT_CONFIG_GLOBAL`、`GIT_CONFIG_SYSTEM` | | | Shell PATH 和启动文件 | | | `PATH`、`BASH_ENV`、`ENV` | | | 现有被屏蔽的变量 | | | `PAGER`、`GIT_PAGER`、`GIT_EDITOR`、`VISUAL`、`EDITOR`、`GIT_SSH`、`GIT_SSH_COMMAND`、`GIT_ASKPASS`、`BROWSER`、`GH_BROWSER` | | ### `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 )`。 当启用沙盒时，系统会在权限提示之前根据沙盒网络策略（出站访问、本地和私有主机）对请求进行检查，因此被策略阻止的目标会立即失败，而不是弹出权限提示。 如果 **“允许沙盒绕过** ”设置已打开，并且沙盒网络代理无法访问 URL（而不是策略拒绝的 URL），`web_fetch` 则会提示你在沙盒外部重试请求。 批准后会再次尝试获取，并返回其结果。 若要允许 `web_fetch` 在开发期间访问 `localhost` （例如，对于本地文档服务器），请设置以下环境变量： ```bash export COPILOT_WEB_FETCH_ALLOW_LOCALHOST=1 ``` ### 沙箱工具目录授权 启用本地沙盒后， Copilot CLI 发现沙盒命令可能需要的工具目录并授予每个 **只读** 访问权限，因此命令可以运行已安装的工具链，而无需修改它。 在进程启动之前，发现会针对每个命令运行，并从命令环境读取两种类型的源。 * **`PATH`**（在 Windows 上为 `Path`）。 列表中的每个目录都是授予候选项。 * **命名工具链变量。** CLI 检查下表中的变量。 目录值指定该目录。 路径列表在操作系统的路径分隔符（Windows 上为分号，其他系统上为冒号）处分割，每个条目都将成为授权候选项。 Git 文件变量仅在 macOS 和 Linux 上检测。 仅当候选目录是一个作为目录存在的绝对路径时，候选目录才会被接受。 相对路径、缺失路径、文件系统根（如 `/` 或 `C:\`）和系统关键位置从发现中排除。 排除位置的示例包括 Windows 上的 `%WINDIR%`，以及 macOS 和 Linux 上的 `/bin`、`/sbin`、`/usr/bin`、`/usr/sbin`、`/boot`、`/proc`、`/sys` 和 `/dev`。 原因已记录到 `sandbox_spawn`。 这些授权项保留其路径写法，而不是自动添加符号链接的目标。 如果阻止通过链接进行访问，请显式授予预期目标对象。 删除重复的目录，在 Windows 上不区分大小写。 | Variable | 工具链 | 价值 | 通常设置为 | | ----------------------- | --------------------- | ---- | ------------- | | `BAZEL_VC` | Bazel /Visual C++ | 单个目录 | Windows操作系统 | | `BAZEL_VS` | Bazel / Visual Studio | 单个目录 | Windows操作系统 | | `BAZELISK_HOME` | Bazelisk | 单个目录 | All | | `BAZELISK_HOME_DARWIN` | Bazelisk | 单个目录 | macOS | | `BAZELISK_HOME_LINUX` | Bazelisk | 单个目录 | Linux | | `BAZELISK_HOME_WINDOWS` | Bazelisk | 单个目录 | Windows操作系统 | | `CONDA_PREFIX` | Conda | 单个目录 | All | | `DOTNET_ROOT` | .NET | 单个目录 | All | | `GIT_CONFIG_SYSTEM` | Git 系统配置 | File | macOS 和 Linux | | `GIT_EXEC_PATH` | Git 辅助程序 | 单个目录 | All | | `GIT_SSL_CAINFO` | Git 证书包 | File | macOS 和 Linux | | `GIT_SSL_CAPATH` | Git 证书 | 单个目录 | All | | `GIT_TEMPLATE_DIR` | Git 模板 | 单个目录 | All | | `GOPATH` | Go | 路径列表 | All | | `GOROOT` | Go | 单个目录 | All | | `JAVA_HOME` | Java | 单个目录 | All | | `LD_LIBRARY_PATH` | 共享库 | 路径列表 | Linux | | `NODE_PATH` | Node.js | 路径列表 | All | | `NVM_HOME` | Node.js （nvm） | 单个目录 | Windows操作系统 | | `NVM_SYMLINK` | Node.js （nvm） | 单个目录 | Windows操作系统 | | `PATH` / `Path` | 可执行文件（全部） | 路径列表 | All | | `PSModulePath` | PowerShell | 路径列表 | All | | `PYENV_ROOT` | Python （pyenv） | 单个目录 | All | | `PYTHONHOME` | Python | 单个目录 | All | | `PYTHONPATH` | Python | 路径列表 | All | | `RUSTUP_HOME` | Rust（rustup） | 单个目录 | All | | `VCINSTALLDIR` | Visual C++ | 单个目录 | Windows操作系统 | | `VCPKG_ROOT` | vcpkg | 单个目录 | All | | `VIRTUAL_ENV` | Python （venv） | 单个目录 | All | | `VSINSTALLDIR` | Visual Studio | 单个目录 | Windows操作系统 | 除两个 Git 文件变量外，每个平台都会读取每个变量。 **“通常设置于”** 列显示各项通常在哪一列中填写或设置。 未设置的变量不会产生任何影响。 `CARGO_HOME` 通过针对所选 Cargo 目录和文件的工具专用授权单独处理。 它并不授予对整个 Cargo 主页的访问权限。 开发人员工具授权还可以跟随已重定位的缓存，包括 Go 和 NuGet 缓存。 这些并不是唯一的自动授权。 启用“**允许开发工具访问**”后，Copilot CLI将授予所选用户配置文件中的应用程序目录访问权限，包括 macOS 和 Linux 上的 `~/.local/bin` 和 `~/.local/lib`，以及 Windows 上 `%LOCALAPPDATA%\Programs` 的直接子目录。 它还授予特定于工具的缓存和软件包注册源，其中一些是可写的，例如 npm 的缓存和共享生成缓存。 运行 `/sandbox policy` 以查看按源和访问权限分组的已解析路径。 **“开发工具”** 部分列出了当前目录中检测到的工具及其路径。 添加命令，例如 `/sandbox policy npm install`，在不运行该命令的情况下检查其开发人员工具访问权限。 报表不会创建缺失的缓存。 有关如何组合策略的概念，请参阅 [了解 GitHub Copilot CLI 中用于本地沙盒的文件系统策略](/zh/copilot/concepts/agents/copilot-cli/understanding-local-sandboxing)。 ## OpenTelemetry 监视 Copilot CLI 可以通过 [OpenTelemetry（OTel](https://opentelemetry.io/) ）导出跟踪和指标，从而了解代理交互、LLM 调用、工具执行和令牌使用情况。 所有信号名称和属性都遵循 [OTel GenAI 语义约定](https://github.com/open-telemetry/semantic-conventions-genai/tree/main/docs/gen-ai/)。 默认情况下，OTel 处于关闭状态，开销为零。 当满足以下任一条件时，它将激活： * `COPILOT_OTEL_ENABLED=true` * `OTEL_EXPORTER_OTLP_ENDPOINT` 已设置 * `COPILOT_OTEL_FILE_EXPORTER_PATH` 已设置 OTel 配置也可以在 VS Code 中设置，或者在企业范围内的 `managed-settings.json` 文件中设置。 请参阅 [](https://code.visualstudio.com/docs/agents/guides/monitoring-agents#_enable-otel-monitoring) 文档中的 VS Code 和 [企业管理设置](/zh/copilot/reference/enterprise-administrators/enterprise-managed-settings)。 ### OTel 环境变量 | Variable | 默认 | 说明 | | ---------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------ | | `COPILOT_OTEL_ENABLED` | `false` | 显式启用 OTel。 如果 `OTEL_EXPORTER_OTLP_ENDPOINT` 已设置，则不是必需的。 | | `OTEL_EXPORTER_OTLP_ENDPOINT` | — | OTLP 终结点 URL。 设置此项会自动启用 OTel。 | | `COPILOT_OTEL_EXPORTER_TYPE` | `otlp-http` | 导出程序类型： `otlp-http` 或 `file`。 当设置`file`时自动选择`COPILOT_OTEL_FILE_EXPORTER_PATH`。 | | `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/json` | OTLP HTTP 线路协议： `http/json` 或 `http/protobuf`。 仅适用于 `otlp-http` 导出器。 | | `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` | — | 仅为跟踪覆盖 `OTEL_EXPORTER_OTLP_PROTOCOL`。 | | `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` | — | 仅为指标覆盖 `OTEL_EXPORTER_OTLP_PROTOCOL`。 | | `OTEL_SERVICE_NAME` | `github-copilot` | 资源属性中的服务名称。 | | `OTEL_RESOURCE_ATTRIBUTES` | — | 逗号分隔的 `key=value` 对的额外资源属性。 对特殊字符使用百分比编码。 | | `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | `false` | 捕获完整的提示和响应内容。 请参阅 [内容捕获](#content-capture)。 | | `OTEL_LOG_LEVEL` | — | OTel 诊断日志级别：`NONE`、、`ERROR``WARN`、`INFO``DEBUG`、`VERBOSE`。 `ALL` | | `COPILOT_OTEL_FILE_EXPORTER_PATH` | — | 将所有信号作为 JSON 行写入此文件。 设置此项会自动启用 OTel。 | | `COPILOT_OTEL_SOURCE_NAME` | `github.copilot` | 用于跟踪程序和计量的检测范围名称。 | | `OTEL_EXPORTER_OTLP_HEADERS` | — | OTLP 导出器（例如 `Authorization=Bearer token`）的身份验证头。 | ### Traces 运行时为每个智能体交互发出分层跨度树。 每个树都包含根`invoke_agent`范围，以及`chat``execute_tool`子范围。 #### `invoke_agent` span 属性 包装整个智能体调用：一个用户消息的所有 LLM 调用和工具执行。 * 无论是**顶级会话**还是**子智能体调用**（例如 explore、task），都使用 span 类型 `INTERNAL`（进程内）；面向提供者的推断则由子 `CLIENT``chat` span 表示。 * **顶层会话**还会携带`server.address`和`server.port`；子代理调用则不会携带。 | Attribute | 说明 | Scope | | ------------------------------------------ | --------------------------------------------------- | ----- | | `gen_ai.operation.name` | `invoke_agent` | 两者都有 | | `gen_ai.provider.name` | 提供者（例如`github`、`anthropic`） | 两者都有 | | `gen_ai.agent.id` | 已知时稳定的代理定义标识符;顶级默认使用 `github.copilot.default` | 两者都有 | | `gen_ai.agent.name` | 代理名称（可用时） | 两者都有 | | `gen_ai.agent.description` | 代理说明（可用时） | 两者都有 | | `gen_ai.agent.version` | 已知时代理定义版本;否则为运行时版本 | 两者都有 | | `gen_ai.conversation.id` | 会话标识符 | 两者都有 | | `enduser.pseudo.id` | 若可用，从 `analytics_tracking_id` 获取假名 Copilot 用户标识符 | 两者都有 | | `gen_ai.request.model` | 请求的模型 | 两者都有 | | `gen_ai.response.finish_reasons` | | | | `["stop"]` 或 `["error"]` | 两者都有 | | | `gen_ai.usage.input_tokens` | 总输入令牌数（所有轮次） | 两者都有 | | `gen_ai.usage.output_tokens` | 总输出标记（所有轮次） | 两者都有 | | `gen_ai.usage.cache_read.input_tokens` | 读取缓存的输入令牌 | 两者都有 | | `gen_ai.usage.cache_creation.input_tokens` | 创建的缓存输入令牌 | 两者都有 | | `github.copilot.turn_count` | LLM 往返次数 | 两者都有 | | `github.copilot.cost` | 用于计费的每请求模型乘数。 | | | **不是货币值。** | 两者都有 | | | `github.copilot.nano_aiu` | 已消耗的 AI 单位，以纳 AI 单位计（1 AIU = 1,000,000,000 纳 AI 单位） | 两者都有 | | `server.address` | 服务器主机名 | 仅限顶层 | | `server.port` | 服务器端口 | 仅限顶层 | | `error.type` | 错误类名称（出错时） | 两者都有 | | `gen_ai.input.messages` | 完整输入消息作为 JSON 格式（仅限内容捕获） | 两者都有 | | `gen_ai.output.messages` | JSON格式的完整输出消息（仅用于捕获内容） | 两者都有 | | `gen_ai.system_instructions` | JSON 格式的系统提示内容（仅限内容捕获） | 两者都有 | | `gen_ai.tool.definitions` | 工具模式为 JSON（仅内容捕获） | 两者都有 | #### `chat` span 属性 每个 LLM 请求一个跨度。 范围类型： `CLIENT`. | Attribute | 说明 | | ------------------------------------------ | -------------------------------------------------- | | `gen_ai.operation.name` | `chat` | | `gen_ai.provider.name` | 提供者名称 | | `gen_ai.request.model` | 请求的模型 | | `gen_ai.request.stream` | 是否使用了流式处理模式（仅流式处理） | | `gen_ai.conversation.id` | 会话标识符 | | `gen_ai.response.finish_reasons` | 停止原因 | | `gen_ai.response.id` | 响应 ID | | `gen_ai.response.model` | 已解析的模型 | | `gen_ai.response.time_to_first_chunk` | 首次流式处理区块的时间（以秒为单位）（仅流式处理） | | `gen_ai.usage.cache_creation.input_tokens` | 创建的缓存令牌 | | `gen_ai.usage.cache_read.input_tokens` | 读取缓存令牌 | | `gen_ai.usage.input_tokens` | 此轮次输入令牌 | | `gen_ai.usage.output_tokens` | 此轮次输出令牌 | | `github.copilot.cost` | 用于计费的每请求模型乘数。 | | **不是货币值。** | | | `github.copilot.nano_aiu` | 此轮消耗的 AI 单元，以纳 AI 单元计（1 AIU = 1,000,000,000 纳 AIU） | | `github.copilot.server_duration` | 服务器端持续时间 | | `github.copilot.initiator` | 请求发起者 | | `github.copilot.turn_id` | 轮次标识符 | | `github.copilot.interaction_id` | 交互标识符 | | `server.address` | 服务器主机名 | | `server.port` | 服务器端口 | | `error.type` | 错误类名称（出错时） | | `gen_ai.input.messages` | JSON 格式的完整提示消息（仅限内容捕获） | | `gen_ai.output.messages` | JSON 形式的完整响应消息（仅内容捕获） | | `gen_ai.system_instructions` | JSON 格式的系统提示内容（仅限内容捕获） | #### `execute_tool` span 属性 为每个工具调用指定一个跨度。 范围类型： `INTERNAL`. | Attribute | 说明 | | ---------------------------- | ---------------------- | | `gen_ai.operation.name` | `execute_tool` | | `gen_ai.provider.name` | 提供程序名称（如果可用） | | `gen_ai.tool.name` | 工具名称（例如， `readFile`） | | `gen_ai.tool.type` | `function` | | `gen_ai.tool.call.id` | 工具调用标识符 | | `gen_ai.tool.description` | 工具说明 | | `error.type` | 错误类名称（出错时） | | `gen_ai.tool.call.arguments` | 工具输入参数以 JSON 格式（仅内容捕获） | | `gen_ai.tool.call.result` | 工具输出为 JSON（仅限内容捕获） | > \[!NOTE] > 若要测量 AI 单位消耗量，请仅从根`github.copilot.nano_aiu`跨度读取`invoke_agent`。 该属性也会标记在子 `chat` span 上，因此如果在每个 span 上都对其进行求和，就会导致重复计数。 > `github.copilot.cost` 是用于计费计算的按请求模型乘数，它不是货币值，不能解释为一个。 ### Metrics #### GenAI 约定指标 | Metric | 类型 | 单位 | 说明 | | ----------------------------------------------- | --- | ------------------ | ---------------------------------------------------------------------------------------- | | `gen_ai.client.operation.duration` | 直方图 | s | LLM API 调用和代理调用持续时间 | | `gen_ai.client.token.usage` | 直方图 | tokens | 按类型排序的令牌计数 （`input`/`output`） | | `gen_ai.client.operation.time_to_first_chunk` | 直方图 | s | 接收第一个流媒体数据块的时间 | | `gen_ai.client.operation.time_per_output_chunk` | 直方图 | s | 第一个区块后的区块间延迟 | | `gen_ai.invoke_agent.duration` | 直方图 | s | 一个代理调用的端到端持续时间 | | `gen_ai.invoke_agent.inference_calls` | 直方图 | `{inference_call}` | 单次代理调用期间发起的模型调用次数，在提供方分发时计数（包括失败和部分调用；不包括在分发前被阻止的请求）。 维度： `gen_ai.agent.name`. | | `gen_ai.invoke_agent.tool_calls` | 直方图 | `{tool_call}` | 在一个代理调用期间进行的客户端工具调用数（包括失败和部分调用）;不包括合成 CLI 工具生命周期和提供程序执行的服务器端工具。 维度： `gen_ai.agent.name`. | | `gen_ai.invoke_workflow.duration` | 直方图 | s | GenAI 工作流的端到端持续时间（例如编排并行子智能体的机群模式运行）。 | #### 特定于供应商的指标 | Metric | 类型 | 单位 | 说明 | | -------------------------------------------- | ------- | ----- | -------------------------------------- | | `github.copilot.tool.call.count` | Counter | calls | 通过 `gen_ai.tool.name` 和 `success` 调用工具 | | `github.copilot.tool.call.duration` | 直方图 | s | 工具执行由 `gen_ai.tool.name` 产生的延迟 | | `github.copilot.agent.turn.count` | 直方图 | 轮次 | 每个代理调用的 LLM 往返次数 | | `github.copilot.mcp.server.connection.count` | Counter | 尝试 | 按传输方式和结果划分的已完成 MCP 服务器连接尝试次数 | | `github.copilot.code.lines_added` | Counter | lines | 由文件编辑工具添加的行，实时记录 | | `github.copilot.code.lines_removed` | Counter | lines | 文件编辑工具删除的行会被实时记录 | ### 跨度事件 在活动 `chat` 或 `invoke_agent` 跨度上记录的生命周期事件。 | 事件 | 说明 | 密钥属性 | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------- | | `github.copilot.hook.start` | 挂钩开始执行 | | | `github.copilot.hook.type`、`github.copilot.hook.invocation_id` | | | | `github.copilot.hook.end` | 挂钩成功完成 | | | `github.copilot.hook.type`、`github.copilot.hook.invocation_id` | | | | `github.copilot.hook.error` | 挂钩失败 | | | `github.copilot.hook.type`、`github.copilot.hook.invocation_id`、`github.copilot.hook.error_message` | | | | `github.copilot.session.truncation` | 对话历史记录被截断 | | | `github.copilot.token_limit`、`github.copilot.pre_tokens`、`github.copilot.post_tokens`、`github.copilot.pre_messages`、`github.copilot.post_messages`、`github.copilot.tokens_removed`、`github.copilot.messages_removed`、`github.copilot.performed_by` | | | | `github.copilot.session.compaction_start` | 历史压缩开始 | 没有 | | `github.copilot.session.compaction_complete` | 已完成历史记录压缩 | | | `github.copilot.success`、`github.copilot.pre_tokens`、`github.copilot.post_tokens`、`github.copilot.tokens_removed`、`github.copilot.messages_removed`、`github.copilot.message`（仅内容捕获） | | | | `github.copilot.skill.invoked` | 调用了技能 | | | `github.copilot.skill.name`、`github.copilot.skill.path`、`github.copilot.skill.plugin_name`、`github.copilot.skill.plugin_version` | | | | `github.copilot.session.shutdown` | 会话正在关闭 | | | `github.copilot.shutdown_type`、`github.copilot.total_premium_requests`、`github.copilot.lines_added`、`github.copilot.lines_removed`、`github.copilot.files_modified_count` | | | | `github.copilot.session.abort` | 用户取消了当前操作 | `github.copilot.abort_reason` | | `exception` | 会话错误 | | | `github.copilot.error_type`、`github.copilot.error_status_code`、`github.copilot.error_provider_call_id` | | | ### 资源属性 所有信号都携带这些资源属性。 | Attribute | 价值 | | ------------------------------------------ | ----- | | `service.name` | | | `github-copilot` （可通过 `OTEL_SERVICE_NAME`） | | | `service.version` | 运行时版本 | ### 内容捕获 默认情况下，不会捕获提示内容、响应或工具参数，仅捕获模型名称、令牌计数和持续时间等元数据。 若要捕获完整内容，请设置 `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true`。 > \[!WARNING] > 内容捕获可能包括敏感信息，例如代码、文件内容和用户提示。 仅在受信任的环境中启用此功能。 启用内容捕获后，将填充以下属性。 | Attribute | Content | | ---------------------------- | ------------- | | `gen_ai.input.messages` | 完整提示消息 （JSON） | | `gen_ai.output.messages` | 完整响应消息 （JSON） | | `gen_ai.system_instructions` | 系统提示内容 （JSON） | | `gen_ai.tool.definitions` | 工具架构 （JSON） | | `gen_ai.tool.call.arguments` | 工具输入参数 | | `gen_ai.tool.call.result` | 工具输出结果 | ## 延伸阅读 * [GitHub Copilot CLI](/zh/copilot/how-tos/copilot-cli) * [GitHub Copilot 挂钩参考](/zh/copilot/reference/hooks-reference) * [GitHub Copilot CLI 插件参考](/zh/copilot/reference/copilot-cli-reference/cli-plugin-reference) * [GitHub Copilot 命令行界面编程参考](/zh/copilot/reference/copilot-cli-reference/cli-programmatic-reference) * [GitHub Copilot CLI 配置目录](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference)