
Gemini CLI API Key 怎么配置?3 步跑通官方与中转
一句话答案:从 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 排查、价格明细各有专文,这里一句话带过。

先搞清楚:你现在该用哪个 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 的问题,别往下折腾。

第二步:写 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(失败详情)。三个字段对照看:
error字段存在 → 认证或请求失败,往下看报错表。response有正常内容 → 配置成功。stats有 token 计数 → 请求真打到了计费接口,不是本地缓存糊弄你。
交互模式下还有条更快的路:进去敲 /stats model,官方文档说这个命令给出当前会话 token 用量和当前配额的限制。

国内用户:走中转站怎么配
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 轮换。

京ICP备2024094994号-29