---
title: "Gemini CLI 入门"
wiki: cli
category: "终端 Agent 工具"
slug: gemini-cli-overview
url: https://learnagent.wiki/cli/cards/gemini-cli-overview
tags: ["Gemini CLI", "Google", "终端 Agent", "CLI", "入门"]
last_updated: 2026-04-22
reading_time: 12
---

> **Gemini CLI 是 Google 官方推出的开源终端 Agent**，仓库 `google-gemini/gemini-cli`，Apache-2.0 协议，截至 2026-04 的最新版本是 **v0.38.2**（4 月 17 日发布）。它把 Gemini 系列模型直接接进你的命令行，让你在 shell 里像和人对话一样指挥它读代码、改文件、跑命令、查文档。

# Gemini CLI 入门

## 基础概念

**Gemini CLI 是 Google 官方推出的开源终端 Agent**，仓库 `google-gemini/gemini-cli`，Apache-2.0 协议，截至 2026-04 的最新版本是 **v0.38.2**（4 月 17 日发布）。它把 Gemini 系列模型直接接进你的命令行，让你在 shell 里像和人对话一样指挥它读代码、改文件、跑命令、查文档。

它和 [Claude Code](/cli/cards/claude-code-overview)、[Codex CLI](/cli/cards/codex-cli-overview) 属于同一类——**都是模型厂商自己出的"亲儿子"终端 Agent**，但 Gemini CLI 有两张特别打的牌：

- **超大上下文窗口**：默认 **1M tokens**（约等于 30000 行代码或 1500 页文本），单次会话就能把一个中等规模仓库整个塞进去，不用分块也不用 RAG 检索。这是 Claude Code（约 200K）和 Codex CLI（128K-200K）目前都达不到的量级。
- **慷慨的免费额度**：用 Google 个人账号 OAuth 登录，**每天 1000 次模型请求、每分钟约 60 次**，对个人开发者和小项目几乎等同于"白嫖"。

它要解决的痛点很现实：以前想让 AI 帮你看一个 50 万行的 monorepo，要么得切分成几十段喂给模型，要么得搭一套向量检索做 RAG。Gemini CLI 把这件事简化成了"全部塞进上下文，让模型自己读"。

### 核心要素

| 要素 | 说明 |
|------|------|
| **开源协议** | Apache-2.0，仓库公开，社区可贡献、可 fork、可二次封装 |
| **默认模型** | `gemini-2.5-pro` / `gemini-2.5-flash`，可通过 `-m` 切换；2026 年起逐步接入 Gemini 3 系列 |
| **上下文窗口** | 1M tokens，是当前主流终端 Agent 里最大的 |
| **认证方式** | Google 账号 OAuth（推荐）/ Gemini API Key / Vertex AI（企业） |
| **内置工具** | 文件读写、shell 执行、Web 抓取、Google Search grounding、文件夹检索 |
| **扩展机制** | 支持 [MCP](/mcp/cards/what-is-mcp) server、`GEMINI.md` 项目级提示词、自定义 tool |
| **运行模式** | 交互式 REPL + 非交互脚本模式（支持 JSON 输出，方便做 CI 集成） |

### 架构与一次调用流程

```mermaid
sequenceDiagram
    participant User as 你（终端）
    participant CLI as Gemini CLI
    participant Auth as 认证层<br/>(OAuth / API Key / Vertex)
    participant Model as Gemini 模型
    participant Tools as 内置工具<br/>(文件 / Shell / Web)
    participant MCP as MCP Server<br/>(可选)

    User->>CLI: gemini "分析 src/ 下的代码结构"
    CLI->>Auth: 取 token
    CLI->>CLI: 加载 GEMINI.md + 项目上下文
    CLI->>Model: prompt + 工具清单 (含 MCP)
    Model-->>CLI: 决定调 read_file / list_dir
    CLI->>Tools: 执行工具
    Tools-->>CLI: 返回结果
    CLI->>Model: 工具结果 + 继续推理
    Model-->>CLI: 生成最终回答
    CLI-->>User: 展示结果 + 高亮 diff
    Note over CLI,MCP: 若需访问外部系统，<br/>同样按 MCP 协议调用 Server
```

