# Gemini CLI 集成配置指南

> **最后核实**：2026-09-18 · 📄 依据官方文档（Gemini CLI v0.60.0（2026-09-15；Pro/免费档 2026-06-18 起停止服务，企业付费 Key 仍可用））

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Gemini ✅ · Claude ❌ · GPT ❌ · 国产 ❌ |
| 协议与 Base URL | Gemini：`https://api.qcode.cc/gemini`（CLI 自动拼 `/v1beta/...`，不要手动加 `/v1beta`） |
| 配置位置 | `~/.gemini/settings.json` 或环境变量 `GOOGLE_GEMINI_BASE_URL` + `GEMINI_API_KEY` |
| 官方文档 | [google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) |

> **⚠️ 重要变更：面向个人登录档的 Gemini CLI 已被 Google Antigravity CLI 取代**。官方 2026-05-19 的公告逐字是：自 **2026-06-18** 起，Gemini CLI 与 Gemini Code Assist 的 IDE 扩展「will stop serving requests」——对象是 **Google AI Pro、Ultra**，以及用个人账号免费使用的那批人。当天上线的是 **Antigravity CLI 与 Antigravity 2.0**（作为 IDE 的 Antigravity 早在 2025-11-18 就已发布）。企业侧不同：走 Gemini Code Assist Standard / Enterprise 授权的组织访问不变，同一篇公告写明「Gemini CLI will remain accessible via paid Gemini and Gemini Enterprise Agent Platform API keys」。**所以本页对企业付费 Key 依然有效**；Pro / Ultra / 免费档请改用 [Google Antigravity CLI](/docs/ide/antigravity)。
>
> 顺带一句：仓库并没有停更——核查当天（2026-09-18）还在发 nightly，最新稳定版是 v0.60.0（2026-09-15）。因此准确说法是「**停止服务消费者登录档**」，不是「停止维护」。

> **🚧 试用阶段**：Gemini 资源目前仅小范围开放，尚未大规模提供。如有较大用量需求，请联系[在线客服](javascript:void(Tawk_API.toggle()))或发送邮件至 **hi@qcode.cc**，我们可以为您专门购买 Gemini 资源并开通服务。

QCode.cc 支持 Claude Code、OpenAI Codex 以及 Google Gemini CLI。购买套餐后，三个工具**共享套餐配额**，让你可以灵活选择使用哪个工具。

## 什么是 Gemini CLI

