Skip to main content
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 會在沒有其輸出的情況下繼續。
  • 模型：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 中啟動的權限模式。 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 選擇器中找到它們並按名稱恢復。當您並行處理多個任務時，這最為重要。 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 級別模型）的背景請求編寫。接受計畫會將其替換為基於計畫的標題。命名 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 並使用可選名稱：
如果您省略名稱，Claude Code 會根據對話中的第一個提示為新分支命名。從 v2.1.198 開始，這也適用於 壓縮 之後；較早的版本會回退到字面名稱 Branched conversation，而不是查看壓縮摘要之外的原始第一個提示。 從命令列，將 --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 程序中，從倒帶選單的前一個 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 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 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 和平行處理機制：