这张图画的是 Gemini CLI 一次完整调用：用户输入 → CLI 加 `GEMINI.md` → 模型判断要不要调工具 → 工具结果回传给模型 → 循环直到模型给出最终答案。整个流程和 Claude Code 几乎一模一样，差别在于**模型和认证后端是 Google 的**。

## 基础用法

### 安装

```bash
# 方式 1：npm 全局安装（最常见）
npm install -g @google/gemini-cli

# 验证
gemini --version
# 预期输出：0.38.2（截至 2026-04）

# 方式 2：用 npx 临时跑（不想全局装时）
npx @google/gemini-cli
```

要求 Node.js 18+。装完后命令名就是 `gemini`。

### 配置认证

第一次跑 `gemini` 会弹出认证选项，选一个即可：

```bash
gemini
# 终端会提示：
#   1. Login with Google (推荐，免费 1000 次/天)
#   2. Use Gemini API Key
#   3. Use Vertex AI

# 选 1 会打开浏览器走 OAuth；选 2 需要先在 AI Studio 拿 key
export GEMINI_API_KEY="your-key-here"
```

API Key 可以在 [Google AI Studio](https://aistudio.google.com/) 一键生成，零成本。如果你公司用 GCP，更推荐走 Vertex AI 路线，权限和审计都接到企业 IAM。

### 最小示例

```bash
# 一次性调用，问完即退
gemini "把 README.md 翻译成中文，保留代码块"

# 交互式 REPL
gemini
> 帮我看看 src/api/users.ts 这个文件有什么潜在 bug
> 加个单元测试覆盖刚才说的边界情况
> /exit

# 指定模型
gemini -m gemini-2.5-flash "总结一下当前目录的项目结构"

# 非交互脚本模式（CI 友好，输出 JSON）
gemini --output-format json "列出 package.json 里所有依赖" > deps.json
```

预期行为：

```text
你：帮我看看 src/api/users.ts 有什么潜在 bug
Gemini：[调用工具：read_file src/api/users.ts]
Gemini：发现三个潜在问题：
  1. 第 42 行 user.id 可能为 undefined，没做空值判断……
  2. ……
```

### 项目级配置：GEMINI.md

在项目根放一个 `GEMINI.md`，Gemini CLI 每次启动都会自动读进上下文，相当于给 Agent 写"项目说明书"：

```markdown
# 这个项目是什么
- 一个 Next.js 14 + TypeScript 的内容站
- 数据流：.publish → scripts/build-content.ts → public/data → 页面

# 编码约定
- 不要在页面组件里直接读 .publish 源文件
- 新增 API 必须配 Vitest 测试
```

这和 Claude Code 的 `CLAUDE.md`、Codex CLI 的 `AGENTS.md` 是一类东西——**都是给终端 Agent 的项目记忆**。

## 同类工具对比

| 维度 | Gemini CLI | [Claude Code](/cli/cards/claude-code-overview) | [Codex CLI](/cli/cards/codex-cli-overview) |
|------|------------|-------------|-----------|
| 背后模型 | Gemini 2.5 Pro / Flash / Gemini 3 | Claude Sonnet/Opus 系列 | GPT-5 系列 |
| 上下文窗口 | **1M tokens（最大）** | ~200K | 128K-200K |
| 免费门槛 | **个人 Google 账号 1000 次/天免费** | 需 Anthropic 订阅或 API 计费 | 开源免费，但 API 调用要付费 |
| 默认权限模型 | 工具白名单 + 显式确认 | 工具白名单 + dangerous 模式 | 默认沙箱执行（容器隔离） |
| 项目级提示词 | `GEMINI.md` | `CLAUDE.md` | `AGENTS.md` |
| 扩展机制 | MCP + 自定义 tool + Google Search grounding | MCP + Skills + Hooks | MCP（较新）+ shell 命令 |
| 开源 | ✅ Apache-2.0 | ⚠️ CLI 部分开源，模型闭源 | ✅ Apache-2.0（Rust 重写） |
| SWE-bench Verified | 约 85-88% | 约 80% | 约 75-80% |
| 最强场景 | 整库通读、长文档处理、Google 生态联动 | 复杂多文件重构、长链推理 | 沙箱内自主执行任务、CI/CD |

**核心区别一句话**：Gemini CLI 的杀手锏是 **大上下文 + 免费额度**，最适合"整库丢给它分析"这种场景；Claude Code 强在多文件推理一致性；Codex CLI 强在沙箱自主执行。这三个不是替代关系，而是按任务挑工具——**预算紧 / 需要读大型 monorepo / 想白嫖 → Gemini CLI 几乎是首选**。

## 常见误区

| 误区 | 准确理解 |
|------|----------|
| 以为 Gemini CLI 只能用 Google 自家模型 | Gemini CLI 确实只接 Gemini 系列，但通过 MCP server 可以让 Gemini 模型反过来调用其他系统（数据库、第三方 API），扩展面并不窄 |
| 以为必须有 GCP 项目和企业账号才能用 | 完全不需要。**用任何一个普通的 Google 账号 OAuth 登录就能跑**，每天 1000 次免费请求，个人开发足够 |
| 以为 1M 上下文 = 可以无脑塞所有代码 | 上下文越大，模型注意力越分散，成本也越高（即使免费额度够，也吃响应速度）。**实际工程里仍要做选择性加载**，1M 是上限不是日常 |
| 把 Gemini CLI 和 Gemini App / AI Studio 当一回事 | Gemini App 是消费者聊天产品；AI Studio 是网页版 prompt playground；Gemini CLI 是终端 Agent，**三者共用模型，但产品形态完全不同** |
| 以为 Gemini CLI 不支持 MCP | 它从早期版本就支持 MCP server 配置，可以挂载任何标准 MCP server，和 Claude Code 接同一份 server 配置基本可以复用 |
| 以为开源等于"自己跑模型" | Gemini CLI 客户端是开源的，**但 Gemini 模型本身不开源**，调用仍然走 Google 云端。要真正本地化得换 Ollama / vLLM 路线 |
| 以为免费额度等于"无限用" | 免费额度按"模型请求数"计，**不是按 token**。一次大上下文调用也只算 1 次请求，但触发限流时会直接 429。生产环境建议接 API key 或 Vertex AI |

## 优劣势分析

| 优势 | 劣势 |
|------|------|
| **1M 上下文窗口领先同行**：整库分析、长文档处理、跨文件追溯不再受 context 限制 | **响应延迟较高**：大 prompt + 大模型，单轮 1-3 秒起步，比本地工具慢 |
| **免费额度最香**：Google 账号 OAuth 即有 1000 次/天 + 60 次/分钟，个人和初创团队几乎零门槛 | **限流逻辑不透明**：免费层在高峰期偶发降级或排队，关键场景仍需付费层兜底 |
| **Apache-2.0 开源**：客户端代码完全开放，可 fork、可二次封装、可审计，企业内部部署没顾虑 | **模型本身仍闭源**：要彻底本地化或离线场景下不可用 |
| **Google 生态原生集成**：Search grounding、Drive、Workspace、Vertex AI 一条龙，企业里比 Claude/OpenAI 更顺 | **生态成熟度还不及 Claude Code**：Skills、第三方插件、社区 MCP 数量上仍少一截 |
| **支持 MCP**：与 [MCP 生态](/mcp/cards/what-is-mcp)无缝接入，已有 MCP server 几乎可以零改造复用 | **国内访问需自行解决网络问题**：Google 服务大陆不可直连，要走代理或 Vertex AI 区域节点 |
| **非交互脚本模式 + JSON 输出**：CI/CD 集成天生友好，GitHub Action 官方现成模板 | **认证种类多容易混乱**：OAuth / API Key / Vertex 三套配额和权限模型不同，新手容易选错 |
| **Plan Mode（2026-03 上线）**：先只读分析、出方案，得到用户确认后才动手写文件，把"AI 把项目改坏"的概率压到最低 | **代码风格与 Claude Code 略有差异**：复杂多文件重构的一致性目前评测仍略逊 Claude |

## 思考题

<details>
<summary>初级：什么样的任务最适合用 Gemini CLI 而不是 Claude Code 或 Codex CLI？</summary>

**参考答案：**

挑选维度看三件事：**上下文规模、预算、是否需要 Google 生态联动**。

最适合 Gemini CLI 的典型任务：

1. **整库代码审查 / 架构梳理**：把一个 30k 行的 monorepo 一次性塞进上下文，让它出"全局视角"的总结。Claude Code 200K 上下文做不到，Codex CLI 也吃力。
2. **大文档处理**：一份 800 页的 PDF 标准、一本协议文档，1M 窗口能整本喂进去做问答和总结。
3. **预算敏感的个人项目 / 学习场景**：每天 1000 次免费请求，个人玩 side project 完全够用，零成本起步。
4. **强依赖 Google Search 的实时信息**：内置 Search grounding，对"调研最新版本特性""验证某个 API 是否还存在"这类任务比离线模型可靠。
5. **GCP/Workspace 内部团队**：认证、审计、权限直接走 Vertex AI 和企业 IAM，比再接一套 Anthropic / OpenAI 体系省事。

反过来，**复杂多文件重构、需要稳定一致的代码风格、长链推理深度**这些场景，目前 Claude Code 仍然更稳；**沙箱内全自主执行**则 Codex CLI 更强。工具选型不是"哪个最好"，而是"任务匹配哪个"。

</details>

<details>
<summary>中级：Gemini CLI 给的 1M 上下文是不是越大越好？工程上怎么用才不浪费？</summary>

**参考答案：**

**不是越大越好**，1M 上下文窗口在实际工程里有三个隐藏成本：

1. **注意力衰减**：所有大模型都有"中间塌陷"问题（lost in the middle）——把内容堆到 800K 时，中段信息的召回率明显下降。研究和实测都显示 Gemini 也不例外。
2. **响应延迟**：prompt 越长，首字延迟越高。把 500K tokens 塞进去，单轮响应可能要 5-10 秒，对交互体验是硬伤。
3. **限流压力**：虽然按"请求数"计，但服务端对超大 prompt 会有额外节流和排队，免费层尤其明显。

工程上的合理用法：

- **分阶段加载**：先用一个 small prompt 让 Gemini 给出"我需要看哪些文件"的清单，再用第二轮 prompt 只把这些文件塞进去，节省 token + 提升注意力质量。
- **GEMINI.md 做静态背景**：把项目说明、约定、关键架构图放进 `GEMINI.md`，让模型每次都自动加载固定的"大背景"，正文 prompt 只放变化部分。
- **配合 MCP / 自定义 tool 做按需检索**：让模型自己决定调 `read_file` / `grep` 而不是预先把所有文件喂进去，这是 [Agent + Tool Use](/agent/cards/tool-use) 的标准做法。
- **1M 留给"真的需要"的场景**：例如分析一份完整的标准文档、做整库的 cross-file 追溯。日常 70% 的开发任务，几万 token 就够了。

一句话：**1M 是后备的"安全网"，不是日常的"默认配额"**。把它当上限来用，而不是当目标来用。

</details>

## 参考资料

1. Gemini CLI 官方仓库：<https://github.com/google-gemini/gemini-cli> (查询日期: 2026-04-22)
2. Gemini CLI 配额与定价文档：<https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/quota-and-pricing.md> (查询日期: 2026-04-22)
3. Gemini API 速率限制：<https://ai.google.dev/gemini-api/docs/rate-limits> (查询日期: 2026-04-22)
4. Google AI Studio（API Key 申请入口）：<https://aistudio.google.com/> (查询日期: 2026-04-22)
5. 官方文档站：<https://google-gemini.github.io/gemini-cli/> (查询日期: 2026-04-22)
6. 2026 年终端 Agent 横评（DataCamp）：<https://www.datacamp.com/blog/gemini-cli-vs-claude-code> (查询日期: 2026-04-22)
7. 三大终端 Agent 实测对比（IntuitionLabs）：<https://intuitionlabs.ai/articles/claude-code-vs-codex-vs-gemini-cli-comparison> (查询日期: 2026-04-22)

---
*Source: https://learnagent.wiki/cli/cards/gemini-cli-overview*
*Markdown mirror of https://learnagent.wiki, served as text/markdown for LLM ingestion.*