Gemini CLI 集成配置指南

使用 QCode.cc API 密钥配置 Google Gemini CLI

更新于 2026-09-18

本页目录

最后核实：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

⚠️ 重要变更：面向个人登录档的 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。

顺带一句：仓库并没有停更——核查当天（2026-09-18）还在发 nightly，最新稳定版是 v0.60.0（2026-09-15）。因此准确说法是「停止服务消费者登录档」，不是「停止维护」。

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

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

什么是 Gemini CLI ¶

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

可用模型 ¶

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

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

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

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

版本提示：2026-06-18 起 Gemini CLI 停止服务 Pro / Ultra / 免费个人档，请改用 Google Antigravity CLI（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 这种认证场景，所以像下面这样两个变量一起设置即可。

macOS 配置 ¶

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

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

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

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

# 更新 Homebrew
brew update

# 安装 Node.js
brew install node

方法二：官网下载 ¶

访问 https://nodejs.org/
下载适合 macOS 的 LTS 版本
打开下载的 .pkg 文件
按照安装程序指引完成安装

macOS 注意事项 ¶

如果遇到权限问题，可能需要使用 sudo
首次运行可能需要在系统偏好设置中允许
建议使用 Terminal 或 iTerm2

验证 Node.js 安装 ¶

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

node --version
npm --version

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

步骤 2：安装 Gemini CLI ¶

使用 npm 全局安装 Gemini CLI：

npm install -g @google/gemini-cli

安装完成后，验证安装：

gemini --version

步骤 3：配置 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"

将 cr_xxxxxxxxxx 替换为你的 QCode.cc API 密钥。使用与 Claude Code 相同的 API 密钥即可。

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

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

# 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"

然后执行：

source ~/.zshrc

验证 Gemini CLI 环境变量 ¶

在终端中验证：

echo $GOOGLE_GEMINI_BASE_URL
echo $GEMINI_API_KEY
echo $GEMINI_MODEL

Linux / WSL2 配置 ¶

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

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

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

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

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

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

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

方法二：使用包管理器 ¶

# 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 安装 ¶

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

node --version
npm --version

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

步骤 2：安装 Gemini CLI ¶

使用 npm 全局安装 Gemini CLI：

npm install -g @google/gemini-cli

安装完成后，验证安装：

gemini --version

步骤 3：配置 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"

将 cr_xxxxxxxxxx 替换为你的 QCode.cc API 密钥。使用与 Claude Code 相同的 API 密钥即可。

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

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

# 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"

然后执行：

source ~/.bashrc

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

验证 Gemini CLI 环境变量 ¶

在终端中验证：

echo $GOOGLE_GEMINI_BASE_URL
echo $GEMINI_API_KEY
echo $GEMINI_MODEL

Windows 配置 ¶

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

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

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

打开浏览器访问 https://nodejs.org/
点击 "LTS" 版本进行下载（推荐长期支持版本）
下载完成后双击 .msi 文件
按照安装向导完成安装，保持默认设置即可

方法二：使用包管理器 ¶

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

# 使用 Chocolatey
choco install nodejs

# 或使用 Scoop
scoop install nodejs

Windows 注意事项 ¶

建议使用 PowerShell 而不是 CMD
如果遇到权限问题，尝试以管理员身份运行
某些杀毒软件可能会误报，需要添加白名单

验证 Node.js 安装 ¶

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

node --version
npm --version

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

步骤 2：安装 Gemini CLI ¶

使用 npm 全局安装 Gemini CLI：

npm install -g @google/gemini-cli

安装完成后，验证安装：

gemini --version

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

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

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 密钥。使用与 Claude Code 相同的 API 密钥即可。

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 中验证：

echo $env:GOOGLE_GEMINI_BASE_URL
echo $env:GEMINI_API_KEY
echo $env:GEMINI_MODEL

常见问题 ¶

Node.js 版本过低 ¶

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

解决：

检查 Node.js 版本：node --version
官方要求 Node.js 20.0.0 或更高（包内 engines.node >=20.0.0；写在 18 上装完会直接报错）
使用 nvm 升级：nvm install --lts && nvm use --lts

环境变量未生效 ¶

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

解决：

确认已重新打开终端或执行 source 命令
检查变量名是否正确（区分大小写）
验证 API 密钥格式是否正确（cr_ 开头）

网络连接问题 ¶

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

解决：

检查网络连接是否正常
验证 GOOGLE_GEMINI_BASE_URL 是否正确设置
尝试备用节点：
🇨🇳 亚洲：https://asia.qcode.cc/gemini

Gemini CLI 集成配置指南

相关文档