--- title: "Gemini CLI 中转配置：Base URL 与密钥" canonical: https://relayswitch.ai/zh/guides/gemini-cli generated: 2026-11-12T04:22:51.177Z source: https://api.relayswitch.io/v1/catalog base_url: https://api.relayswitch.io/v1 --- 配置教程 · 核对于 2026-11-11 # Gemini CLI 中转配置 Gemini CLI 在 API key 模式下可以改接口地址：一个环境变量填 Base URL，一个填密钥。下面以本站为例，把它接到中转站上，按 token 从预付余额扣费。哪些功能走中转后用不了，也一并写明。 ## 01动手之前：这个工具的现状 动手之前先读一下 [Gemini CLI 仓库](https://github.com/google-gemini/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](https://relayswitch.ai/zh/guides/claude-code) 和 [Codex CLI](https://relayswitch.ai/zh/guides/codex-cli) 的配置。 ## 02原理：两个环境变量 Gemini CLI 的 [配置文档](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md) 里有一个变量 `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 安装时），和一把本站密钥。密钥在 [控制台](https://app.relayswitch.io/console?lang=zh) 创建：邮箱开通，USDT 或银行卡充值，最低 $10，余额以美元计，没有订阅。充值步骤见 [充值页](https://relayswitch.ai/zh/pay)。 建议给 Gemini CLI 单独建一把密钥并设一个美元预算：预算用完这把密钥就停，账户里其余的余额不受影响。 ## 04第一步：安装 Gemini CLI bash 1`# npm（需要 Node.js 20 或更高）` 2`npm install -g @google/gemini-cli` 3 4`# Homebrew（macOS、Linux）` 5`brew install gemini-cli` 不想全局安装，也可以用 `npx @google/gemini-cli` 直接运行。npm 下载慢的话，换 registry 的办法和 [Claude Code 国内安装](https://relayswitch.ai/zh/guides/claude-code-install) 里写的一样，包名换成 `@google/gemini-cli` 即可。 ## 05第二步：设置 Base URL 和密钥 macOS、Linux： bash 1`export GOOGLE_GEMINI_BASE_URL="https://api.relayswitch.io"` 2`export GEMINI_API_KEY="sk-relay-..."` 3`gemini` Windows PowerShell： powershell 1`$env:GOOGLE_GEMINI_BASE_URL="https://api.relayswitch.io"` 2`$env:GEMINI_API_KEY="sk-relay-..."` 3`gemini` 第一次启动时 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`# 只对这一次启动生效` 2`gemini -m gemini-3-flash-preview` 3 4`# 或者用环境变量` 5`export GEMINI_MODEL="gemini-3-flash-preview"` 6`gemini` 按 [官方的模型文档](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/model.md)，优先级从高到低是 `--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 1`mkdir -p ~/.gemini` 2`cat >> ~/.gemini/.env <<'EOF'` 3`GOOGLE_GEMINI_BASE_URL="https://api.relayswitch.io"` 4`GEMINI_API_KEY="sk-relay-..."` 5`GEMINI_MODEL="gemini-3-flash-preview"` 6`EOF` Windows 上对应的文件是 `%USERPROFILE%\.gemini\.env`，内容是同样的三行。按 [认证文档](https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/authentication.mdx)，Gemini CLI 从当前目录往上找，只读取找到的第一个 `.env`，不合并，所以项目目录里另有 `.env` 时，主目录下的这份不会被读到。另外，密钥不要写进会随代码提交的 `.env`。 ## 08第五步：验证接通 先绕开 Gemini CLI，按 Gemini 格式直接向网关发一条最小的请求： bash 1`curl -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 1`gemini -m gemini-3-flash-preview -p "回复 ok"` 几秒后，控制台的用量页会出现这条请求，带模型 id、计费 tokens 和费用。两条都通，剩下的问题就在 Gemini CLI 自己的设置里。会话里运行 `/stats model`，可以看到这次会话按模型统计的 token 用量；实际扣费以用量页为准。 ## 09Gemini 模型与价格 下表是此刻目录里走 Gemini 格式的 19 个 Gemini id，按发布日期从新到旧排，价格渲染时读取。没有倍率：表里的美元价就是扣减价，人民币是参考价。id 照抄到 `-m` 后面。 | 模型 | 开发商 | 输入 / 百万 | 输出 / 百万 | | --- | --- | --- | --- | | [Gemini 4 Argon](https://relayswitch.ai/zh/models/gemini-4-argon)gemini-4-argon | Google | $0.60≈ ¥4.08 | $3.00≈ ¥20.41 | | [Gemini 3.8 Flash](https://relayswitch.ai/zh/models/gemini-3.8-flash)gemini-3.8-flash | Google | $0.4925≈ ¥3.35 | $2.25≈ ¥15.31 | | [Gemini 3.7 Flash](https://relayswitch.ai/zh/models/gemini-3.7-flash)gemini-3.7-flash | Google | $0.4925≈ ¥3.35 | $2.25≈ ¥15.31 | | [Gemini 3.5 Flash Lite](https://relayswitch.ai/zh/models/gemini-3.5-flash-lite)gemini-3.5-flash-lite | Google | $0.225≈ ¥1.53 | $1.875≈ ¥12.76 | | [Gemini 3.6 Flash](https://relayswitch.ai/zh/models/gemini-3.6-flash)gemini-3.6-flash | Google | $0.4925≈ ¥3.35 | $2.25≈ ¥15.31 | | [Gemini 3.5 Flash](https://relayswitch.ai/zh/models/gemini-3.5-flash)gemini-3.5-flash | Google | $1.50≈ ¥10.21 | $9.00≈ ¥61.24 | | [Gemini 3.1 Flash Lite Preview](https://relayswitch.ai/zh/models/gemini-3.1-flash-lite-preview)gemini-3.1-flash-lite-preview | Google | $0.1875≈ ¥1.28 | $1.125≈ ¥7.65 | | [Gemini 3.1 Pro Preview](https://relayswitch.ai/zh/models/gemini-3.1-pro-preview)gemini-3.1-pro-preview | Google | $1.20≈ ¥8.16 | $7.20≈ ¥48.99 | | [Gemini 3 Flash Preview](https://relayswitch.ai/zh/models/gemini-3-flash-preview)gemini-3-flash-preview | Google | $0.375≈ ¥2.55 | $2.25≈ ¥15.31 | | [Gemini 2.5 Flash](https://relayswitch.ai/zh/models/gemini-2.5-flash)gemini-2.5-flash | Google | $0.30≈ ¥2.04 | $2.50≈ ¥17.01 | | [Gemini 2.5 Pro](https://relayswitch.ai/zh/models/gemini-2.5-pro)gemini-2.5-pro | Google | $0.9375≈ ¥6.38 | $7.50≈ ¥51.03 | | [Gemini 2.5 Flash Lite](https://relayswitch.ai/zh/models/gemini-2.5-flash-lite)gemini-2.5-flash-lite | Google | $0.075≈ ¥0.51 | $0.30≈ ¥2.04 | | [Gemini 3.1 Flash Lite](https://relayswitch.ai/zh/models/gemini-3.1-flash-lite)gemini-3.1-flash-lite | Google | $0.15≈ ¥1.02 | $0.90≈ ¥6.12 | | [Gemini 3.1 Pro](https://relayswitch.ai/zh/models/gemini-3.1-pro)gemini-3.1-pro | Google | $0.60≈ ¥4.08 | $3.60≈ ¥24.49 | | [Gemini 3.1 PRO Preview Customtools](https://relayswitch.ai/zh/models/gemini-3.1-pro-preview-customtools)gemini-3.1-pro-preview-customtools | Google | $4.80≈ ¥32.66 | $28.80≈ ¥195.96 | | [Gemini 4 Carbon](https://relayswitch.ai/zh/models/gemini-4-carbon)gemini-4-carbon | Google | $2.3529≈ ¥16.01 | $11.7647≈ ¥80.05 | | [Gemini Flash Latest](https://relayswitch.ai/zh/models/gemini-flash-latest)gemini-flash-latest | Google | $1.80≈ ¥12.25 | $9.00≈ ¥61.24 | | [Gemini Flash Lite Latest](https://relayswitch.ai/zh/models/gemini-flash-lite-latest)gemini-flash-lite-latest | Google | $0.72≈ ¥4.90 | $6.00≈ ¥40.82 | | [Gemini PRO Latest](https://relayswitch.ai/zh/models/gemini-pro-latest)gemini-pro-latest | Google | $4.80≈ ¥32.66 | $28.80≈ ¥195.96 | 美元 / 百万 tokens，人民币参考价按 ECB 2026-11-11 汇率 全部模型见 [模型与价格](https://relayswitch.ai/zh/models)。只想通过 API 调 Gemini、不用命令行工具的，看 [Gemini API 中转](https://relayswitch.ai/zh/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](https://relayswitch.ai/zh/guides/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 API 中转](https://relayswitch.ai/zh/gemini-api) - [Claude Code 配置第三方 API](https://relayswitch.ai/zh/guides/claude-code) - [Codex CLI 中转配置](https://relayswitch.ai/zh/guides/codex-cli) - [CC Switch 配置中转站](https://relayswitch.ai/zh/guides/cc-switch) - [Claude Code 中转站](https://relayswitch.ai/zh/claude-code) - [模型与价格](https://relayswitch.ai/zh/models) - [充值](https://relayswitch.ai/zh/pay) - [全部配置教程](https://relayswitch.ai/zh/guides) - [Gemini CLI 官方配置文档](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md) ## 在 Gemini CLI 里用一把按量计费的密钥 邮箱开通，USDT 或银行卡充值，最低 $10。Base URL https://api.relayswitch.io。 [模型与价格](https://relayswitch.ai/zh/models)[获取密钥](https://app.relayswitch.io/console?lang=zh)