Gemini CLI 中转站配置方法及指南

# Gemini CLI 中转站配置教程

> 适用对象：`@google/gemini-cli`（Google 官方开源命令行 AI 工具）  
> 中转站地址：`https://api.zaimod.com`  
> 阅读顺序按「准备 → 安装 → 配置 → 验证 → 排错」排列，赶时间可直接跳 **四、配置速查表**。

---

## 一、开始之前

### 1.1 准备清单

| 项目      | 应该填什么                                 | 注意                                        |
| ------- | ------------------------------------- | ----------------------------------------- |
| 中转站地址   | `https://api.zaimod.com`               | **只写到域名**，不带 `/v1`、不带 `/v1beta`，末尾也别加 `/` |
| API Key | `sk-` 开头的一串字符                         | 在中转站控制台「令牌」页新建，需勾选可访问 Gemini 的分组          |
| 模型名     | 如 `gemini-2.5-pro`、`gemini-2.5-flash` | 以控制台「模型」列表里的**实际 ID** 为准，不要凭记忆写           |
| Node.js | 20 或更高                                | 终端执行 `node -v` 确认，低于 20 会在启动时报语法错误        |

### 1.2 三个环境变量各管什么

| 变量                       | 作用                            | 本教程填什么                  |
| ------------------------ | ----------------------------- | ----------------------- |
| `GEMINI_API_KEY`         | 身份凭证，替代谷歌账号登录                 | 你的 `sk-` 令牌             |
| `GOOGLE_GEMINI_BASE_URL` | 覆盖默认请求域名（仅在「API Key 认证」模式下生效） | `https://api.zaimod.com` |
| `GEMINI_MODEL`           | 可选，指定默认模型                     | `gemini-2.5-pro`        |

> **为什么这里不能带 `/v1beta`**：Gemini CLI 拿到 base url 后，会自己往后拼 `/v1beta/models/{模型}:generateContent`。你若把地址写成 `https://api.zaimod.com/v1beta`，实际请求就变成 `/v1beta/v1beta/models/...`，必然 404。  
> 这一点和 n8n、扣子那类客户端「必须写 `/v1`」的习惯**正好相反**，是本文最容易踩的坑。

---

## 二、安装 Gemini CLI

### 步骤 1 · 确认 Node.js 版本

```bash
node -v
npm -v
```

要求 **Node 20+**。低于 20 请先升级（推荐用 nvm 管理版本，避免污染系统 Node）。

### 步骤 2 · 安装

三种方式任选其一。

**方式 A：全局安装（推荐，后续直接敲 `gemini`）**

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

**方式 B：不安装，临时运行一次**

```bash
npx https://github.com/google-gemini/gemini-cli
```

**方式 C：macOS / Linux 用 Homebrew**

```bash
brew install gemini-cli
```

### 步骤 3 · 验证安装

```bash
gemini --version
```

能打印出版本号即安装成功。此时**先不要急着启动**，先去配环境变量——否则首次启动会引导你走谷歌账号登录，后面还得清一次登录状态。

---

## 三、配置中转站

### 步骤 4 · 设置环境变量

按你的系统选一种，**不要混用**（原文把 Linux 的 `export` 和 Windows 的 `set` 塞进同一个代码块，很容易复制错）。

**macOS / Linux（bash、zsh 通用，仅当前终端窗口有效）**

```bash
export GEMINI_API_KEY="sk-你的令牌"
export GOOGLE_GEMINI_BASE_URL="https://api.zaimod.com"
export GEMINI_MODEL="gemini-2.5-pro"
```

**Windows CMD（`set` 只对当前窗口有效，关掉即失效）**

```bat
set GEMINI_API_KEY=sk-你的令牌
set GOOGLE_GEMINI_BASE_URL=https://api.zaimod.com
set GEMINI_MODEL=gemini-2.5-pro
```

**Windows PowerShell（推荐，只对当前会话有效）**

```powershell
$env:GEMINI_API_KEY="sk-你的令牌"
$env:GOOGLE_GEMINI_BASE_URL="https://api.zaimod.com"
$env:GEMINI_MODEL="gemini-2.5-pro"
```

> 注意：CMD 里写 `set` 时**等号两边不要有空格**（`set A = B` 会连空格一起写进值里），这是 Windows 下最常见的配置失败原因。

