{"meta":{"title":"GitHub Copilot 命令行界面编程参考","intro":"查找用于以编程方式运行 Copilot 命令行界面（CLI） 的选项。","product":"GitHub Copilot","breadcrumbs":[{"href":"/zh/copilot","title":"GitHub Copilot"},{"href":"/zh/copilot/reference","title":"参考资料"},{"href":"/zh/copilot/reference/copilot-cli-reference","title":"\n              Copilot 命令行界面（CLI） 参考"},{"href":"/zh/copilot/reference/copilot-cli-reference/cli-programmatic-reference","title":"CLI 编程参考"}],"documentType":"article"},"body":"# GitHub Copilot 命令行界面编程参考\n\n查找用于以编程方式运行 Copilot 命令行界面（CLI） 的选项。\n\n除了以交互方式运行 Copilot 命令行界面（CLI） 外，还可以在单个命令中直接将提示传递到 CLI，而无需输入交互式会话。 这样，就可以在脚本、CI/CD 管道和自动化工作流中以编程方式使用 Copilot 。 有关详细信息，请参阅“[以编程方式运行GitHub Copilot 命令行界面 (CLI)](/zh/copilot/how-tos/copilot-cli/automate-copilot-cli/run-cli-programmatically)”。\n\n本文介绍以编程方式运行时 Copilot 命令行界面（CLI） 特别相关的命令行选项和环境变量。\n\n若要查看可用选项的完整列表，请参阅 [GitHub Copilot CLI 命令参考](/zh/copilot/reference/copilot-cli-reference/cli-command-reference#command-line-options) 或在终端中输入以下命令：\n\n```shell copy\ncopilot help\n```\n\n## 命令行选项\n\n在以编程方式运行Copilot 命令行界面（CLI）时，有许多命令行选项特别有用。\n\n| 选项                          | 说明                                                                                                                |\n| --------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| `-p PROMPT`                 | 在非交互式模式下执行提示。 CLI 运行提示并在完成后退出。                                                                                    |\n| `-s`                        | 取消统计信息和修饰，只输出代理的响应。 非常适合在脚本中通过管道传输输出。                                                                             |\n| `--add-dir=DIRECTORY`       | 将目录添加到允许的路径列表。 这可以多次用于添加多个目录。 当代理需要读取/写入当前工作目录之外时非常有用。                                                            |\n| `--agent=AGENT`             | 指定要使用的值 自定义智能体 。                                                                                                  |\n| `--allow-all`（或 `--yolo`）   | 允许 CLI 所有权限。 等效于 `--allow-all-tools --allow-all-paths --allow-all-urls`。                                          |\n| `--allow-all-paths`         | 完全禁用文件路径验证。 不再需要路径限制时的更简单替代 `--add-dir` 方法。                                                                       |\n| `--allow-all-tools`         | 允许每个工具在不需显式许可的情况下运行。                                                                                              |\n| `--allow-all-urls`          | 允许访问所有 URL，而无需为每个 URL 显式许可。                                                                                       |\n| `--allow-tool=TOOL ...`     | 选择性地授予特定工具的权限。 对于多个工具，请使用带引号的逗号分隔列表。                                                                              |\n| `--allow-url=URL ...`       | 允许代理提取特定的 URL 或域。 当工作流需要 Web 访问已知终结点时非常有用。 对于多个 URL，请使用带引号的逗号分隔列表。                                                |\n| `--deny-tool=TOOL ...`      | 拒绝特定工具。 可用于限制代理在锁定工作流中可以执行的操作。 对于多个工具，请使用带引号的逗号分隔列表。                                                              |\n| `--model=MODEL`             | 选择 AI 模型（例如， `gpt-5.2` 或 `claude-sonnet-4.6`）。 可用于在可重现的工作流中固定模型。 请参阅下面的 [“选择模型](#choosing-a-model) ”。             |\n| `--no-ask-user`             | 阻止代理暂停以寻求其他用户输入。                                                                                                  |\n| `--secret-env-vars=VAR ...` | 一个环境变量，其值需要在输出中被隐藏。 对于多个变量，请使用带引号的逗号分隔列表。 防止机密在日志中被公开至关重要。 默认情况下，环境变量`GITHUB_TOKEN``COPILOT_GITHUB_TOKEN`中的值会被隐藏。 |\n| `--share=PATH`              | 在以非交互方式完成后将会话记录导出为 Markdown 文件（默认为 `./copilot-session-<ID>.md`）。 可用于审核或存档代理执行的操作。 请注意，会话脚本可能包含敏感信息。               |\n| `--share-gist`              | 完成后将会话记录发布为机密 GitHub gist。 方便共享 CI 产生的结果。 请注意，会话脚本可能包含敏感信息。                                                       |\n\n##\n\n```\n          `--allow-tool` 选项的工具\n```\n\n您可以使用<c0>选项指定各种工具。\n\n| 工具类型       | 它控制的内容                                                                                                                                                           |\n| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| shell      | 执行 shell 命令。                                                                                                                                                     |\n| 写入         | 创建或修改文件。                                                                                                                                                         |\n| 读取         | 读取文件或目录。                                                                                                                                                         |\n| url        | 从 URL 提取内容。                                                                                                                                                      |\n| 内存         | 将新事实存储到代理的永久性内存中。 这不会影响使用现有内存。 请参阅“[关于 GitHub Copilot 的智能记忆](/zh/copilot/concepts/agents/copilot-memory)”。                                                       |\n| MCP-SERVER | 从特定 MCP 服务器调用工具。 使用服务器配置的名称作为标识符，例如 `github`。 请参阅“[为 GitHub Copilot 命令行界面 (CLI) 添加 MCP 服务器](/zh/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers)”。 |\n\n### 工具筛选器\n\n使用`shell`、`write`、`url`和MCP服务器工具类型，您可以在括号中指定一个筛选器，以控制允许哪些特定工具。\n\n<!-- markdownlint-disable -->\n\n| 工具类型           | 示例                                       | 示例的说明                                       |\n| -------------- | ---------------------------------------- | ------------------------------------------- |\n| **命令行界面**      | `shell(git:*)`                           | 允许所有 Git 子命令（如 `git push`、`git status`等）。   |\n|                | `shell(npm test)`                        | 允许精确命令 `npm test`。                          |\n| **写**          | `write(.github/copilot-instructions.md)` | 允许 CLI 写入此特定路径。                             |\n|                | `write(README.md)`                       | 允许 CLI 写入路径以 `/README.md` 结尾的任何文件。          |\n| **url**        | `url(github.com)`                        | 允许 CLI 访问 github.com 上的 HTTPS URL。          |\n|                | `url(http://localhost:3000)`             | 允许 CLI 使用显式协议和端口访问本地开发服务器。                  |\n|                | `url(https://*.github.com)`              | 允许 CLI 访问任何 GitHub 子域（例如 `api.github.com`）。 |\n|                | `url(https://docs.github.com/copilot/*)` | 允许访问此站点的 Copilot 文档。                        |\n| **MCP-SERVER** | `github(create_issue)`                   | 仅允许来自 `create_issue` MCP 服务器的 `github` 工具。  |\n\n<!-- markdownlint-enable -->\n\n> \\[!NOTE]\n> 仅支持 `shell` 通配符以匹配指定工具的所有子命令，并在 `url` 主机名开头匹配任何子域，或在路径末尾匹配任何路径后缀，如上表所示。\n\n## 环境变量\n\n可以使用环境变量在以编程方式运行时配置 CLI 行为的各个方面。 这对于在 CI/CD 工作流或其他自动化环境中设置配置特别有用，你可能不希望直接在命令行中指定某些选项。\n\n| Variable               | 说明                                    |\n| ---------------------- | ------------------------------------- |\n| `COPILOT_ALLOW_ALL`    | 设置为 `true` 以获得完全权限                    |\n| `COPILOT_MODEL`        | 设置模型（例如，`gpt-5.2``claude-sonnet-4.5`） |\n| `COPILOT_HOME`         | 设置 CLI 配置文件的目录（`~/.copilot` 默认情况下）    |\n| `COPILOT_GITHUB_TOKEN` | 身份验证令牌（最高优先级）                         |\n| `GH_TOKEN`             | 身份验证令牌（第二个优先级）                        |\n| `GITHUB_TOKEN`         | 身份验证令牌（第三个优先级）                        |\n\n有关环境变量 Copilot 命令行界面（CLI）的完整详细信息，请使用终端中的命令 `copilot help environment` 。\n\n## 选择模型\n\n在非交互模式下向Copilot 命令行界面（CLI）发送提示时，如果`-s`或`--silent`选项未使用，CLI 用于生成响应的模型会在响应输出中显示。\n\n可以使用此选项 `--model` 来指定 CLI 应使用的 AI 模型。 这样，你可以选择最适合提示的模型、平衡速度、成本和功能等因素。\n\n例如，对于简单的任务（例如解释某些代码或生成摘要），可以选择快速、低成本的模型，例如 Claude Haiku 模型：\n\n```bash copy\ncopilot -p \"What does this project do?\" -s --model claude-haiku-4.5\n```\n\n对于需要更深层次推理（如调试或重构代码）的更复杂的任务，可以选择更强大的模型，例如 GPT Codex 模型：\n\n```bash copy\ncopilot -p \"Fix the race condition in the worker pool\" \\\n  --model gpt-5.3-codex \\\n  --allow-tool='write, shell'\n```\n\n> \\[!NOTE]\n> 可以在终端中输入`--model`查看`copilot help`选项的说明，其中可以找到所有可用模型的模型字符串。\n\n或者，可以将环境变量设置为 `COPILOT_MODEL` 在 shell 会话期间指定模型。\n\n若要跨 shell 会话保留模型选择，可以在 CLI 配置文件中设置 `model` 密钥。 此文件位于 `~/.copilot/settings.json`（如果您已设置 `$COPILOT_HOME/settings.json` 环境变量，则位于 `COPILOT_HOME`）。 某些模型还允许你设置推理工作量级别，该级别控制模型在响应之前思考的时间。\n\n```json copy\n{\n  \"model\": \"gpt-5.3-codex\",\n  \"effortLevel\": \"low\"\n}\n```\n\n> \\[!TIP]\n> 在配置文件中持久设置模型的最简单方法是在交互式会话中使用 `/model` 斜杠命令。 使用此命令所做的选择将写入配置文件。\n\n### 模型优先级\n\n确定要用于给定提示的模型时，CLI 会按以下优先级顺序检查模型规范（从最高到最低）：\n\n* 使用自定义代理的位置：自定义代理定义中指定的模型（如果有）。\n* `--model`命令行选项。\n* `COPILOT_MODEL` 环境变量。\n* `model`配置文件中的键（`~/.copilot/settings.json`或`$COPILOT_HOME/settings.json`）。\n* CLI 的默认模型。\n\n## 使用自定义代理\n\n可以使用此选项 `--agent` 将工作委托给专用代理。 有关详细信息，请参阅“[为 GitHub Copilot 命令行界面 (CLI) 创建和使用自定义智能体](/zh/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli)”。\n\n在此示例中， `code-review` 使用代理。 这要求已使用此名称创建自定义代理。\n\n```bash\ncopilot -p \"Review the latest commit\" \\\n  --allow-tool='shell' \\\n  --agent code-review\n```\n\n## 延伸阅读\n\n* [GitHub Copilot 命令行界面 (CLI)](/zh/copilot/how-tos/copilot-cli)\n* [GitHub Copilot CLI 命令参考](/zh/copilot/reference/copilot-cli-reference/cli-command-reference)\n* [GitHub Copilot CLI 插件参考](/zh/copilot/reference/copilot-cli-reference/cli-plugin-reference)"}