Gemini CLI API Key 怎么配置?3 步跑通官方与中转封面图
AI 编程约 8 分钟

Gemini CLI API Key 怎么配置?3 步跑通官方与中转

AI 指南··◉ 0 浏览

一句话答案:从 https://aistudio.google.com/apikey 拿 Key,写进 GEMINI_API_KEY 环境变量,再跑 gemini -p "hi" 看到模型回话就算配好。 全程三步,不用改配置文件。但有个前提得先说:2026 年 6 月 18 日之后,Gemini CLI 不再给个人 Google 账号免费额度,API Key 这条路是个人用户目前最稳的主路径。

本篇只解决 API Key 怎么配、怎么验、配不上怎么办。settings.json 字段详解、429 排查、价格明细各有专文,这里一句话带过。

Gemini CLI 官方仓库 README 中的认证方式章节截图,展示 Gemini API Key、OAuth 与 Vertex AI 三个选项

先搞清楚:你现在该用哪个 Google CLI

这是 2026 年下半年最容易踩的坑。很多人照着一年前的教程操作,卡在登录环节,然后以为自己 Key 配错了。

官方 README 顶部有段醒目状态说明,核心三条:

  • Gemini CLI 现在只服务企业授权场景:Gemini Code Assist Standard / Enterprise,以及 Google Cloud 上的 Code Assist for GitHub。
  • 个人免费额度和 Google AI Pro / Ultra 已迁到 Antigravity CLI,时间是 2026 年 6 月 18 日,官方博客发了迁移公告。
  • 没针对 Gemini 4 系列调优,官方明确不建议拿它给 Gemini 模型跑分。

对应到你的情况:

你的身份 该用什么 为什么
有 Code Assist 企业授权 Gemini CLI(本文) 这是它现在的主场
个人 Google 账号 / AI Pro / Ultra Antigravity CLI(agy) 个人额度已迁过去
只要模型 API,不写代码 Gemini API CLI(gemini-api) 无状态 API 命令行,不是编程 agent
想用第三方或中转 Key Gemini CLI 仍可用 API Key 认证分支没下线

所以本篇讲的配置在三种情况都成立:自己有 AI Studio 的 Key、公司给了授权但你想走 Key 计费、用第三方中转 Key。差别只在第三步填什么。

第一步:从 Google AI Studio 拿 Key

官方认证文档写得很直白,Key 来自 Google AI Studio,地址 https://aistudio.google.com/app/apikey。

进去之后创建 API Key、选一个 Cloud 项目关联、复制那串 AIza 开头的字符串。三个实测容易出问题的地方:

  • Key 按项目走,不按账号走。 同一账号在不同项目下的 Key 额度分别计算。公司账号建过的 Key,个人账号里可能一个都没有。
  • 首尾空格是最常见的静默失败原因。 CLI 不校验 Key 格式,错 Key 也不会立刻报错,要等真正发请求才炸。
  • 别把 Key 提交进 Git。 官方专门用一段警告提醒 Key 等同账号凭证。已泄露就去 AI Studio 撤销重建,别靠改代码补救。

拿到 Key 先别急着配 CLI,用 curl 单独验一次,能省掉后面一半排查时间:

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

返回模型列表说明 Key 本身没问题,后面报错都出在 CLI 侧。返回 400 或 403 是 Key 的问题,别往下折腾。

Google AI Studio API Key 创建页面截图,展示获取 Gemini API Key 的入口

第二步:写 GEMINI_API_KEY 环境变量

变量名就一个,GEMINI_API_KEY。

macOS / Linux

export GEMINI_API_KEY="你的Key"

永久生效就追加到 shell 配置文件:

echo 'export GEMINI_API_KEY="你的Key"' >> ~/.zshrc
source ~/.zshrc

macOS 从 Catalina 起默认 zsh,写进 ~/.bashrc 不生效,这个错很常见。

Windows PowerShell

$env:GEMINI_API_KEY = "你的Key"

持久化到用户级:

[Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "你的Key", "User")

写完必须关掉当前窗口重开一个,旧窗口不会自动读新变量。

CI / 容器 / 服务器

用流水线 secret 注入。有个实测坑:CLI 检测到 CI、CONTINUOUS_INTEGRATION 或 CI_ 开头的变量就不进交互模式。所以 CI 里看到"没反应"不一定是认证失败,可能被判定成非交互环境。官方解法是临时去掉该变量:env -u CI_TOKEN gemini。

