---
title: "安装、认证和配置"
description: "把 GitHub Copilot CLI 安装、/login、trusted directories、tool allow-deny、path URL 权限和 LSP 接入串成闭环。"
verifiedAt: "2026-05-06"
---

第一天使用 Copilot CLI，不要先追求复杂自动化。先完成最小闭环：安装、登录、确认可信目录、运行只读问题、理解工具批准，再决定是否开放写入和 shell——这条顺序倒过来，你会在前 30 分钟就给 agent 太多权限。

> [!TIP]
> **阅读目标**：读完本章，你应该能安全安装并配置 Copilot CLI，而不是一上来给它所有工具和路径权限。

## 1. 安装方式

官方安装页列出几种方式：

- **npm**：跨平台，前提是 Node.js 22 或更高版本。
- **WinGet**：Windows。
- **Homebrew**：macOS 和 Linux。
- **Install script**：macOS 和 Linux。
- **GitHub release executable**：从 copilot-cli repository 下载对应平台可执行文件。

常用命令：

```bash
npm install -g @github/copilot
brew install copilot-cli
winget install GitHub.Copilot
```

如果 npm 配置了 `ignore-scripts=true`，官方要求安装时临时关闭该选项。

## 2. 认证

首次启动：

```bash
copilot
```

然后在 CLI interface 输入：

```text
/login
```

按屏幕提示完成 GitHub 认证。官方文档还说明可以用 fine-grained personal access token 认证，但 token 必须启用 Copilot Requests permission，并且 resource owner 选择个人账号，不选择组织。

## 3. Trusted directories

首次在目录里启动 CLI 时，它会询问是否信任当前目录及其子目录。官方配置页说明，你可以只信任当前 session，也可以信任未来 session。

规则：

- 只在真实项目目录信任。
- 不要在 home directory 信任。
- 不要在含密钥、客户数据、未知可执行文件的目录信任。
- 永久信任目录记录在 `~/.copilot/config.json`，Windows 是 `$HOME\.copilot\config.json`。
- 可以用 `COPILOT_HOME` 改变配置目录位置。

```mermaid
flowchart TD
    Start["启动 copilot"] --> Trust{"信任当前目录?"}
    Trust -->|当前 session| Session["只本次会话"]
    Trust -->|未来 session| Config["写入 config.json"]
    Trust -->|不信任| Stop["不要让 CLI 操作该目录"]
    Session --> Tools["工具批准"]
    Config --> Tools
    Tools --> Work["执行任务"]

    style Trust fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Stop fill:#fee2e2,stroke:#dc2626,stroke-width:2px
```

## 4. Allowed tools

工具权限可以通过交互批准，也可以用 flags 配置：

- `--allow-all-tools`：允许任何工具，无需逐次批准。
- `--allow-tool`：允许特定工具。
- `--deny-tool`：拒绝特定工具，优先级高于 allow。
- `--available-tools`：限制本次会话可用工具集合。

Shell 工具可以细化到命令：

```bash
copilot --deny-tool='shell(rm)'
copilot --deny-tool='shell(git push)'
copilot --allow-tool='shell(git)'
copilot --allow-tool='write'
```

团队默认策略应是 deny dangerous、allow narrow。`--allow-all-tools` 只适合受限容器或一次性沙箱，不适合日常项目目录。

## 5. Path 和 URL 权限

官方配置页说明，默认情况下 Copilot CLI 可以访问当前工作目录、子目录和 system temp directory。

注意：

- Path permissions 适用于 shell、文件操作和搜索工具。
- Shell command 的 path 识别是 heuristic，不保证覆盖复杂 shell 结构。
- URL permissions 可以控制 CLI 能访问的 URL。
- 可以用 allow-all 选项放开路径和 URL，但这属于高风险配置。

## 6. LSP server

官方 LSP 文档说明，LSP servers 可以给 Copilot CLI 更精确的代码智能，帮助它定位定义、查引用、重命名 symbol。

接入分两步：

1. 安装语言对应的 LSP server。
2. 在 `~/.copilot/lsp-config.json` 或仓库 `.github/lsp.json` 配置 server。

可以用 `/lsp` 管理：

- `/lsp` 或 `/lsp show`：查看状态。
- `/lsp test SERVER-NAME`：测试 server 是否能启动。
- `/lsp reload`：重新加载配置。
- `/lsp help`：查看帮助。

<details>
<summary>深读：为什么 LSP 不应该第一天就全装</summary>

LSP 能提高代码理解，但 LSP server 本身也是本地可执行软件。官方文档也提醒只安装可信来源的 LSP server。

第一天先让 CLI 在受控目录里完成只读和小改动；等团队明确语言栈和安全要求后，再为核心语言接入 LSP。
</details>

## 本章自检

完成本章后，用这 4 个问题检查：

1. 安装方式是否来自官方列出的 npm、Homebrew、WinGet、script 或 release？
2. 是否完成 `/login`，并确认组织 policy 允许 Copilot CLI？
3. 当前目录是否真的适合加入 trusted directory？
4. 工具、path、URL、LSP 是否按最小权限配置？

通过标准：CLI 可以完成只读问答和小范围写入，并且每个权限都能解释原因。

## 官方来源

- [Installing GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli) —— 官方安装和认证页。
- [Configuring GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/configure-copilot-cli) —— 官方 trusted directories、tools、paths、URLs 配置页。
- [Adding LSP servers for GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers) —— 官方 LSP 配置页。
- [Getting started with GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/cli-getting-started) —— 官方快速开始。

## 接下来去哪

<Cards>
  <Card title="委派任务" description="配置完成后，继续学习 autopilot 和 /delegate 的差异。" href="/docs/github-copilot/official/05-copilot-cli/delegate-tasks" />
  <Card title="回滚和 PR 管理" description="开始写入前，先掌握 snapshot 和 /undo。" href="/docs/github-copilot/official/05-copilot-cli/rollback-pr" />
</Cards>
