# GitHub Copilot CLI 命令参考
查找有助于有效使用的 Copilot 命令行界面（CLI） 命令和键盘快捷方式。
## 命令行命令
| 命令 | Purpose |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `copilot` | 启动交互式用户界面。 |
| `copilot completion SHELL` | 生成一份适用于所选 Shell 的 shell 脚本，你可以利用该脚本来为 Copilot 命令行界面（CLI） 启用 Tab 键补全功能。 支持的 shell： `bash`、 `zsh`、 `fish`。 请参阅[使用 `copilot completion`](#using-copilot-completion)。 |
| `copilot help [TOPIC]` | 显示帮助信息。 帮助主题包括：`config`、、、`commands``environment`、`logging``monitoring`、 `permissions`和`providers`。 |
| `copilot init` | 初始化 Copilot 此存储库的自定义说明。 |
| `copilot login` | 使用 OAuth 设备流通过 Copilot进行身份验证。 接受 `--host HOST` 以指定 GitHub 主机 URL （默认值： `https://github.com`） 。 |
| `copilot login` \[选项] | 使用 OAuth 设备流通过 Copilot进行身份验证。 请参阅 [`copilot login` 选项](#copilot-login-options)。 |
| `copilot mcp` | 从命令行管理 MCP 服务器配置。 |
| `copilot plugin` | 管理插件和插件市场。 |
| `copilot update` | 下载并安装最新版本。 |
| `copilot version` | 显示版本信息并检查更新。 |
###
```
`copilot login` 选项
```
| 选项 | Purpose |
| ------------- | ------- |
| `--host HOST` | |
```
GitHub 主机 URL （默认值： `https://github.com`） 。 使用此方法向使用数据驻留（例如 `https://example.ghe.com`）的 GitHub Enterprise Cloud 实例进行身份验证。 |
```
默认身份验证模式是基于 Web 的浏览器流。 完成后，身份验证令牌安全地存储在系统凭据存储中。 如果未找到凭据存储，则令牌存储在纯文本配置文件中`~/.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
# Use a fine-grained PAT via environment variable
COPILOT_GITHUB_TOKEN=github_pat_... copilot
```
### 使用 `copilot completion`
该命令 `copilot completion SHELL` 输出指定 shell（bash、zsh 或 fish）的脚本。
通过执行该脚本（或将其写入 shell 的补全目录），即可在终端中为 `copilot` 的子命令、命令选项以及命令选项的已知取值，启用 Tab 键自动补全功能。
#### 用法示例
Bash （仅限当前会话）：
```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
```
## 交互式界面中的全局快捷方式
| Shortcut | Purpose |
| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
| `@ FILENAME` | 将文件内容包含在上下文中。 |
| `# NUMBER` | 在上下文中包含 GitHub 问题或拉取请求。 |
| `! COMMAND` | 在本地 shell 中执行命令，绕过 Copilot。 |
| `?` | 打开快速帮助（在空白提示中）。 |
| Esc | 取消当前操作。 |
| Ctrl+C | 取消操作/清除输入。 按两次退出。 |
| Ctrl+D | 关闭。 |
| Ctrl+G | 在外部编辑器中编辑提示（`$EDITOR`）。 |
| Ctrl+L | 清除屏幕。 |
| Ctrl+Enter 或 Ctrl+Q | 将消息排队，以在智能体繁忙时发送。 |
| Ctrl+R | 反向搜索命令历史记录。 |
| Ctrl+V | 从剪贴板粘贴为附件。 |
| Ctrl+然后 X`/` | 开始键入提示后，这样就可以运行斜杠命令，例如，如果要更改模型，而无需重新键入提示。 |
| Ctrl+然后 X`e` | 在外部编辑器中编辑提示（`$EDITOR`）。 |
| Ctrl+然后 X`o` | 从时间线打开最新的链接。 |
| Ctrl+Z | 将进程挂起到后台 (Unix)。 |
| Shift+Enter 或 Option+Enter （Mac） / Alt+Enter （Windows/Linux） | 在输入中插入换行符。 |
| Shift键+Tab键 | 在标准模式、计划和 Autopilot 模式之间循环。 |
## 交互式界面中的时间线快捷方式
| Shortcut | Purpose |
| ------------------------------- | ------------------------------------------------- |
| Ctrl+O | 虽然提示输入中没有任何内容，但这会扩展 Copilot 回复时间线中的最近项目以显示更多详细信息。 |
| Ctrl+E | 虽然提示输入中没有任何内容，但这会展开Copilot的响应时间轴中的所有项。 |
| Ctrl+T | 在响应中展开/折叠推理显示。 |
| 向上翻页/向下翻页 | 将当前时间线视图向上或向下翻动一页。 |
## 交互式界面中的导航快捷方式
| Shortcut | Purpose |
| ------------------------------------------------------------ | ---------------------------- |
| Ctrl+A | 移动到行首（输入时）。 |
| Ctrl+B | 移到上一个字符。 |
| Ctrl+E | 移动到行的末尾（键入时）。 |
| Ctrl+F | 移动到下一个字符。 |
| Ctrl+H | 删除上一个字符。 |
| Ctrl+K | 从光标删除到行尾。 如果光标位于行的末尾，请删除换行符。 |
| Ctrl+U | 从光标删除到行首。 |
| Ctrl+W | 删除上一个单词。 |
| 主页 | 移动到文本的开头。 |
| 结束 | 移动到文本的末尾。 |
| Alt+←/→ （Windows/Linux）
| |
```
选项+←/→ （Mac） | 按单词移动光标。 |
```
\| ↑/↓ | 浏览命令历史。 |
\| Tab键 / Ctrl+Y | 接受当前的内联补全建议。 |
## 交互式接口中的斜杠命令
| 命令 | Purpose |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/add-dir PATH` | 将目录添加到允许的文件访问列表。 |
| `/agent` | 浏览并选择可用代理（如果有）。 请参阅“[关于自定义代理](/zh/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/about-custom-agents)”。 |
| `/ask QUESTION` | 在不添加到对话历史记录的情况下提出一个快速的附带问题。 仅在实验模式下可用。 |
| `/allow-all [on\|off\|show]`、`/yolo [on\|off\|show]` | 启用所有权限（工具、路径和 URL）。 |
| `/changelog [summarize] [VERSION\|last N\|since VERSION]`、`/release-notes [summarize] [VERSION\|last N\|since VERSION]` | 显示 CLI 更改日志。 可选地指定一个版本、最近发布的版本数量或起始版本。 请为 AI 生成的摘要添加关键字 `summarize` 。 |
| `/chronicle ` | 会话历史工具和分析。 仅在实验模式下可用。 |
| `/clear [PROMPT]`、`/new [PROMPT]`、`/reset [PROMPT]` | 启动新对话。 |
| `/compact` | 汇总对话历史记录以减少上下文窗口使用情况。 请参阅“[在 GitHub Copilot 命令行界面 (CLI) 中管理上下文](/zh/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/context-management#compaction)”。 |
| `/context` | 显示上下文窗口令牌使用情况和可视化效果。 请参阅“[在 GitHub Copilot 命令行界面 (CLI) 中管理上下文](/zh/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/context-management#checking-your-context-usage)”。 |
| `/copy` | 将最后一个响应复制到剪贴板。 |
| `/cwd`、`/cd [PATH]` | 更改工作目录或显示当前目录。 |
| `/delegate [PROMPT]` | 使用 AI 生成的拉取请求提交更改到远程存储库。 请参阅“[将任务委派给 Copilot](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/use-copilot-cli/delegate-tasks-to-cca)”。 |
| `/diff` | 查看当前目录中所做的更改。 |
| `/downgrade ` | 下载并重启到特定 CLI 版本。 可用于团队帐户。 |
| `/env` | 显示加载的环境详细信息（说明、MCP 服务器、技能、代理、插件、LSP、扩展）。 |
| `/exit`、`/quit` | 退出 CLI。 |
| `/experimental [on\|off\|show]` | 切换、设置或显示实验性功能。 |
| `/feedback`、`/bug` | 提供有关 CLI 的反馈。 |
| `/fleet [PROMPT]` | 支持对任务的某些部分进行并行子代理执行。 请参阅“[使用 \`/fleet\` 命令并行运行任务](/zh/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/fleet)”。 |
| `/help` | 显示交互式命令的帮助。 |
| `/ide` | 连接到 IDE 工作区。 请参阅“[连接GitHub Copilot 命令行界面 (CLI)到VS Code](/zh/enterprise-cloud@latest/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\|busy\|NUMBERm\|NUMBERh]` | 防止计算机进入睡眠状态：当命令行界面（CLI）会话处于活动状态，或者软件代理繁忙，或者在设定的时间段内。 仅在实验模式下可用。 |
| `/list-dirs` | 显示允许访问文件的所有目录。 |
| `/login` | 登录到 Copilot。 |
| `/logout` | 注销 Copilot。 |
| `/lsp [show\|test\|reload\|help] [SERVER-NAME]` | 管理语言服务器配置。 |
| `/mcp [show\|add\|edit\|delete\|disable\|enable\|auth\|reload] [SERVER-NAME]` | 管理 MCP 服务器配置。 请参阅“[为 GitHub Copilot 命令行界面 (CLI) 添加 MCP 服务器](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers#managing-mcp-servers)”。 |
| `/model`、`/models [MODEL]` | 选择要使用的 AI 模型。 |
| `/plan [PROMPT]` | 在编码之前创建实现计划。 |
| `/plugin [marketplace\|install\|uninstall\|update\|list] [ARGS...]` | 管理插件和插件市场。 请参阅“[关于 GitHub Copilot 命令行界面 (CLI) 的插件](/zh/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/about-cli-plugins)”。 |
| `/pr [view\|create\|fix\|auto]` | 管理当前分支的拉取请求。 请参阅“[使用 /pr 命令管理拉取请求](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests)”。 |
| `/remote [on\|off]` | 显示远程控制状态（如果未提供任何参数）、启用远程转向（`on`）或结束远程连接（`off`）。 请参阅“[通过其他设备控制 GitHub Copilot 命令行界面 (CLI) 会话](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely)”。 |
| `/rename [NAME]` | 重命名当前会话（如果省略，将自动生成名称；这是`/session rename`的别名）。 |
| `/research TOPIC` | 使用 GitHub 搜索和 Web 源进行深入调查。 请参阅“[使用GitHub Copilot 命令行界面 (CLI)进行研究](/zh/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/research)”。 |
| `/reset-allowed-tools` | 重置允许的工具列表。 |
| `/restart` | 重启 CLI，保留当前会话。 |
| `/resume [SESSION-ID]`、`/continue [SESSION-ID]` | 通过从列表中选择（可选指定会话 ID）切换到其他会话。 |
| `/review [PROMPT]` | 运行代码评审代理以分析更改。 请参阅“[使用 GitHub Copilot 命令行界面 (CLI) 请求代码评审](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/use-copilot-cli/agentic-code-review)”。 |
| `/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`、、、`checkpoints`、`files``plan``rename``cleanup`、`prune`、。 `delete``delete-all` |
| `/share [file\|html\|gist] [session\|research] [PATH]`、`/export [file\|html\|gist] [session\|research] [PATH]` | 将会话共享到 Markdown 文件、交互式 HTML 文件或 GitHub gist。 |
| `/skills [list\|info\|add\|remove\|reload] [ARGS...]` | 管理技能以提升能力。 请参阅“[为 GitHub Copilot 命令行界面 (CLI) 添加代理技能](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot/create-skills)”。 |
| `/statusline`、`/footer` | 配置状态行中显示的项。 |
| `/tasks` | 查看和管理后台任务（子代理和 shell 会话）。 |
| `/terminal-setup` | 为多行输入支持配置终端（Shift+Enter 和 Ctrl+Enter）。 |
| `/theme [default\|dim\|high-contrast\|colorblind]` | 查看或设置颜色模式。 |
| `/undo`、`/rewind` | 倒退最后一轮并还原文件更改。 |
| `/update`、`/upgrade` | 将 CLI 更新到最新版本。 |
| `/usage` | 显示会话使用情况指标和统计信息。 |
| `/user [show\|list\|switch]` | 管理当前 GitHub 用户。 |
| `/version` | 显示版本信息并检查更新。 |
要获取所有可用的斜杠命令的完整列表，请在 CLI 的交互式界面中输入 `/help`。
## 命令行选项
| 选项 | Purpose |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--add-dir=PATH` | 将目录添加到允许的文件访问列表（可多次使用）。 |
| `--add-github-mcp-tool=TOOL` | 添加工具以启用 GitHub MCP 服务器，而不是默认 CLI 子集（可多次使用）。 将 `*` 用于所有工具。 |
| `--add-github-mcp-toolset=TOOLSET` | 添加工具集以启用 GitHub MCP 服务器，而不是默认 CLI 子集（可多次使用）。 对所有工具集使用 `all`。 |
| `--additional-mcp-config=JSON` | 仅为此会话添加 MCP 服务器。 服务器配置可以作为 JSON 字符串或文件路径（前缀） `@`提供。 从 `~/.copilot/mcp-config.json` 扩充配置。 覆盖任何已安装的同名 MCP 服务器配置。 请参阅“[为 GitHub Copilot 命令行界面 (CLI) 添加 MCP 服务器](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers)”。 |
| `--agent=AGENT` | 指定要使用的值 自定义智能体 。 请参阅“[关于自定义代理](/zh/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/about-custom-agents)”。 |
| `--allow-all` | 启用所有权限（等效于 `--allow-all-tools --allow-all-paths --allow-all-urls`）。 |
| `--allow-all-paths` | 禁用文件路径验证并允许访问任何路径。 |
| `--allow-all-tools` | 允许所有工具在不确认的情况下自动运行。 以编程方式使用 CLI 时是必需的（env： `COPILOT_ALLOW_ALL`）。 |
| `--allow-all-urls` | 允许在没有确认的情况下访问所有 URL。 |
| `--allow-tool=TOOL ...` | CLI 有权使用的工具。 不会提示输入权限。 对于多个工具，请使用带引号的逗号分隔列表。 请参阅“[允许和拒绝工具使用](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/allowing-tools#allowing-or-denying-permission-for-specific-tools)”。 |
| `--allow-url=URL ...` | 允许访问特定的网址或域。 对于多个 URL，请使用带引号的逗号分隔列表。 |
| `--autopilot` | 在提示模式下启用 Autopilot 延续。 请参阅“[允许 GitHub Copilot CLI 自主工作](/zh/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/autopilot)”。 |
| `--available-tools=TOOL ...` | 只有这些工具可供模型使用。 对于多个工具，请使用带引号的逗号分隔列表。 请参阅“[允许和拒绝工具使用](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/allowing-tools)”。 |
| `--banner`、`--no-banner` | 显示或隐藏启动横幅。 |
| `--bash-env` | 启用 `BASH_ENV` 对 bash shell 的支持。 |
| `--connect[=SESSION-ID]` | 直接连接到远程会话（可选）指定会话 ID 或任务 ID。 与 `--resume` 和 `--continue`. |
| `--continue` | 恢复当前工作目录中的最新会话，回退到全局最新会话。 |
| `--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`）。 |
| `--enable-all-github-mcp-tools` | 启用所有 GitHub MCP 服务器工具，而不是默认 CLI 子集。 |
```
`--add-github-mcp-toolset`和`--add-github-mcp-tool`选项被覆盖。 |
```
\| `--enable-reasoning-summaries` | 请求对支持它的 OpenAI 模型进行推理摘要。 |
\| `--excluded-tools=TOOL ...` | 这些工具将不适用于模型。 对于多个工具，请使用带引号的逗号分隔列表。 |
\| `--experimental` | 启用实验性功能（使用 `--no-experimental` 进行禁用）。 |
\| `-h`、`--help` | 显示帮助。 |
\| `-i PROMPT`、`--interactive=PROMPT` | 启动交互式会话并自动执行此提示。 |
\| `--log-dir=DIRECTORY` | 设置日志文件目录（默认值： `~/.copilot/logs/`）。 |
\| `--log-level=LEVEL` | 设置日志级别（选项：`none`、、`error``warning`、`info`、`debug`、`all``default`）。 |
\| `--max-autopilot-continues=COUNT` | Autopilot 模式下的最大延续消息数（默认值：无限制）。 请参阅“[允许 GitHub Copilot CLI 自主工作](/zh/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/autopilot)”。 |
\| `--mode=MODE` | 设置初始代理模式（选项：`interactive`、、`plan``autopilot`）。 不能与 `--autopilot` 或 `--plan`. |
\| `--model=MODEL` | 设置要使用的 AI 模型。 传递`auto`让Copilot自动选择最佳可用模型。 |
\| `--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` | 禁用此会话的远程访问。 |
\| `--output-format=FORMAT` | FORMAT 可以是 `text` （默认值）或 `json` （输出 JSONL：每行一个 JSON 对象）。 |
\| `-p PROMPT`、`--prompt=PROMPT` | 以编程方式执行提示（完成后退出）。 请参阅“[以编程方式运行GitHub Copilot 命令行界面 (CLI)](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/automate-copilot-cli/run-cli-programmatically)”。 |
\| `--plan` | 在计划模式下启动。
`--mode plan` 的速记。 不能与 `--mode` 或 `--autopilot`. |
\| `--plain-diff` | 禁用富差异渲染（通过你的 git 配置指定的差异工具进行语法高亮显示）。 |
\| `--plugin-dir=DIRECTORY` | 从本地目录加载插件（可以多次使用）。 |
\| `--remote` | 启用从GitHub.com和GitHub Mobile远程访问此会话。 请参阅“[通过其他设备控制 GitHub Copilot 命令行界面 (CLI) 会话](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely)”。 |
\| `--resume[=VALUE]` | 通过从列表中选择来恢复以前的交互式会话。 （可选）指定会话 ID、ID 前缀或会话名称。 名称匹配精确且不区分大小写;当没有显式名称匹配时，回退到自动生成的摘要。 |
\| `-s`、`--silent` | 仅输出代理响应（不使用使用情况统计信息），对于使用 `-p`脚本编写非常有用。 |
\| `--screen-reader` | 启用屏幕阅读器优化。 |
\| `--secret-env-vars=VAR ...` | 从 shell 和 MCP 服务器环境（可以多次使用）中修订环境变量。 对于多个变量，请使用带引号的逗号分隔列表。 默认情况下， `GITHUB_TOKEN` 和 `COPILOT_GITHUB_TOKEN` 环境变量中的值会从输出中隐藏。 |
\| `--share=PATH` | 程序化会话结束后，将会话共享到 Markdown 文件（默认路径：`./copilot-session-.md`）。 |
\| `--share-gist` | 在编程会话完成后，将会话共享给机密 GitHub gist。 |
\| `--stream=MODE` | 启用或禁用流模式（模式选项： `on` 或 `off`）。 |
\| `-v`、`--version` | 显示版本信息。 |
\| `--yolo` | 启用所有权限（等效于 `--allow-all`）。 |
有关命令和选项的完整列表，请运行 `copilot help`。
> \[!NOTE]
> 选项`--remote`、`--no-remote`和`--connect`需要您的帐户具有远程会话功能。
## 工具可用性值
和`--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` | 运行子代理 |
### 其他工具
| 工具名称 | 说明 |
| -------------- | ------------------------- |
| `ask_user` | 向用户提问 |
| `glob` | 查找匹配模式的文件 |
| `grep`（或 `rg`） | 搜索文件中的文本 |
| `show_file` | 将代码段内联展示在时间线中。 仅在实验模式下可用。 |
| `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'
```
## 环境变量
| Variable | 说明 |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `COLORFGBG` | 适用于深色/浅色终端背景检测的回退。 |
| `COPILOT_ALLOW_ALL` | 将其设置为 `true` 以自动允许所有权限（相当于 `--allow-all`）。 |
| `COPILOT_AUTO_UPDATE` | 设置为 `false` 禁用自动更新。 |
| `COPILOT_CACHE_HOME` | 替代缓存目录（用于市场缓存、自动更新包和其他临时数据）。 有关平台默认值，请参阅 [GitHub Copilot CLI 配置目录](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-config-dir-reference#changing-the-location-of-the-configuration-directory) 。 |
| `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` | 自定义说明中额外目录的逗号分隔列表。 |
| `COPILOT_EDITOR` | 用于交互式编辑的编辑器命令（在 `$VISUAL` 和 `$EDITOR` 后检查）。 如果未设置，则默认为`vi`。 |
| `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_MODEL` | 设置 AI 模型。 |
\| `COPILOT_PROMPT_FRAME` |
`1`设置为在输入提示周围启用装饰性 UI 框架，或`0`将其禁用。 替代当前会话的 `PROMPT_FRAME` 实验性功能标志。 |
\| `COPILOT_SKILLS_DIRS` | 技能附加目录的逗号分隔列表。 |
\| `COPILOT_SUBAGENT_MAX_CONCURRENT` | 整个会话树中的最大并发子代理数。 默认值：`32`。 范围： `1`–`256`. |
\| `COPILOT_SUBAGENT_MAX_DEPTH` | 最大子代理嵌套深度。 默认值：`6`。 范围： `1`–`256`. |
\| `GH_HOST` | GitHub 和 GitHub CLI 的 Copilot 命令行界面（CLI） 主机名（默认值：`github.com`）。 将其设置为带有数据驻留主机名的 GitHub Enterprise Cloud。 仅替代为 Copilot 命令行界面（CLI） 的 `COPILOT_GH_HOST`。 |
\| `GH_TOKEN` | 身份验证令牌。 优先于 `GITHUB_TOKEN`. |
\| `GITHUB_TOKEN` | 身份验证令牌。 |
\| `PLAIN_DIFF` | 设置为 `true` 以禁用多差异呈现。 |
\| `USE_BUILTIN_RIPGREP` | 设置为 `false` 以使用系统 ripgrep，而不是捆绑的版本。 |
## 配置文件设置
有关配置文件设置的详细信息（包括用户设置、存储库设置、本地设置及其级联方式的完整列表），请参阅 [GitHub Copilot CLI 配置目录](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings)。
> \[!NOTE]
> 用户设置以前存储在 `~/.copilot/config.json`. 该位置中的现有用户可编辑设置将在启动时自动迁移到 `~/.copilot/settings.json` 该位置。
##
```
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/enterprise-cloud@latest/copilot/how-tos/configure-custom-instructions/add-repository-instructions)”。
## 挂钩引用
有关挂钩的详细信息（包括挂钩配置格式、挂钩事件、输入有效负载和决策控制），请参阅 [GitHub Copilot CLI 挂钩参考](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-hooks-reference)。
## MCP 服务器配置
MCP 服务器向 CLI 代理提供其他工具。 在`~/.copilot/mcp-config.json`中配置持久性服务器。 使用 `--additional-mcp-config` 来为单个会话添加服务器。
###
```
`copilot mcp` 子命令
```
用于 `copilot mcp` 从命令行管理 MCP 服务器配置，而无需启动交互式会话。
| 子命令 | 说明 |
| --------------------- | ---------------------------------------------- |
| `list [--json]` | 列出按源分组的所有已配置的 MCP 服务器。 |
| `get [--json]` | 显示特定服务器的配置和工具。 |
| `add ` | 将服务器添加到用户配置。 写入到 `~/.copilot/mcp-config.json`。 |
| `remove ` | 删除用户级服务器。 工作区服务器必须直接在其配置文件中进行编辑。 |
```
**
`copilot mcp add` 选项：**
```
| 选项 | 说明 |
| ------------------------ | ------------------------------------ |
| `-- [args...]` | 本地 （stdio） 服务器的命令和参数。 |
| `--url ` | 远程服务器的 URL。 |
| `--type ` | 传输类型：`local`、、`stdio``http`或`sse`。 |
| `--env KEY=VALUE` | 环境变量（可重复）。 |
| `--header KEY=VALUE` | 远程服务器的 HTTP 标头（可重复）。 |
| `--tools ` | 工具筛选器： `"*"` 表示全部，逗号分隔列表，或 `""` 表示无。 |
| `--timeout ` | 超时（以毫秒为单位）。 |
| `--json` | 将添加的配置输出为 JSON 格式。 |
| `--show-secrets` | 显示完整的环境变量和标头值。 |
> \[!CAUTION]
```
`--show-secrets` 可以将敏感的环境变量和标头值输出到终端或日志。 仅在受信任的环境中使用此选项，避免在共享日志或历史记录中复制、粘贴或其他捕获输出。
```
### 传输类型
| 类型 | 说明 | 必填字段 |
| ----------------- | ------------------------- | ---- |
| `local` / `stdio` | 本地进程通过 stdin/stdout 进行通信。 | |
```
`command`、`args` |
```
\| `http` | 使用可流式 HTTP 传输的远程服务器。 | `url` |
\| `sse` | 使用服务器发送事件 (Server-Sent Events) 传输的远程服务器。 | `url` |
### 本地服务器配置字段
| 领域 | 必需 | 说明 |
| --------- | -- | ------------------------------------------- |
| `command` | 是的 | 用于启动服务器的命令。 |
| `args` | 是的 | 命令参数（数组）。 |
| `tools` | 是的 | 要启用的工具：`["*"]`，可以是所有工具或特定工具名称的列表。 |
| `env` | 否 | 环境变量。 支持`$VAR`和`${VAR}``${VAR:-default}`扩展。 |
| `cwd` | 否 | 服务器的工作目录。 |
| `timeout` | 否 | 工具调用超时（以毫秒为单位）。 |
| `type` | 否 | |
```
`"local"` 或 `"stdio"`。 默认值：`"local"`。 |
```
### 远程服务器配置字段
| 领域 | 必需 | 说明 |
| ------ | -- | -- |
| `type` | 是的 | |
```
`"http"` 或 `"sse"`。 |
```
\| `url` | 是的 | 服务器 URL。 |
\| `tools` | 是的 | 要启用的工具。 |
\| `headers` | 否 | HTTP 标头。 支持变量扩展。 |
\| `oauthClientId` | 否 | 静态 OAuth 客户端 ID（跳过动态注册）。 |
\| `oauthPublicClient` | 否 | OAuth 客户端是否为公共客户端。 默认值：`true`。 |
\| `oidc` | 否 | 启用 OIDC 令牌注入。 在 `true` 的情况下，注入 `GITHUB_COPILOT_OIDC_MCP_TOKEN` 环境变量（本地服务器）或 `Bearer``Authorization` 标头（远程服务器）。 |
\| `timeout` | 否 | 工具调用超时（以毫秒为单位）。 |
### OAuth 重新身份验证
使用 OAuth 的远程 MCP 服务器可能会在令牌过期或需要其他帐户时显示 `needs-auth` 状态。 使用 `/mcp auth ` 触发新的 OAuth 流。 这会打开浏览器身份验证提示，允许你登录或切换帐户。 完成流后，服务器会自动重新连接。
### 筛选器映射
控制如何使用服务器配置中的`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` 禁用特定服务器。
### MCP 服务器命名
服务器名称可以包含任何可打印字符，包括空格、Unicode 字符和标点符号。 不允许控制字符（U+0000–U+001F、U+007F）和右大括号（`}`）。 服务器名称用作工具名称的前缀，例如，名为 `my-server` 的服务器生成类似 `my-server-fetch` 的工具名称，而名为 `My Server` 的服务器生成类似 `My Server-fetch` 的工具名称。
### MCP 服务器信任级别
MCP 服务器从多个源加载，每个源具有不同的信任级别。
| 来源 | 信任级别 | 需评审 |
| ---------------------------------- | ------------ | ---- |
| 内置 | 高 | 否 |
| 存储库 （`.github/mcp.json`） | 中等 | 推荐 |
| 工作区 （`.mcp.json`） | 中等 | 推荐 |
| 用户配置（`~/.copilot/mcp-config.json`） | User-defined | 用户责任 |
| 远程服务器 | 低 | 始终 |
所有 MCP 工具调用都需要显式权限。 这甚至适用于对外部服务的只读操作。
### 企业 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`。
## 技能指南
技能是可扩展 CLI 功能的 Markdown 文件。 每个技能都位于其自己的目录中，其中包含一个 `SKILL.md` 文件。 调用（通过 `/SKILL-NAME` 或自动由代理调用）时，技能的内容将注入到会话中。
### 技能前页字段
| 领域 | 类型 | 必需 | 说明 |
| -------------------------- | ------------------ | -- | ------------------------------------------------- |
| `name` | 字符串 | 是的 | 技能的唯一标识符。 仅字母、数字和连字符。 最多 64 个字符。 |
| `description` | 字符串 | 是的 | 技能的作用以及何时使用它。 最多 1024 个字符。 |
| `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` | 自定义 | 其他目录（逗号分隔）。 |
| （与 CLI 捆绑） | 内置 | CLI 附带的技能。 最低优先级 - 可以被任何其他来源替代。 |
### 命令（可选技能格式）
命令是 `.md` 中存储为单个 `.claude/commands/` 文件的技能的替代项。 命令名称派生自文件名。 命令文件使用简化的格式（不需要 `name` 字段）和支持 `description`， `allowed-tools`以及 `disable-model-invocation`。 命令的优先级低于具有相同名称的技能。
## 自定义代理参考
自定义代理是在 Markdown 文件中定义的专用 AI 代理。 文件名（减扩展名）将成为代理 ID。 使用 `.agent.md` 或 `.md` 用作文件扩展名。
### 内置代理
| 代理人 | 默认模型 | 说明 |
| ------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| `code-review` | claude-sonnet-4.5 | 高信噪比代码审查。 分析代码差异中的缺陷、安全问题和逻辑错误。 |
| `configure-copilot` | 变化 | 内置子代理，用于通过自然语言管理 Copilot 命令行界面（CLI） 配置- 添加 MCP 服务器、安装代理和管理技能。 仅在实验模式下可用。 |
| `explore` | claude-haiku-4.5 | 快速代码库浏览。 搜索文件、读取代码和回答问题。 提供不超过300字的简明答案。 可以安全地并行运行。 |
| `general-purpose` | claude-sonnet-4.5 | 支持复杂多步骤任务的全功能代理。 在单独的上下文窗口中运行。 |
| `research` | claude-sonnet-4.6 | 深度研究代理。 基于代码库、相关存储库和 Web 中的信息生成报表。 |
| `rubber-duck` | 互补模型 | 使用互补模型来对提案、设计、实现或测试进行建设性的批评。 标识薄弱点并建议改进。 使用 Claude 时，它使用 GPT 模型;使用 GPT 时，它使用 Claude Opus 4.7。 从不进行直接代码更改。 仅在实验模式下可用。 |
| `task` | claude-haiku-4.5 | 命令执行（测试、构建、代码检查）。 成功时返回简要摘要，失败时返回全部输出。 |
### 自定义代理程序前端字段
| 领域 | 类型 | 必需 | 说明 |
| ------------- | ------ | -- | ---------------------------------------------------------------------------- |
| `description` | 字符串 | 是的 | 说明显示在代理列表和`task` 工具中。 |
| `infer` | 布尔 | 否 | 允许主代理自动委派。 默认值：`true`。 |
| `mcp-servers` | 对象 | 否 | 要连接的 MCP 服务器。 使用与`~/.copilot/mcp-config.json`相同的模式。 |
| `model` | 字符串 | 否 | 此代理的 AI 模型。 未设置时，继承外部代理的模型。 当会话模型设置为 `Auto` （服务器选择）时，子代理始终继承解析的会话模型，而不考虑此字段。 |
| `name` | 字符串 | 否 | 显示名称。 默认为文件名。 |
| `tools` | 字符串\[] | 否 | 代理可用的工具。 默认值： `["*"]` （所有工具）。 |
### 自定义代理位置
| Scope | 位置 |
| ----- | -- |
| 项目 | |
```
`.github/agents/` 或 `.claude/agents/` |
```
\| 用户 | `~/.copilot/agents/` |
\| 插件 | `/agents/` |
Project级代理优先于用户级代理。 插件代理的优先级最低。
### 子代理限制
CLI 强制实施深度和并发限制以防止生成失控代理。
| Limit | 默认 | 环境变量 |
| ----- | ---- | --------------------------------- |
| 最大深度 | `6` | `COPILOT_SUBAGENT_MAX_DEPTH` |
| 最大并发数 | `32` | `COPILOT_SUBAGENT_MAX_CONCURRENT` |
```
**深度** 计数彼此嵌套的代理数。 达到深度限制时，最内部的代理无法生成进一步的子代理。
**并发** 计数在整个会话树中同时运行的子代理数。 达到限制后，将拒绝新的子代理请求，直到活动代理完成。 值被限制在`1`和`256`之间。
```
## 权限审批结果
当 CLI 提示执行作的权限时，可以使用以下键进行响应。
| 密钥 | Effect |
| --- | ----------------- |
| `y` | 允许此特定请求一次。 |
| `n` | 拒绝此特定请求一次。 |
| `!` | 在会话剩余时段允许所有类似的请求。 |
| `#` | 在会话剩余时段拒绝所有类似的请求。 |
| `?` | 显示有关请求的详细信息。 |
运行 `/clear` 或启动新会话时，会话审批会重置。
## OpenTelemetry 监视
```
Copilot 命令行界面（CLI） 可以通过 [OpenTelemetry（OTel](https://opentelemetry.io/) ）导出跟踪和指标，从而了解代理交互、LLM 调用、工具执行和令牌使用情况。 所有信号名称和属性都遵循 [OTel GenAI 语义约定](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/)。
```
默认情况下，OTel 处于关闭状态，开销为零。 当满足以下任一条件时，它将激活：
* `COPILOT_OTEL_ENABLED=true`
* `OTEL_EXPORTER_OTLP_ENDPOINT` 已设置
* `COPILOT_OTEL_FILE_EXPORTER_PATH` 已设置
### 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_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 调用和工具执行。
* **顶级会话**会将跨度类型 `CLIENT`（远程服务调用）与 `server.address` 和 `server.port` 一起使用。
* **子代理调用** （例如，浏览、任务）在没有服务器属性的情况下使用范围类型 `INTERNAL` （进程内）。
| Attribute | 说明 | Span 类型 |
| -------------------------------- | --------------------------- | ------- |
| `gen_ai.operation.name` | `invoke_agent` | 两者都有 |
| `gen_ai.provider.name` | 提供者（例如`github`、`anthropic`） | 两者都有 |
| `gen_ai.agent.id` | 会话标识符 | 两者都有 |
| `gen_ai.agent.name` | 代理名称（可用时） | 两者都有 |
| `gen_ai.agent.description` | 代理说明（可用时） | 两者都有 |
| `gen_ai.agent.version` | 运行时版本 | 两者都有 |
| `gen_ai.conversation.id` | 会话标识符 | 两者都有 |
| `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.aiu` | AI 单元消耗 | 两者都有 |
\| `server.address` | 服务器主机名 | 仅 `CLIENT` |
\| `server.port` | 服务器端口 | 仅 `CLIENT` |
\| `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.conversation.id` | 会话标识符 |
| `gen_ai.response.id` | 响应 ID |
| `gen_ai.response.model` | 已解析的模型 |
| `gen_ai.response.finish_reasons` | 停止原因 |
| `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.cost` | 轮次成本 |
| `github.copilot.aiu` | AI 单元消耗当前回合 |
| `github.copilot.server_duration` | 服务器端持续时间 |
| `github.copilot.initiator` | 请求发起者 |
| `github.copilot.turn_id` | 轮次标识符 |
| `github.copilot.interaction_id` | 交互标识符 |
| `github.copilot.time_to_first_chunk` | 首次流式处理区块的时间（以秒为单位）（仅流式处理） |
| `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（仅限内容捕获） |
### 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 | 第一个区块后的区块间延迟 |
#### 特定于供应商的指标
| 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 往返次数 |
### 跨度事件
在活动 `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/enterprise-cloud@latest/copilot/how-tos/copilot-cli)
* [GitHub Copilot CLI 挂钩参考](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-hooks-reference)
* [GitHub Copilot CLI 插件参考](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-plugin-reference)
* [GitHub Copilot 命令行界面编程参考](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-programmatic-reference)
* [GitHub Copilot CLI 配置目录](/zh/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-config-dir-reference)