---
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]
> **這組文章不重複官方手冊**。要查某個命令、配置項或官方引數，去 [官方教程中文版](/zh-Hant/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="/zh-Hant/docs/gemini-cli/understanding/02-install-auth-first-run" />
  <Card title="再控制邊界" description="理解工具、Shell、許可權、Plan mode 和 checkpoint，再讓它修改真實專案。" href="/zh-Hant/docs/gemini-cli/understanding/05-tools-shell-permissions" />
  <Card title="最後做選擇" description="和 Codex CLI、Claude Code、OpenCode 對比，決定它在你的工作流裡負責哪一塊。" href="/zh-Hant/docs/gemini-cli/understanding/11-gemini-cli-vs-codex-claude-opencode" />
</Cards>

## 推薦閱讀順序

1. [Gemini CLI 是什麼](/zh-Hant/docs/gemini-cli/understanding/01-what-is-gemini-cli)：先建立定位，避免把它當成普通聊天框。
2. [安裝、認證和第一次啟動](/zh-Hant/docs/gemini-cli/understanding/02-install-auth-first-run)：跑通 OAuth、API Key 或 Vertex AI 中最適合你的入口。
3. [Gemini CLI 怎麼完成一個任務](/zh-Hant/docs/gemini-cli/understanding/03-how-gemini-cli-works)：理解 ReAct loop、工具呼叫和持續觀察。
4. [GEMINI.md、記憶和專案上下文](/zh-Hant/docs/gemini-cli/understanding/04-project-context-gemini-md)：把一次性說明變成專案長期上下文。
5. [工具、Shell 和許可權邊界](/zh-Hant/docs/gemini-cli/understanding/05-tools-shell-permissions)：知道什麼時候讓它執行，什麼時候只讓它規劃。
6. [MCP 和 Extensions](/zh-Hant/docs/gemini-cli/understanding/06-mcp-extensions)：把 Gemini CLI 接到外部系統。
7. [Skills、Subagents、Hooks](/zh-Hant/docs/gemini-cli/understanding/07-skills-subagents-hooks)：把專門能力、分工和自動化分層。
8. [Plan mode、Checkpoint、Headless](/zh-Hant/docs/gemini-cli/understanding/08-plan-checkpoint-headless)：用控制機制降低改壞專案的風險。
9. [模型、配額和成本](/zh-Hant/docs/gemini-cli/understanding/09-models-quota-cost)：理解免費層、API Key、Vertex AI、模型路由和 token caching。
10. [Code Assist、Cloud 和 GitHub Action](/zh-Hant/docs/gemini-cli/understanding/10-code-assist-cloud-github)：理解 Google 生態裡的位置。
11. [Gemini CLI vs Codex CLI vs Claude Code vs OpenCode](/zh-Hant/docs/gemini-cli/understanding/11-gemini-cli-vs-codex-claude-opencode)：做工具選型。
12. [真實專案貫穿實戰](/zh-Hant/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 官方教程中文版](/zh-Hant/docs/gemini-cli/official)
- [入門](/zh-Hant/docs/gemini-cli/official/00-getting-started)
- [CLI 工作流](/zh-Hant/docs/gemini-cli/official/01-cli-workflow)
- [上下文與配置](/zh-Hant/docs/gemini-cli/official/02-context-config)
- [工具與 MCP](/zh-Hant/docs/gemini-cli/official/03-tools-mcp)
- [Agents & Skills](/zh-Hant/docs/gemini-cli/official/04-agents-skills)
- [安全與企業](/zh-Hant/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 是什麼](/zh-Hant/docs/gemini-cli/understanding/01-what-is-gemini-cli)。這一篇會先拆清楚 Gemini CLI 為什麼不是“又一個命令列聊天框”，以及它和 Gemini Code Assist 的關係。
