配置教程 · 核对于 2026-11-11

Gemini CLI 中转配置

Gemini CLI 在 API key 模式下可以改接口地址：一个环境变量填 Base URL，一个填密钥。下面以本站为例，把它接到中转站上，按 token 从预付余额扣费。哪些功能走中转后用不了，也一并写明。

01动手之前：这个工具的现状

动手之前先读一下 Gemini CLI 仓库 README 顶部的说明，它在 2026 年年中之后变了不少：

  • 2026 年 6 月 18 日起，个人免费额度和 Google AI Pro / Ultra 订阅的入口移到了 Antigravity CLI。Gemini CLI 现在面向 Gemini Code Assist 的企业授权，README 另外注明原有的付费 API key 和 Vertex key 仍然可用。
  • 它没有针对 Gemini 4 系列做调优，官方也说不要拿它给新模型跑分。

本文讲的正是保留下来的 API key 这条路：密钥换成本站的，地址指向本站。已经在用 Gemini CLI、只想换一个按量计费的接口的，往下看；想找一个长期的主力编码工具，可以先看看 Claude Code 和 Codex CLI 的配置。

02原理：两个环境变量

Gemini CLI 的 配置文档 里有一个变量 GOOGLE_GEMINI_BASE_URL：覆盖 Gemini API 请求的默认地址，只在用 API key 认证时生效；值必须是合法的 URL，而且除了指向本机的地址以外必须是 HTTPS。密钥则来自 GEMINI_API_KEY。

本站网关在 /v1beta/models/{model}:generateContent 上提供 Gemini 原生格式，密钥从 x-goog-api-key 请求头读取，这正是 Gemini API 的标准写法。所以两个变量指过来之后，Gemini CLI 不用改任何别的设置：

  • GOOGLE_GEMINI_BASE_URL 填 https://api.relayswitch.io，不带 /v1。
  • GEMINI_API_KEY 填以 sk-relay- 开头的本站密钥。

03准备

Node.js 20 或更高（走 npm 安装时），和一把本站密钥。密钥在 控制台 创建：邮箱开通，USDT 或银行卡充值，最低 $10，余额以美元计，没有订阅。充值步骤见 充值页。

建议给 Gemini CLI 单独建一把密钥并设一个美元预算：预算用完这把密钥就停，账户里其余的余额不受影响。

04第一步：安装 Gemini CLI

bash
1# npm（需要 Node.js 20 或更高）
2npm install -g @google/gemini-cli
3
4# Homebrew（macOS、Linux）
5brew install gemini-cli

不想全局安装，也可以用 npx @google/gemini-cli 直接运行。npm 下载慢的话，换 registry 的办法和 Claude Code 国内安装 里写的一样，包名换成 @google/gemini-cli 即可。

05第二步：设置 Base URL 和密钥

macOS、Linux：

bash
1export GOOGLE_GEMINI_BASE_URL="https://api.relayswitch.io"
2export GEMINI_API_KEY="sk-relay-..."
3gemini

Windows PowerShell：

powershell
1$env:GOOGLE_GEMINI_BASE_URL="https://api.relayswitch.io"
2$env:GEMINI_API_KEY="sk-relay-..."
3gemini

第一次启动时 Gemini CLI 会让你选认证方式，选 Use Gemini API key。之前用 Google 账号登录过的，它会沿用旧的方式，这时在会话里运行 /auth 打开认证方式的对话框，换成 API key。

这一点很关键：按文档，GOOGLE_GEMINI_BASE_URL 只在 API key 认证下生效。用 Google 账号登录时，请求不看这个变量，也就不会发到本站。

06第三步：指定模型

Gemini CLI 默认的模型设置是 auto：由它自己在内置的 Pro 和 Flash 之间挑。接中转时建议明确指定一个模型，这样用的是哪个 id、按什么价格计费，一眼就清楚：

bash
1# 只对这一次启动生效
2gemini -m gemini-3-flash-preview
3
4# 或者用环境变量
5export GEMINI_MODEL="gemini-3-flash-preview"
6gemini

按 官方的模型文档，优先级从高到低是 --model（简写 -m）、GEMINI_MODEL、settings.json 里的 model.name，都没设才是 auto。会话中途想换，运行 /model，在对话框里选 Manual；也可以直接运行 /model set gemini-3-flash-preview --persist，带上 --persist 会把选择保存下来。