### 步骤 5 · 让它永久生效

步骤 4 的方式关掉终端就没了。想一次配好长期使用：

**macOS / Linux** —— 追加到 shell 配置文件末尾：

```bash
# zsh 用户
echo 'export GEMINI_API_KEY="sk-你的令牌"' >> ~/.zshrc
echo 'export GOOGLE_GEMINI_BASE_URL="https://api.zaimod.com"' >> ~/.zshrc
source ~/.zshrc
# bash 用户把 ~/.zshrc 换成 ~/.bashrc
```

**Windows** —— 图形界面最稳妥：`Win + R` 输入 `sysdm.cpl` → 高级 → 环境变量 → 在「用户变量」里新建上面三个变量。命令行方式（立刻永久生效，但需重开终端）：

```bat
setx GEMINI_API_KEY "sk-你的令牌"
setx GOOGLE_GEMINI_BASE_URL "https://api.zaimod.com"
setx GEMINI_MODEL "gemini-2.5-pro"
```

设置完**必须新开一个终端窗口**，旧窗口读取的还是旧变量。

### 步骤 6 · 首次启动：认证方式必须选 API Key

在项目目录下执行：

```bash
gemini
```

首次启动会走两步引导：

1. **选择主题配色** —— 随便选，不影响功能。
2. **选择认证方式（Authentication）** —— 这里必须选 **`Use Gemini API Key`**。

> 如果错选了 `Login with Google`，Gemini CLI 会走谷歌账号 OAuth，**完全绕过你的 `GOOGLE_GEMINI_BASE_URL`**，配置白做。选错的话，退出后重新启动再选一次；若仍默认走登录，删除 `~/.gemini/oauth_creds.json` 后重试（部分版本可在会话内用 `/auth` 切换，以你本地版本的实际界面为准）。

### 步骤 7 · 验证是否真的走了中转

**先验钥匙和地址本身有没有配对**，绕开 CLI 直接打一次原生 Gemini 接口：

```bash
curl "https://api.zaimod.com/v1beta/models/gemini-2.5-pro:generateContent" \
  -H "x-goog-api-key: sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"说一句话证明你在线"}]}]}'
```

判断标准：

- 返回 JSON 里出现 `candidates[0].content.parts[0].text` 且有文字 → 地址和令牌都正确。
- `401 Invalid token` → 令牌错或没带 `sk-` 前缀。
- `404 Invalid URL` → 地址多了 `/v1`、`/v1beta`，或模型 ID 不存在。

**再验 CLI 端到端**（非交互模式，一次出结果）：

```bash
gemini -p "用一句话说明你是谁"
```

能正常输出回复即全链路打通。同时可在中转站控制台的**调用日志**里看到这次请求，日志有记录 = 确实走了中转；控制台无记录而 CLI 却有回复 = 仍在走谷歌官方，回到步骤 6 检查认证方式。

---

## 四、配置速查表

| 配置项                      | 值                                         |
| ------------------------ | ----------------------------------------- |
| `GOOGLE_GEMINI_BASE_URL` | `https://api.zaimod.com`（不带版本段、不带结尾斜杠）     |
| `GEMINI_API_KEY`         | `sk-...`（中转站令牌，不是 Google AI Studio 的 key） |
| `GEMINI_MODEL`（可选）       | `gemini-2.5-pro` / `gemini-2.5-flash`     |
| 认证方式                     | `Use Gemini API Key`                      |
| 全局配置文件                   | `~/.gemini/settings.json`（MCP、主题、沙箱等）     |
| 项目上下文文件                  | 项目根目录 `GEMINI.md`                         |

---

## 五、常用命令

```bash
gemini                                  # 在当前目录启动交互式会话
gemini --include-directories ../lib,../docs   # 额外挂载目录
gemini -m gemini-2.5-flash              # 本次指定模型
gemini -p "解释这个代码库的架构"          # 非交互，直接出结果
gemini -p "..." --output-format json    # 结构化输出，便于脚本处理
```

会话内可用的斜杠命令：

| 命令          | 用途                 |
| ----------- | ------------------ |
| `/settings` | 查看与修改当前配置（含预览功能开关） |
| `/auth`     | 切换认证方式（部分版本提供）     |
| `/bug`      | 上报问题               |
| `/quit`     | 退出                 |

---

