返回首页

Gemini CLI 使用教程

完整的 Google Gemini CLI 安装配置指南
支持 Windows、macOS、Linux 三大平台

您的 Gemini API 地址：

请将配置中的 http://your-service-domain/gemini 替换为上方显示的地址

安装 Node.js

Gemini CLI 需要 Node.js 20 或更高版本。从官网下载并安装：

下载地址： https://nodejs.org/

推荐下载 LTS (长期支持) 版本，安装时选择 "Automatically install the necessary tools" 选项

验证安装：

PowerShell / CMD

node --version
npm --version

应显示类似 v20.x.x 和 10.x.x 的版本号

安装 Gemini CLI

使用 npm 全局安装 Gemini CLI：

PowerShell / CMD

npm install -g @google/gemini-cli

注意： 如果遇到权限错误，请以管理员身份运行 PowerShell

验证安装：

PowerShell / CMD

gemini --version

应显示 Gemini CLI 的版本信息

配置环境变量

配置 Gemini CLI 使用 Relay Service：

方法 1: 临时设置（当前会话）

PowerShell

方法 2: 永久设置（用户环境变量）

PowerShell（管理员权限）

重要：

将 你的API密钥 替换为实际的 API Key
永久设置后需要重新打开 PowerShell 窗口才能生效
使用与 Claude Code 相同的 API 密钥即可

验证配置：

PowerShell

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

开始使用 Gemini CLI

启动 Gemini CLI：

PowerShell / CMD

gemini

成功！ Gemini CLI 已启动。您可以开始与 AI 对话了。

首次运行时，Gemini CLI 会检测到自定义基础 URL 并使用您配置的 API 密钥进行认证。

常用功能：

对话模式： 直接输入问题，按回车发送
代码生成： 请求 Gemini 生成代码片段
文件操作： 使用内置工具读取和编辑文件
Shell 命令： 执行系统命令
退出： 输入 /exit 或按 Ctrl+C

故障排除

问题 1: 找不到 gemini 命令

原因： npm 全局安装路径未添加到系统 PATH
解决：

找到 npm 全局安装路径：

PowerShell

npm config get prefix

将该路径添加到系统 PATH 环境变量
重新打开 PowerShell 窗口

问题 2: 环境变量未生效

原因： 设置环境变量后未重启终端
解决： 关闭所有 PowerShell/CMD 窗口，重新打开

问题 3: API 连接失败

检查项：

API 密钥是否正确（包含 cr_ 前缀）
基础 URL 是否正确配置
网络连接是否正常
防火墙是否阻止了连接

问题 4: Node.js 版本过低

原因： Gemini CLI 需要 Node.js 20+
解决： 从 nodejs.org 下载并安装最新 LTS 版本

安装 Node.js

Gemini CLI 需要 Node.js 20 或更高版本。

方法 1: 使用 Homebrew (推荐)

Terminal

# 安装 Node.js
brew install node

# 验证安装
node --version
npm --version

方法 2: 从官网下载

下载地址： https://nodejs.org/
下载 macOS Installer (.pkg)，双击安装

安装 Gemini CLI

使用 npm 全局安装 Gemini CLI：

Terminal

npm install -g @google/gemini-cli

注意： 如果遇到权限错误，请使用 sudo npm install -g @google/gemini-cli

验证安装：

Terminal

gemini --version

配置环境变量

配置 Gemini CLI 使用 Relay Service：

方法 1: 临时设置（当前会话）

Terminal

方法 2: 永久设置

添加到你的 shell 配置文件：

对于 zsh (macOS 默认)

对于 bash

提示： 使用与 Claude Code 相同的 API 密钥即可

验证配置：

Terminal

echo $GOOGLE_GEMINI_BASE_URL
echo $GEMINI_API_KEY
echo $GEMINI_MODEL

开始使用 Gemini CLI

启动 Gemini CLI：

Terminal

gemini

成功！ Gemini CLI 已启动。您可以开始与 AI 对话了。

