---
title: "Plan mode、Checkpoint、Headless"
description: "用 Plan mode、checkpoint 和 headless mode 控制 Gemini CLI 的风险、回退和自动化。"
verifiedAt: "2026-05-09"
---

Plan mode（计划模式 🔬，Gemini CLI 当前为实验功能）、checkpoint（检查点）、headless mode（无头 / 脚本模式）分别解决三个问题：**先想清楚、改坏能回退、自动化能调用**。

## Plan mode

Plan mode 适合复杂任务。它让 agent 先产出计划，再进入执行。

适合：

- 多文件改动。
- 需要理解架构。
- 要接外部系统。
- 有并发修改。
- 涉及发布、部署、迁移。

一个好计划应该包含：

- 目标。
- 文件范围。
- 分阶段动作。
- 验证命令。
- 风险和停止条件。

## Checkpoint

Checkpoint 解决“改了一半发现方向错了”的问题。它让你在关键节点保留回退点。

建议在这些节点建 checkpoint：

- 大改前。
- 自动化生成文件前。
- 跑迁移脚本前。
- 进入不熟悉代码路径前。
- 批量替换前。

> [!IMPORTANT]
> checkpoint 不是替代 git 的版本管理。长期项目仍然应该用清晰的 commit 和 branch 管理。

## Headless mode

Headless mode 适合脚本和 CI：

```bash
git diff | gemini -p "Summarize this change"
gemini --output-format json -p "Classify this issue"
```

它适合“一次输入、一次输出”的任务，不适合需要复杂交互确认的高风险任务。

## 三者怎么组合

```text
人工复杂任务    Plan mode -> 分批执行 -> checkpoint -> 验证
批量低风险任务  headless -> JSON 输出 -> 脚本校验 -> 人工抽查
高风险任务      Plan mode -> 人工确认 -> checkpoint -> 最小写入 -> 验证
```

| 控制手段 | 解决的问题 | 不解决的问题 |
| --- | --- | --- |
| Plan mode | 先明确范围、步骤、验证、停止条件 | 不替代人工判断和测试 |
| Checkpoint | 关键节点可回退 | 不替代长期 git 分支和 commit |
| Headless | 非交互式输入输出 | 不适合高风险多轮确认任务 |

## 实用原则

如果任务可能产生不可逆影响，就不要 headless 自动跑。先让 Gemini CLI 输出计划和风险，再由人决定是否执行。

## 典型错误

- 把 Plan mode 当成“慢一点的聊天”，但没有要求影响文件、验证命令和停止条件。
- 把 checkpoint 当成 git 分支，结果长期修改没有 commit 记录。
- 把 headless 用在需要多轮确认的任务，例如批量删除、发布、部署。
- 让 headless 直接写正式文件，没有临时文件、JSON 校验和失败分支。

## 一个可靠流程

复杂改动先进入 Plan mode，只读扫描代码和配置。用户确认后，只执行第一小步，并在关键改动前建立 checkpoint。每一步跑最小验证，失败就停下来回到计划，而不是继续扩大修改。

自动化场景则相反：prompt 固定、输入可控、输出结构化。headless 更适合分类、摘要、生成草稿，不适合让模型在 CI 里自主修复生产问题。

## 验收标准

人工任务看四项：是否有计划，是否有回退点，是否有验证命令，是否有人确认高风险动作。脚本任务看四项：退出码、JSON 解析、空输出处理、配额失败处理。

## 最小落地模板

可以把复杂任务拆成三句话：

```text
先只读分析并给计划，不要改文件。
我确认计划后，只执行第一批文件，并在改前说明验证方式。
每批结束后输出 diff 范围、检查结果和下一批是否继续。
```

这不是模板化提示词，而是控制权设计：先让 Gemini CLI 暴露计划，再让它小步执行，最后用验证结果决定是否继续。

## 何时不用

简单单文件解释不需要 Plan mode；已经有清晰 Git 分支和小 diff 时，checkpoint 不是必须；需要人工多轮确认的任务不要 headless。控制手段要匹配风险，过度上工具会增加排障成本。

商业教程里要写出“什么时候不用”，否则读者会把所有功能都叠上，反而不知道问题出在哪里。

## 组合示例

真实任务可以这样组合：先 Plan mode 只读产出方案；用户批准后做第一批小改；改前建 checkpoint；改后跑最小验证；需要批量重复时，再把稳定部分改成 headless 脚本。顺序反过来就容易失控。

最重要的是每一步都能停。不能停的自动化，不适合处理真实项目。

不可逆动作不要交给 headless 自主执行，包括删除远端资源、发布正式版本、改生产配置和写入账号后台。即使输出是 JSON，也不代表这个动作已经可自动批准。

Checkpoint、Plan 和 headless 都是控制权工具。它们的价值不是显得专业，而是让人知道什么时候批准、什么时候回退、什么时候停止。

## 官方资料

- Plan mode 🔬：[docs/cli/plan-mode.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/plan-mode.md)
- Checkpointing：[docs/cli/checkpointing.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/checkpointing.md)
- Headless mode：[docs/cli/headless.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/headless.md)
- Rewind（回放）：[docs/cli/rewind.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/rewind.md)

## 下一篇

<Cards>
  <Card title="模型、配额和成本" description="控制执行之后，继续看模型、配额、缓存和自动化成本。" href="/docs/gemini-cli/understanding/09-models-quota-cost" />
  <Card title="Plan mode" description="需要查官方 Plan mode 行为时，回到官方 Plan mode 页。" href="/docs/gemini-cli/official/01-cli-workflow/19-plan-mode" />
  <Card title="Headless mode" description="需要脚本化调用和 JSON 输出时，回到 headless mode 页面。" href="/docs/gemini-cli/official/07-integrations-automation/72-headless-mode" />
</Cards>
