---
title: "FAQ"
description: "Gemini CLI 常見問題：第三方 OAuth piggyback 風險、429 配額、ESM 錯誤、快取 token、版本檢查和安全儲存 API key。"
verifiedAt: "2026-05-09"
---

FAQ 適合先看，因為它覆蓋了很多“不是 bug，但容易踩坑”的問題。

> [!NOTE]
> 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。

> [!WARNING]
> 不要把 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。

## 檢視版本

```bash
gemini --version
gemini -v
npm list -g @google/gemini-cli
```

在 Gemini CLI 會話內也可以用：

```text
/about
```

如果機器上曾經混用 npm、Homebrew、MacPorts、npx 或原始碼構建，要同時查 shell 實際命中的入口：

```bash
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 內容時，先脫敏再貼。

## 下一步

<Cards>
  <Card title="故障排查" description="FAQ 不能定位時，進入認證、網路、PATH、sandbox、CI 分層排查。" href="/zh-Hant/docs/gemini-cli/official/08-troubleshooting-reference/81-troubleshooting" />
  <Card title="配額與費用" description="429、訂閱和模型可用性要回到 quota/pricing 邏輯。" href="/zh-Hant/docs/gemini-cli/official/00-getting-started/06-quota-and-pricing" />
  <Card title="Terms / Privacy" description="OAuth、API key、訂閱和資料邊界要和條款一起看。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/65-terms-privacy" />
</Cards>

## 官方來源

- [Google Developers Gemini CLI](https://developers.google.com/gemini-code-assist/docs/gemini-cli?hl=zh-cn)
- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
- [Gemini CLI FAQ](https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/faq.md)
