Skip to main content
工作階段是與專案目錄相關聯的已儲存對話。Claude Code 在您工作時將其儲存在本地，因此您可以從中斷的地方繼續、分支以嘗試不同的方法，或在任務之間切換。 桌面應用程式、claude.ai/code 和 VS Code 擴充功能各自維護自己的 session 歷史記錄，桌面應用程式也可以恢復 CLI session。本頁涵蓋 CLI。

​
恢復工作階段

工作階段在您工作時會持續儲存到本機逐字稿檔案，因此您可以在退出或執行 /clear 後返回其中一個工作階段。請使用這些進入點：

​
恢復執行中的背景工作階段

當您使用 claude --resume 或 /resume 恢復的對話屬於仍在執行的背景工作階段時，Claude Code 會開啟該執行中的工作階段本身。在命令列上使用 --bg 時，恢復則改為背景分派。在 v2.1.285 之前，Claude Code 會拒絕並告訴您使用 claude attach <id> 開啟該工作階段，或先使用 claude stop <id> 停止它。
  • 從您的 shell：claude --resume <session> 會在同一個終端機中對該工作階段執行 claude attach，而不是自行載入逐字稿。您在命令列上傳遞的提示詞，例如 claude --resume <session> "check the tests too"，會先作為該工作階段的下一個回合送出，Claude Code 會在附加之前列印 Sent your prompt to the background session (<id>); opening it…。在終端機中輸入的 claude -p --resume <session> "prompt" 也會執行相同操作，因此 -p 不會讓該次執行保持非互動式。 當命令列具有以下任何一項時，Claude Code 不會開啟該工作階段：
    • 經由管道傳送或重新導向的輸入或輸出
    • 設定工作階段的旗標，例如 --permission-mode、--model 或 --settings
    • 讀取輸出的旗標，例如 --output-format json 或 --json-schema
    • 限制或倒轉執行的旗標，例如 --max-turns 或 --max-budget-usd
    具有其中任何一項，或當 agent 檢視已關閉時，Claude Code 不會傳送任何內容，並以狀態 1 退出，列印該工作階段正在背景執行，以及用來開啟它的 claude attach <id> 命令；若無法判定 ID，則會告訴您在 claude agents 中尋找它。新增 --fork-session 可改為恢復該對話的副本。若要在您自己的工作階段中繼續對話本身並套用您的旗標，請執行 claude stop <id>，然後重複該命令。 以 / 或 ! 開頭的提示詞不會被傳送，而當工作階段正在等待您回答問題時，任何提示詞也都不會被傳送。在這兩種情況下，Claude Code 都不會開啟該工作階段，訊息會包含 Your prompt was not sent to it 以及原因。
  • 從工作階段內：/resume 會將您目前的對話移到背景，並將此終端機附加到執行中的工作階段，列印 Opening "<title>", running in the background (<id>)。在空白提示詞上按 ← 即可返回 agent 檢視，其中也會列出您離開的對話。當目前的對話無法移到背景時（例如因為您已附加到背景工作階段，或工作階段持久化已關閉），/resume 會改為列印要執行的 claude attach 命令。

​
恢復的工作階段會復原什麼

