---
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="/zh-Hant/docs/github-copilot/official/05-copilot-cli/delegate-tasks" />
  <Card title="回復和 PR 管理" description="開始寫入前，先掌握 snapshot 和 /undo。" href="/zh-Hant/docs/github-copilot/official/05-copilot-cli/rollback-pr" />
</Cards>
