Gemini CLI（旧版）中转站配置教程

# Gemini CLI（旧版）中转站配置教程

> 适用：`@google/gemini-cli`（命令 `gemini`），仅在维护旧配置或兼容环境时使用  
> 中转站地址：`https://api.zaimod.com`  
> 主线：**装 CLI → 写 `~/.gemini/.env` 三行 → 建令牌 → `gemini` 启动**，约 6 分钟

---

## 一、这条线还值不值得用

先把结论放在最前面，省得白折腾：

| 你的身份                                  | Gemini CLI 还能用吗    | 建议                            |
| ------------------------------------- | ------------------ | ----------------------------- |
| 个人 / 免费 / Google AI Pro、Ultra 订阅      | ❌ 2026-06-18 起停止服务 | 改用 **Antigravity CLI（`agy`）** |
| 企业版 Code Assist Standard / Enterprise | ✅ 仍支持              | 按需继续用                         |
| **走 API Key 计费（本教程这种）**               | ✅ 不受该时间点限制         | 可以继续用，但新装建议直接上 `agy`          |

也就是说：**"Gemini CLI 已停服"针对的是 Google 账号登录那几条消费级通道，不是你这种用中转站 Key 的用法。** 这也是官方文档站还保留"旧版兼容"这一分页的原因。

> 新装用户请直接看 **《Antigravity CLI 配置教程》**。`agy` 是 Go 原生二进制，不用 Node.js，启动更快，而且继承 Gemini CLI 的技能 / MCP 体系。  
> 官方公告：`https://developers.googleblog.com/en/an-important-update-transitioning-gemini-cli-to-antigravity-cli/`

---

## 二、一分钟速查表

| 项目   | 填什么                                                                      |
| ---- | ------------------------------------------------------------------------ |
| 前置   | Node.js **20 或更高**（`node -v` 确认）                                         |
| 安装   | `npm install -g @google/gemini-cli`                                      |
| 配置文件 | `~/.gemini/.env`（Windows：`C:\Users\<用户名>\.gemini\.env`）                  |
| 文件内容 | 三行：地址 / Key / 模型                                                         |
| 接口地址 | `GOOGLE_GEMINI_BASE_URL=https://api.zaimod.com`（**纯域名，不带 `/v1beta`**）     |
| 令牌分组 | **Gemini-反重力**                                                           |
| 验证   | `gemini --version` → `gemini` → 顶部出现 `Authenticated with gemini-api-key` |

```ini
GOOGLE_GEMINI_BASE_URL=https://api.zaimod.com
GEMINI_API_KEY=你的API_KEY
GEMINI_MODEL=gemini-3.5-flash
```

> **注意 `.env` 的写法**：是 `KEY=VALUE`，**没有 `export`、没有引号**。这三行是写进文件的内容，不是在终端里敲的命令 —— 这是本篇最常见的低级错误。

---

> **视频版**：原页面还嵌了一段配置演示视频（B 站 `BV1f7tu6fEt4`，`https://www.bilibili.com/video/BV1f7tu6fEt4`）。视频可以帮你先建立整体印象，但**具体命令以本页文字为准** —— 视频不会讲 `.env` 与终端环境变量的优先级、也不覆盖三个系统的差异。

---

## 三、第一步：装 CLI

### 3.1 确认 Node.js

```bash
node -v
```

要求 **20 或以上**。低于 20 会在启动时直接报语法错误（不是警告，是跑不起来）。没有就先装，参见《Node.js 环境安装教程》。

> 原文开头只写了"请先确认已经安装 Node.js 环境"，没给版本下限。`@google/gemini-cli` 的 `engines` 字段要求 `>=20`，而 Node 18 已在 2025 年 EOL，所以这一条其实是硬门槛。

### 3.2 安装

```bash
npm install -g @google/gemini-cli
```

会从 npm 官方仓库拉最新版。

**macOS / Linux 提示权限不足（EACCES）时，不要加 `sudo`。**

原文三个系统都写了 `sudo npm install -g`，这条要改掉：`sudo` 会把包装进 root 拥有的目录，之后每次 `npm update -g` 都要 `sudo`，还容易把 `~/.npm` 的权限搞乱。正确做法是其中之一：

```bash
# 方案 A：用 nvm 管 Node（推荐，全局包跟着用户走）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
nvm install --lts

# 方案 B：把 npm 全局目录改到用户家目录
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
```

### 3.3 另外两种不落地的用法

```bash
# 临时跑一次，不装
npx https://github.com/google-gemini/gemini-cli

# macOS / Linux 用 Homebrew（更新滞后，需手动 brew upgrade）
brew install gemini-cli
```

### 3.4 验证安装

```bash
gemini --version
```

