Gemini CLI 中转站怎么配置 Gemini API Key

发布于 2026-05-30

安装 Gemini CLI，理解 Google 登录、Gemini API Key 与中转站 Base URL 的区别，完成环境变量和模型配置，并用最小请求验证 Gemini 兼容性。

Gemini CLI 是什么

Gemini CLI 是 Google 推出的命令行 AI 工具，可以在终端里调用 Gemini 做问答、代码解释、文件分析和开发辅助。它不是 Claude Code 或 Codex 的换皮版本，认证方式、环境变量和模型调用路径都不一样。

这个教程只讲两条和中转站用户有关的路径:

Login with Google: 用 Google 账号登录，适合先体验官方 Gemini CLI。
Gemini API Key (AI Studio): 用 GEMINI_API_KEY 调用，很多中转站教程会让你选这条。

很多“Gemini CLI 中转站”实际提供的是 Google/Gemini 模型的聚合 API，未必等于原生 Gemini CLI 协议完全兼容。

所以不要一上来就全局改配置。先选一个明确支持 Google 或 Gemini 模型的服务商，小额充值或用测试 Key 跑通，再决定是否长期使用。

如果你还在选服务商，可以先看 Gemini CLI 中转站对比。想看更宽的多模型聚合选择，可以看 OpenRouter 平替与 AI API 聚合站和 AI API 服务商目录。

安装 Gemini CLI

安装前先确认 Node.js 版本。Gemini CLI 建议使用 Node.js 20+:

node --version

官方推荐的 npm 安装方式:

npm install -g @google/gemini-cli
gemini --version

如果你只是临时测试，也可以不全局安装，直接用:

npx @google/gemini-cli

装好后先启动一次:

gemini

装完后怎么方便地用

配置短命令别名

如果你觉得每次输入 gemini 太长，可以给自己的 shell 配一个短别名。建议用 gm，不要直接用 g，因为 g 很容易和 git、目录跳转或其他工具冲突。

macOS / Linux 的 Bash 或 Zsh 可以写入对应配置文件:

# Zsh 默认一般是 ~/.zshrc；Bash 一般是 ~/.bashrc 或 ~/.bash_profile
echo 'alias gm="gemini"' >> ~/.zshrc
source ~/.zshrc

之后就可以这样启动:

gm

Windows PowerShell 可以写进 $PROFILE:

notepad $PROFILE

然后加入:

Set-Alias gm gemini

注意: 这个别名只是在你的终端里把 gm 展开成 gemini，方便启动 Gemini CLI。它不等于 Gemini CLI 内部命令别名；在 Gemini CLI 里执行 shell 命令时，你本机 shell 里的 alias 不一定会生效。

选择认证方式

第一次启动 Gemini CLI 时，你主要看 Login with Google 和 Gemini API Key 这两个选项。可以先按下面这个判断:

只是想先体验官方 Gemini CLI: 选 Login with Google，适合能正常打开 Google 登录页的个人用户。
想接中转站或 API Key: 选 Gemini API Key (AI Studio)，这是大多数中转站教程会让你选的路径。

先启动一次:

gemini

进入界面后，如果已经出现认证选项，按你的情况选择即可。如果之后想重新切换认证方式，在 Gemini CLI 里输入:

/auth

然后选择对应路径:

○ Login with Google
● Gemini API Key (AI Studio)

如果你用的是中转站，通常要选 Gemini API Key (AI Studio)，然后让 Gemini CLI 读取你在终端里配置的 GEMINI_API_KEY。

配置 API Key 和中转地址

只用官方 AI Studio API Key 时，最小配置是:

export GEMINI_API_KEY="你的 Gemini API Key"
gemini

如果你用的是中转站，很多服务商会让你同时配置 API Key 和中转地址。常见写法是:

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

更适合长期使用的方式，是把它写进 shell 配置文件。Zsh 用户通常写进 ~/.zshrc:

nano ~/.zshrc

加入:

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

保存后让配置生效:

source ~/.zshrc

Bash 用户一般改 ~/.bashrc:

nano ~/.bashrc
source ~/.bashrc

Windows CMD 可以临时这样设置:

set GEMINI_API_KEY=你的中转站 API Key
set GOOGLE_GEMINI_BASE_URL=https://你的中转站地址

