CLI 疑難排解：登入、PATH 與設定失效

Gemini CLI 發生問題時，先找出失敗層級，通常比重新安裝所有工具更有效。本篇建立一條可重複使用的排查路線：從找不到命令、登入失敗，到檔案權限、額度及設定未載入。你會得到能儲存的診斷紀錄，並知道修正後要重跑哪個最小測試。

開始前：儲存症狀與環境

先記下你正在做什麼、完整錯誤碼、發生時間、作業系統、終端機及 CLI 版本。本文以 Gemini CLI 0.59.0 與官方疑難排解檔案為基準。回報時遮蔽金鑰、權杖、私人路徑與檔案內容；不要把整份家目錄設定直接公開，很多問題只需要版本與錯誤碼就能定位。

把問題分成「命令還沒啟動」「CLI 啟動但不能登入」「能對話但某個工具失敗」「工具能用但設定不符預期」。每一類的下一步不同。先用一個沒有檔案、沒有工具的簡短問題測試；如果連這個都失敗，就不必先修改專案的 GEMINI.md。

第一步：確認執行的確實是預期版本

在 PowerShell 執行以下診斷命令。Get-Command -All 可以看到是否有多個同名入口；npm prefix -g 可幫你找到全域安裝位置。這些命令只列出版本與路徑，不會列印登入憑證。macOS 或 Linux 可改用 command -v gemini，並同樣執行版本檢查。

node --version
npm --version
Get-Command gemini -All
npm prefix -g
gemini --version

如果顯示找不到 gemini，先回到安裝教學確認安裝完成，並重新開啟終端機讓 PATH 更新。若版本與剛安裝的不一致，可能是另一個入口排在前面；先確認實際路徑，不要反覆安裝不同版本，讓診斷更加混亂。

Windows 若因 PowerShell 執行原則阻擋 npm 或 gemini 的 .ps1 啟動器，先確認錯誤指的是哪個檔案。可依安裝方式使用對應 .cmd 入口，或由系統管理者檢查既定政策。不要為了一次啟動就把整臺電腦的執行政策永久改成無限制。

第二步：把登入、方案與額度分開處理

能開啟 CLI 卻無法登入時，確認選的是Google 帳號、API Key 或 Vertex AI哪一條認證路線。個人 Google 帳號與組織帳號的條件不同，瀏覽器登入另一個帳號也可能造成混淆。重新選擇認證時觀察顯示的帳號，不要只看瀏覽器已經登入 Google。

官方排解檔案提醒，GOOGLE_CLOUD_PROJECT 等環境變數可能讓個人帳號進入組織資格檢查。先檢查這些變數是否存在及用途，再決定是否在目前終端機移除；公司原本需要的設定不能一律清空。只要確認存在與否即可，不必輸出所有環境變數。

若錯誤是額度或速率限制，重新登入不一定有幫助。記錄回傳狀態、模型與認證方式，到對應用量頁面核對。Gemini 消費者訂閱與 API 計費不是同一個帳本，付費方案名稱也不能直接證明 API 額度已增加；細節請看方案篇與API 用量篇。

第三步：確認工作目錄與設定來源

能正常對話，但規則沒生效時，先檢查目前資料夾。專案設定與全域設定可能不同；從另一個終端機啟動，也可能使用另一組環境。執行 /memory list 檢視實際載入的檔案，再以 /memory show 檢查內容，不要只憑模型的語氣判斷是否讀到了規則。

/memory list
/memory show
/memory reload

在本篇核對的 0.59.0 中，reload 是重新載入的指令名稱，refresh 保留為別名。修改記憶層級檔案後重新載入，再核對清單與內容；若仍看不到，檢查檔名、信任狀態與啟動位置。settings.json 則先用 JSON 驗證器檢查，不能用 /memory 的結果證明所有程式設定都已更新。

遇到檔案存取失敗，先確認路徑真的存在，並區分 .geminiignore 的探索忽略、作業系統權限、可信任資料夾與沙箱邊界。這幾者作用不同。用專案內的非敏感小檔測試，再逐步移到實際檔案，較容易知道哪個邊界造成失敗。

第四步：把擴充與網路問題縮成一個測試

若只有MCP 服務失敗，檢視 /mcp 的連線狀態，再確認伺服器入口或遠端端點。遇到連線埠佔用，先查明佔用者，改用服務允許的其他埠；不要直接結束所有 Node 或 Python 程式，因為其他工作可能也在使用它們。

公司網路若回報憑證錯誤，依官方文件與資訊人員指示設定 Node 信任的憑證來源。不要用停用 TLS 驗證來掩蓋問題。比較公司網路與已允許的測試環境時，儲存錯誤差異與使用的設定，讓資訊人員能判斷代理伺服器或憑證鏈是否需要調整。

常見問題與可交接的診斷紀錄

「什麼時候才需要重新安裝」當執行入口缺少檔案、套件安裝中斷，或官方修正要求更新時才有明確理由。先儲存版本與錯誤，再採原本的安裝方式更新。重新安裝後要重跑同一個最小測試，不能只因為安裝命令成功就宣佈問題解決。

「要不要刪除整個 .gemini」不要把它當成第一步，因為裡面可能有設定、指令、技能與歷史。若要隔離某個可疑設定，先備份並只處理該檔案，記錄原值；修正後確認其他功能仍可使用，避免排查一個問題卻遺失可重用的工作內容。

「模型說修好了算完成嗎」應以原本失敗的操作重新驗證。例如規則問題要核對載入來源，MCP 問題要看實際工具結果，批次問題要檢查退出碼與輸出。把成功與失敗範例都留下，日後升級才能快速發現回歸。

最後整理一份紀錄：症狀、版本、最小重現、已排除原因、有效修正及尚未完成的部分。若要向官方提報，只附重現所需的最小資料。這份紀錄也能連到指令總表或相關設定篇，讓下一位處理者直接沿著證據繼續。

完成後的檢核

接著可以閱讀 Gemini CLI 安裝、settings.json，把本篇的操作接到下一個工作流程。

返回 Gemini 教學總目錄

• AI 工具
• 教學
• Gemini CLI 與 API