# Claude Code 會在 30 天後刪除歷史記錄：如何保存它

> Claude Code 工作階段的儲存位置、如何設定 cleanupPeriodDays，以及如何使用 rsync、launchd 或 cron 整理外部封存檔。

Source: https://ailoot.ai/blog/zh-hant-tw/claude-code-history-30-days/
Canonical: https://ailoot.ai/blog/zh-hant-tw/claude-code-history-30-days/
Language: zh-Hant-TW
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-056
Revision: sha256-0c6ba7818c6cc6d881c5392336861882f996370b8a2d1bc8efe90a3e42ffb740


如需服務使用說明，請參閱 [Ailoot 文件](https://ailoot.ai/docs/)。



## Claude Code 真的會刪除工作階段歷史記錄嗎？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaways">

重點整理

會。每次 Claude Code 啟動時，都會刪除超過 30 天的工作階段檔案。`~/.claude/settings.json` 中的 `cleanupPeriodDays` 設定負責這項操作；其預設值是 `30`。刪除時不會發出警告、不會徵求同意，也沒有任何復原方法。

</div>

你開啟 Claude Code，想接續兩個月前的工作階段，卻發現它已經不見了。檔案已從磁碟上徹底刪除。這不是故障，也不是罕見的錯誤，而是預設清理機制的運作方式。

有一項設定控制清理：`cleanupPeriodDays`。其預設值是 `30`。每次 Claude Code 啟動時，都會掃描歷史記錄資料夾，刪除超過該期限的所有內容。我的 `~/.claude/settings.json` 裡完全沒有這項設定，這表示系統使用了預設值，而我的部分舊工作階段已經消失了。

Anthropic 的儲存庫中已有多項相關錯誤回報，但都尚未修復。

## Claude Code 將工作階段歷史記錄存放在哪裡？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaways">

重點整理

每個工作階段的歷史記錄都存放在 `~/.claude/projects/<project-path>/<session-id>.jsonl`。資料夾名稱是你執行 Claude Code 時，工作目錄的絕對路徑，斜線會替換成連字號。`.jsonl` 檔案逐行記錄整段對話，包括你的提示、模型回應、工具呼叫和檔案編輯。這正是清理機制會刪除的內容。

</div>

找到歷史記錄很簡單。開啟終端機並查看資料夾內容：

```bash
ls ~/.claude/projects/
```

每個子資料夾都是一個獨立專案。資料夾名稱會編碼路徑：例如，位於 `/Users/alex/dev/shop` 的專案會成為 `-Users-alex-dev-shop` 資料夾。裡面則有工作階段檔案：

```bash
ls -lt ~/.claude/projects/-Users-alex-dev-shop/
# 3f8a1c2e-....jsonl   ← 一個工作階段 = 一個檔案
# a91b7d40-....jsonl
```

每個 `.jsonl` 都是逐行記錄檔：一行代表一個工作階段事件。內容不只有對話文字，還包含你決策背後的邏輯：為什麼選擇特定的資料庫結構、否決了哪些選項、Claude 在哪裡出錯，以及你如何修正。

本質上，這就是專案開發日誌。失去它令人難受，因為你失去的不是一段「聊天」，而是數週來累積的脈絡。我在指南[「Claude Memory 與 CLAUDE.md」](https://ailoot.ai/blog/zh-hant-tw/claude-memory-claude-md-auto-memory/)中介紹了這些脈絡的組成方式。

## Anthropic 為什麼要在 30 天後刪除逐字稿？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaways">

重點整理

Anthropic 的立場是保護隱私與安全。工作階段檔案以純文字形式儲存在磁碟上，可能包含原始碼、密碼和 API 金鑰。永久保存會帶來風險：如果筆記型電腦遭竊，或有人取得磁碟存取權，就能拿到所有這些敏感資料。30 天期限是在「能接續近期工作」與「不在磁碟上保存超過必要時間的機密資訊」之間取得平衡。

</div>

刪除有其理由，在全部關閉之前值得先了解。逐字稿是純文字。如果 Claude 在工作階段中讀取 `.env` 檔案、將金鑰插入命令，或你在提示中貼上密碼，這些內容都會以純文字形式寫入 `.jsonl`。這種檔案留在磁碟上的時間越久，日後外洩的機率就越高。

Anthropic 說得很清楚：逐字稿可能包含原始碼、憑證和其他敏感資料；將它們保存在磁碟上的時間超過必要範圍，會造成實際的隱私風險。30 天期限是經過權衡後的折衷方案。

社群的反對意見集中在三件事：刪除是悄悄進行的（設定時或啟動時都沒有警告）、不會徵求同意（不會詢問你），而且無法復原（不會移至垃圾桶，也沒有回復機制）。在 issue \#59248 中，開發者只要求一件事：讓清理機制更公平——提供警告、復原期限，以及不那麼積極的預設期限。

## 為什麼備份指令碼本身可能觸發刪除？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaways">

重點整理

清理機制依檔案修改時間（mtime）決定要刪除哪些檔案。它不會檢查工作階段實際的最後活動時間。任何碰觸 `.jsonl` 檔案的程序——雲端同步、rsync、編輯器或指令碼——都可能改變其 mtime，讓新的工作階段看起來像是舊的。下一次 Claude Code 啟動時，就會將該工作階段判定為過期並刪除。諷刺的是，在受管理資料夾內天真地備份歷史記錄，反而會加速它的消失。

</div>

這是最棘手的部分，也讓試圖自行保護資料的人容易踩坑。清理機制會查看 mtime，也就是檔案的最後修改時間。它假設 mtime 代表你最後一次在該工作階段工作的時間。實際上，任何東西都可能改變 mtime：Dropbox 或 iCloud 同步用戶端、`rsync`、防毒軟體、索引器，或你自己的備份指令碼。

陷阱就在這裡。你決定保存歷史記錄，並為 `~/.claude/projects/` 設定雲端同步。某個時候，同步服務會重寫檔案，並將其 mtime 設為較早的日期（從雲端副本還原時就可能發生）。Claude Code 在啟動時看到「舊」檔案便會將它刪除。你本想保存它，卻反而加速了它被刪除。

結論只有一個：**備份必須放在 `~/.claude/projects/` 之外**。清理機制只會在這個資料夾內運作。儲存在外部的副本不受清理機制影響。我會以這項原則為基礎建立解決方案。

## 如何立即停止刪除歷史記錄？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaways">

重點整理

只需一項設定。開啟 `~/.claude/settings.json`，將 `cleanupPeriodDays` 設為較大的數值，例如 `3650`（十年）。實際上，這會停用自動刪除：沒有任何內容會超過這項期限。請注意：這項設定只能保護尚未刪除的內容。已被清理機制刪除的歷史記錄無法復原。因此，第一步就是趁你還沒再失去另一個工作階段之前採取行動。

</div>

依照以下三個步驟停止刪除：

1.  開啟設定檔案：`~/.claude/settings.json`（如果檔案不存在，請建立它）。
2.  加入數值較大的 `cleanupPeriodDays` 設定：

```json
{
  "cleanupPeriodDays": 3650
}
```

3.  儲存檔案。設定會在下次啟動 Claude Code 時生效。

數值 `3650` 代表十年：實際上，系統將不再刪除內容。如果你想保留清理功能，但延長期限，請設為 `365`（一年）；屆時只有超過一年的工作階段會消失。你可以使用這個命令檢查設定是否已套用：

```bash
grep cleanupPeriodDays ~/.claude/settings.json
```

有一項容易忽略的注意事項：延長期限**不會**復原已刪除的內容。清理機制會在啟動時執行，過去執行時刪除的內容已經永遠消失。因此你應該先設定此項目——它能防止未來的損失，但無法取回已經刪除的內容。如果你不只想避免遺失 Claude Code 歷史記錄，也想避免因為誤下命令而毀掉專案，請參閱指南[「如何設定 Claude Code，避免它破壞你的專案」](https://ailoot.ai/blog/zh-hant-tw/claude-code-safe-overnight-setup/)。

工作階段歷史記錄是專案第二大腦的一部分，其中包含你未曾記錄在其他地方的決策邏輯。`cleanupPeriodDays` 可以保存檔案，但不會讓它們成為六個月後能讓你找到所需內容的系統。



## 如何自動將歷史封存到清理資料夾之外？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaways">

重點整理

將工作階段複製到 `~/.claude/projects/` 之外的封存資料夾，清理機制不會影響該處。每天使用 `rsync -a` 複製到另一個目錄即可：新檔案會加入，舊檔案則會保留。由於封存資料夾位於外部，`cleanupPeriodDays` 和 mtime 問題都不會影響它。在 macOS 上使用 launchd、Linux 上使用 cron 自動執行，歷史記錄就會自行累積。

</div>

想法很簡單：讓 Claude Code 隨意處理自己的資料夾，同時在外部保留獨立封存副本。它可避開這套清理機制，但磁碟故障、誤刪或複製失敗仍可能讓它遺失。設定方式如下：

1.  在受管理目錄外建立封存資料夾：

```bash
mkdir -p ~/claude-history-archive
```

2.  將目前的歷史記錄複製到那裡。`-a` 旗標會保留結構和時間戳記；`--ignore-existing` 則會讓已複製的檔案保持不變：

```bash
rsync -a ~/.claude/projects/ ~/claude-history-archive/
```

3.  設定每天自動執行一次。在 macOS 上使用 launchd。建立檔案 `~/Library/LaunchAgents/com.example.claudearchive.plist`：

```xml
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.example.claudearchive</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/bin/rsync</string>
    <string>-a</string>
    <string>/Users/YOUR_NAME/.claude/projects/</string>
    <string>/Users/YOUR_NAME/claude-history-archive/</string>
  </array>
  <key>StartInterval</key>
  <integer>86400</integer>
</dict>
</plist>
```

4.  載入代理程式，讓它在背景執行：

```bash
launchctl load ~/Library/LaunchAgents/com.example.claudearchive.plist
```

在 Linux 上，只需在 crontab 中加入一行（`crontab -e`）即可完成相同設定：

```bash
0 3 * * * rsync -a ~/.claude/projects/ ~/claude-history-archive/
```

為什麼這種做法有效，而上一節的同步方式會失敗？封存資料夾位於 `~/.claude/projects/` 之外，清理機制完全看不到它。複製作業只有一個方向（從運作中的資料夾到封存資料夾），而且不會碰觸運作中檔案的 mtime，因此不會發生 mtime 問題。即使 Claude Code 明天從自己的資料夾刪除某個工作階段，它在封存資料夾中的副本仍會保留。

## 如何將工作階段封存檔轉變為可搜尋的第二大腦？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaways">

重點整理

使用 git 管理封存檔，就能建立一個具備版本管理、可完整搜尋所有工作階段的資料庫。在封存資料夾中執行 `git init`，然後每天執行 `git add -A && git commit`，即可取得變更歷史記錄，並防止意外覆寫。你可以用一般的 grep 搜尋過去的工作階段，也可以使用 jq 擷取結構化內容，因為 `.jsonl` 是逐行分隔的 JSON。這能讓封存檔成為實用工具。

</div>

光是累積檔案還不夠——你還得能存取它們。只要兩個步驟，就能讓封存檔成為實用工具。

首先，使用 git 管理版本。在封存資料夾中初始化儲存庫：

```bash
cd ~/claude-history-archive
git init
git add -A && git commit -m "Claude Code 歷史記錄的第一個快照"
```

將 `git add -A && git commit` 加到執行 rsync 的每日工作中。現在你就有了版本歷史記錄：可以查看新增了什麼以及何時新增，並透過一個命令復原意外覆寫的內容。

其次，進行搜尋。`.jsonl` 檔案是逐行分隔的 JSON，因此可以使用熟悉的工具。找出討論特定主題的工作階段：

```bash
grep -rl "資料庫遷移" ~/claude-history-archive/
```

使用 jq 從工作階段中只擷取提示文字（因為它是 JSON）：

```bash
jq -r 'select(.type=="user") | .message.content' session.jsonl
```

到這個階段，工作階段歷史記錄就開始成為專案的第二大腦：這是一個能讓你在幾秒鐘內找出「我們三月時是怎麼決定這件事」的資料庫。如需了解工作階段脈絡的存放位置及管理方式，請參閱另一篇說明[「Claude Code 中的 Token 都去哪了」](https://ailoot.ai/blog/zh-hant-tw/where-claude-code-tokens-go/)。

## 可以復原已刪除的工作階段嗎？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaways">

重點整理

沒有內建的復原方法。Claude Code 不會將刪除的檔案移至垃圾桶，也不會保留回復紀錄；檔案已徹底刪除。唯一的機會是刪除**之前**建立的外部副本：macOS 上的 Time Machine 快照、OneDrive 或 Dropbox 版本歷史記錄，或手動備份。如果都沒有，工作階段就遺失了。因此必須事先做好保護——趁還沒有任何東西可失去之前。

</div>

坦白說，答案大概是不行。Claude Code 沒有復原功能、垃圾桶，也沒有已刪除逐字稿的復原記錄。檔案就這樣從磁碟上消失了。

有一種方法：如果事先啟用了系統備份，就可以嘗試還原：

1.  **macOS Time Machine**——如果某個快照在刪除前包含 `~/.claude/projects/`，你可以從所需日期的備份中取回檔案。
2.  **OneDrive / Dropbox 版本歷史記錄**——如果資料夾已啟用版本管理並同步，請在雲端的版本歷史記錄中尋找檔案（但請記住 mtime 陷阱：同步也可能觸發刪除）。
3.  **手動副本**——你曾手動使用 `rsync` 或 `cp` 複製到受管理資料夾以外的任何副本。

如果這些副本都不存在，工作階段就已經遺失。而這種情況並不少見：Anthropic 儲存庫中的一則錯誤回報提到，有 38 筆記錄中的 26 筆損毀，代表數個月的工作付諸流水。唯一可靠的保護方法，是在損失發生**之前**就先設好。趁現在還有內容可保存，今天就設定 `cleanupPeriodDays` 和自動封存。

## cleanupPeriodDays 應該設為多少？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaways">

重點整理

對大多數人來說，建議使用 `3650`（十年，實際上會停用刪除）並搭配外部自動封存。只有在你不需要歷史記錄，而且更重視不要將機密資訊保存在磁碟上時，才保留預設值 `30`。`365` 是合理的折衷方案，每年清理一次。另一種做法是完全不寫入歷史記錄：使用 `CLAUDE_CODE_SKIP_PROMPT_HISTORY` 環境變數或 `--no-session-persistence` 旗標，但這與本文的目的相反。

</div>

只有一項設定，但它有幾種不同的意義。比較各選項，並依照你的用途選擇：

| 數值 | 功能 | 適用對象 |
|----|----|----|
| `30`（預設值） | 啟動時刪除超過 30 天的工作階段 | 不需要歷史記錄，而且更重視避免將敏感資料存放在磁碟上的人 |
| `365` | 保留一年的歷史記錄，之後每年清理一次 | 需要近期歷史記錄，但不需要永久封存的人 |
| `3650` | 實際上停用刪除 | 想保留所有內容並使用外部封存的人（建議） |
| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 完全不將歷史記錄寫入磁碟 | 追求最高隱私，而且完全不需要歷史記錄的人 |

有一項重要的安全注意事項：如果你設定 `3650` 並保留所有內容，就代表你同意將可能包含金鑰和程式碼的逐字稿存放在磁碟上。這是封存便利性與風險之間的刻意取捨。要降低風險：將封存檔存放在加密磁碟上（macOS 可使用 FileVault），不要放在公用雲端，也不要將它提交至公開的 git 儲存庫。我另外整理了一篇指南，說明 Claude Code 可能洩漏哪些資料：[「Claude Code 的資料安全」](https://ailoot.ai/blog/zh-hant-tw/claude-code-data-access-safety/)。

## 今天要做什麼：檢查清單

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaways">

重點整理

這些步驟能降低歷史遺失風險：以 `cleanupPeriodDays: 3650` 延長保留，將工作階段複製到 `~/.claude/projects/` 之外，並為封存保留版本。只有成功複製檔案，才受保護不被 Claude Code 清理。每天成功執行仍可能留下最近一天未封存，失敗或漏跑會延長缺口。同磁碟副本不能防範磁碟故障。

</div>

依照以下步驟設定保護措施：

1.  在 `~/.claude/settings.json` 中將 `cleanupPeriodDays: 3650` 設定好——你已停止刪除。
2.  在受管理資料夾外建立 `~/claude-history-archive`，並執行第一次 `rsync -a`。
3.  使用 macOS 的 launchd 或 Linux 的 cron 設定每日執行。
4.  在封存資料夾中初始化 git，並將 `git add -A && git commit` 加入同一項工作。
5.  確認封存檔位於加密磁碟上，且未同步至公用雲端。
6.  檢查每次排程是否成功複製，再查看近期封存工作階段，定期在獨立暫存資料夾還原樣本，驗證可閱讀。
7.  若也要防範裝置或磁碟遺失，請另存有適當存取控制的獨立備份並測試還原；同磁碟 Git 歷史不是獨立備份。

工作階段歷史記錄只是讓 Claude 可靠運作的其中一層脈絡。

<div class="section" role="doc-bibliography" aria-label="Sources">

### 來源

- [Claude Code 文件 - settings.json 設定 (cleanupPeriodDays)](https://code.claude.com/docs/en/settings)
- [Claude Code 文件 - 最新消息](https://code.claude.com/docs/en/whats-new)

</div>





進一步認識 [Ailoot](https://ailoot.ai/)。

## 常見問題：Claude Code 會在 30 天後刪除歷史記錄：如何保存它

### 每天封存，就能保證工作階段永不遺失嗎？

不能。它只保護成功複製、已離開受管理資料夾的檔案。每天成功執行仍可能缺少最近一天的變更，失敗會擴大缺口；同磁碟副本也可能與原稿一起損壞。

### 如何確認封存可以使用？

確認排程複製成功，查看近期封存工作階段，並定期在獨立暫存資料夾還原樣本。若也要防範裝置或磁碟遺失，請測試獨立儲存的備份還原。


## Ailoot · 公司及其專案組合

Ailoot以累積的營運經驗、廣大的客戶群、穩定的服務及持續的KPI管理為基礎。

公司及其專案組合：數百萬客戶，每月銷售額達數十億。

Ailoot將這些營運經驗用於API存取，讓客戶的產品、代理、應用程式及自動化流程使用AI功能。