![](/uploads/editor/20261101/img_6ae6264cf1bba3.07186297.png)

能打印版本号即成功。**此时先别敲 `gemini`** —— 配置还没写，首次启动会引导 Google 账号登录，之后还得清一次登录态。

> 这张截图是 **CMD 窗口**（标题栏 `C:\WINDOWS\system32\cmd.exe`），而正文让"打开 PowerShell"。两条路都能跑，但如果你照着正文开 PowerShell、发现提示符长得不一样，不是配错了。截图版本 `0.44.0` 也已经偏旧，实际装上通常是 0.6x。

---

## 四、第二步：写 `~/.gemini/.env`

Gemini CLI 会读取配置目录里的 `.env`。三行，就这么多。

### 4.1 Windows

```powershell
New-Item -ItemType Directory -Force "$HOME\.gemini" | Out-Null
notepad "$HOME\.gemini\.env"
```

清空原内容，粘贴三行，保存：

```ini
GOOGLE_GEMINI_BASE_URL=https://api.zaimod.com
GEMINI_API_KEY=你的API_KEY
GEMINI_MODEL=gemini-3.5-flash
```

**两个保存细节：**

- 文件名是 `.env`（**前面有个点，没有扩展名**）。记事本保存时把「保存类型」改成「所有文件」，否则会变成 `.env.txt`，CLI 读不到。
- 编码用 UTF-8。别用带 BOM 的 UTF-8 —— 某些解析器会把 BOM 当成第一行内容的一部分，导致第一个变量名变成 `\ufeffGOOGLE_GEMINI_BASE_URL`，症状是"地址明明写了却还在走官方"。

### 4.2 macOS

```bash
mkdir -p ~/.gemini
touch ~/.gemini/.env
open -e ~/.gemini/.env
```

粘贴同样的三行，`Command + S` 保存。

### 4.3 Linux

```bash
mkdir -p ~/.gemini
nano ~/.gemini/.env
```

粘贴三行，`Ctrl + O` → 回车 → `Ctrl + X`。

### 4.4 三个变量各管什么

| 变量                       | 作用                          | 不填会怎样                 |
| ------------------------ | --------------------------- | --------------------- |
| `GOOGLE_GEMINI_BASE_URL` | 覆盖默认请求域名，仅在 API Key 认证模式下生效 | 请求发往 Google 官方，中转站白配  |
| `GEMINI_API_KEY`         | 身份凭证，替代 Google 账号登录         | 启动即要求 OAuth 登录        |
| `GEMINI_MODEL`           | 默认模型                        | 用官方默认模型，该模型若不在分组里就会报错 |

**地址为什么只能是纯域名**：CLI 拿到 base url 后会自己拼 `/v1beta/models/{模型}:generateContent`。你写 `https://api.zaimod.com/v1beta`，实际请求就成了 `/v1beta/v1beta/models/...`，必然 404。末尾的 `/` 同理。

> 这条和 n8n、扣子那类"必须写到 `/v1`"的客户端正好相反 —— 换域名时最易踩的坑就在这里。

### 4.5 `.env` 和终端环境变量打架怎么办

同一个变量如果**既在 `.env` 里、又在本机环境变量里**（比如你之前按别的教程 `export` 过），排查时会非常迷惑：改了 `.env` 却不生效。

常见行为（dotenv 默认策略）是**不覆盖已存在的环境变量**，即终端里的值优先。所以出现"改了 `.env` 没反应"时，先在新终端里确认：

```bash
# macOS / Linux
echo $GEMINI_API_KEY
echo $GOOGLE_GEMINI_BASE_URL
```

```powershell
# Windows
echo $env:GEMINI_API_KEY
```

有值 = 环境变量在压 `.env`。要么清掉环境变量，要么两处写成一样，**别只改一处**。

---

## 五、第三步：建令牌（Gemini-反重力）

**1. 控制台 → 令牌管理 → 创建令牌**

**2. 名称**随意，建议 `gemini`。

**3. 令牌分组选「智能自动」即可**

注意这里和 Antigravity CLI 是**反着**的：`agy` 用「Gemini-GCP」，旧版 `gemini` 用「Gemini-反重力」。两个名字都很反直觉，配反了就是 401 或模型列表空。

**4.「模型限制列表」留空**

界面原话是「请选择该令牌支持的模型，留空支持所有模型」。填了之后，只要列表里没有当前模型，请求就返回 **403**。留空最省事。

**5. 提交 → 令牌列表 → 「密钥」列 → 复制密钥**

![](/uploads/editor/20261101/img_6ae6268313d7e3.68124402.png)

选「复制密钥」拿到纯密钥；「复制连接信息」是带 `Base URL` 和 `Bearer` 的一整段，粘进 `.env` 会直接 401。