第三步:验证,别只看有没有报错

配完最忌讳"没报错所以成功了"。用无头模式验,输出机器可读,判断标准明确:

gemini -p "用一句话说明什么是环境变量" --output-format json

按官方 headless 文档,JSON 输出里有 response(模型回答)、stats(token 用量与延迟)、可选 error(失败详情)。三个字段对照看:

  1. error 字段存在 → 认证或请求失败,往下看报错表。
  2. response 有正常内容 → 配置成功。
  3. stats 有 token 计数 → 请求真打到了计费接口,不是本地缓存糊弄你。

交互模式下还有条更快的路:进去敲 /stats model,官方文档说这个命令给出当前会话 token 用量和当前配额的限制。

gemini -p 无头模式输出 JSON 结果的终端截图,展示 response/stats 字段

国内用户:走中转站怎么配

SERP 前排的 php.cn、CSDN 那几篇讲的基本都是这条路,需求真实存在。原理不复杂,CLI 源码里的检测顺序是:先看 GOOGLE_GENAI_USE_GCA,再看 GOOGLE_GENAI_USE_VERTEXAI,接着看 GOOGLE_GEMINI_BASE_URL,最后才看 GEMINI_API_KEY。只要 GOOGLE_GEMINI_BASE_URL 有值,认证类型就切成网关模式,请求全走你填的地址。

所以中转要两个变量一起写:

export GOOGLE_GEMINI_BASE_URL="https://你的中转站地址/gemini"
export GEMINI_API_KEY="中转站给你的Key"

几个必须说清的点:

  • 这个变量在官方代码里真实存在,不是社区野路子。 但官方认证文档正文没教用户配中转,也没推荐过任何第三方服务,属于"代码支持、文档不背书"。第三方中转的服务质量、数据安全、合规性官方没有任何承诺。
  • 顺序是硬约束。 GOOGLE_GEMINI_BASE_URL 优先级高于 GEMINI_API_KEY,设了它一定走网关,想切回官方必须 unset GOOGLE_GEMINI_BASE_URL。
  • 中转 Key 通常不是 AIza 开头,看到 sk- 是正常的。
  • 网关模式下 /stats model 不能判断额度,那些数据来自中转商自己的计费系统。

如果只是直连不通、不想用中转,另一条正统路线是配 GOOGLE_VERTEX_BASE_URL 走 Vertex AI,需要一整套 GOOGLE_GENAI_USE_VERTEXAI=true 加 GOOGLE_API_KEY、GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION。代价是配置项多、要有 GCP 项目。

配不上的六种情况,对号入座

每条都来自官方 troubleshooting 文档或源码逻辑,不是推测。

现象 原因 解法
静默失败,没报错也没回复 Key 复制时带了空格或换行 重新复制,echo $GEMINI_API_KEY | wc -c 核对长度
提示需要 Code Assist Standard 授权 环境里定义了 GOOGLE_CLOUD_PROJECT,触发了组织订阅校验 个人用户 unset 它,检查 .zshrc 和 .env 有无残留
登录报 Request contains an invalid argument Workspace 或关联 Cloud 的账号无法激活免费层 改用 AI Studio 的 Key,官方文档直接这么建议
登录报账号在当前地区不可用 地区不在支持列表 换账号,或改走 API Key / Vertex AI
UNABLE_TO_GET_ISSUER_CERT_LOCALLY 公司网络做了 SSL 拦截 先试 NODE_USE_SYSTEM_CA=1,不行再设 NODE_EXTRA_CA_CERTS 指向企业根证书
command not found: gemini 没全局安装,或 npm 全局目录不在 PATH 重装 npm install -g @google/gemini-cli@latest,检查 PATH

还有个隐蔽的:项目 .env 里写 DEBUG=true 不生效,因为 DEBUG 和 DEBUG_MODE 被自动排除在项目级 .env 之外,要开调试得用 ~/.gemini/.env。

如果你遇到的是 429 限流而非认证错误,那是另一个问题域,看站内的 Gemini CLI 429 报错排查。

让配置别每次重开终端就丢

