管理 sessions

命名、恢復、分支和在 Claude Code 對話之間切換。涵蓋 --continue、--resume、--from-pr、/resume 選擇器、session 命名、匯出文字記錄，以及文字記錄的儲存位置。

session 是與專案目錄相關聯的已儲存對話。Claude Code 在您工作時將其儲存在本地，因此您可以從中斷的地方繼續、分支以嘗試不同的方法，或在任務之間切換。

桌面應用程式、claude.ai/code 和 VS Code 擴充功能各自維護自己的 session 歷史記錄，桌面應用程式也可以恢復 CLI session。本頁涵蓋 CLI。

恢復 session

Sessions 在您工作時會持續儲存到本地文字記錄檔案，因此您可以在退出或執行 /clear 後返回到一個。使用這些進入點：

使用 claude -p 或 Agent SDK 建立的 Claude Code sessions 會被排除在 session 選擇器和 claude --continue 之外。您仍然可以透過將其 session ID 傳遞給 claude --resume <session-id> 來恢復它。使用 claude --continue 時，Claude Code 也會跳過第一個提示是 /loop 的 sessions。當您執行 claude -p --continue 時，Claude Code 會包含 -p、SDK 和 /loop sessions。

您可以從任何目錄執行 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>。

在 v2.1.223 之前，查詢會停在目前專案目錄及其 git worktree，因此您必須從工作階段最後工作的目錄恢復。

claude --continue 會開啟已完成的背景 session，但不會開啟仍在執行的 session；開啟已完成的背景 sessions 需要 Claude Code v2.1.257 或更新版本。如果您最近的對話是您移到背景的對話，且它仍在那裡執行，Claude Code 會以 Your most recent conversation is running in the background 和該 session 的 ID 退出。從 claude agents 附加到 session，或執行 claude --resume 以選擇另一個。

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

當您使用 claude --resume 或 /resume 恢復的對話屬於仍在執行的背景工作階段時，Claude Code 會開啟該執行中的工作階段本身。在命令列上使用 --bg 時，恢復則改為背景分派。在 v2.1.285 之前，Claude Code 會拒絕並告訴您使用 claude attach <id> 開啟該工作階段，或先使用 claude stop <id> 停止它。

• 從您的 shell：claude --resume <session> 在同一終端機中對該 session 執行 claude attach，而不是載入文字記錄本身。您在命令列上傳遞的提示，如 claude --resume <session> "check the tests too"，會先作為該 session 的下一個輪次進行。Claude Code 會列印 Sent your prompt to the background session (<id>); opening it… 然後附加。在終端機上輸入的 claude -p --resume <session> "prompt" 也會執行相同操作，因此 -p 不會保持該執行非互動式。

  當命令列具有以下任何情況時，Claude Code 不會開啟 session：

  • 管道或重新導向的輸入或輸出
  • 設定 session 的旗標，例如 --permission-mode、--model 或 --settings
  • 讀取輸出的旗標，例如 --output-format json 或 --json-schema
  • 限制或倒帶執行的旗標，例如 --max-turns 或 --max-budget-usd

  使用這些中的任何一個，或當代理檢視已關閉時，Claude Code 不會傳送任何內容，並以狀態 1 退出，列印 session 在背景執行以及開啟它的 claude attach <id> 命令，或當它無法確定 ID 時告訴您在 claude agents 中找到它。新增 --fork-session 以恢復對話的副本。要在您自己的 session 中繼續對話本身，並套用您的旗標，請執行 claude stop <id>，然後重複該命令。

  以 / 或 ! 開頭的提示不會被傳送，當 session 等待您回答問題時也不會傳送任何提示。在這兩種情況下，Claude Code 都不會開啟 session，訊息會包含 Your prompt was not sent to it 以及原因。

• 從 session 內：/resume 將您目前的對話移到背景，並將此終端機附加到執行中的 session，列印 Opening "<title>", running in the background (<id>)。在空提示上按 ← 以返回代理檢視，這也會列出您留下的對話。當目前的對話無法移到背景時（例如因為您已附加到背景 session 或 session 持久性已關閉），/resume 會列印要執行的 claude attach 命令。

恢復的 session 會復原什麼

當 Claude Code 從其文字記錄載入對話時，恢復的 session 會復原對話以及儲存在其中的狀態：

