Codex 檔案結構怎麼看？完整備份與還原脈絡指南

Codex 用久之後，電腦裡常會出現大量 sessions、SQLite、Skills、Plugins、cache 與暫存檔。這些檔案看起來零碎，實際上分別保存設定、對話歷史、任務狀態、可重複流程與執行環境，不能全部當成垃圾檔案處理。

如果希望重裝、換電腦或硬碟故障後仍能接回原本的工作脈絡，最穩定的方法是同時保留四件事：工作規則、對話與任務歷史、實際專案，以及可重複使用的 Skills。只備份聊天或只複製專案，都可能讓上下文斷掉。

這篇文章會先拆解 Codex 的三層檔案結構，再整理哪些資料一定要留、哪些可以重新產生，以及如何用「可攜式脈絡＋原始狀態＋專案資料」完成一套可驗證的備份。

---

先看懂 Codex 的三層檔案地圖

談 Codex 備份之前，先不要急著逐一研究每個檔名。比較實用的理解方式，是把所有資料分成三層：程式與執行環境、個人 Codex 狀態，以及實際專案工作區。

Codex
├─ 程式與執行環境：App、runtime、sandbox binaries
├─ 個人狀態：CODEX_HOME，預設為 ~/.codex
└─ 專案工作區：程式碼、文件、Git、研究與 outputs

第一層是 Codex App 與執行工作需要的元件。這類資料通常可以透過重新安裝恢復，不是長期工作脈絡的核心。

第二層是 CODEX_HOME。OpenAI 官方文件說明，Codex 的本機狀態預設放在 ~/.codex；Windows 通常可理解為 %USERPROFILE%\.codex。

設定、登入快取、歷史、logs 與 caches 都可能出現在這裡。

第三層是實際專案。Codex 的對話可能知道你做過什麼，但真正的程式碼、文章、研究資料、簡報、試算表與交付成果仍在專案目錄。

想先理解 Codex 的產品定位與操作入口，可以搭配閱讀Codex 新手完整指南。

---

CODEX_HOME 裡通常有哪些檔案？

官方文件列出的常見內容包括 config.toml、auth.json、歷史資料，以及其他 logs 與 caches。

桌面版還可能依版本出現 sessions、archived sessions、Plugins、Skills、attachments、automations 與多個 SQLite 資料庫。

下面的分類比死背檔名更重要，因為桌面版的內部檔名與資料庫版本可能隨更新改變。

config.toml 與 AGENTS.md 保存的東西不同

config.toml 比較像 Codex 的控制面板，負責模型、推理強度、approval、sandbox、MCP 與各種功能設定。AGENTS.md 則是工作約定，例如完成修改後要跑哪些測試、哪些檔案不能動、成品應放到哪裡。

OpenAI 的 AGENTS.md 文件說明，Codex 可以先讀全域規則，再從專案根目錄一路讀到目前工作目錄，越接近工作位置的指示優先。因此，若只備份全域 AGENTS.md，卻漏掉專案內的 AGENTS.md，仍可能失去重要的專案脈絡。

想進一步理解這類 AI 工作環境設計，可以延伸閱讀Harness Engineering 新手教學。

為什麼會出現很多 SQLite、WAL 與 SHM？

Codex Desktop 需要快速保存任務列表、狀態與索引，因此可能使用 SQLite。你有時會同時看到 資料庫.sqlite、資料庫.sqlite-wal 與 資料庫.sqlite-shm。

這些 sidecar 檔案不應在 Codex 正在執行時被隨意刪除。比較保守的做法，是讓任務停止、完全退出 Codex，再建立完整時間點快照。

文章中提到的 thread_history_1.sqlite、state_5.sqlite 等名稱只是特定桌面版本可能觀察到的例子，不是 OpenAI 對所有版本承諾的固定備份格式。

---

想保留工作脈絡，哪些資料一定要備份？

判斷優先順序時，不要只看容量。幾 KB 的 AGENTS.md 可能比數百 MB 的 cache 更重要，因為它保存了長期工作方法；反過來，一大包 runtime 檔案即使很佔空間，也可能重新安裝就能恢復。

