疑難排解與常見錯誤

Copilot CLI 卡住、連不上、被擋、帳單看不懂——這一章是你的自救手冊，教你先分清楚問題出在哪一層，再對症下藥，而不是一路亂猜瞎試。

前面十五章教你怎麼把 GitHub Copilot CLI 用得順手；這一章反過來，處理它「不順手」的時候。想像你家裡請了一位很能幹的助理，大多數時候合作愉快，但偶爾會卡關：可能是你根本認錯人（找到的是他退休的前輩）、可能是他忘了帶識別證進不了門、可能是公司規定他這個月不能加班、也可能是辦公室網路被鎖住他傳不出訊息。這一章就是一張「先查哪裡、再查哪裡」的排錯地圖，照順序走一遍，通常都能找到真正的病灶。

角色定位比照本站 Codex CLI 單元第 16 章的「診斷三件套」與 Gemini CLI 單元第 16 章的「疑難排解與遷移判斷」，但內容完全針對 GitHub Copilot CLI 重新查證——不是把其他單元的文字改個名字交差。

16.1 第一步，先確認你裝的到底是哪一個

在查任何具體錯誤之前，有一個更根本的問題必須先排除：你裝的、你正在照著操作的教學，講的是不是同一個東西？

GitHub 把「Copilot CLI」這個名字用過兩次，這是全書第 0 章就講過的核心陷阱，這裡在疑難排解的脈絡下再提醒一次，因為它是新手卡關時最容易忽略的第一個可能性：

如果照著本章後面的步驟排查，發現你的指令、旗標、行為統統對不上——先回頭確認一次你裝的、你查到的資料，講的到底是不是 @github/copilot 這個獨立套件。這個誤會排除掉，很多「查了半天查不到」的困惑會直接消失。

16.2 安裝與版本自查

懷疑是安裝本身出問題時，先用這兩個指令自我檢查：

copilot version    # 確認目前裝的版本號
copilot update     # 更新到最新版

官方提供四種安裝管道，各自的平台限制不太一樣，裝不起來時先確認自己走的是對的那一條：

另外也可以直接到 github.com/github/copilot-cli/releases/ 下載執行檔手動安裝，但這條路要自己手動更新版本。順帶一提，GitHub Codespaces 的預設映像已經內建 Copilot CLI，不用額外再裝一次。

Node.js 版本太舊是新手最常在這一步卡住的地方——npm install -g @github/copilot 執行沒有明顯報錯，但裝完的 copilot 指令怪怪的或根本跑不起來，先用 node --version 確認自己的 Node.js 是 22 以上，這是官方寫死的最低需求。

16.3 登入卡住：官方列出的 6 類認證錯誤

登入相關的疑難排解，第 3 章已經講過完整的首次啟動流程；這裡把官方文件逐條列出的錯誤訊息與對應解法整理成一張查表，卡住時直接對照畫面上的錯誤字句：

幾個補充細節：

• 認證用環境變數的優先序是 COPILOT_GITHUB_TOKEN > GH_TOKEN > GITHUB_TOKEN，適合 CI／headless 環境不走互動登入時使用（延伸細節見第 3 章）。
• 企業帳號登入指定主機：copilot login --host HOST。
• 表格裡第 3 項的「classic PAT（ghp_ 開頭）被忽略」是新手最容易誤判的一個——CLI 不會明講「你用了舊格式的 token」，只會表現得像沒登入一樣，讓人誤以為是別的問題。看到自己確定登入過、卻一直被要求重新認證，先檢查用的是不是 ghp_ 開頭的舊式 token。

16.4 方案與企業政策擋住你的存取

這一節處理一種特別容易讓人誤會成「設定壞掉」的狀況：其實是你的方案或組織政策根本沒有把 CLI 打開，不是哪裡故障了。

企業／組織帳號還多一層政策關卡：

• Business／Enterprise 使用者需要組織管理員在政策頁面額外啟用，不是訂閱了對應方案就自動能用。
• Enterprise 層級的政策可以設成「Enabled everywhere」「Disabled everywhere」「Let organizations decide」三選一，前兩者會凌駕底下所有 organization 各自的設定。
• 2025-11-04 起有一次政策行為變更：如果 enterprise 政策設成「Unconfigured」（未設定），底下 organization 政策的預設值會變成 Disabled，不再是可以自由選擇的中性狀態。這代表不少企業使用者「以為公司已經開通，實際上預設是關的」。
• CLI 在多個時間點都會檢查政策：認證時、選模型時、功能存取時、設定 MCP server 時，任何一關被擋，都會看到類似「存取被組織政策拒絕，請聯絡管理員」的錯誤訊息。