**6. 回到 `.env`**，只选中 `你的API_KEY` 这几个字（不含引号，也不含 `GEMINI_API_KEY=`），粘贴替换。

**7. 服务器地址在哪看**

https://api.zaimod.com

控制台「数据看板」右侧的「API 信息」模块会列出各条线路。本教程统一用 `https://api.zaimod.com`，不需要再挑线路。

---

## 六、第四步：启动与验证

保存 `.env` 后，**关掉终端重新打开**（让文件重新加载），然后：

```bash
gemini
```

![](/uploads/editor/20261101/img_6ae6270bb5eed7.36118468.png)

### 6.1 看这一行

顶部横幅第二行写着：

```console
Authenticated with gemini-api-key /auth
```

这句话就是"走的是 API Key、不是 Google 账号"的铁证。

| 显示                                  | 含义                                   |
| ----------------------------------- | ------------------------------------ |
| `Authenticated with gemini-api-key` | ✅ 配置生效                               |
| `Login with Google` / 弹出浏览器授权       | ❌ 没读到 `GEMINI_API_KEY`，回第四章检查文件路径与格式 |
| 横幅里有模型名（如右下角 `gemini-3.5-flash`）    | ✅ `GEMINI_MODEL` 生效                  |

### 6.2 发一句话

```console
你好
```

正常返回内容即成功。但**最终还是要看控制台**：「使用日志」里要有这次请求记录。有回复没记录 = 还在走官方。

### 6.3 换模型

会话里敲：

```console
/model
```

模型名以**控制台模型广场**为准。原文里 `gemini-3.5-flash` 只是示例，不同分组的模型池不一样，写死的名字很可能在别的分组里不存在。

---

## 七、和环境变量版教程怎么配合

本系列另有一篇《Gemini CLI 中转站配置教程》，走的是**环境变量**路线（`export` / `$env:` / `set`）；本篇走的是 **`.env` 文件**路线。两者都官方支持，差别如下：

| 维度     | `.env` 文件（本篇）       | 环境变量（另一篇）              |
| ------ | ------------------- | ---------------------- |
| 生效范围   | 只对 `gemini` 生效      | 对当前 shell 里所有程序生效      |
| 多套配置切换 | 换文件即可               | 要改 shell 配置或每次 export  |
| 排查难度   | 低（一个文件全看得见）         | 中（散落在 rc 文件 / 注册表）     |
| 典型坑    | 存成 `.env.txt`、带 BOM | CMD 里 `set A = B` 多写空格 |

**建议**：只用一个 `gemini` 的场景用 `.env`（本篇）；需要脚本化、在 CI 里跑的场景用环境变量（另一篇）。**不要两边都配** —— 见 4.5 的优先级问题。

---

## 八、常见问题

| 现象                            | 原因                                            | 处理                                                         |
| ----------------------------- | --------------------------------------------- | ---------------------------------------------------------- |
| `gemini : 无法将"gemini"项识别为...` | npm 全局 bin 不在 PATH                            | 重开终端；`npm config get prefix` 看目录，把 `<prefix>/bin` 加进 PATH  |
| 启动即要求 Google 登录               | `.env` 没被读到：文件名成 `.env.txt`、路径不对、或变量名拼错       | 用 `ls -a ~/.gemini` 确认文件存在；对照 4.4 的变量名逐字核                  |
| 改了 `.env` 没反应                 | 环境变量在压（见 4.5），或没重开终端                          | `echo $GEMINI_API_KEY` 确认来源                                |
| `401` / 无效令牌                  | 密钥粘错、带了 `Bearer `、令牌被删                        | 回控制台「复制密钥」重取                                               |
| `403`                         | 「模型限制列表」里没有当前模型                               | 编辑令牌，清空该列表                                                 |
| `404` / `Not Found`           | `GOOGLE_GEMINI_BASE_URL` 带了 `/v1beta` 或末尾 `/` | 改成纯域名                                                      |
| `model not found` / 400       | `GEMINI_MODEL` 写的模型在该分组里不存在                   | 去模型广场查实际 ID，或先删掉这一行                                        |
| 启动报语法错误 / 闪退                  | Node.js 低于 20                                 | 升级到 LTS（`nvm install --lts`）                               |
| `npm install -g` 报 EACCES     | 用了系统级 Node，全局目录不可写                            | **别加 sudo**，改用 nvm 或 `npm config set prefix ~/.npm-global` |
| 能聊但工具调用失败                     | 分组不支持工具能力                                     | 换分组；仍不行考虑迁到 `agy`                                          |

---

上一篇：Claude Code 配置{else}上一篇：没有了下一篇：Antigravity CLI 配置{else}下一篇：没有了