Gemini CLI 使用指南

Gemini CLI 是 Google 官方的 AI 编程助手命令行工具，支持通过 cch 代理服务使用。本指南将帮助您在不同操作系统上完成安装和配置。

macOS

环境准备：安装 Node.js

claude 需要 Node.js 环境才能运行（需 v18 或更高版本）。

方法一：使用 Homebrew（推荐）

 更新 Homebrew
brew update
 安装 Node.js
brew install node

方法二：官网下载

1. 访问 https://nodejs.org/ https://nodejs.org/
2. 下载适合 macOS 的 LTS 版本（需 v18 或更高）
3. 打开下载的 .pkg 文件，按照安装向导完成

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

node --version
npm --version

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

安装 gemini gemini

确保您已安装 Node.js 18 或更高版本，然后全局安装 Gemini CLI：

npm install -g @google/gemini-cli

验证安装：

gemini --version

连接 cch 服务

方法一：配置文件方式（推荐）

创建配置目录

Gemini CLI 的配置文件位于 ~/.gemini/ 目录。

macOS / Linux：

mkdir -p ~/.gemini

创建 .env 配置文件

在 ~/.gemini/ 目录下创建 .env 文件：

macOS / Linux：

nano ~/.gemini/.env

添加以下内容：

GOOGLE_GEMINI_BASE_URL=当前站点地址
GEMINI_API_KEY=your-api-key-here
GEMINI_MODEL=gemini-3-pro-preview

创建 settings.json 配置文件

在 ~/.gemini/ 目录下创建 settings.json 文件：