## 六、常见问题

| 现象                  | 原因                                      | 处理                                                                                   |
| ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------ |
| `401 Invalid token` | 令牌错误、已删除，或误用了 Google AI Studio 的 key    | 到中转站控制台重新建一个令牌，确认以 `sk-` 开头                                                          |
| `404 Invalid URL`   | base url 带了 `/v1` 或 `/v1beta`，或末尾多了 `/` | 改成纯域名 `https://api.zaimod.com`                                                        |
| `404` 但地址没问题        | 模型 ID 写错（控制台里叫别的名字）                     | 到控制台模型列表复制准确 ID，用 `-m` 指定试一次                                                         |
| `403` / 分组无权限       | 令牌所属分组没有 Gemini 通道                      | 控制台编辑令牌，勾选可用分组                                                                       |
| 启动报 Node 版本相关错误     | Node < 20                               | 升级 Node 后重装 CLI                                                                      |
| 环境变量设置了但不生效         | 旧终端窗口未刷新；或 CMD 里 `set A = B` 写进了空格      | 新开终端；`echo $GOOGLE_GEMINI_BASE_URL`（PowerShell 用 `$env:GOOGLE_GEMINI_BASE_URL`）核对实际值 |
| 一直提示登录谷歌账号          | 首次启动选了 OAuth，环境变量被绕过                    | 删 `~/.gemini/oauth_creds.json`，重启后选 `Use Gemini API Key`                             |
| 能回复但控制台无日志          | 请求没走中转                                  | 同上一行，检查认证方式与 base url 是否同时生效                                                         |

---

## 附录 A · 原文勘误

整理时发现的问题，逐条列出便于核对：

1. **标题不一致**：页面标题是《Gemini CLI 中转站配置使用教程》，正文一级标题却是《Gemini CLI 中文使用指南》，与实际内容（中转配置）不符。
2. **shell 语法混排**：Linux 的 `export` 与 Windows 的 `set` 塞在同一个代码块里，仅靠一行中文注释 `#cmd 使用下面这个` 区分，复制时极易出错。
3. **`set` 的时效性未说明**：`set` 只对当前 CMD 窗口有效，原文未提示需要 `setx` 才能永久生效，用户重启终端后常以为配置丢了。
4. **缺失首次启动的认证选择步骤**：原文直接写 `gemini` 启动，未说明必须选 `Use Gemini API Key`。这是最关键的一处遗漏——选错则中转地址完全不生效。
5. **未说明 base url 不能带版本段**：原文示例恰好给的是纯域名（正确），但没有强调这一点，用户很容易"顺手"加上 `/v1beta` 导致 404。
6. **排错命令无效**：原文用 `curl -I` 探测中转站首页，这只能验证域名可达（首页返回的是控制台页面，状态 200），既无法证明令牌有效，也不能证明模型路径正确。已补充直接打模型接口的 curl 作为替代。
7. **主题混杂**：全文约七成篇幅是官方 README 的翻译（功能列表、GitHub Action、发布节奏、MCP 说明），与"配置中转站"这一主题无关，已精简：只保留第五节的可执行命令速查，其余介绍性内容不再收录。
8. **卸载指引缺失**：原文只写"请参考官方的卸载指南"却没给命令，补充如下：

```bash
npm uninstall -g @google/gemini-cli
rm -rf ~/.gemini          # 如需彻底清除登录状态与配置（macOS / Linux）
```

Windows 删除 `%USERPROFILE%\.gemini` 目录。

---

## 附录 B · 地址变更对照

| 位置                                    | 原地址                      | 现地址                     |
| ------------------------------------- | ------------------------ | ----------------------- |
| `GOOGLE_GEMINI_BASE_URL`（macOS/Linux） | `https://api.zaimod.com` | `https://api.zaimod.com` |
| `GOOGLE_GEMINI_BASE_URL`（Windows CMD） | `https://api.zaimod.com` | `https://api.zaimod.com` |
| 排错用 `curl` 目标                         | `https://api.zaimod.com` | `https://api.zaimod.com` |

除域名外，路径写法、变量名、参数均未改动。**旧平台的令牌不能沿用**，需在新平台重新生成。

上一篇：N8N 工作流使用API中转教程{else}上一篇：没有了下一篇：Claude Code 中转站安装与配置指南{else}下一篇：没有了