Gemini CLI 使用教程

Gemini CLI 是 Google 开发的开源（Apache 2.0 许可）命令行 AI 代理，一个可通过命令行调用 Gemini API 的工具。默认支持每分钟最多 60 次请求、每天最多 1000 次请求，旨在加速开发者的工作流程。

1. 引言

2025年6月，Google 面向开发者发布了 Gemini CLI。

主要功能包括：

• 使用自然语言与 AI 互动
• 支持代码生成、审查与执行辅助
• 可与 Google 搜索与系统命令联动
• 拥有超大上下文窗口（最多 100 万 Token）
• 不仅适合编程开发，也可用于文档生成、Bug 修复等多种场景

2. 快速入门

前提条件

已安装 Node.js 18 或以上版本。

Windows 平台

（一）安装 Node.js 环境

Windows 安装方法

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

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

方法二：使用包管理器

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

# 使用 Chocolatey
choco install nodejs

# 或使用 Scoop
scoop install nodejs

Windows 注意事项

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

验证安装是否成功

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

node --version
npm --version

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

（二）安装 Gemini CLI

安装

在终端运行以下命令即可开始：

# 临时体验（无需安装）
npx https://github.com/google-gemini/gemini-cli

# 或全局安装（推荐长期使用）
npm install -g @google/gemini-cli

验证安装是否成功

执行以下命令检查安装是否成功：

gemini --version

如果看到输出版本消息，则表示安装成功。

（三）初始设置

首次启动

使用以下命令运行 gemini：

gemini

主题选择：启动 gemini 的时候，会看到选择主题的选项，然后选择你喜欢的 CLI 的主题。

选择身份认证的方法：可以选择使用 Google 登录验证或 Gemini API Key。

认证方式

方式一：使用 Google 登录（推荐）

选择"使用 Google 登录"后，浏览器会打开，要求使用 Google 账户登录。按照提示完成认证，即可免费使用 Gemini 2.5 Pro（支持百万 token 的上下文窗口，每分钟 60 次请求，每日 1000 次请求）。

方式二：Gemini API Key

也可以使用其他验证方式，比如选择「Gemini API Key」，具体步骤如下：

1. 打开浏览器，访问：https://makersuite.google.com/app/apikey
2. 登录你的 Google 账号，生成 Gemini API Key
3. 在你的项目目录创建 .env 文件，配置上生成的 Gemini API Key：

GEMINI_API_KEY=你的API密钥

如果要设置永久环境变量，在 PowerShell 中运行：

# 设置用户级环境变量（永久生效）
[System.Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "你的API密钥", [System.EnvironmentVariableTarget]::User)

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

认证完成后即可使用！身份验证完成之后会显示一个输入框。

（四）使用 codeyy.top 服务

配置环境变量

如果你使用 codeyy.top 的 Gemini 服务，需要设置以下环境变量：

# PowerShell 临时设置
$env:GEMINI_API_KEY = "你的codeyy.top API密钥"
$env:GEMINI_API_BASE = "https://codeyy.top/v1beta"

