本页汇总 Gemini CLI 使用中最高频的问题：遇到 429 Resource Exhausted 要先检查 AI Studio 用量后再申请配额提升；ERR_REQUIRE_ESM 通常是 package.json 缺少 "type": "module"；Windows 下 chmod 报错需换用 icacls 或 WSL；API Key 应存入 .gemini/.env 而非硬编码；OAuth 用户的 Token 缓存统计不可用。

常见问题解答（FAQ）

通用问题

为什么 Gemini CLI 不能与 Claude Code、OpenClaw 等第三方工具配合使用？

用第三方工具借用 Gemini CLI 的 OAuth 认证访问后端服务，违反了 Google 的服务条款和政策，可能导致账号被暂停。正确做法是在第三方 AI 编码工具中直接配置 Vertex AI 或 Google AI Studio API Key。

遇到 API error: 429 - Resource exhausted 怎么处理？

429 错误表示已超出 API 请求速率限制。

处理步骤：

1. 查看用量：登录 Google AI Studio 或 Google Cloud 控制台确认当前用量
2. 等待重置：免费配额通常按分钟或按天重置，等一段时间再试
3. 优化调用频率：多次请求之间加延迟，或合并多个小请求为一个
4. 申请配额提升：如持续触达上限，向 Google 申请更高配额
5. 升级订阅：Google AI Pro/Ultra 订阅用户享有更高的 Gemini 2.5 Pro/Flash 配额

详见 配额与定价 文档。

为什么 /stats 没有显示缓存 Token 数？

Token 缓存统计只对 API Key 用户（Gemini API Key 或 Vertex AI）可用，使用 Google 账号（OAuth）登录的用户不支持，因为 Gemini Code Assist API 不支持缓存内容创建。

即使无法看到缓存统计，也可以用 /stats 查看总 Token 使用量。

---

安装与更新

如何查看当前安装的版本？

有多种方式：

# 命令行查询
gemini --version
gemini -v

# 包管理器查询
npm list -g @google/gemini-cli
bun pm ls -g @google/gemini-cli
brew list --versions gemini-cli

也可以在 CLI 会话中输入 /about 查看版本信息。

如何更新到最新版本？

# npm 全局安装
npm install -g @google/gemini-cli@latest

# Homebrew
brew upgrade gemini-cli

如果是从源码编译的，先 git pull 拉取最新代码，再 npm run build 重新构建。

---

运行报错

ERR_REQUIRE_ESM 错误怎么解决？

这个错误通常出现在 Node.js 项目中，原因是 CommonJS 和 ES Modules 之间配置不一致。

检查清单：

1. package.json 中必须有 "type": "module"：

   {
     "type": "module"
   }

2. tsconfig.json 中 module 字段必须设置为 NodeNext 或兼容值：

   {
     "compilerOptions": {
       "module": "NodeNext"
     }
   }

如果改完还不行，删除 node_modules 和 package-lock.json，重新 npm install。

---

平台兼容性

Windows 上运行 chmod +x 等命令报错怎么办？

chmod 是 Unix 命令，Windows 原生不支持。

解决方案：

• 用 Windows 等价命令：文件权限管理用 icacls

  icacls yourfile.sh /grant Users:RX

• 用 Git Bash 或 WSL：在 Unix 兼容层环境中运行 Unix 命令
  • Git Bash：安装 Git for Windows 后直接使用
  • WSL：wsl chmod +x yourfile.sh

更多 Windows 兼容性问题参见 故障排查 和 沙箱安全隔离。

---

配置与认证

如何配置 GOOGLE_CLOUD_PROJECT？

macOS/Linux：

export GOOGLE_CLOUD_PROJECT="your-project-id"
# 永久保存：加到 ~/.bashrc 或 ~/.zshrc

Windows PowerShell：

$env:GOOGLE_CLOUD_PROJECT="your-project-id"
# 永久保存：加到 $PROFILE 文件

API Key 应该存在哪里？

推荐方式：存入项目的 .gemini/.env 文件，Gemini CLI 启动时会自动加载：

# .gemini/.env
GEMINI_API_KEY=your-api-key-here

记得把 .gemini/.env 加入 .gitignore，不要把 API Key 提交到代码仓库。

更安全的做法是使用系统密钥管理工具（macOS Keychain、Windows Credential Manager、Linux Secret Service），在脚本运行时动态读取。

settings.json 在哪里？

Gemini CLI 有两个配置文件，按优先级合并（项目级覆盖用户级）：

级别	路径
用户级	~/.gemini/settings.json
项目级	./.gemini/settings.json（项目根目录）

详见 配置参考（settings.json）。

---

订阅与配额

升级了 Google AI Pro/Ultra 还是触达限速，是 Bug 吗？

不是 Bug。Pro/Ultra 的更高配额是针对 Gemini 2.5（Pro 和 Flash），并且是 Gemini CLI 和 IDE 插件的共享配额。如果两个地方都在高频使用，仍然可能触达上限。

可以在 Google One 订阅管理 确认订阅状态，在 配额与限制文档 查看具体的速率上限。

Google AI Pro/Ultra 用户的数据隐私如何？

付费用户的数据不会被 Google 用于训练机器学习模型。免费用户可以在设置中主动选择退出数据使用。详见 Gemini Code Assist 个人版隐私声明。

---

仍然没有找到答案？

• 搜索 Gemini CLI GitHub Q&A 讨论区
• 在 CLI 中输入 @cli_help 你的问题 直接问内置的 CLI 帮助代理
• 查看 故障排查指南 了解更多已知问题

常见问题

Q: 免费用户的 Gemini 2.5 Pro 每天能用多少次？

A: 免费额度每分钟和每天都有上限，具体数字会根据 Google 策略调整。最新数据请查阅 配额与定价 页面或 官方配额文档。

Q: Gemini CLI 的 OAuth 登录和 API Key 有什么区别？

A: OAuth 登录使用个人 Google 账号（免费/Pro/Ultra 订阅），无需手动管理 Key，适合个人使用；API Key 方式适合脚本/CI/CD 集成，支持 Token 缓存统计，但需要在 Google AI Studio 或 Google Cloud 手动创建和管理密钥。详见 认证配置。

Q: 在无头模式（CI/CD）中也需要配置认证吗？

A: 是的。无头模式下必须使用 API Key（GEMINI_API_KEY 环境变量），不支持 OAuth 交互式登录。详见 无头模式技术参考。