想写进配置文件的，用户级的设置文件是 ~/.gemini/settings.json，键是 model.name：

json
1{
2 "model": {
3 "name": "gemini-3-flash-preview"
4 }
5}

Gemini CLI 文档里点名的内置模型 id 中，本站目录此刻列出了 4 个：gemini-3-flash-preview、gemini-2.5-pro、gemini-2.5-flash、gemini-2.5-flash-lite。auto 或者内部的辅助调用用到不在目录里的 id 时，那一次请求会返回 404，这也是建议手动指定模型的原因。

07第四步：写进 ~/.gemini/.env

终端里 export 的变量只对当前窗口有效。要让每次启动都生效，官方推荐的办法之一是把变量写进主目录下的 .gemini/.env：

bash
1mkdir -p ~/.gemini
2cat >> ~/.gemini/.env <<'EOF'
3GOOGLE_GEMINI_BASE_URL="https://api.relayswitch.io"
4GEMINI_API_KEY="sk-relay-..."
5GEMINI_MODEL="gemini-3-flash-preview"
6EOF

Windows 上对应的文件是 %USERPROFILE%\.gemini\.env，内容是同样的三行。按 认证文档，Gemini CLI 从当前目录往上找，只读取找到的第一个 .env，不合并，所以项目目录里另有 .env 时，主目录下的这份不会被读到。另外，密钥不要写进会随代码提交的 .env。

08第五步：验证接通

先绕开 Gemini CLI，按 Gemini 格式直接向网关发一条最小的请求：

bash
1curl -i "https://api.relayswitch.io/v1beta/models/gemini-3-flash-preview:generateContent" \
2 -H "x-goog-api-key: sk-relay-..." \
3 -H "content-type: application/json" \
4 -d '{"contents": [{"role": "user", "parts": [{"text": "回复 ok"}]}]}'

返回 200 和一段带 candidates 的 JSON，说明地址、密钥、模型三样都对。然后让 Gemini CLI 不进交互界面，直接答一句：

bash
1gemini -m gemini-3-flash-preview -p "回复 ok"

几秒后，控制台的用量页会出现这条请求，带模型 id、计费 tokens 和费用。两条都通，剩下的问题就在 Gemini CLI 自己的设置里。会话里运行 /stats model，可以看到这次会话按模型统计的 token 用量；实际扣费以用量页为准。

09Gemini 模型与价格

下表是此刻目录里走 Gemini 格式的 19 个 Gemini id，按发布日期从新到旧排，价格渲染时读取。没有倍率：表里的美元价就是扣减价，人民币是参考价。id 照抄到 -m 后面。

模型开发商输入 / 百万输出 / 百万
Gemini 4 Argongemini-4-argonGoogle$0.60≈ ¥4.08$3.00≈ ¥20.41
Gemini 3.8 Flashgemini-3.8-flashGoogle$0.4925≈ ¥3.35$2.25≈ ¥15.31
Gemini 3.7 Flashgemini-3.7-flashGoogle$0.4925≈ ¥3.35$2.25≈ ¥15.31
Gemini 3.5 Flash Litegemini-3.5-flash-liteGoogle$0.225≈ ¥1.53$1.875≈ ¥12.76
Gemini 3.6 Flashgemini-3.6-flashGoogle$0.4925≈ ¥3.35$2.25≈ ¥15.31
Gemini 3.5 Flashgemini-3.5-flashGoogle$1.50≈ ¥10.21$9.00≈ ¥61.24
Gemini 3.1 Flash Lite Previewgemini-3.1-flash-lite-previewGoogle$0.1875≈ ¥1.28$1.125≈ ¥7.65
Gemini 3.1 Pro Previewgemini-3.1-pro-previewGoogle$1.20≈ ¥8.16$7.20≈ ¥48.99
Gemini 3 Flash Previewgemini-3-flash-previewGoogle$0.375≈ ¥2.55$2.25≈ ¥15.31
Gemini 2.5 Flashgemini-2.5-flashGoogle$0.30≈ ¥2.04$2.50≈ ¥17.01
Gemini 2.5 Progemini-2.5-proGoogle$0.9375≈ ¥6.38$7.50≈ ¥51.03
Gemini 2.5 Flash Litegemini-2.5-flash-liteGoogle$0.075≈ ¥0.51$0.30≈ ¥2.04
Gemini 3.1 Flash Litegemini-3.1-flash-liteGoogle$0.15≈ ¥1.02$0.90≈ ¥6.12
Gemini 3.1 Progemini-3.1-proGoogle$0.60≈ ¥4.08$3.60≈ ¥24.49
Gemini 3.1 PRO Preview Customtoolsgemini-3.1-pro-preview-customtoolsGoogle$4.80≈ ¥32.66$28.80≈ ¥195.96
Gemini 4 Carbongemini-4-carbonGoogle$2.3529≈ ¥16.01$11.7647≈ ¥80.05
Gemini Flash Latestgemini-flash-latestGoogle$1.80≈ ¥12.25$9.00≈ ¥61.24
Gemini Flash Lite Latestgemini-flash-lite-latestGoogle$0.72≈ ¥4.90$6.00≈ ¥40.82
Gemini PRO Latestgemini-pro-latestGoogle$4.80≈ ¥32.66$28.80≈ ¥195.96

