CLEAN MY CODEX · GUIDE
Clean My Codex 使用说明
01
为什么需要它
起码有 40G，一个会话就占了 500m，但看不出来空间都用在哪里。
- 很多历史会话已经没用了，却只能一条条删。
- 插件更新了几次，旧版本还一直留在电脑里。
- Codex 建了不少 Worktree 和工作区，已经分不清哪些还在用。
02
它能做什么
Clean My Codex 先统计空间占用，再由你选择要清理的内容。扫描时只读取文件信息；确认清理后，才会删除你选中的项目。
- 1扫描各模块
打开应用后会开始扫描 Codex 数据、会话、会话资产、插件和 Worktree；工作区在你打开对应页面时统计。
- 2查看谁占了空间
结果分成六个模块，列出文件数量、路径、磁盘占用和是否建议清理。没有明确证据可以删除的内容，只会显示，不会推荐。
- 3选中后再清理
勾选不再需要的项目，点击“开始清理”。确认框会再列出实际删除范围，确认后才会执行。
03
清理前要做什么
删除后无法撤销。0.1.7 仍在测试，也可能遇到尚未覆盖的 Codex 版本或电脑环境。请先备份需要保留的内容。
- 1退出 ChatGPT/Codex
会话删除需要修改 Codex 正在使用的数据。应用还开着时，Clean My Codex 不会继续。
- 2备份 Codex 数据
建议备份 ~/.codex 和 ~/Library/Application Support/Codex。macOS 用户也可以使用最近一次 Time Machine 备份。
- 3第一次只扫描
先核对每个模块的内容和路径，不要直接全选。显示“推荐清理 0 项”并不代表扫描失败。
04
六个模块分别是什么
表格里的“会连带什么”指删除当前项目时，还会不会删除别的项目。手动清理前，确认框会再次列出实际删除范围。
| 模块 | 它是什么 | 怎么清理 | 会连带什么 |
|---|---|---|---|
| Codex 数据 | Codex 的临时目录、日志、数据库、缓存，以及安装或更新留下的暂存目录。 | 大部分内容只统计。工具只会清理已过等待时间、不再使用且名称能确认来自 Codex 的安装或更新残留。 | 不会连带删除其他模块。 |
| 会话 | 侧边栏里的对话，包括续写分段和对话派生出的子代理。 | 优先让 Codex 通过 thread/delete 删除，再定向清理残留的 rollout、索引行和数据库记录。 | 会删除同一顶层会话的续写分段、所有层级子代理，以及它们的会话资产。 |
| 会话资产 | 某个会话生成并保存在本机的 ImageGen 图片、Visualization、Viewer 和 Plan。 | 直接删除你选中的资产目录。Visualization 和对应 Viewer 会作为一组处理。 | 不会删除来源会话。 |
| 插件版本 | Codex 插件的当前版本、旧版本，以及没有完成的安装残留。 | 执行前重新确认正在使用的版本，只删除已确认的旧版本或安装残留。 | 当前版本、运行组件和 plugins/data 中的数据会保留。 |
| Worktree | Codex 为处理代码任务创建的独立工作目录。它通常位于 ~/.codex/worktrees。 | 只处理能确认由 Codex 创建的 Worktree，并通过 git worktree remove 移除。 | 默认保留关联会话；你可以在确认框里选择同时删除。 |
| 工作区 | Codex 创建或使用的项目目录，通常位于 ~/Documents/Codex。里面可能有代码、文档和其他工作成果。 | 先检查 Git 是否有未提交或未推送内容，再删除你确认的目录。 | 默认保留关联会话；你可以在确认框里选择同时删除。 |
05
会话和文件怎么关联
删除方向取决于归属关系。会话的子代理和会话资产有明确归属；工作区和 Worktree 可能同时关联多个会话。
一个主会话可以有多个子代理，子代理还能继续派生。删除主会话时，所有后代一起删除。
每个资产目录只属于一个 thread ID。删除会话会删除它的资产；单独删除资产不会删除会话。
同一个目录可以关联多个会话。删除会话不会删除目录；删除目录时可以选择是否同时删除关联会话。
删除会话
续写分段、全部后代子代理、该会话的会话资产
关联的工作区和 Worktree
删除会话资产
来源会话
删除工作区或 Worktree
关联会话
同时删除关联会话
06
定时清理会删什么
定时任务只处理过期临时目录、已确认的插件旧版本，以及超过保留期的旧会话。其他模块只能手动清理。
置顶会话、存在未完成 goal 的会话、仍有排队任务的会话；任一子代理符合条件，整个顶层会话都会跳过。
独立会话资产、Worktree、工作区、配置、凭据、缓存和数据库文件。
07
哪些内容不会删除
下面的内容可能计入总占用，但不会出现在删除计划中。
- 配置、登录凭据、密钥、MCP OAuth 文件与环境变量文件
- Codex 的运行期 SQLite 数据库、崩溃恢复副本与桌面状态文件本身
- 当前正在使用的插件版本、运行组件和 plugins/data 中的持久化数据
- 桌面登录使用的 Chromium 用户资料、Cookies 与本地存储
- 桌面应用自己的日志、全部运行缓存，以及用户编写的 rules、skills、hooks、memories 等
- 你自己创建的 Worktree；即使放在同一个目录下，没有 Codex 标记也只展示、不提供删除
08
下载安装包
首页会按浏览器识别 macOS 或 Windows。部分 Mac 浏览器无法准确识别芯片类型，可以在“关于本机”里确认。
点击屏幕左上角苹果菜单 → 关于本机。写着 M1、M2、M3、M4 或更新 M 系列的是 Apple 芯片；写着 Intel 的选择 Intel 安装包。
macOS 包做了临时签名，但尚未经过 Apple 公证；Windows 安装包目前也没有代码签名。请只从本页或项目 Release 下载，并先保留备份。如果你不接受未签名软件的风险，请暂时不要安装。
09
常见问题
扫描会把我的会话上传吗？
不会。扫描和清理都在本机完成，没有分析统计，也不会上传凭据、会话内容或文件信息。应用启动时只会请求 GitHub Releases 检查新版本，下载仍由你手动决定。
为什么有些 ChatGPT 模式的会话扫描不到？
ChatGPT 模式的会话内容保存在云端，不在本机的 Codex 数据目录中，因此 Clean My Codex 不会扫描或删除这些会话。需要管理或删除时，请回到 ChatGPT/Codex 的会话列表中操作。
为什么“推荐清理”是 0？
扫描可能确实没有找到可确认的残留。Clean My Codex 不会仅凭文件较旧，或名称里带有 cache、tmp，就把它列为推荐清理。你仍然可以打开各模块查看占用，但不要在不清楚内容时手动勾选。
删 Worktree 会删掉我的原项目吗？
不会。Worktree 是原仓库的另一份检出。工具只处理能确认由 Codex 创建的那一份，并通过 Git 正确注销；原仓库目录不在删除目标里。
删会话后，工作成果还在吗？
工作区和 Worktree 默认都保留；专属于会话的 ImageGen、Visualization 与 Plan 资产会随会话删除。执行前请在确认框核对清单，并保留备份。
工作区和 Worktree 有什么区别？
工作区通常位于 ~/Documents/Codex，可能包含代码、文档和其他实际成果。Worktree 通常位于 ~/.codex/worktrees，是 Git 为某个代码任务准备的独立工作目录。不使用 Git 也没关系：清理时把两者都当作可能包含工作成果的文件夹，先打开确认内容。
为什么删会话前要退出 ChatGPT/Codex？
会话清理会修改 Codex 正在使用的索引和数据库记录。应用仍在运行时，这些文件可能继续变化。Clean My Codex 检测到 ChatGPT/Codex 还开着，就会停止会话删除。
删错了能恢复吗？
Clean My Codex 没有撤销或回收站。只能从你自己的 Time Machine、磁盘备份或其他备份中恢复，所以第一次清理前要先备份。
定时清理会删工作区、Worktree 或会话资产吗？
不会。工作区、Worktree 和单独的会话资产只能手动清理。定时任务也不会删除配置、凭据、缓存或数据库文件。旧会话如果符合保留期条件，可能由定时任务删除，并带上该会话自己的资产。
会影响 Codex 登录状态或配置吗？
Clean My Codex 不会把登录凭据、密钥、MCP OAuth 文件、环境变量文件或 Chromium 登录资料加入删除计划。0.1.7 仍是测试版本，重要配置仍建议备份。
为什么有些项目只显示占用，不能勾选？
有些文件用于解释磁盘占用，但工具没有足够证据确认可以删除；有些内容则明确受保护。只显示不提供勾选，是当前版本的安全限制。