當 Claude Code 從逐字稿載入對話時，恢復的工作階段會復原該對話以及其中儲存的狀態：
  • 對話記錄：完整的記錄，包括工具呼叫和結果。在前一個程序結束時（例如當機時）仍在執行的工具，在您恢復時不會完成或再次執行。Claude 會看到該呼叫被標記為在結果記錄之前就被中斷，並被告知在再次執行之前先檢查它是否已生效，除非設定了 CLAUDE_CODE_RESUME_INTERRUPTED_TURN。
  • 模型：工作階段會繼續使用其原本使用的模型，但設定您的模型中所述的情況除外。
  • Agent：使用 --agent 或 agent 設定啟動的工作階段會繼續作為該 agent 運作，並保留其工具限制和模型。恢復時傳遞 --agent 可選擇不同的 agent；關於任一情況下的系統提示詞，請參閱恢復對話中的系統提示詞旗標。Claude Code 會在兩個地方尋找該 agent：工作階段的原始目錄（前提是您已信任該工作區），然後是您進行恢復的目錄，因此當您從另一個目錄恢復時，專案範圍的 agent 仍會載入。如果 Claude Code 在這兩個地方都找不到該 agent，工作階段會以預設工具恢復，並顯示指出該 agent 名稱的警告。
  • 權限模式：如果您在終端機中使用 claude --continue、claude --resume <session-id> 或 claude --resume <name>（當名稱符合單一工作階段時）且不帶 -p 恢復，Claude Code 會復原工作階段當時的權限模式，但恢復時的權限模式中的情況除外，該節也涵蓋工作階段選擇器、/resume 以及使用 claude -p 恢復。傳遞 --permission-mode 或 --dangerously-skip-permissions 可覆寫復原的模式。
  • 進行中的目標：工作階段結束時仍在進行中的目標會延續；其回合計數、計時器和 token 花費基準會重設。
  • 排程任務：尚未過期的任務會被復原。背景 Bash 和監視任務則不會。
  • 背景工作：隨著前一個程序結束的背景 subagent、背景 Bash 命令或工作流程，會在恢復的逐字稿中顯示為未完成的註記。Claude Code 不會因這些註記而開始一個回合；Claude 會在您的下一個提示詞時一併讀取它們。
並非原始啟動時的每個設定旗標都會被復原。如果工作階段依賴 --mcp-config、--settings、--plugin-dir、--fallback-model 或使用 --add-dir 新增的目錄，請在恢復時再次傳遞它們；在工作階段中途使用 /add-dir 新增的目錄也不會被復原，但工作階段選擇器仍會使用它們來定位工作階段。標準設定檔（例如 settings.json 和 settings.local.json）會在啟動時重新讀取，因此存放在其中的設定不需要再次傳遞。關於 --system-prompt 和 --append-system-prompt，請參閱恢復對話中的系統提示詞旗標。

​
恢復時的權限模式

Claude Code 以哪種權限模式啟動恢復的工作階段，取決於您的恢復方式。以下情況適用於 Claude Code 從逐字稿載入對話時；當您改為開啟仍在執行的背景工作階段時，該工作階段會保持其目前的權限模式。
  • 終端機：claude --continue、claude --resume <session-id> 或 claude --resume <name>（當名稱符合單一工作階段時），且不帶 -p。Claude Code 會復原工作階段當時的權限模式，但表格中的情況除外。傳遞 --permission-mode 或 --dangerously-skip-permissions 可覆寫復原的模式。
  • 非互動式：claude -p --resume 或 claude -p --continue。Claude Code 會以新的 claude -p 執行會採用的權限模式啟動該次執行，但以 plan mode 結束的工作階段在下列條件下會以 plan mode 恢復。
  • VS Code：擴充功能的對話面板。表格僅涵蓋以 plan mode 結束的對話；其餘情況請參閱恢復過去的對話。
  • 啟動時的工作階段選擇器：您從工作階段選擇器選擇的工作階段，無論您是單獨使用 claude --resume、使用 claude --from-pr，還是使用符合多個工作階段的名稱來開啟選擇器。Claude Code 會以從相同命令列啟動新工作階段時的權限模式啟動該工作階段，但以 plan mode 結束的工作階段會在 plan mode 中恢復。如果您傳遞 --permission-mode、--dangerously-skip-permissions 或 --fork-session，Claude Code 不會復原 plan mode。不會復原其他已儲存的權限模式。
  • 在工作階段內使用 /resume，帶或不帶引數：您切換到的對話會以您目前工作階段所在的權限模式繼續，但以 plan mode 結束的對話會在 plan mode 中恢復，即使您是以 --permission-mode 或 --dangerously-skip-permissions 啟動 Claude Code。如果該對話在本次 Claude Code 執行中稍早已開啟過，例如您一開始所在的對話，或您以 /clear 或 /resume 離開的對話，它則會改為以您目前的權限模式繼續。