# PowerShell 永久设置（用户级）
[System.Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "你的codeyy.top API密钥", [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable("GEMINI_API_BASE", "https://codeyy.top/v1beta", [System.EnvironmentVariableTarget]::User)

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

Linux 平台

（一）安装 Node.js 环境

Gemini CLI 需要 Node.js 18 或以上版本才能运行。

Linux 安装方法

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

# 添加 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

Linux 注意事项

• 某些发行版可能需要安装额外的依赖
• 如果遇到权限问题，使用 sudo
• 确保你的用户在 npm 的全局目录有写权限

验证安装是否成功

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

node --version
npm --version

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

（二）安装 Gemini CLI

安装

打开终端，运行以下命令：

# 临时体验（无需安装）
npx https://github.com/google-gemini/gemini-cli

# 或全局安装（推荐长期使用）
npm install -g @google/gemini-cli

如果遇到权限问题，可以使用 sudo：

sudo npm install -g @google/gemini-cli

验证安装是否成功

执行以下命令检查安装是否成功：

gemini --version

如果看到输出版本消息，则表示安装成功。

（三）初始设置

参考 Windows 平台的初始设置步骤，认证方式相同。

（四）使用 codeyy.top 服务

配置环境变量

如果你使用 codeyy.top 的 Gemini 服务，需要设置以下环境变量：

对于 bash：

# 临时设置
export GEMINI_API_KEY="你的codeyy.top API密钥"
export GEMINI_API_BASE="https://codeyy.top/v1beta"

# 永久设置
echo 'export GEMINI_API_KEY="你的codeyy.top API密钥"' >> ~/.bashrc
echo 'export GEMINI_API_BASE="https://codeyy.top/v1beta"' >> ~/.bashrc
source ~/.bashrc

对于 zsh：

# 临时设置
export GEMINI_API_KEY="你的codeyy.top API密钥"
export GEMINI_API_BASE="https://codeyy.top/v1beta"

# 永久设置
echo 'export GEMINI_API_KEY="你的codeyy.top API密钥"' >> ~/.zshrc
echo 'export GEMINI_API_BASE="https://codeyy.top/v1beta"' >> ~/.zshrc
source ~/.zshrc

Mac 平台

（一）安装 Node.js 环境

Gemini CLI 需要 Node.js 18 或以上版本才能运行。

macOS 安装方法

方法一：使用 Homebrew（推荐）

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

# 更新 Homebrew
brew update

# 安装 Node.js
brew install node

方法二：官网下载

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

macOS 注意事项

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

验证安装是否成功

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

node --version
npm --version

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

（二）安装 Gemini CLI

安装

打开 Terminal，运行以下命令：

# 临时体验（无需安装）
npx https://github.com/google-gemini/gemini-cli

# 或全局安装（推荐长期使用）
npm install -g @google/gemini-cli

如果遇到权限问题，可以使用 sudo：

sudo npm install -g @google/gemini-cli

验证安装是否成功

执行以下命令检查安装是否成功：

gemini --version

如果看到输出版本消息，则表示安装成功。

（三）初始设置

参考 Windows 平台的初始设置步骤，认证方式相同。

（四）使用 codeyy.top 服务

配置环境变量

如果你使用 codeyy.top 的 Gemini 服务，需要设置以下环境变量：

对于 zsh (默认)：

# 临时设置
export GEMINI_API_KEY="你的codeyy.top API密钥"
export GEMINI_API_BASE="https://codeyy.top/v1beta"

# 永久设置
echo 'export GEMINI_API_KEY="你的codeyy.top API密钥"' >> ~/.zshrc
echo 'export GEMINI_API_BASE="https://codeyy.top/v1beta"' >> ~/.zshrc
source ~/.zshrc

对于 bash：

# 临时设置
export GEMINI_API_KEY="你的codeyy.top API密钥"
export GEMINI_API_BASE="https://codeyy.top/v1beta"

# 永久设置
echo 'export GEMINI_API_KEY="你的codeyy.top API密钥"' >> ~/.bash_profile
echo 'export GEMINI_API_BASE="https://codeyy.top/v1beta"' >> ~/.bash_profile
source ~/.bash_profile

3. 基础使用方法

交互模式

在项目目录或空目录中运行：

gemini

出现 > 提示符后，即进入与 Gemini 的交互模式，可用自然语言交流。退出请输入 /quit 或 /exit。

示例1：对话

在 Gemini CLI 输入框中输入：

请用Node.js写一个简单的接口api

Gemini 会生成完整的 Express 示例代码。

示例2：让 AI 审查或修改现有代码

把你要改的代码保存为文件，比如 my-data.ts，在 Gemini CLI 中输入：

review-code my-data.ts 请优化性能

非交互模式

适用于脚本中单次命令运行，使用 --prompt（或 -p）标志：

gemini --prompt "列出 1 到 10 的质数"

或通过管道传递：

echo "怎么样才能躺平？" | gemini

4. Gemini CLI 执行多样化任务（示例）

Gemini CLI 不仅是一个简单的聊天工具，还能深度整合本地环境，执行多样化任务。

探索新代码库

# 克隆仓库并进入目录
git clone https://github.com/anything/repository
cd repository
gemini
> 解释这个系统架构的主要部分。
> 介绍了哪些安全机制？

自动化工作流程

gemini
> 根据最近 7 天的 git 历史，按功能和负责人分组，生成幻灯片资料。
> 制作一个用于壁挂显示的 GitHub Issue 交互最多的全屏 Web 应用。

系统操作，批量处理文件任务

gemini
> 将此目录中的所有图片转换为 PNG 格式，并根据 EXIF 日期重命名。
> 将 PDF 发票按支出月份整理。

5. 命令参考

Gemini CLI 支持三种命令形式：

• 启动时的命令行参数（如 gemini --model ...）
• 交互模式中的斜杠命令（如 /help）
• 提示中的特殊前缀（如 @ 或 !）

5.1 命令行参数

运行 gemini --help 查看所有选项。

5.2 斜杠命令

在交互模式中以 /<命令> 形式输入。

5.3 特殊前缀

在提示中添加以下前缀触发特定操作：

6. 配置文件 (settings.json)

Gemini CLI 的行为可通过 settings.json 自定义，按以下优先级加载：

• 全局设置：~/.gemini/settings.json
• 项目设置：(项目根目录)/.gemini/settings.json

主要配置项：

• theme：CLI 主题名称，如 "GitHub"
• contextFileName：指定上下文文件名，默认为 GEMINI.md，可设为数组如 ["GEMINI.md", "PROMPT.md"]
• fileFiltering：
  • respectGitIgnore：是否遵循 .gitignore，默认 true
  • enableRecursiveFileSearch：是否递归搜索文件以补全 @，默认 true
• autoAccept：自动跳过安全工具的执行确认，默认 false
• sandbox：启用沙盒（true 或 "docker"），默认 false
• checkpointing：
  • enabled：启用 /restore，默认 false
• preferredEditor：指定差分显示编辑器，默认 "vscode"
• coreTools / excludeTools：指定或排除内置工具
• mcpServers：定义提供自定义工具的 MCP 服务器

7. 内部机制：提示如何生成

用户输入的提示不会直接发送给 AI 模型。Gemini CLI 会附加多种信息，构建更智能、上下文相关的最终提示，包括：

• 系统指令：定义 AI 基本行为，包含 GEMINI.md 内容
• 全局上下文：~/.gemini/GEMINI.md
• 项目上下文：项目根目录或父目录的 GEMINI.md
• 本地上下文：当前目录子目录的 GEMINI.md
• 工具定义：包含 read_file、run_shell_command 及 Google 搜索工具的功能说明
• 对话历史：包含用户与 AI 的历史交互
• 用户最新提示：包含用户输入及 @ 命令展开的文件内容

VSCode 插件

在 VSCode 中使用 Gemini 扩展：

1. 打开 VSCode，进入扩展市场
2. 搜索 "Gemini" 或 "Google AI" 相关扩展
3. 安装后，在扩展设置中配置 API 密钥和服务器地址（如使用 codeyy.top，设置为 https://codeyy.top/v1beta）
4. 使用命令面板或快捷键调用 Gemini

Jetbrains IDE 插件

在 Jetbrains IDE 中使用 Gemini：

1. 打开 IDE，进入插件市场
2. 搜索 "Gemini" 或 "Google AI Studio" 插件
3. 安装后配置 API 密钥和服务器地址（如使用 codeyy.top，设置为 https://codeyy.top/v1beta）
4. 在代码编辑时使用插件功能

API 使用示例

使用 REST API 调用 Gemini（通过 codeyy.top）：

# REST API 调用示例
curl -X POST https://codeyy.top/v1beta/models/gemini-pro:generateContent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "contents": [{
      "parts": [{
        "text": "Hello, Gemini! Explain quantum computing."
      }]
    }]
  }'

Python SDK 示例

import google.generativeai as genai

# 使用 codeyy.top 服务
genai.configure(api_key="YOUR_API_KEY", transport='rest')
# 设置自定义端点（如果 SDK 支持）
model = genai.GenerativeModel('gemini-pro')
response = model.generate_content("Explain quantum computing")
print(response.text)

Node.js 示例

const { GoogleGenerativeAI } = require("@google/generative-ai");

// 使用 codeyy.top 服务
const genAI = new GoogleGenerativeAI("YOUR_API_KEY");
// 如果 SDK 支持，可以设置 baseURL 为 https://codeyy.top/v1beta
const model = genAI.getGenerativeModel({ model: "gemini-pro" });

async function run() {
  const result = await model.generateContent("Explain quantum computing");
  const response = await result.response;
  console.log(response.text());
}

run();

支持的模型

通过 codeyy.top 可以使用以下 Gemini 模型：

• gemini-pro - 通用对话和文本生成模型
• gemini-pro-vision - 支持图像输入的多模态模型
• gemini-2.5-flash - 快速响应模型
• gemini-2.5-pro - 高性能模型（支持百万 token 上下文）

常见问题