美元 / 百万 tokens，人民币参考价按 ECB 2026-11-11 汇率

全部模型见 模型与价格。只想通过 API 调 Gemini、不用命令行工具的，看 Gemini API 中转。

10走中转后的限制

接之前先知道这几件事，免得排查半天：

  • 网关在 /v1beta 下只提供 generateContent 和 streamGenerateContent 两个方法，对话和工具调用用的就是它们。countTokens 等其它方法返回 404。
  • 请求里的 safetySettings、thinkingConfig、cachedContent 和 Google 的内置工具不会传给模型。Gemini CLI 里依赖 Google 搜索的联网搜索工具，走中转时拿不到搜索结果。
  • 密钥只能放在请求头里。自己写脚本时把密钥拼在 URL 的 ?key= 后面，网关会直接拒绝并返回 400。
  • 用 Google 账号登录才有的功能，以及 Vertex AI 的认证方式，不在本文范围内。

11排错

启动就报 Base URL 无效：检查地址有没有多余的引号或空格，协议必须是 https://。

请求没有出现在本站的用量页：多半还在用 Google 账号登录，运行 /auth 换成 API key；或者变量没传进这个进程，确认当前目录往上有没有别的 .env 抢先被读取。

401 是密钥不对，402 是余额或这把密钥的预算用完，404 是模型 id 不在目录里，429 是这把密钥的速率限制，等响应头 retry-after 给出的秒数再发。想在 Gemini CLI、Claude Code、Codex 之间统一管理地址和密钥，可以用 CC Switch。

常见问题

GOOGLE_GEMINI_BASE_URL 带不带 /v1？
不带，填 https://api.relayswitch.io。Gemini 的 SDK 会自己在后面拼 /v1beta/models/…。填成 https://api.relayswitch.io/v1 也能用，网关对多出来的 /v1 做了兼容。
还需要 Google 账号或者 AI Studio 的密钥吗？
不需要。选了 Use Gemini API key 之后，Gemini CLI 不走 Google 账号登录，请求带的是 GEMINI_API_KEY 里的值，也就是本站的 sk-relay- 密钥。账户在本站，用邮箱开通。
用 Google 账号登录的方式能走中转吗？
不能。按 Gemini CLI 的配置文档，GOOGLE_GEMINI_BASE_URL 只在 gemini-api-key 这种认证方式下生效。之前用 Google 账号登录过的，在会话里运行 /auth 换成 API key。
用量页里为什么出现了我没选的模型？
Gemini CLI 的文档写明，/model 和 --model 不改变子代理使用的模型，一些内部的辅助调用（补全提示、分类）也有自己固定的模型。这些请求用的是同一把密钥，所以会出现在同一份用量里。
Antigravity CLI 也能这样配吗？
本文只核对了 Gemini CLI 的文档。Antigravity CLI 是另一个工具，它怎么设置接口地址我们没有核对过，所以这里不写。
能在 Gemini CLI 里调用 Claude 或 GPT 吗？
Gemini CLI 的提示词和工具是为 Gemini 模型写的，其它模型在它里面的表现本站没有验证，建议只填 gemini- 开头的 id。Claude 用 Claude Code，GPT 用 Codex CLI，同一把密钥都能配。
相关页面

在 Gemini CLI 里用一把按量计费的密钥

邮箱开通，USDT 或银行卡充值，最低 $10。Base URL https://api.relayswitch.io。

模型与价格获取密钥