PowerShell 可以用:

$env:GEMINI_API_KEY="你的中转站 API Key"
$env:GOOGLE_GEMINI_BASE_URL="https://你的中转站地址"

注意: GOOGLE_GEMINI_BASE_URL 是否可用、地址是否要带路径，必须以服务商文档为准。不要把别家教程里的地址直接复制到你的服务商上。

常用启动方式

配置好以后，你可以用三种方式使用:

# 进入交互模式
gm

# 直接问一个问题
gemini "解释一下这个项目的目录结构"

# 指定模型做一次测试，模型名以服务商文档为准
gemini -m gemini-2.5-flash "用一句话介绍 Gemini CLI"

装完后怎么验证是否可用

建议用一个干净终端做临时测试，先清掉可能干扰的旧变量:

unset GEMINI_API_KEY GOOGLE_API_KEY
export GEMINI_API_KEY="服务商或官方提供的测试 Key"
gemini

如果服务商要求自定义 Base URL，再加上它给你的中转地址:

export GOOGLE_GEMINI_BASE_URL="https://你的中转站地址"
gemini "用一句话说明你当前连接的模型"

通过基础问答以后，再做四个小测试:

gemini -p "解释这个代码库的架构" 能否正常返回。
gemini -m gemini-2.5-flash "hello" 能否按指定模型返回。
在项目目录里启动 gemini，让它读取一个小文件，确认文件上下文可用。
做一次低风险代码解释或生成任务，确认流式输出、工具调用和模型名没有明显异常。

能正常回答，只代表基础请求通了；还要继续测试代码读取、文件修改、流式输出和模型名。服务商文档没有写 Gemini CLI 配置方法时，就让客服确认“Gemini CLI 原生接入”还是“OpenAI 兼容接口接 Gemini 模型”。

接中转站时看什么

我通常先看两件事：文档有没有写 GEMINI_API_KEY，有没有写 GOOGLE_GEMINI_BASE_URL。如果首次启动时出现认证选择，再看它是否要求你在 /auth 里选 Gemini API Key (AI Studio)。

如果只是在模型列表里写了 Gemini，或者只说“兼容 OpenAI 格式”，先别当成 Gemini CLI 已兼容。它可能只是能用 OpenAI 兼容接口调用 Gemini 模型，不一定能让 Gemini CLI 正常跑文件读取、流式输出和工具调用。

服务商文档没写清楚时，用小额额度试一次最小流程。客服如果说不出变量名、Base URL 和 /auth 怎么选，就先按“待验证”处理。

一般会遇到哪些报错

401 / unauthorized: Key 类型不对，或服务商不接受 Gemini CLI 当前发送的认证方式。
403 / permission denied: Key 能认证，但账号、项目或模型权限不足。
404 / not found: Base URL 路径不对，常见于 /v1 是否需要的问题。
model not found: 模型别名和服务商公开模型名不一致。
429 / too many requests: 额度不足、触发限流，或 Gemini CLI / coding agent 在重复重试。
network error / timeout: 本地网络、代理、中转站节点或上游响应超时。
能聊天但不能改代码: 可能只兼容普通补全接口，不完整支持 Gemini CLI 的工具调用和流式能力。

遇到 401 或 429 时，不要先换站。先点开页面底部的相关错误排查页，按 Base URL、API Key、模型名、余额和限流规则逐项确认。

可以用哪些工具提升便利性

如果你只是接一个中转地址，手动写 ~/.zshrc 就够了。工具的价值主要出现在你经常切换 provider 的时候。

比如 CC Switch 这类配置管理工具，适合同时管理 Claude Code、Codex、Gemini CLI、OpenCode 的 provider、Base URL、API Key、模型名和使用统计。

但顺序不能反: 先手动跑通最小配置，再把可用配置交给工具管理。否则工具只会帮你更快地整理一堆错误配置。

下一步

真正有价值的 Gemini CLI 中转站页面，不该只罗列“支持 Gemini”。它应该告诉你服务商是否公开 Google/Gemini 模型、价格、支付方式和 Gemini CLI 配置方法。模型列表只是入场券，能不能稳定跑 CLI 才是门槛。

Gemini CLI Gemini API Base URL