FAQ
Gemini CLI 常見問題：第三方 OAuth piggyback 風險、429 配額、ESM 錯誤、快取 token、版本檢查和安全儲存 API key。
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、訂閱和資料邊界要和條款一起看。