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、订阅和数据边界要和条款一起看。