常用功能：

对话模式： 直接输入问题，按回车发送
代码生成： 请求 Gemini 生成代码片段
文件操作： 使用内置工具读取和编辑文件
Shell 命令： 执行系统命令
退出： 输入 /exit 或按 Ctrl+C

故障排除

问题 1: 找不到 gemini 命令

原因： npm 全局安装路径未添加到 PATH
解决： 确认 npm 全局路径

Terminal

npm config get prefix

确保该路径的 bin 目录在 PATH 中

问题 2: 环境变量未生效

解决： 关闭所有 Terminal 窗口，重新打开；或运行 source ~/.zshrc (或 ~/.bash_profile)

问题 3: API 连接失败

检查项：

API 密钥是否正确
基础 URL 是否正确配置
网络连接是否正常

安装 Node.js

Gemini CLI 需要 Node.js 20 或更高版本。

Ubuntu / Debian:

Terminal

# 使用 NodeSource 仓库安装 Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node --version
npm --version

Fedora / RHEL:

Terminal

# 使用 NodeSource 仓库
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo dnf install -y nodejs

# 验证安装
node --version
npm --version

Arch Linux:

Terminal

sudo pacman -S nodejs npm

# 验证安装
node --version
npm --version

安装 Gemini CLI

使用 npm 全局安装 Gemini CLI：

Terminal

sudo npm install -g @google/gemini-cli

验证安装：

Terminal

gemini --version

配置环境变量

配置 Gemini CLI 使用 Relay Service：

方法 1: 临时设置（当前会话）

Terminal

方法 2: 永久设置

添加到你的 shell 配置文件：

对于 bash (默认)

# 添加到 ~/.bashrc
echo 'export GOOGLE_GEMINI_BASE_URL=""' >> ~/.bashrc
echo 'export GEMINI_API_KEY="你的API密钥"' >> ~/.bashrc
echo 'export GEMINI_MODEL="gemini-2.5-pro"' >> ~/.bashrc

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

对于 zsh

提示： 使用与 Claude Code 相同的 API 密钥即可

验证配置：

Terminal

echo $GOOGLE_GEMINI_BASE_URL
echo $GEMINI_API_KEY
echo $GEMINI_MODEL

开始使用 Gemini CLI

启动 Gemini CLI：

Terminal

gemini

成功！ Gemini CLI 已启动。您可以开始与 AI 对话了。

常用功能：

对话模式： 直接输入问题，按回车发送
代码生成： 请求 Gemini 生成代码片段
文件操作： 使用内置工具读取和编辑文件
Shell 命令： 执行系统命令
退出： 输入 /exit 或按 Ctrl+C

故障排除

问题 1: 找不到 gemini 命令

原因： npm 全局安装路径未添加到 PATH
解决： 确认 npm 全局路径

Terminal

npm config get prefix

将 [prefix]/bin 添加到 PATH 环境变量

问题 2: 环境变量未生效

解决： 运行 source ~/.bashrc (或 ~/.zshrc)，或重新打开终端

问题 3: API 连接失败

检查项：

API 密钥是否正确（包含 cr_ 前缀）
基础 URL 是否正确配置
网络连接是否正常
防火墙规则是否允许连接

问题 4: 权限错误

解决： 使用 sudo npm install -g @google/gemini-cli 安装

了解更多

Gemini CLI 官方资源：

官方仓库： github.com/google-gemini/gemini-cli
官方文档： google-gemini.github.io/gemini-cli
npm 包： npmjs.com/package/@google/gemini-cli

高级功能：

MCP 扩展： 支持 Model Context Protocol，可接入自定义工具和服务
Google Search： 内置 Google 搜索功能，获取实时信息
文件操作： 读取、编辑、创建文件
Shell 集成： 执行系统命令和脚本
交互式模式： 支持 vim、top 等交互式命令

提示： Gemini CLI 是一个功能强大的终端 AI 助手，配合我们的中转服务，您可以享受稳定、高速的 AI 辅助开发体验！