疑難排解與遷移判斷

16.1 先把錯誤分流

不要一看到失敗就重裝。先記下命令、作業系統、Node/npm 版本、Gemini CLI 版本、登入方式、錯誤碼、是否在 CI、是否使用 MCP、是否開 sandbox。大多數問題可以先分成八類：認證、quota/billing、終端機安裝、shell/env、權限與 sandbox、MCP、headless/CI 格式、產品路線。

最小排查紀錄：
command: gemini ...
where: local terminal / headless / GitHub Action
auth: Google login / GEMINI_API_KEY / Vertex ADC / service account
version: gemini --version 與 node -v
error: 完整錯誤碼與第一段訊息
scope: 只在此 repo、此 shell、此帳號、此網路或所有地方發生
recent change: 升級 CLI、換 key、改 config、改 MCP、改 CI secret

官方 exit code 對照表

在腳本或 CI 裡，你通常看不到完整的終端機畫面，只看得到一個數字——這時候 CLI 結束時回傳的 exit code，往往比從一長串錯誤輸出裡找關鍵字更快定位問題類型。官方 troubleshooting 文件列出幾個固定碼✅官方，建議直接寫進你的最小排查紀錄：

0 是正常結束；非零但不在上表的碼，代表未分類的錯誤，這時候才需要回頭看 stderr 的完整訊息。這份對照表以你目前版本的 troubleshooting.md 為準，之後版本可能新增或調整編碼。

16.2 Auth、帳號、API key、Vertex

認證問題通常表現為未登入、token 過期、帳號不符、API key 無效、Vertex 專案或地區錯誤、IAM 權限不足，或在 CI 中讀不到 secret。先確認你要用的是哪條路：互動式 Google 帳號登入、Gemini API key、Vertex AI/Google Cloud ADC、service account，還是企業平台提供的方式。混用時最容易出錯。

僅限已確認 Gemini CLI 路線：遇到「需要組織訂閱」怎麼分辨

若你的組織已確認這台電腦應使用 Gemini CLI，卻在登入時看到「需要組織訂閱」，先確認團隊指定的帳號與路線。接著才檢查 shell 是否殘留 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID；即使值是空字串，也可能讓工具走到組織驗證流程。這是排除設定殘留，不是繞過組織資格或付費限制。

先只檢查目前終端機：macOS／Linux 的 Bash、Zsh 可用下列指令；Windows PowerShell 請用 PowerShell 那組，不要把 unset 貼進 PowerShell。

# macOS／Linux（Bash、Zsh）
env | grep GOOGLE_CLOUD
unset GOOGLE_CLOUD_PROJECT GOOGLE_CLOUD_PROJECT_ID

# Windows PowerShell
Get-ChildItem Env:GOOGLE_CLOUD_PROJECT,Env:GOOGLE_CLOUD_PROJECT_ID -ErrorAction SilentlyContinue
Remove-Item Env:GOOGLE_CLOUD_PROJECT -ErrorAction SilentlyContinue
Remove-Item Env:GOOGLE_CLOUD_PROJECT_ID -ErrorAction SilentlyContinue

這些做法只影響目前這個終端機。確認是你自己留下的設定後，macOS／Linux 再檢查 ~/.bashrc、~/.zshrc 與專案 .env；Windows 再檢查 $PROFILE 與專案 .env。公司管理的設定、共用專案設定或不確定用途的值不要自行刪除，先問管理員。這跟第 3 章走 Vertex AI 時要處理的 GOOGLE_API_KEY／GEMINI_API_KEY是不同的兩組變數、不同的成因；先確認路線，再處理對應設定。

另一種容易搞混成因的錯誤，是把 Gemini API key 誤用在 Vertex AI 端點上——Vertex 不接受 API key 這種認證方式，硬打通常會得到類似 API keys are not supported by this API - Expected OAuth2 access token... 的錯誤。看到這行代表認證方式跟你想連的端點對不上，不是 key 本身失效，是走錯路線；回第 3 章確認你要用的究竟是API key 路線還是Vertex AI 的 ADC／service account 路線，兩條路線的憑證不能互通、不能混用。

