Gemini CLI 接入第三方模型：环境变量、settings.json 与 MCP 配置实战（2026）

Gemini CLI 接第三方模型只有两条正路：临时用就走 GOOGLE_GEMINI_BASE_URL + GEMINI_API_KEY 两个环境变量，长期用就写进 ~/.gemini/settings.json 把 security.auth 选成 endpoint 类型——不改源码、不换 fork，原生支持。 我在 Ubuntu 22.04 上用 Gemini CLI 0.8.x（npm 包 @google/gemini-cli，2026 年版本）接了两个中转站实测，从装好到第一条回复大约 5 分钟。真正费时间的不是配置本身，而是模型名映射和流式输出这两个坑——症状隐蔽，报错还不指路。

这篇按顺序给：装与验证、两条接入路径的完整写法、MCP 服务器配置、免费额度账本，最后是排错顺序。接 Claude Code 和 Codex CLI 的做法我之前都写过，这次补上 Gemini CLI，三家凑齐后你会发现思路是同一套：改端点、给钥匙、验工具调用。

Gemini CLI 是什么？和 Claude Code、Codex CLI 比有什么不同？

它是 Google 出的开源终端编程智能体，Node 20 以上直接 npm 装，自带 100 万 token 上下文窗口的 Gemini 模型，定位和 Claude Code、Codex CLI 同类。 三家放一起看，差异主要在配置载体：

Gemini CLI 的优势很直白：官方给免费额度，且开源，代码在 GitHub 上能翻，配置字段名不用猜。如果你还没看过前两篇，Claude Code 的 BASE_URL 写法 和 Codex CLI 的 wire_api 坑 可以先收藏，回头对照着读会更快。

怎么装、怎么跑？

# Ubuntu 22.04，Node 20+（nvm 装的 20.x 实测）
$ node -v
v20.18.0

# 安装（2026 年版本，npm 包名是 @google/gemini-cli）
$ npm install -g @google/gemini-cli
$ gemini --version
0.8.1

# 项目目录里启动交互界面
$ cd ~/projects/my-app
$ gemini

首次启动会让你选登录方式：Login with Google（官方 OAuth）、Gemini API Key、Vertex AI 三个选项。如果你只用官方模型，选第一个就完了，这篇文章剩下的部分都可以不看。要接中转站，就选 Gemini API Key，或者干脆先退出，按下面的路径配。

路径一：环境变量接入，两条命令生效

适合临时切换和先验证通不通。 中转站给你的一般是两样东西：一个 base URL、一个 key。设进环境变量再启动：

$ export GOOGLE_GEMINI_BASE_URL="https://api.example.com"
$ export GEMINI_API_KEY="sk-中转站给你的key"
$ gemini

两个细节决定成败：URL 结尾不要带 /v1——Gemini CLI 会自己拼路径，带了就变成 /v1/v1/...，症状是 404；另外变量名一个字母都不能错，是 GOOGLE_GEMINI_BASE_URL，不是 GEMINI_BASE_URL，后者不生效且没有任何提示。验证是否走通了最直接的办法是在交互界面里随便问一句，然后看 /about 命令的输出，里面会显示当前生效的端点。

路径二：settings.json 持久化，一次配置长期用

环境变量关掉终端就没了，长期用要落到 ~/.gemini/settings.json。 2026 年版本的写法是把认证方式选成 endpoint 类型，让 CLI 跳过官方 OAuth 直接打你指定的地址：

{
  "security": {
    "auth": {
      "type": "gemini-api-key",
      "selectedType": "endpoint"
    }
  },
  "model": {
    "name": "deepseek-chat"
  }
}

key 仍然建议放环境变量里（写进 ~/.bashrc），避免明文躺在配置文件里：

$ echo 'export GEMINI_API_KEY="sk-你的key"' >> ~/.bashrc
$ source ~/.bashrc

我一开始以为 settings.json 里配了 model.name 就万事大吉，后来发现中转站那边根本不认识 gemini-2.5-pro 这种名字——它只认自己映射表里的名字，比如 deepseek-chat 或者它自己起的别名。模型名映射是接中转站的第一坑，下一节单独说。