[Gemini CLI](https://geminicli.com/) 是 Google 推出的命令行 AI 编程助手，类似于 Claude Code，可以帮助你在终端中进行代码开发、调试和文件操作。

## 可用模型

通过 QCode.cc 可使用以下 Gemini 模型：

**以实时查询为准**，不要照抄任何文档里的固定清单（包括本页）：

```bash
curl -s https://api.qcode.cc/gemini/v1beta/models \
  -H "x-goog-api-key: cr_你的QCode密钥"
```

返回的 id 就是当前可调的 Gemini 模型，把它填进 `GEMINI_MODEL` 即可。
完整在售清单与实时单价见 [qcode.cc/models](https://qcode.cc/models)。

> **版本提示**：2026-06-18 起 Gemini CLI 停止服务 Pro / Ultra / 免费个人档，请改用 [Google Antigravity CLI](https://antigravity.google/)（CLI 与 Antigravity 2.0 于 2026-05-19 上线）；企业付费 Key 不受影响，仍可继续用 Gemini CLI。

## 配置概述

Gemini CLI 需要配置以下环境变量：

- `GOOGLE_GEMINI_BASE_URL` - 服务地址

- `GEMINI_API_KEY` - API 密钥（与 Claude Code 相同）

- `GEMINI_MODEL` - 模型选择
配置文件也是官方支持的路径：用户级 `~/.gemini/settings.json`，项目级 `.gemini/settings.json`（项目覆盖用户）。模型对应 `model.name`，认证类型对应 `security.auth.selectedType`；文件里的字符串值可以用 `$VAR`、`${VAR}`、`${VAR:-默认值}` 引用环境变量。官方文档写明 `GOOGLE_GEMINI_BASE_URL` 用于 gemini-api-key 这种认证场景，所以像下面这样两个变量一起设置即可。


<div data-os="macos" markdown="1">

## macOS 配置

### 步骤 1：安装 Node.js 环境

Gemini CLI 需要 Node.js 环境才能运行。

#### 方法一：使用 Homebrew（推荐）

如果你已经安装了 Homebrew，使用它安装 Node.js 会更方便：

```bash
# 更新 Homebrew
brew update

# 安装 Node.js
brew install node
```

#### 方法二：官网下载

1. 访问 [https://nodejs.org/](https://nodejs.org/)

2. 下载适合 macOS 的 LTS 版本

3. 打开下载的 `.pkg` 文件

4. 按照安装程序指引完成安装

#### macOS 注意事项

- 如果遇到权限问题，可能需要使用 `sudo`

- 首次运行可能需要在系统偏好设置中允许

- 建议使用 Terminal 或 iTerm2

#### 验证 Node.js 安装

安装完成后，打开 Terminal，输入以下命令：

```bash
node --version
npm --version
```

如果显示版本号，说明安装成功了！

### 步骤 2：安装 Gemini CLI

使用 npm 全局安装 Gemini CLI：

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

安装完成后，验证安装：

```bash
gemini --version
```

### 步骤 3：配置 Gemini CLI 环境变量

设置以下环境变量以连接到中转服务：

#### 临时设置（当前会话）

在终端中运行以下命令：

```bash
export GOOGLE_GEMINI_BASE_URL="https://api.qcode.cc/gemini"
export GEMINI_API_KEY="cr_xxxxxxxxxx"
export GEMINI_MODEL="gemini-2.5-pro"
```

> 将 `cr_xxxxxxxxxx` 替换为你的 [QCode.cc API 密钥](https://qcode.cc/dashboard)。使用与 Claude Code 相同的 API 密钥即可。

#### 永久设置（Shell 配置文件）

将以下内容添加到你的 shell 配置文件中（`~/.zshrc`）：

```bash
# Gemini CLI 配置
export GOOGLE_GEMINI_BASE_URL="https://api.qcode.cc/gemini"
export GEMINI_API_KEY="cr_xxxxxxxxxx"
export GEMINI_MODEL="gemini-2.5-pro"
```

然后执行：

```bash
source ~/.zshrc
```

### 验证 Gemini CLI 环境变量

在终端中验证：

```bash
echo $GOOGLE_GEMINI_BASE_URL
echo $GEMINI_API_KEY
echo $GEMINI_MODEL
```

</div>

<div data-os="linux" markdown="1">

## Linux / WSL2 配置

### 步骤 1：安装 Node.js 环境

Gemini CLI 需要 Node.js 环境才能运行。

#### 方法一：使用 nvm（推荐）

nvm 可以方便地管理多个 Node.js 版本：

```bash
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc

# 安装最新 LTS 版本
nvm install --lts
```

#### 方法二：使用包管理器

```bash
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora
sudo dnf install nodejs

# Arch Linux
sudo pacman -S nodejs npm
```

#### Linux / WSL2 注意事项

- WSL2 用户建议在 Linux 子系统中安装，而不是 Windows

- 使用 nvm 可以避免权限问题

- 确保 shell 配置文件正确加载了 nvm

#### 验证 Node.js 安装

安装完成后，打开终端，输入以下命令：

```bash
node --version
npm --version
```

如果显示版本号，说明安装成功了！

### 步骤 2：安装 Gemini CLI

使用 npm 全局安装 Gemini CLI：

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

安装完成后，验证安装：

```bash
gemini --version
```

### 步骤 3：配置 Gemini CLI 环境变量

设置以下环境变量以连接到中转服务：

#### 临时设置（当前会话）

在终端中运行以下命令：

```bash
export GOOGLE_GEMINI_BASE_URL="https://api.qcode.cc/gemini"
export GEMINI_API_KEY="cr_xxxxxxxxxx"
export GEMINI_MODEL="gemini-2.5-pro"
```

> 将 `cr_xxxxxxxxxx` 替换为你的 [QCode.cc API 密钥](https://qcode.cc/dashboard)。使用与 Claude Code 相同的 API 密钥即可。

#### 永久设置（Shell 配置文件）

将以下内容添加到你的 shell 配置文件中（`~/.bashrc`）：

```bash
# Gemini CLI 配置
export GOOGLE_GEMINI_BASE_URL="https://api.qcode.cc/gemini"
export GEMINI_API_KEY="cr_xxxxxxxxxx"
export GEMINI_MODEL="gemini-2.5-pro"
```

然后执行：

```bash
source ~/.bashrc
```

如果你使用 Zsh，则添加到 `~/.zshrc` 并执行 `source ~/.zshrc`。

### 验证 Gemini CLI 环境变量

在终端中验证：

```bash
echo $GOOGLE_GEMINI_BASE_URL
echo $GEMINI_API_KEY
echo $GEMINI_MODEL
```

</div>

<div data-os="windows" markdown="1">

## Windows 配置

### 步骤 1：安装 Node.js 环境

Gemini CLI 需要 Node.js 环境才能运行。

#### 方法一：官网下载（推荐）

1. 打开浏览器访问 [https://nodejs.org/](https://nodejs.org/)

2. 点击 "LTS" 版本进行下载（推荐长期支持版本）

3. 下载完成后双击 `.msi` 文件

4. 按照安装向导完成安装，保持默认设置即可

#### 方法二：使用包管理器

如果你安装了 Chocolatey 或 Scoop，可以使用命令行安装：

```powershell
# 使用 Chocolatey
choco install nodejs

# 或使用 Scoop
scoop install nodejs
```

#### Windows 注意事项

- 建议使用 PowerShell 而不是 CMD

- 如果遇到权限问题，尝试以管理员身份运行

- 某些杀毒软件可能会误报，需要添加白名单

#### 验证 Node.js 安装

安装完成后，打开 PowerShell 或 CMD，输入以下命令：

```powershell
node --version
npm --version
```

如果显示版本号，说明安装成功了！

### 步骤 2：安装 Gemini CLI

使用 npm 全局安装 Gemini CLI：

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

安装完成后，验证安装：

```powershell
gemini --version
```

### 步骤 3：配置 Gemini CLI 环境变量

设置以下环境变量以连接到中转服务：

#### PowerShell 临时设置（当前会话）

在 PowerShell 中运行以下命令：

```powershell
$env:GOOGLE_GEMINI_BASE_URL = "https://api.qcode.cc/gemini"
$env:GEMINI_API_KEY = "cr_xxxxxxxxxx"
$env:GEMINI_MODEL = "gemini-2.5-pro"
```

> 将 `cr_xxxxxxxxxx` 替换为你的 [QCode.cc API 密钥](https://qcode.cc/dashboard)。使用与 Claude Code 相同的 API 密钥即可。

#### PowerShell 永久设置（用户级）

在 PowerShell 中运行以下命令：

```powershell
# 设置用户级环境变量（永久生效）
[System.Environment]::SetEnvironmentVariable("GOOGLE_GEMINI_BASE_URL", "https://api.qcode.cc/gemini", [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "cr_xxxxxxxxxx", [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable("GEMINI_MODEL", "gemini-2.5-pro", [System.EnvironmentVariableTarget]::User)
```

> 设置后需要重新打开 PowerShell 窗口才能生效。

### 验证 Gemini CLI 环境变量

在 PowerShell 中验证：

```powershell
echo $env:GOOGLE_GEMINI_BASE_URL
echo $env:GEMINI_API_KEY
echo $env:GEMINI_MODEL
```

</div>

## 常见问题

### Node.js 版本过低

**问题**：Gemini CLI 提示 Node.js 版本不兼容

**解决**：

1. 检查 Node.js 版本：`node --version`

2. 官方要求 Node.js **20.0.0 或更高**（包内 `engines.node >=20.0.0`；写在 18 上装完会直接报错）

3. 使用 nvm 升级：`nvm install --lts && nvm use --lts`

### 环境变量未生效

**问题**：设置环境变量后仍无法连接

**解决**：

1. 确认已重新打开终端或执行 `source` 命令

2. 检查变量名是否正确（区分大小写）

3. 验证 API 密钥格式是否正确（`cr_` 开头）

### 网络连接问题

**问题**：无法连接到 QCode.cc 服务

**解决**：

1. 检查网络连接是否正常

2. 验证 `GOOGLE_GEMINI_BASE_URL` 是否正确设置

3. 尝试备用节点：
   - 🇨🇳 亚洲：`https://asia.qcode.cc/gemini`

## 相关文档

- [Antigravity CLI 接入](/docs/ide/antigravity) - Gemini CLI 的官方接替者
- [环境变量配置](/docs/getting-started/environment) - Claude Code 配置

- [Codex 集成](/docs/ide/codex) - OpenAI Codex CLI 配置

- [快速上手](/docs/getting-started/quick-start) - 开始使用 Claude Code