16.3 Quota、rate limit、billing

429、quota exceeded、billing not enabled、permission denied 有時看起來很像，但修法不同。rate limit 通常要降低並行、縮短 prompt、使用 backoff；quota exhausted 要申請額度、切模型或排隊；billing 問題要先開通計費或改用有權限的專案；企業環境還可能有組織政策與預算護欄。

Quota/billing 判斷：
1. 錯誤是否明確寫 rate limit、quota、billing、region、permission？
2. 只在特定模型或特定 region 發生嗎？
3. CI 是否同時開太多 job，導致瞬間請求超限？
4. 帳務專案是否正確，免費/個人/企業路線是否混用？
5. 重試前先設上限；不是所有 429 都該無限重送。

「CLI 顯示的帳號等級」跟「底層 API key 真正的計費層級」是兩件事，兩者偶爾會脫鉤——第 0 章 0.4 節與第 3 章 3.4 節都記錄過同一類落差：畫面顯示付費等級，key 卻還卡在 Free Tier。付費使用者遇到 429 先別急著減少呼叫次數，回這兩節確認 key 實際掛在哪個 tier；完整的成本與配額規劃則交給第 15 章 15.5 節。

16.4 Terminal、Node、npm、PATH

安裝問題多半發生在 Node 太舊、npm global prefix 不在 PATH、npx 快取到舊版、shell 啟動檔沒有被讀取、Windows PowerShell 與 WSL 混用，或公司電腦擋掉 npm registry。先確認你打開的是預期 shell，再確認 node、npm、npx、gemini 指到哪裡。

node -v
npm -v
command -v node
command -v npm
command -v gemini
npm config get prefix
gemini --version

若 shell 找不到 gemini，通常是 global bin 不在 PATH。不要立刻用 sudo 硬裝；先查 npm prefix，再把對應 bin 目錄加到目前 shell 的啟動檔。macOS/Linux 常見是 ~/.zshrc、~/.bashrc；Windows 要分清 PowerShell、Command Prompt、Git Bash、WSL 各自的 PATH。

從原始碼安裝：MODULE_NOT_FOUND 與 ERR_REQUIRE_ESM

不是每個人都走 npm install -g 這條主線；clone 原始碼自己建置時，最常見的兩個錯誤都跟建置步驟有關，不是程式本身壞掉：

Windows 原生環境另有一種常見卡關：全域安裝腳本會產生一個 gemini.ps1 wrapper script，PowerShell 預設的執行原則（execution policy）會直接擋下它，噴出 PSSecurityException——第 2 章 2.2 節提過這個現象會跟其他 Windows 原生故障疊在一起發生，這裡補上具體修法：以系統管理員身分開 PowerShell 執行一次即可，這是 Node.js 全域安裝在 Windows 上的通用行為，不是 Gemini CLI 專屬的怪癖。

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

另一個容易被誤判方向的狀況：公司 TLS 攔截防火牆造成的 UNABLE_TO_GET_ISSUER_CERT_LOCALLY，第 2 章 2.2 節已經教過用 NODE_EXTRA_CA_CERTS 指向公司根憑證檔案。官方建議的排查順序其實是先試更簡單的 NODE_USE_SYSTEM_CA=1，讓 Node.js 直接信任作業系統本身的憑證庫——多數公司 IT 早就把根憑證裝進系統層了，用這個環境變數不需要你自己去跟人要憑證檔案，也比較不會因為檔案路徑跑掉或憑證過期而重新故障；NODE_EXTRA_CA_CERTS 適合當作前者不夠用時的備案，兩者不衝突，可以先後都試。

Linux 上如果系統缺少 ripgrep（rg）執行檔，第 4 章 4.2 節提過的是「靜默退回較慢的內建搜尋」；但在企業代理伺服器後方，缺少 rg 有時會直接造成固定 300 秒的啟動卡住、完全不報錯🌐社群。兩種症狀成因相同（缺 ripgrep），表現卻天差地遠——CLI 卡住超過幾分鐘沒動靜時，先確認 rg 是否真的裝好、PATH 抓不抓得到，比猜測是網路問題更快找到根因。

16.5 Shell、env、config 載入順序

