---
title: "Quickstart"
description: "Gemini CLI 第一次使用流程：安装、认证、启动、只读解释项目、处理文件、运行测试和查看配额。"
verifiedAt: "2026-05-09"
---

第一次使用 Gemini CLI，不要直接让它重构项目。官方 quickstart 会带你安装、认证、配置和发起提示词；真实项目里更稳的顺序是：先只读理解，再让它提出计划，再限定一个文件写入，最后用测试或 diff 验收。

> [!IMPORTANT]
> **第一次任务只读**：先让 Gemini CLI 解释项目结构。确认它能读对目录、理解对目标、说清不确定性，再给写权限。

## 1. 最小启动流程

```bash
npm install -g @google/gemini-cli
gemini
```

启动后完成认证，然后进入一个低风险 Git 仓库或练习目录。第一条提示词不要要求改文件：

```text
请只读分析这个项目，不要修改任何文件。
输出：
1. 主要目录和入口文件。
2. 你会优先阅读的 5 个文件。
3. 这个项目最可能的测试命令。
4. 你现在还不确定的问题。
```

这条提示词同时验证三件事：Gemini CLI 能不能看到项目、能不能区分事实和推测、能不能遵守“不要修改文件”。

## 2. 第一条安全闭环

```mermaid
flowchart TD
    A["启动 gemini"] --> B["只读解释项目结构"]
    B --> C["指定一个小文件让它解释"]
    C --> D["让它提出修改计划"]
    D --> E["确认后只改一个文件"]
    E --> F["运行测试或检查命令"]

    style B fill:#dcfce7,stroke:#22c55e
    style D fill:#fef3c7,stroke:#f59e0b
    style E fill:#fee2e2,stroke:#ef4444
```

第一条闭环合格，不是看回答有多长，而是看它有没有做到：

- 没有写文件。
- 能指出真实文件和目录。
- 能说出不确定的地方。
- 能给出下一步计划，而不是直接动手。

## 3. 官方示例能说明什么

官方示例覆盖了几类典型任务：

- 根据图片内容重命名照片。
- clone 并解释一个远程代码仓库。
- 合并两个 CSV。
- 为登录页面写单元测试。

这些例子说明 Gemini CLI 不只会写代码。它能结合文件、命令、Web、模型能力做本地任务。但进入自己的项目时，要把范围收小。

## 4. 第二轮才允许小范围写入

只读任务跑通后，**先用 `/init` 让 Gemini CLI 自动生成首份 `GEMINI.md`** ——它会扫描你的项目结构和检查命令，写一份初稿放在项目根目录。这一步不算"修改源代码"，只是给 AI 一份长期上下文规则文件，后续你和 AI 沟通项目惯例就不用每次复述。

```text
/init
```

生成后打开 `GEMINI.md` 检查一遍，补三件人类才知道的规则：哪些文件禁止触碰、提交时跑哪些验证命令、团队协作边界。详见 [GEMINI.md 篇](/docs/gemini-cli/official/02-context-config/21-gemini-md)。

然后再选一个低风险文件做写入，例如 README、测试说明、注释或一个小 bug 的测试用例。

```text
只修改 README.md 的安装部分，把命令整理成 npm 和 Homebrew 两种路径。
不要修改其他文件。
改完后先解释 diff，再告诉我建议运行什么检查命令。
```

写入后立刻检查：

```bash
git diff --stat
git diff
```

如果 Gemini CLI 修改了未指定文件，先停下来，不要继续加新需求。回到提示词、权限、工作目录和上下文边界排查。

## 5. 第一次不要做什么

- 不要让它“优化整个项目”。
- 不要让它直接处理密钥、账单、账号、生产数据。
- 不要一开始就接 MCP 写操作。
- 不要用 `--approval-mode=yolo` 处理真实项目。
- 不要在没看 diff 的情况下接受大范围修改。

> [!WARNING]
> **`--approval-mode=yolo` 不适合新手第一天**：它会降低人工确认门槛。真实项目先用可审查、可撤销、范围明确的任务证明 CLI 行为稳定，再考虑自动化。

## 6. 查用量

官方文档说明可以用：

```text
/stats model
```

查看当前 session 的 token 用量、quota 信息和模型相关限制。

不要把 `/stats model` 当成永久配额真相源。不同账号、认证方式、Gemini Code Assist edition、API key、Vertex AI project 都可能影响可用额度。需要费用和 quota 决策时，回到官方 quota and pricing 页面。

第一次成功跑通后，把安装方式、认证方式和测试目录记录下来。后续教程截图如果和读者不同，最常见原因就是这三项不同。

## 7. 接下来去哪

<Cards>
  <Card title="Cloud Shell 入口" description="想免本机安装或快速靠近 Google Cloud 项目，继续看 Cloud Shell 边界。" href="/docs/gemini-cli/official/00-getting-started/04-cloud-shell" />
  <Card title="CLI 工作流" description="本机已经跑通后，进入 slash commands、shell、文件、history 和 checkpoint。" href="/docs/gemini-cli/official/01-cli-workflow" />
  <Card title="工具总览" description="准备让 Gemini CLI 读写文件、跑 shell 或接 MCP 前，先看工具权限边界。" href="/docs/gemini-cli/official/03-tools-mcp/30-tools-overview" />
</Cards>

## 官方来源

- [Gemini CLI Get Started](https://google-gemini.github.io/gemini-cli/docs/get-started/)
- [Gemini CLI Examples](https://google-gemini.github.io/gemini-cli/docs/get-started/examples.html)
- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
