常见问题

这页按实际问题提供诊断入口。涉及模型、订阅和价格时，以当前账号和官方页面为准；不要把某个旧版本 FAQ 的模型示例当成永久范围。

怎样确认运行版本

终端可用 gemini --version 或 gemini -v，会话内使用 /about。包管理器也可列出安装版本，例如 npm 的 npm list -g @google/gemini-cli 或 Homebrew 的 brew list --versions gemini-cli。

如果列出的包版本与实际命令行为不一致，先核对 PATH 和安装来源，再按安装与升级处理。

为什么返回 429

API error: 429 - Resource exhausted 表示请求触及适用额度或速率限制。查看 Google AI Studio 或相应 Cloud 项目的使用量，减少短时间突发请求；持续需要更高额度时再通过服务支持的方式申请。

升级订阅后仍可能遇到共享额度、模型额度或分钟速率限制。CLI 与 IDE Agent Mode 的相应订阅额度共享，见配额与价格。

为什么统计中没有缓存 token

缓存 token 只在实际使用缓存时出现。官方 FAQ 区分 Gemini API key/Vertex AI 与 Google Code Assist OAuth；后者不支持相同的 cached content 创建功能。可以继续用 /stats 看总用量，详细说明见Token 缓存。

配置到底来自哪里

个人设置常在 ~/.gemini/settings.json，项目设置在 .gemini/settings.json。FAQ 的“两处文件”是常见用户入口，完整配置还包括系统默认、系统覆盖、环境和参数，见设置层级。

GOOGLE_CLOUD_PROJECT 在 POSIX Shell 中可用 export GOOGLE_CLOUD_PROJECT="your-project-id"，PowerShell 使用 $env:GOOGLE_CLOUD_PROJECT="your-project-id"。是否需要该值要按认证方式决定，不能把它当成所有登录错误的统一修复。

API key 应放在哪里

官方建议使用 .gemini/.env 或系统凭据管理工具，在运行时提供密钥。环境文件本身不是加密存储；不要提交密钥到版本控制，也不要把密钥硬编码到公开脚本中。加载和变量优先级见环境配置。

可以把 CLI OAuth 交给其他 agent 吗

官方 FAQ 明确不支持第三方 agent 借用 Gemini CLI OAuth 访问后端，第三方集成应采用对应服务支持的 API key 路径。具体政策入口见隐私与条款。

平台或安装错误如何处理

Windows 的 Unix 命令兼容问题、ESM/模块错误、CI 模式检测和 PATH 问题分别见运行环境排障。仍无法定位时，在官方 Gemini CLI GitHub Issues 或 Q&A discussions 搜索相同错误，并准备最小复现信息。