如果拒絕規則移除了 ExitPlanMode 工具，Claude 就無法呈現計畫以供核准，因此 Claude Code 不會復原 plan mode。工作階段會以從相同命令列啟動新工作階段時的權限模式啟動。使用 /resume 時，對話會以您目前的權限模式繼續。 在非互動式和 VS Code 路徑上復原 plan mode 需要 Claude Code v2.1.246 或更新版本。每一列列出工作階段結束時的權限模式、您透過終端機、非互動式和 VS Code 中的哪一種路徑恢復它，以及 Claude Code 啟動恢復之工作階段時採用的權限模式。 claude -p --resume 或 claude -p --continue 執行只有在下列所有條件都成立時，才會以 plan mode 恢復：

​
工作階段選擇器的查找範圍

Claude Code 會依專案目錄儲存工作階段。根據預設，工作階段選擇器會顯示：
  • 來自目前 worktree 的工作階段，包括背景工作階段，它們在清單中會標記為 bg
  • 在其他地方啟動並使用 /add-dir 新增目前目錄的工作階段
使用 Ctrl+W 可將範圍擴大到儲存庫的所有 worktree，或使用 Ctrl+A 擴大到此機器上的每個專案。

​
/loop、-p、Agent SDK 和背景工作階段

第一個提示詞是 /loop 命令的工作階段不會出現在選擇器中，claude --continue 也會跳過它們。在對話稍後才執行 /loop 不會隱藏該工作階段。 Claude Code 會將使用 claude -p 或 Agent SDK 建立的工作階段排除在工作階段選擇器和 claude --continue 之外。您仍然可以將其工作階段 ID 傳遞給 claude --resume <session-id> 來恢復它。當您執行 claude -p --continue 時，Claude Code 會包含 -p、SDK 和 /loop 工作階段。 claude --continue 會開啟已完成的背景工作階段，但不會開啟仍在執行的工作階段；開啟已完成的背景工作階段需要 Claude Code v2.1.257 或更新版本。如果您最近的對話是您移到背景的對話，且它仍在背景執行，Claude Code 會顯示 Your most recent conversation is running in the background 和該工作階段的 ID 並退出。請從 claude agents 附加到該工作階段，或執行 claude --resume 以選擇另一個工作階段。

​
其他 worktree 和專案中的工作階段

從同一儲存庫的另一個 worktree 選擇工作階段時，Claude Code 會在原處恢復它；當該工作階段自己的 worktree 已不存在時，Claude Code 會在您目前的目錄中恢復它。從不相關的專案選擇工作階段時，Claude Code 會改為將 cd 和恢復命令複製到您的剪貼簿。如果該專案的目錄已不存在，Claude Code 會在您目前的目錄中恢復該工作階段，而不是複製一個會失敗的 cd 命令。 使用 /cd 移動工作階段會將其重新定位到新目錄的專案儲存空間，因此之後它會出現在該目錄的選擇器中。

​
依工作階段 ID 或名稱恢復

您可以從任何目錄執行 claude --resume <session-id>，因此可以恢復在其他地方啟動或已使用 /cd 移動的工作階段。Claude Code 會依下列順序尋找該 ID：
  1. 目前的專案目錄及其 git worktree
  2. 此機器上的所有其他專案
跨專案搜尋只有在恰好一個其他專案持有含該 ID 訊息的逐字稿時才會解析該 ID，因此手動複製的重複項會讓 Claude Code 回報找不到，而不是恢復任意一份副本。若沒有任何已儲存的工作階段符合該 ID，Claude Code 會回報 No conversation found with session ID: <session-id>。 依名稱恢復會在目前儲存庫及其 worktree 中解析。兩種形式都會尋找完全相符的項目，即使它位於不同的 worktree 中也會直接恢復：

​
命名您的 sessions