16.5 網路、Proxy 與企業憑證

如果你在公司、學校，或任何「網路被管控」的環境裡用 Copilot CLI，最常見的災情就是它連不上 GitHub。這一節整理標準做法，也附上一個反直覺的官方限制與一個容易誤判的已知 bug。

標準 proxy 環境變數：

export HTTPS_PROXY=http://proxy.corp:8080
export HTTP_PROXY=http://proxy.corp:8080
export NO_PROXY=localhost,127.0.0.1
copilot

也可以帶帳密：http://user:pass@proxy:8080。

企業自簽憑證／TLS 攔截：很多公司網路會在中間攔截 HTTPS 連線做內容檢查，用的是公司自己的根憑證，這時候 Copilot CLI 會因為不認得這張憑證而連線失敗。Copilot 除了讀作業系統本身的信任庫，也會讀標準 Node.js 環境變數 NODE_EXTRA_CA_CERTS 指到的額外憑證檔——這是 Node.js 生態通用的機制，不是 Copilot 自己發明的：

export NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pem
copilot login

常見對應的錯誤訊息長這樣：certificate signature failure、custom certificate、unable to verify the first certificate——看到這幾句，通常就是企業 proxy 在做 SSL inspection，用自己的憑證中間人攔截了連線。

16.6 Windows 平台專屬坑

Windows 上跑 Copilot CLI 有一個官方明講的建議路線，跟一個容易踩到的版本門檻。

官方支援 macOS／Linux／Windows 三個平台，但 Windows 有兩條路可以走，穩定度不一樣：

• WSL（官方推薦）：官方原文寫得很直白——「the recommended way to run the Copilot CLI on Windows is through WSL」（在 Windows 上跑 Copilot CLI 的建議方式是透過 WSL）。走這條路，穩定性與 shell 相容性跟原生 Linux 一樣好。
• 原生 PowerShell（實驗性）：需要 PowerShell 6 以上，但 Windows 11 預設只內建 PowerShell 5.1，得手動另外安裝 PowerShell 6+ 才能用原生模式。

16.7 額度、Quota 與 Context Window

這一節談「用量」——CLI 什麼時候會被擋、額度算法有沒有你意想不到的地方、以及對話視窗滿了會發生什麼事。

2026-06-01 起計費制度大改：從舊制「Premium Request Units」改成新制「GitHub AI Credits」，按 token 計價。1 AI credit = US$0.01。方案月費與內含額度（2026-07 查核，變動快，數字以官方頁為準）：

Context Window 自動壓縮：官方逐字（GA 公告原文）：「When your conversation approaches 95% of the context window, Copilot automatically compresses history.」（對話接近 context window 的 95% 時，Copilot 會自動壓縮歷史紀錄）。也可以自己手動下 /compact 指令主動壓縮，不用等系統自己觸發。

/compact

以下是社群回報、官方目前未正式承認的已知怪象，遇到的時候先知道「不是只有你遇到」，比較好判斷方向：

16.8 回報問題的正確管道

前面幾節列出的社群回報 issue，全部都來自同一個地方：github.com/github/copilot-cli 這個原始碼 repo 的 issue tracker。這也是你自己遇到疑似 bug 時，應該回報的地方——CLI 本身的行為異常、指令跑起來跟文件講的不一樣，優先去這裡搜尋看看有沒有人已經回報過，沒有就開一個新的。

帳號、訂閱方案、組織政策這類問題，性質上不是「程式碼有 bug」，而是帳戶或組織設定層面的事，比較適合透過 GitHub 官方支援管道處理，而不是丟進程式碼 repo 的 issue tracker——這是本書作者依查證所得資訊做的合理歸類（practice／推論），不是逐字照抄某一頁官方文件的說法。

互動模式裡也有一個 /feedback 指令，可以直接在對話裡送出意見回饋：

/feedback

16.9 這個模式的邊界：什麼時候不該用

前面十六章教的都是「怎麼把 Copilot CLI 這套常駐終端機 agent 模式用好、出狀況怎麼修」。這一節反過來，誠實講一句前面沒特別點破的話：這套模式不是萬能，有些情況直接手動做，比透過它做更快、更划算。懂得判斷「這次到底該不該動用它」，跟懂得怎麼用它一樣重要，不然很容易變成拿到一把好用的鎚子，看什麼都像釘子。

