---
title: "Checkpoint 與 rewind"
description: "Gemini CLI checkpointing、/restore、rewind 的作用：修改前儲存狀態、恢復檔案、恢復會話和降低實驗風險。"
verifiedAt: "2026-05-09"
---

Checkpointing 會在 AI 工具修改檔案前自動儲存專案狀態。官方文件說明：它會建立一個 shadow Git repository 快照，並儲存 conversation history 和即將執行的 tool call。

> [!NOTE]
> **價值**：checkpoint 讓你敢做實驗，但不能替代 Git commit、程式碼審查和測試。

## 工作方式

當你批准 `write_file`、`replace` 等會修改檔案系統的工具時，Gemini CLI 可以建立 checkpoint：

- 在 `~/.gemini/history/<project_hash>` 的 shadow Git repo 中儲存專案檔案快照。
- 儲存當前對話歷史。
- 儲存即將執行的工具呼叫。

恢復 checkpoint 會：

- 把專案檔案恢復到快照狀態。
- 恢復對話歷史。
- 重新提出原始工具呼叫。

```mermaid
flowchart LR
    Approve["批准寫入工具"] --> Snapshot["建立 checkpoint"]
    Snapshot --> Change["執行檔案修改"]
    Change --> Review{"結果可接受?"}
    Review -->|是| Test["跑測試並繼續"]
    Review -->|否| Restore["/restore 回到快照"]
    Restore --> Replan["重新審查計劃"]

    style Snapshot fill:#dbeafe,stroke:#3b82f6
    style Restore fill:#fee2e2,stroke:#ef4444
    style Test fill:#dcfce7,stroke:#22c55e
```

## 啟用 checkpointing

官方文件說明 checkpointing 預設關閉，需要在 `settings.json` 中啟用：

```json
{
  "general": {
    "checkpointing": {
      "enabled": true
    }
  }
}
```

> [!CAUTION]
> 官方文件註明 `--checkpointing` CLI flag 已在 `0.11.0` 移除，現在透過 settings 配置。

## 使用 /restore

檢視可恢復 checkpoint：

```text
/restore
```

恢復指定 checkpoint：

```text
/restore <checkpoint_file>
```

## rewind 的使用邊界

rewind 適合回退和重放 session；checkpoint 更偏“檔案修改前狀態”。兩者都降低風險，但不能替代清晰任務邊界。

可以這樣區分：

| 機制 | 解決什麼 | 不能替代什麼 |
| --- | --- | --- |
| Session resume | 繼續舊對話 | 當前檔案狀態檢查 |
| `/chat save` | 給會話打標籤 | Git commit |
| Checkpoint | 修改前恢復點 | 長期版本管理 |
| `/restore` | 恢復 checkpoint | 程式碼審查和測試 |
| Git branch / commit | 專案級版本記錄 | Agent 會話上下文 |

如果任務會跨天、跨分支、跨 agent，應該用 Git 管理長期狀態，用 checkpoint 管理單次 AI 寫入風險。不要把 checkpoint 當成“可以隨便改”的許可證。

## 推薦策略

- 大改前手動確認 Git 工作區。
- 開 checkpoint。
- 每次只授權小步修改。
- 跑測試。
- 確認無誤後再正常 Git commit。

## 恢復演練

第一次在真實專案裡使用 checkpoint 前，建議先用臨時檔案做一次演練：

1. 開啟 checkpointing。
2. 讓 Gemini CLI 修改一個低風險測試檔案。
3. 用 `/restore` 檢視可恢復項。
4. 恢復到修改前狀態。
5. 用 `git diff` 確認檔案確實回來了。

這個演練能確認三個關鍵點：配置是否生效、恢復路徑是否理解、恢復後是否還需要重新給出工具批准。真正遇到誤改時再摸索恢復流程，成本會更高。

## 失敗邊界

checkpoint 不應該承擔這些職責：

- 不用它儲存金鑰、資料庫、遠端服務狀態。
- 不用它替代資料庫 migration 回復。
- 不用它恢復已經推送、部署或釋出到外部系統的結果。
- 不用它覆蓋其他 agent 或使用者剛剛改過的檔案。

涉及外部副作用時，恢復檔案不等於恢復系統。雲資源、CI 釋出、資料庫寫入、賬號後臺操作，都需要單獨的回復方案。

## 接下來去哪

<Cards>
  <Card title="Plan mode" description="高風險修改前先只讀規劃，減少進入恢復流程的機率。" href="/zh-Hant/docs/gemini-cli/official/01-cli-workflow/19-plan-mode" />
  <Card title="Settings" description="繼續看 checkpointing、sandbox、工具許可權如何寫進 settings.json。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/20-settings" />
  <Card title="Sandbox" description="涉及 shell、檔案系統和命令執行時，繼續看 sandbox 與審批邊界。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
</Cards>

## 官方來源

- [Google Developers Gemini CLI](https://developers.google.com/gemini-code-assist/docs/gemini-cli?hl=zh-cn)
- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
