---
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="/docs/gemini-cli/official/01-cli-workflow/19-plan-mode" />
  <Card title="Settings" description="继续看 checkpointing、sandbox、工具权限如何写进 settings.json。" href="/docs/gemini-cli/official/02-context-config/20-settings" />
  <Card title="Sandbox" description="涉及 shell、文件系统和命令执行时，继续看 sandbox 与审批边界。" href="/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)