• 對話歷史記錄：完整歷史記錄，包括工具呼叫和結果。當前一個程序結束時仍在執行的工具（例如在當機中），在您恢復時不會完成或再次執行；Claude 會看到呼叫標記為在其結果被記錄之前被切斷，並被告知在再次執行之前檢查它是否生效，除非設定了 CLAUDE_CODE_RESUME_INTERRUPTED_TURN。在 v2.1.281 之前，Claude Code 會從對話中刪除被切斷的呼叫，或將其顯示為您中斷的呼叫。
• 模型：session 會在其使用的模型上繼續。當模型已被淘汰或不被 availableModels 允許時，模型不會被復原；當 --model 旗標或 ANTHROPIC_MODEL 系列環境變數在啟動時選擇一個時；或在使用提供者特定部署 ID 的提供者上，例如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry；請參閱模型設定以了解解析順序。
• Agent：使用 --agent 或 agent 設定啟動的 session 會繼續作為該 agent，保持其工具限制和模型。在恢復時傳遞 --agent 以選擇不同的；對於任一情況下的系統提示，請參閱恢復對話中的系統提示旗標。Claude Code 在兩個地方查找 agent：session 的原始目錄（前提是您已信任該工作區），然後是您恢復的目錄，因此專案範圍的 agent 在您從另一個目錄恢復時仍會載入。如果 Claude Code 在任一地方都找不到 agent，session 會以預設工具恢復，並顯示警告，命名該 agent。
• 權限模式：如果您從終端機使用 claude --continue、claude --resume <session-id> 或 claude --resume <name>（當名稱符合一個 session 時）恢復，不帶 -p，Claude Code 會復原 session 所在的權限模式，除了恢復時的權限模式中的情況，其中也涵蓋 session 選擇器、/resume 和使用 claude -p 恢復。傳遞 --permission-mode 或 --dangerously-skip-permissions 以覆蓋復原的模式。
• 活躍目標：session 結束時仍然活躍的目標會延續；其輪次計數、計時器和代幣支出基線會重設。
• 排程工作：尚未過期的工作會被復原。背景 Bash 和監視工作不會。
• 背景工作：背景子 agent、背景 Bash 命令或工作流程在前一個程序結束時顯示在恢復的文字記錄中，作為它未完成的註記。Claude Code 不會從這些註記開始一個輪次；Claude 會在您的下一個提示中讀取它們。

並非原始啟動的每個設定旗標都會被復原。如果 session 依賴於 --mcp-config、--settings、--plugin-dir、--fallback-model 或使用 --add-dir 新增的目錄，在恢復時再次傳遞它們；使用 /add-dir 在 session 中途新增的目錄也不會被復原，儘管 session 選擇器仍會使用它們來定位 session。標準設定檔案（例如 settings.json 和 settings.local.json）會在啟動時重新讀取，因此存在於其中的設定不需要再次傳遞。對於 --system-prompt 和 --append-system-prompt，請參閱恢復對話中的系統提示旗標。

恢復時的權限模式

Claude Code 啟動恢復的 session 所在的權限模式取決於您如何恢復。下面的情況適用於 Claude Code 從其文字記錄載入對話時；當您開啟仍在執行的背景 session 時，該 session 會保持它所在的權限模式。

• 終端機：claude --continue、claude --resume <session-id> 或 claude --resume <name>（當名稱符合一個 session 時），不帶 -p。Claude Code 會復原 session 所在的權限模式，除了表格中的情況。傳遞 --permission-mode 或 --dangerously-skip-permissions 以覆蓋復原的模式。
• 非互動式：claude -p --resume 或 claude -p --continue。Claude Code 會在新 claude -p 執行會啟動的權限模式中啟動執行，除了在下面的條件下以 Plan Mode 結束的 session 會在 Plan Mode 中恢復。
• VS Code：擴充功能的對話面板。表格僅涵蓋以 Plan Mode 結束的對話；對於其餘部分，請參閱恢復過去的對話。
• 啟動時的工作階段選擇器：您從工作階段選擇器選擇的工作階段，無論您是單獨使用 claude --resume、使用 claude --from-pr，還是使用符合多個工作階段的名稱來開啟選擇器。Claude Code 會以從相同命令列啟動新工作階段時的權限模式啟動該工作階段，但以 plan mode 結束的工作階段會在 plan mode 中恢復，除非您傳遞 --permission-mode、--dangerously-skip-permissions 或 --fork-session。不會復原其他已儲存的權限模式。
• 在工作階段內使用 /resume，帶或不帶引數：您切換到的對話會以您目前工作階段所在的權限模式繼續，但以 plan mode 結束的對話會在 plan mode 中恢復，即使您是以 --permission-mode 或 --dangerously-skip-permissions 啟動 Claude Code。如果該對話在本次 Claude Code 執行中稍早已開啟過，例如您一開始所在的對話，或您以 /clear 或 /resume 離開的對話，它則會改為以您目前的權限模式繼續。

