结论先说
- 先对号入座选对工具:官方已于 2026-06-18 停止个人谷歌账号(含免费档、Google AI Pro 与 Ultra)在旧版 Gemini CLI 上的请求服务,个人账号请直接改用新版 Antigravity
agy命令行;只有 付费 Gemini API Key、Vertex AI 云项目及企业许可 仍走本文的环境变量接入路线。 - 环境变量优先级高于交互式缓存:支持写进系统 Shell 配置或独立存放在
~/.gemini/.env文件中;一旦终端残留了旧的GOOGLE_API_KEY或GOOGLE_GENAI_USE_VERTEXAI,就会静默抢占认证通道导致报错。 - 免费层 API Key 在终端跑智能体极易秒触发
429:按官方配额表,免费层 API Key 每日请求上限低且仅限轻量 Flash 模型;跑多轮读文件循环须绑定付费结算层级(Paid Tier)。 - Vertex AI 报
limit: 0多半是云项目没开 API 或没绑账单:先在 GCP 控制台启用 Vertex AI API 并核验gcloud默认凭据。 - 谷歌账号与多工具订阅直达入口:体验 Jules 异步提 PR、Stitch 生 UI 与 AI Studio 需登录合规个人谷歌账号,缺号可前往本站 谷歌账号购买页 选购 2FA 谷歌邮箱成品号;跨平台开发与设计订阅对比见 AI 会员充值中心。

图:本站根据 Gemini CLI 官方认证文档 整理的示意图
本文根据 Gemini CLI 官方认证文档(geminicli.com/docs/get-started/authentication)及 Google 开发者博客整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是终端截图。本站(bigolab.com)不是 Google 官方网站。
适用于谁
- 在无图形界面的 CI/CD 流水线、Docker 容器或远程服务器上用 付费 Gemini API Key / Vertex AI 跑
@google/gemini-cli的工程师; - 换了新 API Key 却依然报
401鉴权失败,或莫名其妙撞上429 RESOURCE_EXHAUSTED(甚至提示limit: 0)的人; - 分不清当前手头的任务该继续配 Gemini CLI 环境变量,还是直接改用新版
agy命令行的人。
一、两类合规环境变量配法(API Key 与 Vertex AI)
如果你已确认自己的场景属于按 Token 结算的 API 调用或企业云项目(基础安装与停服背景见 Gemini CLI 停服调整与用法说明),官方推荐以下两种免浏览器弹窗的持久化配法:
路线 A:使用 Google AI Studio 的 GEMINI_API_KEY
适合独立脚本、GitHub Actions 自动化步骤或按量付费开发者(还没申请密钥可先看 Gemini API Key 获取教程)。你可以把密钥直接写入 ~/.gemini/.env,这样不会污染全局其他工具的环境变量:
bash
mkdir -p ~/.gemini
cat << 'EOF' >> ~/.gemini/.env
GEMINI_API_KEY="在这里填入你的AI_Studio密钥"
EOF
首次启动 gemini 如弹出认证方式询问,选择 Use Gemini API Key 即可。
路线 B:通过 Google Cloud Vertex AI 企业项目接入
适合要求数据驻留合规、统一走公司 GCP 账单结算的团队。先在终端执行一次应用默认凭据登录:
bash
gcloud auth application-default login
随后在 ~/.gemini/.env(或 .zshrc / .bashrc)里同时配齐三个必填变量:
bash
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT="你的GCP项目ID"
export GOOGLE_CLOUD_LOCATION="us-central1"
如果你既需要准备登录 AI Studio 领密钥的个人谷歌账号,又想在本地终端备一套按月包干的成熟编码工具兜底,可分别查看本站 谷歌账号购买说明 与 Claude Code 订阅服务。
二、常见 429 限流与环境变量串号排查

图:本站根据 Gemini CLI 官方文档 与 API 速率说明整理的排错示意图
在终端跑代码智能体时,一次提问背后往往连发十几次模型请求。遇到报错时按下面四步逐一拆解:
- 排查环境变量「幽灵覆盖」:很多开发者以前装别的 SDK 时在
.zshrc里留过旧的GOOGLE_API_KEY,或者测完云项目忘了关GOOGLE_GENAI_USE_VERTEXAI=true。在终端跑下面这条检查并清空冲突项后再试:
bash
env | grep -E "GEMINI|GOOGLE"
unset GOOGLE_API_KEY GEMINI_API_KEY GOOGLE_GENAI_USE_VERTEXAI
- 区分每分钟速率(RPM/TPM)与每日配额(RPD)耗尽:打开会话输入
/stats model可以直观看到当前已消耗的 Token 量。如果是短时间内扫大仓库撞上每分钟输入 Token 上限(TPM),等一分钟并用-m参数指定轻量 Flash 模型就能恢复;如果是免费层每日总额度见底,同一项目下换新 Key 也没用(官方限额按项目而非单把密钥计算,详见 Gemini API 免费层限额说明 与 Gemini API 429 错误完整排查表)。 - 排查
limit: 0报错:当报错详情里出现配额上限为0时,说明当前请求落到了一个未在所属地区开放免费层、或未绑定有效结算账户(Billing Account)的空云项目上。登录 Google AI Studio 的 Dashboard 检查密钥所属项目的计费状态即可定位。
常见问题
问:写在当前项目根目录 .env 里的 GEMINI_API_KEY 会被误读吗?
答:如果你的业务代码仓库本身也有 .env 且里面恰好有同名变量,在仓库根目录直接敲 gemini 时可能发生变量覆盖。建议专门给 CLI 用的凭据统一放进用户主目录 ~/.gemini/.env,并与业务代码里的变量名做好区分。
问:无界面模式(Headless)在脚本里怎么跑完一句话就自动退出?
答:使用 -p 参数即可非交互运行并直接把结果打到标准输出,例如 gemini -p "检查当前 git diff 有没有明显空指针隐患",非常适合塞进 Git 钩子或流水线步骤。
问:想用谷歌最新的编码优化模型写大项目,继续充 API 跑旧版 CLI 划算吗?
答:官方文档已提示旧版 Gemini CLI 不再针对新一代旗舰编码模型做专门优化,日常交互式重度开发直接切到新版 Antigravity IDE 或 agy 体验更完整。
问:注册谷歌账号卡在手机号验证,或者国内没有外币卡怎么配齐 AI 开发工具?
答:本站提供支持支付宝、微信支付与 AlipayHK 自动发卡的 谷歌邮箱成品号(登录加固步骤见 谷歌账号说明页),同时支持自助获取兑换码开通 ChatGPT Plus 与 Claude Code 订阅,支持开具增值税发票。
0 条评论
还没有评论,来抢沙发~