---
title: "Gemini CLI 从原理到实战"
description: "从定位、终端任务循环、项目上下文、工具权限、MCP、Skills、模型配额、Code Assist 和真实项目实战理解 Gemini CLI。"
verifiedAt: "2026-05-09"
---

Gemini CLI 的难点不在安装。真正容易混乱的是：它既是终端 AI agent，又和 Gemini Code Assist（Google 的 IDE/CLI 编程助手产品线）、Google Cloud、Gemini API Key、Vertex AI（Google Cloud 模型托管平台）、MCP（Model Context Protocol，模型上下文协议）、GitHub Action、Skills、Subagents、Hooks 发生关系。

这一组文章只解决一个问题：**怎样把 Gemini CLI 理解成一套可以进入真实项目的 Google 系 AI 编程工作流**。读完以后，你应该能判断它适合什么任务、怎么给上下文、什么时候让它执行、什么时候只让它规划，以及它和 Codex、Claude Code、OpenCode 的差异。

> [!NOTE]
> **这组文章不重复官方手册**。要查某个命令、配置项或官方参数，去 [官方教程中文版](/docs/gemini-cli/official)；要理解功能背后的使用判断，读这里。

## 12 篇文章的主线

```mermaid
flowchart TD
    A["01 定位：Gemini CLI 是什么"] --> B["02 起步：安装、认证、第一次运行"]
    B --> C["03 循环：它怎么完成任务"]
    C --> D["04 上下文：GEMINI.md 与记忆"]
    D --> E["05 执行：工具、Shell、权限"]
    E --> F["06 扩展：MCP 与 Extensions"]
    F --> G["07 角色：Skills、Subagents、Hooks"]
    G --> H["08 控制：Plan、Checkpoint、Headless"]
    H --> I["09 成本：模型、配额、缓存"]
    I --> J["10 生态：Code Assist、Cloud、GitHub"]
    J --> K["11 选择：和 Codex / Claude / OpenCode 对比"]
    K --> L["12 实战：真实项目贯穿"]

    style A fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style E fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style K fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style L fill:#fee2e2,stroke:#ef4444,stroke-width:2px
```

前四篇解决“它是什么、怎么跑、怎么理解任务循环和上下文”。第五到第八篇解决“怎么让它受控地执行和扩展”。第九到第十二篇解决“成本、生态、选型和真实项目落地”。

<Cards>
  <Card title="先跑起来" description="安装、认证、第一次启动，先让 Gemini CLI 完成一轮低风险只读任务。" href="/docs/gemini-cli/understanding/02-install-auth-first-run" />
  <Card title="再控制边界" description="理解工具、Shell、权限、Plan mode 和 checkpoint，再让它修改真实项目。" href="/docs/gemini-cli/understanding/05-tools-shell-permissions" />
  <Card title="最后做选择" description="和 Codex CLI、Claude Code、OpenCode 对比，决定它在你的工作流里负责哪一块。" href="/docs/gemini-cli/understanding/11-gemini-cli-vs-codex-claude-opencode" />
</Cards>

## 推荐阅读顺序