在非互動式和 VS Code 路徑上復原 Plan Mode 需要 Claude Code v2.1.246 或更新版本。每一列命名 session 結束時所在的權限模式、您透過哪個終端機、非互動式和 VS Code 路徑恢復它，以及 Claude Code 在恢復的 session 中啟動的權限模式。

使用 `-p` 在 Plan Mode 中恢復

claude -p --resume 或 claude -p --continue 執行只有在所有這些條件都成立時才會在 Plan Mode 中恢復：

• 您傳遞 --permission-prompt-tool，不傳遞 --permission-prompts none，以便 Claude Code 可以呈現計畫以供批准
• 您不傳遞 --permission-mode 或 --dangerously-skip-permissions
• 您不傳遞 --fork-session
• 執行不是透過頻道啟動的

從摘要恢復

在 Pro 或 Max 計畫上，當您恢復已閒置超過約一小時且超過 100,000 代幣的 session 時，Claude Code 會復原對話，然後在您傳送第一條訊息之前開啟對話框。到那時，session 的提示快取已過期，因此無論您選擇對話框的哪個選項，下一個請求都會一次性處理完整歷史記錄。

對話框提供三種方式來繼續 session。它們在每種方式攜帶多少對話到後續請求中有所不同，這是在保留每個細節和每個請求傳送更少代幣之間的權衡：

• 從摘要恢復：立即執行 /compact。Claude Code 透過完整歷史記錄傳送一個摘要請求，然後用摘要、您最近的交換和最多五個最近讀取的檔案替換歷史記錄。後續請求會攜帶摘要而不是完整歷史記錄。
• 按原樣恢復完整 session：載入未更改的對話。在您傳送第一條訊息後，Claude Code 會重新處理並重新快取完整歷史記錄，然後在快取保持溫暖時從快取中重新讀取它以進行後續請求。
• 不要再問我：恢復完整 session 並停止在所有未來恢復上顯示對話框。

按原樣恢復會保留對話的每個細節可用，每個請求的成本會隨著對話的大小而擴展。從摘要恢復的成本較低，因為它攜帶摘要而不是完整歷史記錄，但摘要遺漏的任何內容都不再在 Claude 的上下文中。請參閱為什麼長 session 中的使用量會增加以了解該每個請求成本的來源。

session 選擇器查看的位置

Claude Code 按專案目錄儲存 sessions。預設情況下，session 選擇器顯示：

• 來自目前 worktree 的 sessions，包括背景 sessions，在清單中標記為 bg
• 在其他地方啟動並使用 /add-dir 新增目前目錄的 sessions

使用 Ctrl+W 擴展到儲存庫的所有 worktrees，或使用 Ctrl+A 擴展到此機器上的每個專案。

第一個提示是 /loop 命令的 sessions 不會出現在選擇器中，claude --continue 也會跳過它們。在對話中稍後執行 /loop 不會隱藏 session。在 v2.1.211 之前，對話早期的 /loop 執行會永久隱藏選擇器中的 session。

使用 /cd 移動 session 會將其重新定位到新目錄的專案儲存空間，因此之後會出現在該目錄的選擇器中。從 v2.1.196 開始，移動的 session 即使在當機或強制退出後，也會保持不在舊目錄的選擇器中。在較早的版本上，當舊路徑包含特殊字元（例如底線）時，在不乾淨的退出後，它也可能在舊目錄的清單中重新出現。

從同一儲存庫的另一個 worktree 選擇 session 時，Claude Code 會在原地恢復它；當 session 自己的 worktree 不再存在時，Claude Code 會在您目前的目錄中恢復它。從不相關的專案選擇 session 時，Claude Code 會將 cd 和恢復命令複製到您的剪貼簿。如果該專案的目錄不再存在，Claude Code 會在您目前的目錄中恢復 session，而不是複製會失敗的 cd 命令。

按名稱恢復會在目前儲存庫及其 worktrees 中解析。兩種形式都會尋找完全相符的項目，並直接恢復它，即使它位於不同的 worktree 中：

