# 工作階段還原

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，確保 binary 位於 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 | Binary | 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-TW/docs/configuration)說明 cmux.json。工作階段還原會將應用程式佈局與 Ghostty 終端機渲染設定分開保存。

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

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