P0 是最小可行備份。即使未來 Codex 的內部資料庫改版，只要規則、Skills、專案記憶與實際成果都在，仍能重新建立大部分工作方式。

P1 則補上任務連續性，適合希望保留舊對話與桌面任務列表的人。

---

---

最穩定的做法，是把 Codex 備份拆成三包

把所有資料塞進單一 ZIP 看似簡單，日後卻很難分辨哪些是設定、哪些是敏感憑證、哪些可以安全還原。更容易管理的方法，是把備份拆成三個角色清楚的資料包。

---

A. Portable Context：可攜式脈絡

這一包放 AGENTS.md、config、profiles、rules、自訂 Skills、專案記憶、README 與人類可讀的交接文件。它的重點是「換版本後仍看得懂」，不依賴某個 SQLite schema 才能解讀。

---

B. Raw Codex State：原始狀態快照

這一包放 sessions、archived sessions、history、thread／state indexes、memories、automations 與 attachments。

它比較像災難復原材料，能增加保留原任務狀態的機會，但不應宣稱是 OpenAI 官方保證的跨版本匯入格式。

---

C. Project Data：實際專案

這一包保存程式碼、文章、研究來源、圖片、輸出成果、尚未提交的修改，以及 Git 歷史或可恢復的遠端 repo。第一次接觸 repo、commit 與遠端備份，可以先看GitHub Repository 新手入門。

Codex-Backup-2026-08-31
├─ A-Portable-Context
├─ B-Raw-Codex-State
└─ C-Project-Data

---

Codex 備份實作流程

1. 確認 CODEX_HOME：先找出目前實際使用的 Codex home，不要直接假設所有環境都在同一路徑。
2. 列出重要專案：把本機專案、Git repo、專案記憶庫與獨立 outputs 納入清單。
3. 讓任務完成或停止：不要在 Codex 還持續寫入對話、資料庫或圖片時建立最終快照。
4. 完全退出 Codex：降低 SQLite 主檔與 sidecar 落在不同時間點的風險。
5. 建立時間戳版本：例如 Codex-Backup-2026-08-31，不要直接覆蓋上一份可用備份。
6. 依三包模型複製：先保存 Portable Context 與 Project Data，再加入需要的 Raw State。
7. 產生 manifest 與 SHA-256：記錄相對路徑、檔案大小與 hash，日後才能知道備份是否漂移或損壞。
8. 做還原測試：先在隔離位置 dry-run 或抽樣開啟，不要直接蓋回正在使用的 CODEX_HOME。

備份腳本通常會從命令列執行；如果看到 PowerShell、Terminal、path 或 hash 等名詞不熟悉，可以先讀CLI 新手命令列教學，再開始操作。

---

哪些檔案通常不用放進長期備份？

cache、tmp、sandbox binaries、writer locks、OAuth locks 與多數診斷 logs，通常是可重新產生的執行層。若備份目標是保留脈絡，可以先排除這些項目，減少大量細碎檔案與空間占用。

但「通常可重建」不等於「可以在程式執行中直接刪除」。若只是清理空間，應先辨識目前版本與檔案用途，再把清理和備份分成兩個任務。

不要一邊同步、一邊刪 cache，又一邊讓 Codex 寫入同一個狀態目錄。

公開、可重新安裝的 Plugin 也可以視容量決定是否保留；自己修改、尚未發布或包含專用 scripts 的 Plugin，則應當成原始碼備份。

OpenAI 官方說明，Plugin 可能同時包含 Skills、Connectors、MCP servers、browser extensions 與 hooks，所以複製 Plugin 檔案也不代表外部服務的登入授權一定會跟著恢復。

---

auth.json 與 secrets 為什麼要分開處理？

OpenAI 的 Authentication 文件明確提醒：若 Codex 使用檔案型驗證，auth.json 可能包含 access tokens，必須像密碼一樣處理，不要提交到 Git、貼進工單或分享在聊天中。