為 sessions 提供描述性名稱，以便在 session 選擇器中找到它們並按名稱恢復。當您並行處理多個任務時，這最為重要。 通過 CLI 路由或從 claude.ai 命名 session 後，使用 claude --resume <name> 或 /resume <name> 返回到它；桌面應用程式 session 在 desktop app 中恢復。請參閱恢復 session 以了解名稱解析在 worktrees 中的行為方式。 您未命名的 sessions 仍然會獲得 Claude Code 指派的兩個標籤。只有生成的標題可作為恢復控制代碼：
  • 預設顯示名稱：您從未命名的互動式工作階段在啟動時仍會獲得預設顯示名稱。需要 Claude Code v2.1.196 或更新版本。預設名稱結合了工作目錄的名稱和一個兩字元的後綴，例如 my-app-3f，並在執行中工作階段的列表中識別該工作階段，例如 agent view 和 claude agents --json 輸出。預設名稱不是恢復控制代碼。如果您將其傳遞給 claude --resume 或 /resume，Claude Code 找不到該工作階段。
  • 生成的標題：如果您未命名 session，Claude Code 會為其生成 session 標題。標題是您第一個提示的簡短摘要，由對小型/快速模型（通常是 Haiku 級別模型）的背景請求編寫。您直接從 shell 或指令碼啟動的 claude -p 執行不會獲得一個。 接受計畫會將生成的標題替換為基於計畫的標題。您可以將任一標題傳遞給 claude --resume 或 /resume，Claude Code 會以與您設定的名稱相同的方式解析它。

​
使用 session 選擇器

在 session 內執行 /resume，或不帶引數執行 claude --resume，以開啟互動式 session 選擇器。使用這些快捷鍵來導航、搜尋和擴展清單： 每一列顯示工作階段名稱（如果已設定），否則顯示 AI 生成的工作階段標題、對話摘要或第一個提示詞，以及自上次活動以來的時間、git 分支和檔案大小。 使用 /branch 或 --fork-session 建立的 sessions 會取得自己的 session ID，並顯示為單獨的列。當選擇器為同一個 session 找到多個項目時，它會將它們分組在單一列下。按 → 展開群組。 如果 Claude Code 無法從 claude --resume 選擇器載入您選擇的 session，它會列印 Failed to resume the conversation，並提供重試命令，然後以代碼 1 結束。從 session 內的 /resume 選擇器，Claude Code 會報告失敗，您目前的對話會繼續執行。

​
分支 session

分支會建立迄今為止對話的副本並將您切換到其中，保持原始對話完整。使用它來嘗試不同的方法，而不會失去您所在的路徑。 從 session 內，執行 /branch 並使用可選名稱：
如果您省略名稱，Claude Code 會根據對話中的第一個提示詞為新分支命名。 從命令列，將 --continue 或 --resume 與 --fork-session 結合：
/branch 確認會列印兩個 session ID：您現在所在的新分支和原始分支。原始分支在磁碟上保持不變，並在 session 選擇器中保持可用；使用 /resume <original-name> 或將其 ID 傳遞給 /resume 以返回它。 /branch 複製文字記錄並將執行中的 Claude Code 程序切換為寫入到它。該區別決定了分支繼承的內容： 如果您在兩個終端中恢復同一 session 而不進行分支，來自兩者的訊息會交錯到一個文字記錄中。有關單個 session 內基於 checkpoint 的 rewind，請參閱 Checkpointing。

​
在 session 內管理上下文

這些命令控制上下文視窗中的內容，而無需離開 session：
  • /clear：以空上下文重新開始。Claude Code 會儲存先前的工作階段；使用 /resume 恢復它，或在同一個 Claude Code 程序中，從倒帶選單的前一個工作階段項目。不帶引數時，新工作階段會保留您使用 --name 或 /rename 設定的名稱，但不會保留 AI 生成的工作階段標題。若要改為命名您要離開的工作階段，請傳遞名稱，如 /clear release-prep；新工作階段隨後會以未命名狀態開始
  • /compact [instructions]：用摘要替換歷史記錄，可選擇性地專注於您指定的內容
  • /context：顯示目前消耗上下文的內容
有關壓縮如何與 CLAUDE.md、skills 和規則互動，請參閱上下文視窗指南。有關何時清除與壓縮的策略，請參閱最佳實踐。

​
匯出和定位工作階段資料

執行 /export 以開啟一個選單，讓您將目前對話複製到剪貼簿或將其儲存為純文字檔案，訊息和工具輸出呈現為可讀文字。傳遞檔案名以略過選單並直接寫入該檔案。

​
從指令碼存取對話

