管理 sessions

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

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

桌面應用程式、Claude Code 網頁版和 VS Code 擴充功能各自維護自己的 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 --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 <session-id>：Claude Code 會先在目前專案目錄及其 git worktrees 中查找 ID，然後在此機器上的所有其他專案中查找，因此它會找到在其他地方啟動或使用 /cd 移動的 session。跨專案搜尋只有在恰好一個其他專案持有該 ID 的訊息文字記錄時才會解析 ID，因此手動複製的重複項會導致 Claude Code 報告找不到，而不是恢復任意副本。如果沒有儲存的 session 符合該 ID，Claude Code 會報告 No conversation found with session ID: <session-id>。在 v2.1.223 之前，查詢會停在目前專案目錄及其 git worktrees，因此您必須從 session 最後工作的目錄恢復。

恢復的 session 會復原什麼

恢復的 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 和監視工作不會。

並非原始啟動的每個設定旗標都會被復原。如果 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 --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 結束的對話；對於其餘部分，請參閱恢復過去的對話。
• 啟動時的 Session 選擇器：您從session 選擇器選擇的 session，無論您是使用 claude --resume 單獨開啟它、claude --from-pr 還是符合多個 session 的名稱。Claude Code 不會復原儲存的權限模式。它會在從相同命令列啟動新 session 時所在的權限模式中啟動 session。
• /resume 在 session 內，帶或不帶引數：Claude Code 不會復原儲存的權限模式。您切換到的對話會在您目前 session 所在的權限模式中繼續。

在非互動式和 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，以便 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 在應用程式中恢復，該應用程式保持自己的 session 歷史記錄。請參閱恢復 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 和規則互動，請參閱上下文視窗指南。有關何時清除與壓縮的策略，請參閱最佳實踐。

匯出和定位 session 資料

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

從指令碼存取對話

/export 產生供人閱讀的呈現文字記錄。下列介面產生供指令碼解析的結構化資料：執行的 JSON 結果、session 文字記錄檔案的路徑，或事件的即時串流。根據觸發指令碼的內容選擇：

• 執行 Claude 一次並擷取結果：使用 --output-format json 或 stream-json 叫用 claude -p，以將非互動執行的結果、session ID、使用情況和成本擷取為結構化 JSON。
• 詢問現有 session 一個問題：將 session ID 傳遞給 claude -p --resume，以傳送後續提示（例如摘要要求），並擷取結構化回應。
• 對 session 事件做出反應：讀取 hooks 和 status line commands 作為輸入接收的 transcript_path 欄位。SessionEnd hook 可在 session 結束時封存文字記錄。
• 在 TypeScript 或 Python 應用程式中嵌入 Claude：使用 Agent SDK 以程式設計方式接收每條訊息。

下列範例使用第二個介面。它傳送後續提示給現有 session，並使用 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 的內部格式，在版本之間會變更，因此直接解析這些檔案的指令碼可能在任何版本上中斷。若要建立在 session 資料上，請改用 /export 或 指令碼介面。

位置、保留期和寫入行為可設定：

刪除 session 資料

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

自行命名專案目錄

根據預設，Claude Code 從整個工作目錄路徑衍生 <project> 名稱。若要自行選擇名稱，請將 CLAUDE_CODE_PROJECT_DIR_NAME 與 CLAUDE_CONFIG_DIR 一起設定。Claude Code 隨後會將該 session 的文字記錄和 自動記憶 儲存在您的名稱下。這適合嵌入 Claude Code 的主機，並為每個 session 提供自己的設定目錄。需要 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 將 session 的文字記錄寫入 /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，它會再次讀取和寫入衍生目錄。儲存在您名稱下的 session 會保留在磁碟上：在 session 選擇器 中按 Ctrl+A 以列出該設定目錄下每個專案目錄中的 session（包括已釘選的），無論您如何啟動，claude --resume <session-id> 都會找到儲存在任一名稱下的 session。

另請參閱

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

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