因此，一般 OneDrive 同步資料夾、可分享 ZIP 或專案 repo 應預設排除 auth.json、secrets、API keys 與其他 credential files。

換機時優先重新登入；只有在受控、加密、權限清楚的備份方案中，才評估是否保存驗證狀態。

這也是同步與備份的差別。同步工具會快速複製變更，也可能同步誤刪、損壞或敏感資料；備份則應保留時間點、版本與可恢復驗證。

---

怎麼確認備份真的保住脈絡？

複製命令顯示成功，只能證明檔案曾經被寫到目的地，不能證明日後能恢復。至少要完成下面幾項檢查：

• 備份目錄有建立時間、來源位置與版本說明。
• manifest 記錄的檔案數與實際檔案數一致。
• 重要檔案具有 SHA-256，來源與備份 hash 相同。
• AGENTS.md、config、Skills、README 與重要 outputs 可以正常開啟。
• Git repo 能看到預期的 branch、commit 與未提交修改。
• Raw State 的資料庫與 sessions 在備份時沒有持續寫入。
• 還原先在隔離路徑 dry-run，不直接覆蓋目前正在使用的資料。
• 舊備份在新備份驗證完成前不刪除。

目前官方文件說明了 CODEX_HOME、history、設定、Skills 與驗證資料的位置，但沒有把「整份 CODEX_HOME 複製後可跨所有未來版本完整恢復桌面介面」列為保證。因此，原始狀態快照應與可攜式脈絡包並存，不能成為唯一方案。

---

結語：備份的不是檔案數量，而是決策鏈

Codex 的大量小檔案並不可怕，真正要避免的是只看檔案大小、不看脈絡角色。最少應保存 AGENTS.md、config、自訂 Skills、專案記憶與實際專案；需要保留舊任務時，再加入 sessions、索引、狀態、automations 與附件。

把備份拆成 Portable Context、Raw Codex State 與 Project Data 三包，敏感憑證另外處理，最後用 manifest、hash 與隔離還原驗證。

即使未來 Codex 的內部檔名改變，也比較容易把做事方法、決策原因與實際成果接回來。

---

Codex 檔案與備份常見問題

.codex 資料夾可以整個複製嗎？

可以把它當成關閉 Codex 後的原始狀態快照，但不要把這件事理解成官方保證的跨版本還原格式。實際專案與可攜式脈絡仍要獨立保存。

換電腦時，最少要帶走哪些資料？

至少帶走 AGENTS.md、config、自訂 Skills、專案記憶、實際專案與尚未提交的修改。需要舊任務列表與聊天時，再保留 sessions、history、state 與附件。

sessions 可以取代專案備份嗎？

不行。sessions 可能記得做過什麼，但正式原始檔、Git 歷史、圖片與輸出成果仍在專案資料夾。

Skills 與 Plugins 都要全部備份嗎？

自己建立或修改的 Skills／Plugins 應完整保存。官方公開套件通常可以重新安裝，但仍可能需要重新連接外部服務。

sqlite-wal 與 sqlite-shm 可以刪嗎？

不要在 Codex 或相關資料庫仍在執行時手動刪除。若目標是備份，先完全退出 Codex，再建立一致的狀態快照。

auth.json 要備份嗎？

一般備份預設排除。官方指出它可能含 access tokens，應像密碼處理；換機時優先重新登入。

OneDrive 同步等於備份嗎？

不等於。同步可以同步誤刪與損壞，也未必形成一致時間點。

備份還需要版本、manifest、hash 與還原驗證。

OpenAI 是否保證複製 CODEX_HOME 就能完整還原？

截至 2026 年 8 月 31 日查核的官方文件，OpenAI 說明了本機狀態與常見檔案位置，但未提供這項跨版本完整還原保證。因此應同時保留可攜式脈絡與實際專案。

---

官方延伸閱讀

• OpenAI Docs：Advanced Configuration
• OpenAI Docs：Configuration Reference
• OpenAI Docs：AGENTS.md
• OpenAI Docs：Build Skills
• OpenAI Docs：Authentication