---
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="/zh-Hant/docs/gemini-cli/understanding/09-models-quota-cost" />
  <Card title="Plan mode" description="需要查官方 Plan mode 行為時，回到官方 Plan mode 頁。" href="/zh-Hant/docs/gemini-cli/official/01-cli-workflow/19-plan-mode" />
  <Card title="Headless mode" description="需要指令碼化呼叫和 JSON 輸出時，回到 headless mode 頁面。" href="/zh-Hant/docs/gemini-cli/official/07-integrations-automation/72-headless-mode" />
</Cards>