{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

这个配置文件启用了 IDE 集成，并设置认证方式为 API Key。

参数说明

• GOOGLE_GEMINI_BASE_URL: cch API 基础地址
• GEMINI_API_KEY: 您在 cch 控制台创建的 API 密钥
• GEMINI_MODEL: 使用的模型（默认为 gemini-2.5-pro）

重要提示

• 将 YOUR_API_KEY_HERE 替换为您的实际 API 密钥
• 密钥获取方式：登录控制台 → API 密钥管理 → 创建密钥

方法二：环境变量配置

如果您只想临时使用，可以通过环境变量配置：

macOS / Linux：

export GOOGLE_GEMINI_BASE_URL="当前站点地址"
export GEMINI_API_KEY="your-api-key-here"
export GEMINI_MODEL="gemini-2.5-pro"

环境变量只在当前终端会话中有效。如需持久化配置，请使用配置文件方式。

启动和验证

启动 Gemini CLI

进入您的项目目录并启动 Gemini CLI：

cd /path/to/your/project
gemini

首次启动时，Gemini CLI 会读取配置文件中的设置。

验证配置

在 Gemini CLI 中尝试发送一个简单的请求测试连接：

你好，请帮我创建一个 Python 的 hello world 程序

如果 Gemini CLI 正常响应，说明配置成功！

使用 Agent Mode

Gemini CLI 支持 Agent Mode，可以自动规划和执行复杂任务：

gemini --agent

在 Agent Mode 下，Gemini 会：

• 自动分析任务需求
• 制定执行计划
• 逐步执行并验证结果
• 根据反馈调整策略

常见问题

1. 命令未找到

 检查 npm 全局安装路径并添加到 PATH（如果不在）
npm config get prefix

 添加到 PATH（如果不在）
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. API 连接失败

• 检查环境变量或配置文件中的 GEMINI_API_KEY 是否设置正确
• 验证 GOOGLE_GEMINI_BASE_URL 是否正确
• 测试网络连接

3. 更新 gemini

npm install -g @google/gemini-cli

Windows

环境准备：安装 Node.js

claude 需要 Node.js 环境才能运行（需 v18 或更高版本）。

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

1. 访问 https://nodejs.org/ https://nodejs.org/
2. 下载 LTS 版本（需 v18 或更高）
3. 双击 .msi 文件，按向导安装（保持默认设置）

方法二：使用包管理器

 使用 Chocolatey
choco install nodejs

 或使用 Scoop
scoop install nodejs

提示

建议使用 PowerShell 而不是 CMD，以获得更好的体验

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

node --version
npm --version

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

安装 gemini gemini

确保您已安装 Node.js 18 或更高版本，然后全局安装 Gemini CLI：

npm install -g @google/gemini-cli

验证安装：

gemini --version

连接 cch 服务

方法一：配置文件方式（推荐）

创建配置目录

Gemini CLI 的配置文件位于 ~/.gemini/ 目录。

Windows (PowerShell)：

mkdir $env:USERPROFILE\.gemini

创建 .env 配置文件

在 ~/.gemini/ 目录下创建 .env 文件：

Windows：在 %USERPROFILE%\gemini\ 目录下创建 .env 文件

添加以下内容：

GOOGLE_GEMINI_BASE_URL=当前站点地址
GEMINI_API_KEY=your-api-key-here
GEMINI_MODEL=gemini-3-pro-preview

创建 settings.json 配置文件

在 ~/.gemini/ 目录下创建 settings.json 文件：

{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

这个配置文件启用了 IDE 集成，并设置认证方式为 API Key。

参数说明

• GOOGLE_GEMINI_BASE_URL: cch API 基础地址
• GEMINI_API_KEY: 您在 cch 控制台创建的 API 密钥
• GEMINI_MODEL: 使用的模型（默认为 gemini-2.5-pro）

重要提示

• 将 YOUR_API_KEY_HERE 替换为您的实际 API 密钥
• 密钥获取方式：登录控制台 → API 密钥管理 → 创建密钥

方法二：环境变量配置

如果您只想临时使用，可以通过环境变量配置：

Windows (PowerShell)：

$env:GOOGLE_GEMINI_BASE_URL="当前站点地址"
$env:GEMINI_API_KEY="your-api-key-here"
$env:GEMINI_MODEL="gemini-2.5-pro"

Windows (CMD)：

set GOOGLE_GEMINI_BASE_URL=当前站点地址
set GEMINI_API_KEY=your-api-key-here
set GEMINI_MODEL=gemini-3-pro-preview

环境变量只在当前终端会话中有效。如需持久化配置，请使用配置文件方式。

启动和验证

启动 Gemini CLI

进入您的项目目录并启动 Gemini CLI：

cd C:\path\to\your\project
gemini

首次启动时，Gemini CLI 会读取配置文件中的设置。

验证配置

在 Gemini CLI 中尝试发送一个简单的请求测试连接：

你好，请帮我创建一个 Python 的 hello world 程序

如果 Gemini CLI 正常响应，说明配置成功！

使用 Agent Mode

Gemini CLI 支持 Agent Mode，可以自动规划和执行复杂任务：

gemini --agent

在 Agent Mode 下，Gemini 会：

• 自动分析任务需求
• 制定执行计划
• 逐步执行并验证结果
• 根据反馈调整策略

常见问题

1. 命令未找到

• 确保 npm 全局路径（通常是 C:\Users\你的用户名\AppData\Roaming\npm）已添加到系统 PATH
• 重新打开 PowerShell 窗口

2. API 连接失败

• 检查环境变量或配置文件中的 GEMINI_API_KEY 是否设置正确
• 验证 GOOGLE_GEMINI_BASE_URL 是否正确
• 测试网络连接

3. 更新 gemini

npm install -g @google/gemini-cli

Linux

环境准备：安装 Node.js

claude 需要 Node.js 环境才能运行（需 v18 或更高版本）。

方法一：使用官方仓库（推荐）

 添加 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
 安装 Node.js
sudo apt-get install -y nodejs

方法二：使用系统包管理器

 Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

 CentOS/RHEL/Fedora
sudo dnf install nodejs npm

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

node --version
npm --version

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

安装 gemini gemini

确保您已安装 Node.js 18 或更高版本，然后全局安装 Gemini CLI：

npm install -g @google/gemini-cli

验证安装：

gemini --version

连接 cch 服务

方法一：配置文件方式（推荐）

创建配置目录

Gemini CLI 的配置文件位于 ~/.gemini/ 目录。

macOS / Linux：

mkdir -p ~/.gemini

创建 .env 配置文件

在 ~/.gemini/ 目录下创建 .env 文件：

macOS / Linux：

nano ~/.gemini/.env

添加以下内容：

GOOGLE_GEMINI_BASE_URL=当前站点地址
GEMINI_API_KEY=your-api-key-here
GEMINI_MODEL=gemini-3-pro-preview

创建 settings.json 配置文件

在 ~/.gemini/ 目录下创建 settings.json 文件：

{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

这个配置文件启用了 IDE 集成，并设置认证方式为 API Key。

参数说明

• GOOGLE_GEMINI_BASE_URL: cch API 基础地址
• GEMINI_API_KEY: 您在 cch 控制台创建的 API 密钥
• GEMINI_MODEL: 使用的模型（默认为 gemini-2.5-pro）

重要提示

• 将 YOUR_API_KEY_HERE 替换为您的实际 API 密钥
• 密钥获取方式：登录控制台 → API 密钥管理 → 创建密钥

方法二：环境变量配置

如果您只想临时使用，可以通过环境变量配置：

macOS / Linux：

export GOOGLE_GEMINI_BASE_URL="当前站点地址"
export GEMINI_API_KEY="your-api-key-here"
export GEMINI_MODEL="gemini-2.5-pro"

环境变量只在当前终端会话中有效。如需持久化配置，请使用配置文件方式。

启动和验证

启动 Gemini CLI

进入您的项目目录并启动 Gemini CLI：

cd /path/to/your/project
gemini

首次启动时，Gemini CLI 会读取配置文件中的设置。

验证配置

在 Gemini CLI 中尝试发送一个简单的请求测试连接：

你好，请帮我创建一个 Python 的 hello world 程序

如果 Gemini CLI 正常响应，说明配置成功！

使用 Agent Mode

Gemini CLI 支持 Agent Mode，可以自动规划和执行复杂任务：

gemini --agent

在 Agent Mode 下，Gemini 会：

• 自动分析任务需求
• 制定执行计划
• 逐步执行并验证结果
• 根据反馈调整策略

常见问题

1. 命令未找到

 检查 npm 全局安装路径并添加到 PATH（如果不在）
npm config get prefix

 添加到 PATH（如果不在）
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

2. API 连接失败

• 检查环境变量或配置文件中的 GEMINI_API_KEY 是否设置正确
• 验证 GOOGLE_GEMINI_BASE_URL 是否正确
• 测试网络连接

3. 更新 gemini

npm install -g @google/gemini-cli