1. [Gemini CLI 是什么](/docs/gemini-cli/understanding/01-what-is-gemini-cli)：先建立定位，避免把它当成普通聊天框。
2. [安装、认证和第一次启动](/docs/gemini-cli/understanding/02-install-auth-first-run)：跑通 OAuth、API Key 或 Vertex AI 中最适合你的入口。
3. [Gemini CLI 怎么完成一个任务](/docs/gemini-cli/understanding/03-how-gemini-cli-works)：理解 ReAct loop、工具调用和持续观察。
4. [GEMINI.md、记忆和项目上下文](/docs/gemini-cli/understanding/04-project-context-gemini-md)：把一次性说明变成项目长期上下文。
5. [工具、Shell 和权限边界](/docs/gemini-cli/understanding/05-tools-shell-permissions)：知道什么时候让它执行，什么时候只让它规划。
6. [MCP 和 Extensions](/docs/gemini-cli/understanding/06-mcp-extensions)：把 Gemini CLI 接到外部系统。
7. [Skills、Subagents、Hooks](/docs/gemini-cli/understanding/07-skills-subagents-hooks)：把专门能力、分工和自动化分层。
8. [Plan mode、Checkpoint、Headless](/docs/gemini-cli/understanding/08-plan-checkpoint-headless)：用控制机制降低改坏项目的风险。
9. [模型、配额和成本](/docs/gemini-cli/understanding/09-models-quota-cost)：理解免费层、API Key、Vertex AI、模型路由和 token caching。
10. [Code Assist、Cloud 和 GitHub Action](/docs/gemini-cli/understanding/10-code-assist-cloud-github)：理解 Google 生态里的位置。
11. [Gemini CLI vs Codex CLI vs Claude Code vs OpenCode](/docs/gemini-cli/understanding/11-gemini-cli-vs-codex-claude-opencode)：做工具选型。
12. [真实项目贯穿实战](/docs/gemini-cli/understanding/12-real-project-walkthrough)：把前 11 篇串起来。

## 三个学习阶段

| 阶段 | 先解决的问题 | 过关标准 |
| --- | --- | --- |
| 上手 | Gemini CLI 能不能在我的项目里工作 | 能安装、认证、启动，并让它只读解释项目结构 |
| 受控 | 怎么让它安全地读、写、跑命令 | 能区分工具、权限、sandbox、plan、checkpoint 和人工确认边界 |
| 融合 | 怎么放进长期工作流和团队流程 | 能接 MCP、Skills、Hooks、GitHub Action，并知道何时不用它 |

> [!IMPORTANT]
> **别急着追高级功能**：MCP、Skills、Subagents、Hooks 和 GitHub Action 都有用，但它们应该建立在一个稳定的低风险起步流程上。第一轮任务如果连“只读解释项目结构”都没跑稳，就不要先接复杂自动化。

## 官方资料与教程分工

官方教程中文版按功能分类，适合查命令、配置、参数和入口：

- [Gemini CLI 官方教程中文版](/docs/gemini-cli/official)
- [入门](/docs/gemini-cli/official/00-getting-started)
- [CLI 工作流](/docs/gemini-cli/official/01-cli-workflow)
- [上下文与配置](/docs/gemini-cli/official/02-context-config)
- [工具与 MCP](/docs/gemini-cli/official/03-tools-mcp)
- [Agents & Skills](/docs/gemini-cli/official/04-agents-skills)
- [安全与企业](/docs/gemini-cli/official/06-security-enterprise)

从原理到实战不重复官方手册，而是把这些能力串成使用判断：

- **功能是什么**：只保留足够理解的定义，不堆参数。
- **为什么要用**：解释它解决的真实开发问题。
- **怎么上手**：给一个低风险最小动作。
- **常见坑**：指出新手最容易误用的地方。
- **下一步**：把当前文章接到前后篇和官方页。

## 先记住一张分层图

```text
入口层      Terminal CLI / Cloud Shell / VS Code agent mode / GitHub Action
身份层      Google OAuth / Gemini API Key / Vertex AI / Code Assist license
上下文层    GEMINI.md / settings.json / memory / .geminiignore
执行层      file system / shell / web fetch / web search / todos / planning
扩展层      MCP / Extensions / Skills / Subagents / Hooks
治理层      trusted folders / sandbox / policy engine / telemetry / enterprise controls
```

如果你只想快速使用，先掌握入口层、身份层、上下文层和执行层。如果要进团队和自动化，再进入扩展层和治理层。

## 下一篇

从定位开始：[Gemini CLI 是什么](/docs/gemini-cli/understanding/01-what-is-gemini-cli)。这一篇会先拆清楚 Gemini CLI 为什么不是“又一个命令行聊天框”，以及它和 Gemini Code Assist 的关系。
