# 会话恢复

cmux 会保存你的工作形态，让应用重新启动时能带回相同的窗口、workspace、pane、终端上下文和浏览器状态。

## cmux 会恢复什么

重新启动后，cmux 会恢复应用拥有的布局和元数据：

-   窗口、workspace 和 pane 布局
-   工作目录
-   终端 scrollback，尽力恢复
-   浏览器 URL 和导航历史

cmux 不会 checkpoint 任意实时进程状态。tmux、vim、shell 和未支持的终端应用会作为普通终端重新打开，除非它们有自己的 cmux resume 集成。

## Agent 会话恢复

受支持的 AI coding agent 在 cmux 捕获到 agent 的原生会话 ID 后可以恢复。请在安装 agent CLI 后安装 hooks，确保二进制在 PATH 上：

```
# all integrations cmux can find on PATH
cmux hooks setup

# or one agent at a time
cmux hooks setup antigravity
cmux hooks setup codex
cmux hooks setup grok
cmux hooks setup omp
cmux hooks setup --agent opencode
```

cmux hooks setup 会安装它能找到的所有受支持集成，并打印被跳过 agent 的摘要。只需要一个集成时请指定 agent 名称。

## 自定义 surface resume 命令

高级用户和集成可以把任意终端 surface 绑定到重启命令。cmux 会保存通过公开 CLI 或 socket 创建的绑定，用于检查和手动恢复。

```
cmux surface resume set --kind tmux --checkpoint work --shell "tmux attach -t work"
cmux surface resume show --json
cmux surface resume clear --checkpoint work
```

已批准的前缀可在 Settings > Terminal > Resume Commands 中查看或编辑。cmux 只会自动运行被标记为可信的 resume 绑定，例如从运行中进程检测到的 tmux 绑定或用户批准的前缀。cmux 仍然不会 checkpoint 任意进程内存。 令牌、密码、密钥和 API key 等敏感环境变量键会在保存恢复绑定前被丢弃。 批准项也会绑定到工作目录以及存在时的精确环境变量值。

## 受支持的 agents

| Agent | 二进制 | Resume 命令 | Feed bridge |
| --- | --- | --- | --- |
| Claude Code | `claude` | `claude --resume <id>` | PermissionRequest |
| Codex | `codex` | `codex resume <id>` | PreToolUse, PermissionRequest |
| Grok / Grok Build CLI | `grok` | `grok -r <id>` | PreToolUse |
| OpenCode | `opencode` | `opencode --session <id>` | plugin event bus |
| Pi | `pi` | `pi --session <id>` | 无 |
| OMP | `omp` | `omp --session <id>` | 无 |
| Campfire | `campfire` | `campfire --session <id>` | 无 |
| Amp | `amp` | `amp threads continue <id>` | 无 |
| Cursor CLI | `cursor-agent` | `cursor-agent --resume <id>` | beforeShellExecution |
| Gemini | `gemini` | `gemini --resume <id>` | PreToolUse |
| Antigravity CLI | `agy` | `agy --conversation <id>` | PreToolUse, PostToolUse |
| Rovo Dev | `acli` | `acli rovodev run --restore <id>` | 无 |
| Hermes Agent | `hermes` | `hermes --resume <id>` | pre\_tool\_call, post\_tool\_call, pre\_approval\_request, post\_approval\_response |
| Copilot | `copilot` | `copilot --resume <id>` | PreToolUse |
| CodeBuddy | `codebuddy` | `codebuddy --resume <id>` | PreToolUse |
| Factory | `droid` | `droid --resume <id>` | PreToolUse |
| Qoder | `qodercli` | `qodercli --resume <id>` | PreToolUse |

启用 Claude 集成时，Claude Code 由 cmux Claude wrapper 处理。Antigravity 也接受 agy 作为 setup 别名，Rovo Dev 接受 rovo。

## 手动恢复

cmux 正常启动时会恢复最后保存的 snapshot。你也可以手动重新应用上一个 snapshot：

-   History > Restore Previous App Launch
-   `⌘ ⇧ O`
-   `cmux restore-session`

## 关闭 agent 自动恢复

如需只恢复 pane 而不启动保存的 agent resume 命令，请关闭 Settings > Terminal > Resume Agent Sessions on Reopen 或设置：

~/.config/cmux/cmux.json

```
{
  "terminal": {
    "autoResumeAgentSessions": false
  }
}
```

这只会关闭 agent resume 命令。cmux 仍会恢复布局、工作目录、scrollback 和浏览器历史。

## 工作原理

1.  cmux 会把带版本的 JSON snapshot 写入 ~/Library/Application Support/cmux/session-<bundle-id>.json，并保存一个 previous-session cache 供手动重新打开。
2.  终端 scrollback 会作为有界文本保存，并在恢复时通过临时文件 replay。这是尽力恢复，因为终端应用可以重绘或清屏。
3.  Agent hooks 会写入 ~/.cmuxterm/<agent>-hook-sessions.json，其中包含 agent 会话 ID、cmux workspace ID、surface ID、cwd、可用时的进程 ID，以及经过清理的启动命令。
4.  恢复时，cmux 会先重建窗口和 pane。如果 agent 自动恢复已启用，它会启动一个一次性 shell 命令，用保存的会话 ID 运行 agent 的原生 resume 命令。

常规[配置文档](https://cmux.com/zh-CN/docs/configuration)介绍 cmux.json。会话恢复会把应用布局与 Ghostty 终端渲染设置分开保存。

Canonical: https://cmux.com/zh-CN/docs/session-restore

Documentation index: https://cmux.com/llms.txt