Gemini CLI 接入 CodingPlanX 自定义模型

使用 CodingPlanX.ai API 密钥配置 Google Gemini CLI

Gemini CLI 集成配置指南

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

什么是 Gemini CLI

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

可用模型

通过 CodingPlanX.ai 可使用以下 Gemini 模型：

模型	说明
`gemini-3-pro-preview`	最新预览版，推荐
`gemini-2.5-pro`	稳定版

> 最新版本：Gemini CLI v0.33.1（2026-03-12），支持 Extensions 系统、自定义主题等新功能。

配置概述

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

GOOGLE_GEMINI_BASE_URL - 服务地址
GEMINI_API_KEY - API 密钥（与 Claude Code 相同）
GEMINI_MODEL - 模型选择

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.codingplanx.ai"
export GEMINI_API_KEY="cr_xxxxxxxxxx"
export GEMINI_MODEL="gemini-3-pro-preview"

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

永久设置（Shell 配置文件）

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

# Gemini CLI 配置
export GOOGLE_GEMINI_BASE_URL="https://api.codingplanx.ai"
export GEMINI_API_KEY="cr_xxxxxxxxxx"
export GEMINI_MODEL="gemini-3-pro-preview"

然后执行：

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.codingplanx.ai"
export GEMINI_API_KEY="cr_xxxxxxxxxx"
export GEMINI_MODEL="gemini-3-pro-preview"

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

永久设置（Shell 配置文件）

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

# Gemini CLI 配置
export GOOGLE_GEMINI_BASE_URL="https://api.codingplanx.ai"
export GEMINI_API_KEY="cr_xxxxxxxxxx"
export GEMINI_MODEL="gemini-3-pro-preview"

然后执行：

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.codingplanx.ai"
$env:GEMINI_API_KEY = "cr_xxxxxxxxxx"
$env:GEMINI_MODEL = "gemini-3-pro-preview"

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

PowerShell 永久设置（用户级）

在 PowerShell 中运行以下命令：

# 设置用户级环境变量（永久生效）
[System.Environment]::SetEnvironmentVariable("GOOGLE_GEMINI_BASE_URL", "https://api.codingplanx.ai", [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "cr_xxxxxxxxxx", [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable("GEMINI_MODEL", "gemini-3-pro-preview", [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 18.x 或更高版本
使用 nvm 升级：nvm install --lts && nvm use --lts

环境变量未生效

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

解决：

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

网络连接问题

问题：无法连接到 CodingPlanX.ai 服务

解决：

检查网络连接是否正常
验证 GOOGLE_GEMINI_BASE_URL 是否正确设置