FAQ
Gemini CLI 常見問題：第三方 OAuth piggyback 風險、429 配額、ESM 錯誤、快取 token、版本檢查和安全儲存 API key。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| FAQ | 常見問題 | 高頻問題的快速解答。 |
| 按主題查 | by topic | 按問題類別快速定位。 |
| 自助排查 | self-serve | 先自查再找支援。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你從 Gemini CLI 的常見問題裡快速找到對應的解答。
你是 Gemini CLI FAQ 檢索顧問。
【角色】
Gemini CLI FAQ 檢索顧問，按分層定位、一次只改一個變數的原則幫我找根因，每條結論落到能照做的步驟。
【輸入】
- 我遇到的問題或疑問：___
- 屬於哪類（安裝 / 使用 / 模型 / 安全）：___
- 是否已試過什麼：___
- 緊迫程度：___
- 經驗水平：___
【工作流程】
1. 把問題歸到 FAQ 類別
2. 定位最相關的解答方向
3. 給自助排查的起點
4. 提示需進一步排障或支援的情況
5. 給驗證
【輸出規範】
▌一、問題歸類
▌二、解答方向
▌三、自助排查起點
▌四、何時找支援
【硬約束】
- 先自助排查，拿不準的再找支援
- 解答以官方為準
- 敏感資訊不暴露
- 不要替我臆測原因或編造不存在的設定，資訊不全先問清
- 不確定的機制或報錯一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述FAQ 適合先看，因為它覆蓋了很多“不是 bug，但容易踩坑”的問題。
FAQ 不替代故障排查。它更適合先排除認證誤解、配額誤解、包管理誤解和資料安全誤解。
先分清問題型別
| 現象 | 優先看哪裡 | 不要先做什麼 |
|---|---|---|
| 登入或訂閱報錯 | 認證方式、Google Cloud project、賬號型別 | 直接重灌 CLI |
| 429 / quota | Quota、API key / OAuth / Vertex AI 專案 | 反覆重試或開高併發 |
| Node / ESM 報錯 | package.json、tsconfig.json、依賴安裝 | 把 CLI bug 和業務專案設定混在一起 |
| token stats 不一致 | 目前認證方式是否支援 cached content | 把 /stats 當作統一賬單頁面 |
| 版本混亂 | gemini --version、包管理器、安裝來源 | 同時混用 npm、Homebrew、原始碼構建 |
不能拿 OAuth 給第三方工具搭便車
官方明確不允許第三方軟體、工具或服務借用 Gemini CLI 的 OAuth 認證去訪問後端服務。要在第三方 coding agent 中使用 Gemini，支援方式是使用 Vertex AI 或 Google AI Studio API key。
不要把 Gemini CLI 的登入態當成可複用代理層。這樣既不穩定，也可能違反服務條款。
429 Resource exhausted
API error: 429 - Resource exhausted 通常表示超過 API request limit。
處理方式：
- 檢視 AI Studio 或 Google Cloud 專案裡的用量。
- 批處理時降低併發或加間隔。
- 最佳化 prompt，減少不必要請求。
- 長期需要更高額度時申請 quota increase。
如果你已經升級 Google AI Pro / Ultra，仍然要回官方 quota 頁面確認目前賬號、Gemini Code Assist、IDE agent mode 和 Gemini CLI 是否共享同一額度邊界。不要只看訂閱名推斷所有模型和入口都自動放量。
ERR_REQUIRE_ESM
這通常是 Node.js 專案裡 CommonJS 與 ES Modules 混用導致。
重點檢查：
package.json是否有"type": "module"。tsconfig.json的module是否為NodeNext或相容設定。- 必要時刪除
node_modules和 lockfile 後重新安裝。
cached token 不顯示
Cached token 資訊只會在真正使用 caching 時顯示。API key 使用者可能看到快取 token，OAuth 使用者通常不會看到，因為 Gemini Code Assist API 不支援 cached content creation。
這不是 UI 漏顯示。判斷成本和快取效果時，要同時記錄認證方式、模型、是否真的複用上下文，以及 /stats 是否顯示 cached token。
檢視版本
gemini --version
gemini -v
npm list -g @google/gemini-cli在 Gemini CLI 會話內也可以用：
/about如果機器上曾經混用 npm、Homebrew、MacPorts、npx 或原始碼構建，要同時查 shell 實際命中的入口：
command -v gemini
npm list -g @google/gemini-cli
brew list --versions gemini-cli版本問題要先鎖定“誰在提供目前 gemini 命令”，再決定更新或解除安裝。
設定檔在哪裡
Gemini CLI 的常見設定入口包括全域 ~/.gemini/settings.json 和專案級 .gemini/settings.json。專案 .gemini/.env 可用於載入專案環境變數。
排錯時先區分：
- 全域設定影響所有專案。
- 專案設定隻影響目前儲存庫。
.gemini/.env適合專案級環境變數，不適合提交金鑰。- shell profile 裡的變數可能覆蓋 CLI 判斷。
安全儲存 API key
推薦方式：
- 專案
.gemini/.env。 - macOS Keychain、Windows Credential Manager 或 Linux secret manager。
- CI secret store。
不要把 key 寫進原始碼、教學示例儲存庫或記錄。
什麼時候去 GitHub
如果 FAQ 和 troubleshooting 都沒有覆蓋，先搜官方 issue 和 discussions。提交 issue 前，最少準備版本、系統、安裝方式、認證方式、最小復現命令、錯誤全文和是否能在空目錄復現。涉及賬號、token、專案 ID、公司路徑和 prompt 內容時，先脫敏再貼。
下一步
故障排查
FAQ 不能定位時，進入認證、網路、PATH、sandbox、CI 分層排查。
配額與費用
429、訂閱和模型可用性要回到 quota/pricing 邏輯。
Terms / Privacy
OAuth、API key、訂閱和資料邊界要和條款一起看。