下面三個場景，都能直接對回第 7 章官方文件逐字列出的「不適用」邊界，以及本章 16.7 節已經講過的用量機制——不是憑空歸類，是把已經查證過的官方界線，往「這整套 agent 模式到底要不要動用」這個更前面一層的問題再延伸一層（這一步延伸屬於本書作者的歸納整理，不是逐字照抄某一頁官方文件的說法）：

本章小結

這一章你學會了 GitHub Copilot CLI 出狀況時怎麼自己排查：

• 第一步永遠是確認身分：你裝的是已經 2025-10-25 停止運作的舊 gh copilot，還是本書教的獨立 copilot 指令——很多「查了半天查不到」的困惑，源頭都是認錯對象。
• 安裝與版本：copilot version／copilot update 自查，四種安裝管道各有平台限制，npm 需要 Node.js 22+，套件名字是 @github/copilot 不是 @github/copilot-cli。
• 認證疑難排解：官方列出 6 類錯誤訊息與解法，含 ghp_ 舊式 token 被靜默忽略、Linux keychain 不可用兩個最容易誤判的坑。
• 方案與政策：Free 方案本身不含 CLI（GA 公告寫死在 Pro 以上）；企業政策未明確開啟時，2025-11-04 後的預設值是關的，不是中性的。
• 網路／Proxy／憑證：反直覺限制——proxy 網址不能以 https:// 開頭；企業自簽憑證用 NODE_EXTRA_CA_CERTS；已知社群 bug——無效 proxy 會靜默退出、不給任何清楚錯誤訊息。
• Windows 專屬坑：官方建議走 WSL，原生 PowerShell 是實驗性功能且需要 PowerShell 6+（Windows 11 預設只有 5.1）。
• 額度與 Context Window：CLI 用量跟 IDE 版共用同一個 premium request／AI credit 池；2026-06-01 起改按 token 計價的 AI Credits 新制；context window 接近 95% 會自動壓縮，也能手動 /compact；社群回報多個非官方承認的已知怪象（/usage 低估、quota_exceeded 誤判、context 計算異常），遇到先知道不是只有你踩到。
• 回報問題：CLI 本身的 bug 去 github.com/github/copilot-cli 的 issue tracker；帳號／方案／政策問題走 GitHub 官方支援管道；互動模式裡也有 /feedback 指令可用。
• 這個模式的邊界：Copilot CLI 不是萬能，單次簡單查詢、已經確定怎麼改的小改動、你想全程自己掌控的任務，直接手動做通常更快——這三個邊界都能對回第 7 章官方文件的「不適用」清單，往下延伸到「這次該不該動用整套 agent 模式」這個更前面一層的判斷。

動手試試

1. 跑一次 copilot version，記下你目前的版本號，跟本章開頭的 v1.0.71 對照一下差了幾版。
2. 打開互動模式輸入 /feedback，看看實際跳出來的送出流程長什麼樣。
3. 如果你的環境用得到 proxy，檢查一下你設定的 HTTPS_PROXY 網址開頭是不是 http://（不是 https://）——這是本章最容易忽略的一條反直覺限制。
4. 找一次你之前遇過、覺得莫名其妙的錯誤訊息，回頭對照本章 16.3 或 16.7 的表格，看能不能對得上號。
5. （如果你在 Windows 上）跑一次 $PSVersionTable.PSVersion，確認你的 PowerShell 版本是不是 6 以上；如果不到，想想是不是該考慮改用 WSL。

本章官方文件參考

• 疑難排解（認證）：https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/troubleshoot-copilot-cli-auth
• 疑難排解（網路）：https://docs.github.com/en/copilot/troubleshooting-github-copilot/troubleshooting-network-errors-for-github-copilot
• 網路設定：https://docs.github.com/en/copilot/managing-copilot/configure-personal-settings/configuring-network-settings-for-github-copilot
• 安裝：https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli
• 企業管理：https://docs.github.com/en/copilot/how-tos/copilot-cli/administer-copilot-cli-for-your-enterprise
• 政策說明：https://docs.github.com/en/copilot/concepts/policies
• Premium Requests／計費：https://docs.github.com/en/billing/concepts/product-billing/github-copilot-premium-requests
• 方案頁：https://github.com/features/copilot/plans
• GA 公告：https://github.blog/changelog/2026-02-25-github-copilot-cli-is-now-generally-available/
• 舊版棄用公告：https://github.blog/changelog/2025-09-25-upcoming-deprecation-of-gh-copilot-cli-extension/
• 原始碼 repo／issue tracker：https://github.com/github/copilot-cli