首选 ~/.gemini/.env 文件。 官方文档说 CLI 自动加载它找到的第一个 .env,搜索顺序是从当前目录往上,然后才是 ~/.gemini/.env 和 ~/.env:

mkdir -p ~/.gemini
cat >> ~/.gemini/.env <<'EOF'
GEMINI_API_KEY="你的Key"
EOF

注意一个陷阱:只加载第一个找到的文件,不合并。 项目根目录有 .env 的话,~/.gemini/.env 里的 Key 完全不生效。这是"明明配了却不生效"的高频原因。

次选 shell 配置文件。 简单,但官方专门警告过:export 进 shell 配置的 Key,任何从该 shell 启动的进程都能读到。

第三种是 settings.json 的 apiKey 字段。 支持 $GEMINI_API_KEY 这种变量引用写法,但不建议明文写 Key。字段完整作用范围和优先级,站内 Gemini CLI settings.json 配置指南 讲得更细。

文件建完记得 chmod 600,别让同机器其他用户能读。

配完之后:额度这件事得说清楚

官方配额文档给的数字是:API Key 免费层每天 250 次请求,且只限 Flash 模型;付费按量计费按 token 走。

但有个时间差要提醒。README 状态说明已写明个人免费额度和 AI Pro/Ultra 迁到了 Antigravity CLI,而配额文档页面上还留着 AI Pro 1500 次、AI Ultra 2000 次的记录。两份官方材料表述不一致,官方没有明确说明企业授权场景下这些个人档位是否仍然生效。保守判断:没有 Code Assist 企业授权,就别指望通过 Gemini CLI 消耗 AI Pro 额度,那是 Antigravity CLI 的地盘。

金额换算和各档位值不值,站内 Gemini CLI 免费额度与定价分析 有完整测算。从零安装和第一个项目怎么跑,看 Gemini CLI 入门教程。国内网络环境的整体选择,Gemini CLI 国内使用指南 把几条路线摆在一起对比过。

常见问题

Gemini CLI 的 API Key 免费吗?能免费用多少?

Key 本身免费申请。官方配额文档写了免费层每天 250 次请求,仅限 Flash 模型。额度按项目算,换项目就是另一份。免费层的请求会用于改进产品,介意数据就走付费层。

GEMINI_API_KEY 和 GOOGLE_API_KEY 有什么区别?

前者是 Google AI Studio 的 Key,配 `GEMINI_API_KEY`;后者是 Google Cloud 的 Key,配 `GOOGLE_API_KEY` 且必须同时设 `GOOGLE_GENAI_USE_VERTEXAI=true`。两个都设会走 Vertex AI,因为源码里 Vertex 开关判断在前。想用 AI Studio 的 Key,就把那个开关去掉。

配好了 Key 但 gemini 命令还是提示登录,怎么办?

先确认变量在当前 shell 真的存在:`echo $GEMINI_API_KEY` 有输出才算数。输出为空多半是写进了没被加载的文件,比如 macOS 上把 export 写进了 `~/.bashrc`。另一个可能是项目目录下的 `.env` 抢先被加载,而里面没这个变量。

可以用第三方中转的 Key 吗?安全吗?

技术上是官方代码支持的,设 `GOOGLE_GEMINI_BASE_URL` 就切网关模式。但官方文档正文没教这个用法,也没推荐任何中转服务,服务质量和数据安全完全取决于中转商。你的代码和提示词会经过对方服务器,用生产代码前想清楚这条。

切换 Key 之后需要重启 CLI 吗?

要。环境变量在进程启动时读取,跑着的会话不会感知变化。改完 `~/.gemini/.env` 或环境变量后退出重进。用 `settings.json` 的 `apiKey` 字段的话,官方文档标注这类改动需要重启生效。

用 API Key 会不会被当成滥用或者封号?

正常调用不会。两个边界要注意:不要拿 Gemini CLI 给 Gemini 模型做跑分,官方 README 明确说它的 harness 没针对 Gemini 4+ 调优、结果不具代表性;也不要多人共用 Key 规避配额。超配额的正解是升级付费层,不是多建几个 Key 轮换。

评论 (0)

?
0/1

还没有评论,来发第一条吧

网站上的服务均为第三方提供,
请用户注意自行甄别。

北京酷讯互动科技有限公司

备案京ICP备2024094994号-29

© 2026 AI345 · All Rights Reserved

用户服务协议·隐私政策