/export 產生供人閱讀的呈現逐字稿。下列介面產生供指令碼解析的結構化資料：執行的 JSON 結果、工作階段逐字稿檔案的路徑，或事件的即時串流。根據觸發指令碼的內容選擇：
  • 執行 Claude 一次並擷取結果：使用 --output-format json 或 stream-json 叫用 claude -p，以將非互動執行的結果、工作階段 ID、使用情況和成本擷取為結構化 JSON。
  • 詢問現有工作階段一個問題：將工作階段 ID 傳遞給 claude -p --resume，以傳送後續提示詞（例如摘要請求），並擷取結構化回應。
  • 對工作階段事件做出反應：讀取 hook 和 狀態列命令 作為輸入接收的 transcript_path 欄位。SessionEnd hook 可在工作階段結束時封存逐字稿。
  • 在 TypeScript 或 Python 應用程式中嵌入 Claude：使用 Agent SDK 以程式設計方式接收每條訊息。
下列範例使用第二個介面。它傳送後續提示詞給現有工作階段，並使用 jq 讀取答案：

​
逐字稿儲存位置

根據預設，Claude Code 將逐字稿儲存為 JSONL，位置為 ~/.claude/projects/<project>/<session-id>.jsonl，其中 <project> 是您的工作目錄路徑，非英數字元已被 - 取代。對於轉換後的名稱超過 200 個字元的工作目錄，Claude Code 會將名稱截斷為 200 個字元，並附加完整路徑的雜湊值，以便目錄名稱保持在檔案系統限制內。 每一行都是訊息、工具使用或中繼資料項目的 JSON 物件。項目格式是 Claude Code 的內部格式，在版本之間會變更，因此直接解析這些檔案的指令碼可能在任何版本上中斷。若要建立在工作階段資料上，請改用 /export 或 指令碼介面。 位置、保留期和寫入行為可設定：

​
刪除工作階段資料

逐字稿在 保留掃描規則 下會逐漸過期。若要更快刪除專案的逐字稿和相關狀態，請執行 claude purge。如果您使用 claude rm <id> 刪除 背景工作階段，其逐字稿會保留在磁碟上，並且仍可透過 claude --resume 存取。

​
自行命名專案目錄

根據預設，Claude Code 從整個工作目錄路徑衍生 <project> 名稱。若要自行選擇名稱，請將 CLAUDE_CODE_PROJECT_DIR_NAME 與 CLAUDE_CONFIG_DIR 一起設定。Claude Code 隨後會將該工作階段的逐字稿和 自動記憶 儲存在您的名稱下。這適合嵌入 Claude Code 的主機，並為每個工作階段提供自己的設定目錄。需要 Claude Code v2.1.234 或更新版本。 例如，此啟動會將租戶 A 的資料保留在 /srv/tenant-a 下，並將其專案目錄命名為 work：
Claude Code 將工作階段的逐字稿寫入 /srv/tenant-a/projects/work/，並將其自動記憶寫入 /srv/tenant-a/projects/work/memory/，無論工作目錄為何。 設定時適用三項規則：
  • 同時設定 CLAUDE_CONFIG_DIR：名稱不會隨工作目錄而變化，因此在預設 ~/.claude 下，它會將每個專案的逐字稿和自動記憶合併到一個目錄中。當 CLAUDE_CONFIG_DIR 未設定時，Claude Code 會忽略 CLAUDE_CODE_PROJECT_DIR_NAME。
  • 使用 1-64 個字母、數字、連字號或底線：不要使用 Windows 裝置名稱，例如 con。Claude Code 會忽略任何其他值，並使用衍生名稱。
  • 在啟動 claude 的 shell 環境中設定它：Claude Code 在啟動時從該環境讀取一次，因此設定檔中的 env 區塊無法設定它。
命名設定目錄的專案目錄後，請繼續使用該名稱啟動。如果您使用相同的 CLAUDE_CONFIG_DIR 啟動 Claude Code，但不使用 CLAUDE_CODE_PROJECT_DIR_NAME，它會再次讀取和寫入衍生目錄。儲存在您名稱下的工作階段會保留在磁碟上：在 工作階段選擇器 中按 Ctrl+A 以列出該設定目錄下每個專案目錄中的工作階段（包括已釘選的），無論您如何啟動，claude --resume <session-id> 都會找到儲存在任一名稱下的工作階段。

​
另請參閱

這些頁面涵蓋相關的 session 和平行處理機制：