很多「CLI 壞了」其實是環境變數沒有載入。互動式 shell、login shell、VS Code terminal、CI shell、npm script、GitHub Action step 的環境都可能不同。排查時只輸出非敏感資訊，例如變數是否存在、目前工作目錄、使用哪個 shell、config 檔路徑；不要把 token 原文寫進 log。

設定值疊了好幾層，誰蓋過誰？

「明明改了 settings.json，CLI 的行為卻完全沒變」是設定類問題裡最常見的一句抱怨。原因通常不是設定檔寫錯，而是有更高優先權的來源蓋掉了它。設定值實際上疊了好幾層，由低到高大致是：程式內建預設值 → 系統層預設檔（依作業系統分別放在 /etc/gemini-cli/system-defaults.json、/Library/Application Support/GeminiCli/system-defaults.json 或 C:\ProgramData\gemini-cli\system-defaults.json）→ 使用者層 ~/.gemini/settings.json → 專案層 .gemini/settings.json → 環境變數 → 命令列參數。越後面優先權越高，命令列參數永遠贏。這份順序以你目前版本的 configuration 文件為準，層數與細節可能隨版本調整✅官方。

env | grep -i gemini

CI 環境變數的兩個連帶陷阱

第一個是誤判成互動模式。只要環境裡存在任何 CI_ 開頭的環境變數，Gemini CLI 底層用來偵測執行環境的套件（is-in-ci）就會判定目前在 CI 環境裡，強制切成非互動模式——即使你其實在自己的本機終端機工作。常見成因是殘留了別套 CI 工具（例如 GitLab CI 風格）留下的 CI_TOKEN 之類變數。排除法是先確認有沒有這類殘留，找出來 unset 掉：

env | grep '^CI_'
env -u CI_TOKEN gemini

第二個是 DEBUG 環境變數的放置位置。官方文件提到偵錯用的環境變數應該放進 .gemini/.env，而不是專案根目錄那份一般的 .env，否則設定可能不會生效。第 13 章 13.5 節已經提醒過不要在 GitHub Actions 裡直接設 DEBUG；這裡補上原因：這類工具偵測到 DEBUG 時，有些版本會切換成等待 Node debugger 附加的模式，而不是單純多印一點 log，CI runner 上沒有人會去附加 debugger，workflow 就這樣卡到逾時。本機除錯用 --debug 旗標（見 16.10 節）通常比設 DEBUG 環境變數更可控。

16.6 Sandbox、approval、tool permissions

Gemini CLI 能讀檔、改檔、跑命令或呼叫工具時，安全邊界會影響結果。若 agent 說不能讀、不能寫、不能執行、需要確認、工具不存在，先看目前 sandbox、approval policy、trusted folder、工具 allow/exclude 設定與專案權限。不要為了通過一次任務就永久打開所有權限。

權限排查：
- 這個資料夾是否被信任？
- 目標檔案是否在允許讀寫的 workspace 內？
- 命令是否需要網路、系統路徑、sudo 或外部工具？
- approval 是否被設成永不詢問、每次詢問或自動允許？
- MCP/tool 是否被 allowlist 或 exclude list 擋住？
- 是否應該改成 dry run、plan mode 或手動審核？

自訂 sandbox Dockerfile：Permission denied 不是叫你關掉沙盒

第 7 章 7.6 節提過可以用 .gemini/sandbox.Dockerfile 自訂映像、補齊預設映像沒有的工具。這裡常見一個誤會：自訂 Dockerfile 裡如果直接呼叫 apt-get install 之類的系統套件安裝指令，會撞上 Permission denied——不是 Docker 設定壞了，是官方基礎映像 gemini-cli-sandbox 預設用非 root 的 node 使用者執行，而系統套件安裝本來就需要 root 權限。撞到這個錯誤，直覺反應常常是乾脆整個放棄 sandbox 防護，但正確做法只是在 Dockerfile 裡先切回 root 裝完套件，再切回 node：

# .gemini/sandbox.Dockerfile 內容片段
FROM gemini-cli-sandbox