命名您的 sessions

為 sessions 提供描述性名稱，以便在 session 選擇器中找到它們並按名稱恢復。當您並行處理多個任務時，這最為重要。

通過 CLI 路由或從 claude.ai 命名 session 後，使用 claude --resume <name> 或 /resume <name> 返回到它；桌面應用程式 session 在 desktop app 中恢復。請參閱恢復 session 以了解名稱解析在 worktrees 中的行為方式。

當您使用此機器上另一個活躍 session 已經使用的名稱啟動或恢復互動式 session，或將 session 重新命名為這樣的名稱時，Claude Code 會將名稱保留給已經擁有它的 session，將您的名稱重新命名為帶有兩個單詞後綴的變體，例如 auth-refactor-graceful-unicorn，並告知您。如果您想自己選擇一個名稱，請使用新名稱執行 /rename。在 v2.1.232 之前，兩個 sessions 都保留了該名稱。

在三種情況下，Claude Code 不會重新命名重複項，因此您仍然可以在列表中看到兩個具有相同名稱的 sessions：

• 它不檢查 AI 生成的標題或預設顯示名稱。
• 它不檢查啟動時 background 或 -p session 的 --name。
• 它無法重新命名早期版本 Claude Code 上的 session。

您未命名的 sessions 仍然會獲得 Claude Code 指派的兩個標籤。只有生成的標題可作為恢復控制代碼：

• 預設顯示名稱：您從未命名的互動式 sessions 在啟動時仍會獲得預設顯示名稱。需要 Claude Code v2.1.196 或更新版本。預設名稱結合了工作目錄的名稱和一個兩字元的後綴，例如 my-app-3f，並在執行中 sessions 的列表中識別該 session，例如 agent view 和 claude agents --json 輸出。預設名稱不是恢復控制代碼。如果您將其傳遞給 claude --resume 或 /resume，Claude Code 找不到該 session。命名 session 會在這些列表中取代預設名稱，接受計畫也會這樣做。

• 生成的標題：如果您未命名 session，Claude Code 會為其生成 session 標題。標題是您第一個提示的簡短摘要，由對小型/快速模型（通常是 Haiku 級別模型）的背景請求編寫。您直接從 shell 或指令碼啟動的 claude -p 執行不會獲得一個。

  接受計畫會將生成的標題替換為基於計畫的標題。命名 session 也會取代它。

  您會在 session 選擇器 中和未設定名稱時的狀態列 session_name 欄位中看到第一個提示標題。計畫標題顯示在相同的兩個位置，也顯示在執行中 sessions 的列表中，其中它取代了預設顯示名稱。

  您可以將任一標題傳遞給 claude --resume 或 /resume，Claude Code 會以與您設定的名稱相同的方式解析它。

使用 session 選擇器

在 session 內執行 /resume，或不帶引數執行 claude --resume，以開啟互動式 session 選擇器。使用這些快捷鍵來導航、搜尋和擴展清單：

每一列顯示 session 名稱（如果已設定），否則顯示 AI 生成的 session 標題、對話摘要或第一個提示，以及自上次活動以來的時間、git 分支和檔案大小。使用 Ctrl+A 擴展到所有專案後，也會看到每個 session 的專案路徑。

使用 /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 並使用可選名稱：

/branch try-streaming-approach

如果您省略名稱，Claude Code 會根據對話中的第一個提示為新分支命名。從 v2.1.198 開始，這也適用於 壓縮 之後；較早的版本會回退到字面名稱 Branched conversation，而不是查看壓縮摘要之外的原始第一個提示。

從命令列，將 --continue 或 --resume 與 --fork-session 結合：

claude --continue --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 程序中，從倒帶選單的前一個 session 項目。不帶引數時，新對話會保留您使用 --name 或 /rename 設定的名稱，但不會保留 AI 生成的 session 標題。若要改為命名您要離開的對話，請傳遞名稱，如 /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 -p --resume <session-id> --output-format json "summarize what we changed" | jq -r '.result'

逐字稿儲存位置

根據預設，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_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude

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 和平行處理機制：

• Worktrees：在單獨的分支上執行隔離的平行 sessions
• Checkpointing：將程式碼和對話 rewind 到較早的點
• Context window：什麼填充上下文以及什麼在壓縮中存活
• Non-interactive mode：claude -p 下的 session 行為