---
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="/docs/gemini-cli/official/08-troubleshooting-reference/81-troubleshooting" />
  <Card title="配额与费用" description="429、订阅和模型可用性要回到 quota/pricing 逻辑。" href="/docs/gemini-cli/official/00-getting-started/06-quota-and-pricing" />
  <Card title="Terms / Privacy" description="OAuth、API key、订阅和数据边界要和条款一起看。" href="/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)