模型名怎么映射？免费额度还剩多少？

模型名以中转站的模型列表为准，不要照抄官方文档。 大多数中转站提供 /v1/models 查询接口，先拉一遍列表再填：

$ curl -s https://api.example.com/v1/models \
    -H "Authorization: Bearer $GEMINI_API_KEY" | head -c 500

免费额度这件事要算清两本账：官方 Gemini API 的免费层对个人账号有每分钟请求数和每天请求数限制（2026 年的量级是每分钟几十次、每天上千次量级，具体以官方配额页为准）；中转站则是另一套计费——按 token 或者按次。两条路别混着用：设了 GOOGLE_GEMINI_BASE_URL 之后走的就是中转站的额度，官方免费额度一分不扣；不设就是官方额度。我的做法是日常小任务用官方免费额度，批量任务切中转站。

MCP 服务器怎么配？

Gemini CLI 的 MCP 配置直接写进 settings.json 的 mcpServers 块，和其他工具的 MCP 配置格式同源。 给两个实用例子：

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]
    }
  }
}

配完重启 gemini，交互界面里输入 /mcp 能看到已加载的服务器和工具列表。注意 MCP 走的是本地进程（stdio），和中转站无关——就算模型是第三方接的，工具照样在你本机跑，这点和 Aider 那种纯对话式接法 是本质区别，也是编程智能体的价值所在。

怎么验证真的通了？

别只看能对话，要验证工具调用。 三步：

# 1) 确认端点生效
$ gemini
> /about        # 看 base URL 是否是你的中转站

# 2) 验证读文件（工具调用）
> 读一下 README.md，用一句话总结

# 3) 验证写文件
> 在当前目录建一个 hello.txt，内容写 ok
$ cat hello.txt

三条都过才算接通。第二条失败、第一条正常，多半是中转站不支持 function calling 的透传，换支持工具调用的模型或换中转站。

三个真会踩的坑

1. 模型名映射：前面说过，中转站不认官方模型名。表现是 404 或者"model not found"。先 curl 一次 /v1/models 拿真实名单再填，别猜。
2. 流式输出兼容性：我一开始以为流式输出是天然兼容的，后来发现部分中转站对 Gemini 的 streamGenerateContent 协议透传有问题，症状是回复卡在半截不出字，或者一次性吐全文。判别方法：官方模型流式正常、走中转站就异常，基本可以定位。让中转站确认是否支持 Gemini 原生流式协议，或者退一步用非流式。
3. settings.json 写错位置：配置文件是 ~/.gemini/settings.json，不是 ~/.gemini/config.json，也不是项目目录下的 .gemini/settings.json（项目级配置存在但优先级规则不同）。放错位置的症状是怎么改都不生效，CLI 静默回退到默认行为。

常见问题（2026）

Q：必须要有 Google 账号吗？
A：走中转站不需要——不登录、只用环境变量和 settings.json 就能跑。只有用官方免费额度时才需要 Google 账号做 OAuth 登录。

Q：和 Claude Code、Codex CLI 怎么选？
A：三个都装不冲突，配置各管各的。论免费额度 Gemini CLI 最松，论多 provider 切换 Codex CLI 的 profile 最顺手，论生态 Claude Code 的 MCP 工具最多。接入套路是同一套，学会一家其他两家半小时。

Q：GOOGLE_GEMINI_BASE_URL 和 settings.json 同时配了，听谁的？
A：环境变量优先级更高，这是排查"配置不生效"时最常被忽略的一条——你以为 settings.json 写好了，结果 shell 里残留着一个旧的环境变量在覆盖它，env | grep GEMINI 先查一遍。

一句总结

Gemini CLI 接第三方模型，配置本身只要五分钟，剩下的时间都花在验证上：先 curl 拿真实模型名，再确认流式输出正常，最后用读文件加写文件验工具调用。三条全过，这条链路才算真正能用。

相关阅读

• 让 Claude Code 指向国产大模型：BASE_URL 接入指南
• Codex CLI 接入第三方模型：config.toml 里的 wire_api 是个坑（2026）
• Aider 终端 AI 编程：接国产模型，每步自动 git 提交（2026）