USER root
RUN apt-get update && apt-get install -y --no-install-recommends some-package \
    && rm -rf /var/lib/apt/lists/*
USER node

裝完系統套件切回 USER node 這一步不能省略——不切回去的話，容器裡執行的每個工具呼叫都變成用 root 身分跑，等於自己親手拆掉 sandbox 原本要隔離的那層保護。

approval 模式本身也不是完全可靠的黑盒子，第 7 章 7.3 節已經記錄過 security.disableYoloMode 意外連動 auto_edit、shell 重導向仍跳出核准提示這兩個落差（GitHub issue #13792、#26539）。另外多筆社群回報顯示，開了 -y／--yolo 之後，某些版本的編輯或工具呼叫仍然會要求手動確認，不是設定錯誤，是已知的版本 bug（GitHub issue #18815、#18816）🌐社群。若你的自動化腳本假設「YOLO 模式一定不會卡住等輸入」去做無人值守排程，這個假設在某些版本上並不成立，上線前務必先在目標版本上實測一輪，不要只憑文件承諾。Windows PowerShell 上另有一種容易混淆的狀況：即使開了 YOLO，執行某些系統指令還是會跳出 PowerShell 自己的安全性提示——這跟 Gemini CLI 無關，是 Set-ExecutionPolicy 那層 Windows 自己的保護機制，不是 approval 設定沒生效。

16.7 MCP failures

MCP 失敗常見原因是 server command 不存在、工作目錄錯、env 沒注入、stdio server 輸出雜訊、port 被占用、JSON schema 不合、工具名稱衝突、權限被 CLI 擋住，或 server 啟動太慢。先用最小 MCP server 測，再逐一打開資源、prompt、tool。

第 9 章 9.6 節已經完整整理過 transport 欄位選錯（url／httpUrl／command 三選一混用）、MCP 子行程抓不到 PATH、npx 首次下載卡住這幾個大宗成因，這裡不重複，直接照那節排查即可。有一個更細節、容易讓人以為是自己設定錯的限制值得補充：CLI 對 MCP server 最初的 discovery（也就是 tools/list 那次交握）呼叫，官方寫死了 60 秒逾時；就算你在 settings.json 把該 server 的 timeout 設得再長，也不會延長這個 discovery 階段的等待，逾時一樣會出現 MCP error -32001: Request timed out✅官方。看到這個錯誤代表 server 啟動或第一次交握本身太慢（常見於前面提過的 npx 現抓套件），不是你的 timeout 設定沒生效——解法一樣是先手動裝好套件，讓 command 直接指到已安裝的執行檔，縮短開機時間。另外，如果啟動時直接報 EADDRINUSE，代表該 MCP server 想用的埠已經被別的行程佔用，用 lsof -i :<port>（macOS/Linux）找出來停用，或替這個 server 換一個埠。

16.8 Headless、CI、JSON errors

headless 模式最怕輸出混入互動文字，導致 JSON parser 失敗。自動化腳本應指定穩定輸出格式、分開 stdout/stderr、保存原始輸出、檢查 exit code，並為空回應、截斷、rate limit、timeout、非 JSON 回應設處理分支。CI 中也要固定 CLI 版本或至少記錄版本。

# 概念範例：實際 flags 請以目前文件與 /help 為準
gemini -p "summarize this diff as JSON" \
  --output-format json \
  > gemini-output.json \
  2> gemini-debug.log

若 JSON 解析失敗，先不要只看 parser 報錯。打開原始輸出確認是否有 login prompt、警告、progress、Markdown code fence、模型道歉文字、截斷結果或 stack trace。必要時讓模型只輸出單一 JSON object，並在外層程式加 schema 驗證與重試上限。

16.9 GitHub Action issues

GitHub Action 問題通常落在 secret、permissions、checkout、runner、事件觸發與 PR 權限。fork PR 預設拿不到 repository secrets；GITHUB_TOKEN 權限可能不夠留言或改檔；workflow 在不同 event 下的 payload 不同；node_modules 或 npx cache 也可能讓你跑到舊 CLI。

# 概念片段：請依官方 Action/CLI 文件更新
permissions:
  contents: read
  pull-requests: write
  issues: write

env:
  GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

CI 內的 AI 任務要有明確邊界：只讀 PR diff、不要暴露 secrets、不要自動修改 fork PR、不要在沒有人工審核時執行 destructive command。把 Gemini CLI 版本、模型路由、事件名稱、PR 編號與錯誤輸出寫進 artifact，方便追蹤。

幾個查了老半天才發現是版本 bug 的狀況

下面三個不是你 workflow 寫錯，是特定版本的已知問題，社群陸續回報過，先對照症狀，省下自己重查一輪的時間：

如果你手上還留著舊教學寫的 gemini-cli-action，那是官方整合改名前的舊套件名稱，現在應該全面換成第 13 章使用的 google-github-actions/run-gemini-cli——舊名稱不會馬上完全失效，但不會再拿到新功能與修復，看到教學裡出現舊名稱，先確認發布日期再照抄。

16.10 Logging 與 debug

好的 debug log 要能重現問題，但不能洩漏秘密。至少記錄 CLI 版本、模型或路由名稱、工作目錄、作業系統、Node/npm 版本、認證方式類型、request id、exit code、stderr 摘要、MCP server 名稱與 CI run id。對長任務，要記錄每個階段：讀上下文、呼叫模型、工具呼叫、測試、輸出解析。

「CLI 卡住不動」怎麼分層排查

畫面停在原地、游標不動，是疑難排解裡最讓人心慌卻也最沒有頭緒的狀況——因為看起來所有卡住的樣子都一樣。社群把這種「假死」拆解成四種成因不同、但外觀相似的機制，排查時應該對號入座，而不是一律當成網路問題重跑🌐社群：

最快的單一排查手法是用 timeout 包住整個指令，搭配 --debug 看細節輸出：

timeout 30 gemini --debug -p "你的任務" 2> debug.log
cat debug.log

30 秒後強制中斷，回頭看 debug.log：卡在網路層通常會看到重試訊息；卡在 MCP 子行程，stdio 部分不會有新輸出；卡在 agent 內部迴圈，會看到大量 API 呼叫但輸出 token 極少。互動模式中也可以直接按 F12 打開內建的偵錯主控台，不必重開一個新視窗。

回報 bug 前，先自己蒐集這些

懷疑真的是版本 bug、想回報給官方時，一次附齊資訊比事後被要求補充快很多：

gemini debug --all > debug.txt
gemini --version
node --version

連同作業系統版本、以及一個能重現問題的最小 prompt 一起附在 GitHub issue 裡，官方表示附齊這些資訊的 issue 分流較快。有一個容易讓人白忙一場的細節：CLI 內建的 /bug 指令本身有已知 bug（GitHub issue #12286），產生的 issue 樣板連結有時會導向錯誤頁面、回報不了🌐社群。連續點了沒反應，不要一直重試，直接到 google-gemini/gemini-cli 這個 repo 手動開一個新 issue，把上面蒐集到的資訊貼上去即可。

16.11 何時遷移 Antigravity，何時留在 API/enterprise

若你主要使用個人帳號、互動式 coding agent、終端機輔助改檔，且官方目前把這條路線導向 Antigravity，應評估遷移。若你的系統是自家產品內的 API 呼叫、企業帳務、Vertex AI IAM、資料治理、穩定 CI pipeline 或合規流程，通常不應只因 CLI 產品轉向就倉促改架構；應分開評估「人使用的 coding tool」與「系統使用的模型 API」。

配額重置方式改了：從「每日」到「每週」

第 0 章 0.2 節列過轉型前 Gemini CLI 用 RPM／RPD 這種「每日重置」的請求數配額。Antigravity CLI 換了一套完全不同的計費邏輯：不是按請求數每天重置，而是按「每週運算額度」重置。這個差異對重度使用者影響不小——社群回報，密集使用（例如一次任務產出約 2000 行程式碼這種量級）就可能把一整週的額度打完，觸發長達 168 小時（整整一週）的鎖定，中間完全無法使用，不是降速、是直接鎖住🌐社群。偶爾用一下的輕量使用者受影響有限；但如果你的工作模式是每天都在跑大量產出，遷移前值得先抓自己過去一週的實際用量，估算會不會提早撞牆，而不是等鎖住了才發現換了一套完全不同的節奏。

企業或團隊做決策時，除了「這週用得順不順」，更上位的判斷點是 Apache 2.0 開源與閉源這個結構性差異：Antigravity CLI 短期內功能可能已經夠用，但把關鍵工作流綁進一個閉源、後端隨時可能被廠商關閉的工具，跟綁進一個原始碼在自己手上、隨時能 fork 自架的工具，長期的可維護性、可稽核性與風險等級不是同一個量級。這不是說 Antigravity CLI 不能用，而是這一層風險評估不該只看眼前功能夠不夠，該和第 0 章 0.5 節提到的授權差異一起放進團隊的決策紀錄。

16.12 遷移決策樹

從這裡開始：
1. 你是在「終端機互動改程式」嗎？
   是 → 個人/Pro/Ultra 路線優先評估 Antigravity；企業使用者查管理員政策。
   否 → 繼續。
2. 你是在產品或後端服務中呼叫模型 API 嗎？
   是 → 留在 Gemini API/Vertex/enterprise 路線，按 API 文件與帳務治理升級。
   否 → 繼續。
3. 你是在 CI/GitHub Action 自動 review 或產報告嗎？
   是 → 驗證 headless/Action 是否仍受支援；必要時改 API/Vertex 實作。
   否 → 繼續。
4. 你需要 IAM、審計、資料區域、預算、集中 key 管理嗎？
   是 → 評估 Vertex AI 或 enterprise；不要依賴個人登入。
   否 → 使用目前官方建議的 CLI 路線，並保留可回退方案。

動手遷移前，先跑這三行稽核指令

決定要遷移之後，不要直接動手改設定——先花五分鐘稽核現有工作流裡有多少地方還在假設 gemini 這個指令存在，比事後一個一個踩雷划算：

# 1. 揪出還在呼叫 gemini 指令的 CI/CD pipeline
grep -r "gemini " .github/ .circleci/ .gitlab-ci.yml 2>/dev/null

# 2. 揪出需要改名的 MCP 遠端設定
grep -r '"url"' ~/.gemini/ 2>/dev/null

# 3. 揪出依賴 --acp 介面做橋接的自動化
grep -r "\-\-acp" . 2>/dev/null

第三行抓的是依賴 gemini --acp（Agent Client Protocol，一種讓編輯器或 IDE 跟 coding agent 互通的協定）做 Slack、Discord、Teams 這類橋接的自動化——第 0 章 0.5 節提過 Antigravity CLI 目前沒有對應的 ACP 支援，這類橋接無法直接照搬，需要另外規劃替代方案，或暫時留在 Gemini API／enterprise 路線繼續跑。

本章小結

疑難排解的核心是分流：auth、quota、billing、Node/npm、PATH、shell/env、sandbox、MCP、headless、CI、GitHub Action、logging 與產品路線各有不同修法，各自也有專屬的 exit code、設定疊加順序與已知版本 bug 可以對照，不必每次都從頭猜。Gemini CLI/Antigravity 功能變動快，請用目前官方文件與 /help 驗證。遷移時把互動式 coding tool、API 服務、Vertex/enterprise 治理與 CI 自動化分開判斷，動手前先跑過稽核指令，比改完才發現漏改一個欄位划算。

動手試試

1. 用本章的最小排查紀錄，替你最近一次 CLI 錯誤補完整資訊。
2. 檢查本機 node、npm、gemini 的路徑，確認 PATH 沒有指到舊版本。
3. 為你的 CI workflow 寫一份失敗分流表：auth、quota、JSON、permission、timeout。
4. 挑一個 MCP server，確認 debug log 是否只走 stderr，不污染 JSON/stdout。
5. 用決策樹判斷你的使用情境該遷移 Antigravity、留在 Gemini API、改 Vertex，或走 enterprise。
6. 對照 16.1 節的 exit code 表，把你最近一次失敗的 exit code 記下來，確認判斷跟錯誤訊息一致。
7. 如果你打算遷移，先跑過 16.12 節的三行稽核指令，列出所有需要調整的地方，再動手改。