前两天准备导出一份演示录像，系统突然提示“磁盘空间不足”。我打开存储一看，好家伙，Codex 的本地目录居然占了快 20GB。作为一个每天都在用 Codex CLI 干活的人，我当时的第一反应是：这货到底在本地存了什么？更气人的是，这不是第一次了。之前我一直是“手动清理”流：隔三差五打开隐藏目录，一顿操作猛如虎，删完一看也就腾出三五个 GB，过两周又打回原形。后来我实在受不了，花了两天写了个专门针对 Codex 本地存储的小工具，叫 CX Clear。这篇文章就把 Codex 占用膨胀的原因、我踩过的坑、以及 CX Clear 的设计思路和完整用法一次讲清楚。不管你是刚装了 Codex 还在折腾入门教程，还是已经被它的磁盘占用折磨了一阵子，这篇都值得看完。
1. Codex 用着用着就成了“空间刺客”
1.1 装过就忘的 Codex，到底在你电脑里放了什么
很多人装上 Codex 之后基本不会去翻它的本地目录，这很正常。但它确实会往磁盘里写不少东西，而且都是“细水长流”式的累积。我排查的时候特意把 Codex 的根目录拉出来看了个遍，占空间的大头基本是下面这几类。
第一类是会话记录。每次你跟 Codex 对话、让它改代码、跑测试，它都会把会话上下文、请求响应、中间结果写到本地。这类文件单个不大，但架不住数量多。我自己的目录里光session子目录就有上万个 JSON 文件，几个月的对话全在里面。
第二类是日志文件。Codex 在运行过程中会记录调试日志、错误堆栈、网络请求细节。这类日志默认不会自动压缩，也不会自动轮转，时间一长就是几百个 MB 起步。特别是你在调试复杂任务时反复重试，日志增长速度非常吓人。
第三类是认证缓存和临时文件。登录 token、密钥信息会存在本地，虽然体积小，但属于“绝对不能乱删”的部分。临时文件则是 Codex 在处理大任务时产生的中间产物，任务完成后一般会被清理，可一旦进程被杀、系统重启，这些临时文件就成了“没人认领的孤儿”。
还有一类经常被忽略：旧版本残留。Codex 的安装教程会让你手动安装、更新，但很少会提醒你卸载旧版本。于是你每次升级，老版本的执行文件、资源文件、依赖库都会留在原目录里。积攒几个版本之后，这部分的占用甚至比会话记录还大。
1.2 空间膨胀的三个典型阶段
我在不同机器上观察过 Codex 的目录增长曲线，基本可以分为三个阶段。
第一阶段是刚装好的“无感期”。这时候目录很小，可能只有几十 MB，大家都不会在意。很多 Codex 安装教程也不会提这个事情。
第二阶段是使用几个月后的“渐变期”。我大概高强度用了三个月，目录涨到了 4.7GB。这时候系统还没报警，但你打开磁盘管理工具会开始觉得不对劲。
第三阶段是“爆盘期”。一旦你用 Codex 处理了大量长上下文任务、反复重试失败请求、升级过好几个版本，目录就会突然跳到十几个 GB。我的机器就是这样，某天磁盘直接亮红，一看才发现已经 20GB 了。
一个很典型的征兆是：你 Codex 用得越顺手，磁盘空间反而越吃紧。因为功能用得越多，会话记录和日志就越多。很多人以为是 Codex 本身卡了，其实是本地存储拖累了整体性能。
2. 手动清理为什么总翻车，CX Clear 又是怎么解决的
2.1 手动清理的三个翻车现场
在写工具之前，我试过好几轮手动清理，每一次都踩到同一个类型的坑。
翻车最惨的一次是我直接删了~/.codex/auth目录下的认证缓存。当时只想腾点空间，用力过猛，把登录状态一起干掉了。结果重新打开 Codex，进入需要重新认证的流程。关键是当时我手边没有备用 token，折腾了大半天才恢复环境。从那天起我就明白：清理工具说破天，安全永远是第一优先级。
第二次翻车是找错目录。Codex 的配置目录跟项目目录在磁盘上离得很近，我搜“codex 占用”的时候看到一篇帖子说可以删某个缓存目录，结果一激动把正在跑的项目源码目录给删了。虽然最后从 Git 里拉了回来，但那种绝望感我这辈子都忘不了。
第三次翻车是关于会话记录。我之前为了清理空间，把session目录里的老文件整目录删了。事后想复盘一个两周前的需求细节，发现历史全部为空，只能靠记忆硬扛。对话记录这个东西，平时觉得没什么用，真到需要翻的时候，丢了才叫痛。
2.2 CX Clear 的设计思路：安全等级优先
手动清理的痛点太明显了。所以我在设计 CX Clear 的时候，第一优先级不是“清理得多快”，而是“永远不要误删”。整个工具围绕三个原则来写。
第一个原则是白名单路径。CX Clear 只认 Codex 本身的目录结构，不会像某些通用系统清理工具那样扫描全盘。它内置了一套 Codex 目录清单，包括会话目录、日志目录、缓存目录、认证目录、临时目录等。不属于这个清单的一律不动，这样再也不用担心摸到项目源码。
第二个原则是三级清理策略。我把清理范围分成“安全级”“谨慎级”“激进级”。安全级只清理那些产生后就没任何价值的日志和临时文件；谨慎级会追加清理超过保留天数的过期会话记录；激进级才会碰缓存、旧版本残留这类层级更深的文件，但依然会跳过认证缓存。默认走安全级，新手不可能误伤。
第三个原则是 dry-run 先行。CX Clear 默认不会“说删就删”，它先扫描一遍，告诉你“我准备删哪些、每个占多少、删完能释放多少”，等你确认了再动手。所有操作都会先自动备份到用户目录里，万一发现删错了也能找回。
2.3 和“手动清理”“通用工具”放在一起比
很多人会问我：为什么不直接用手动清理，或者干脆装一个系统级的垃圾清理工具？我直接说结论：通用清理工具对 Codex 来说是“盲人摸象”。
手动清理的问题在于，它完全依赖你个人的记忆和判断。你不知道 Codex 内部哪些文件该留、哪些文件能删，全凭感觉。通用清理工具的问题在于，它只认“缓存”“日志”这种宽泛标签，不知道 Codex 的会话记录要保留多长时间、认证缓存动了会有什么后果。
| 对比项 | 手动清理 | 通用清理工具 | CX Clear |
|---|---|---|---|
| 是否了解 Codex 目录结构 | 否，靠经验 | 否，只认通用标签 | 是，内置完整目录清单 |
| 是否区分认证缓存与普通缓存 | 不区分 | 不区分 | 明确跳过认证缓存 |
| 是否支持保留天数 | 不支持 | 不支持 | 支持按天数保留会话 |
| 是否先预览再删除 | 否 | 部分支持 | 默认强制 |
| 是否自动备份 | 否 | 否 | 是 |
看清这个对比你就明白，CX Clear 不是“又一个清理工具”，而是针对 Codex 场景专门做的“定心丸”。
3. CX Clear 实操：从安装到第一次说走就走的清理
3.1 安装方式：一条命令还是手动编译
CX Clear 我写成了单二进制文件，尽量不依赖外部运行时。安装路径给了两条，你自己选。
第一条是直接拉取预编译脚本，适合绝大部分人。打开终端执行：
curl -fsSL https://example.com/cx-clear/install.sh | bash安装完之后验证一下版本：
cx-clear --version第二条是手动编译，适合想改源码、或者机器架构比较特殊的朋友。源码仓库里只有一个cx_clear.go主文件，依赖很少，直接用 Go 编译就行：
git clone https://example.com/cx-clear.git cd cx-clear go build -o cx-clear . sudo mv cx-clear /usr/local/bin/我个人的建议是：能直接用脚本就用脚本。因为 CX Clear 在安装脚本里会主动检测你的 Codex 目录实际位置，如果你通过 Homebrew、源码编译或者其他方式安装过 Codex，目录路径可能不在默认位置，脚本能自动适配。手动编译的话，这些判断逻辑就没了。
3.2 配置文件与关键参数解析
CX Clear 安装之后会在用户目录下生成一个配置文件，默认路径是~/.cx-clear.yaml。下面是我自己用的配置，每一行都有讲究。
codex_home: ~/.codex keep_days: 14 safe: enabled: true log_max_size_mb: 20 auth_cache: keep exclude: - projects/ report: output: ~/.cx-clear-report.jsoncodex_home是 Codex 的根目录，默认指向~/.codex。如果你把 Codex 安装在自定义路径，这一项必须改，否则后续扫描会扑空。
keep_days: 14是保留天数，意思是超过 14 天的会话历史会被视为“可清理对象”。这个参数我建议按使用强度调：如果你是重度用户，每天产生大量会话，保留 7 天足够；如果你是偶尔用，建议拉到 30 天甚至 60 天。我自己算过一笔账，一天的高强度使用大概会产生 150MB 到 300MB 的会话和缓存，保留 14 天就意味着本地会稳定在 2GB 到 4GB 左右，内存和磁盘的压力都比较均衡。
safe.log_max_size_mb: 20的意思是单个日志文件超过 20MB 就会被轮转压缩。这个值不是越大越好，也不是越小越好。太小会让日志频繁轮转，丢了排查问题需要的现场；太大又会让日志膨胀。我实测下来 20MB 是一个比较舒服的点。
auth_cache: keep这行是保命符。它强制 CX Clear 在清理时跳过认证缓存，无论你后续用了什么清理参数都不会删除登录状态。
exclude下面可以写你要排除的目录。比如你有~/.codex/projects/目录，里面放着重要的项目文件，把它写进排除列表，CX Clear 就永远不会碰它。
3.3 第一次运行：先扫描再清理，别急着动手
装好之后，第一次运行建议先做一次只读扫描。命令是：
cx-clear scan执行完你会看到一份类似下面的输出：
Codex 根目录: /Users/me/.codex 会话历史目录: 4.2GB，共 18352 个文件 日志目录: 862MB，其中超过 20MB 的日志 7 个 临时文件目录: 1.1GB 认证缓存: 12KB（跳过） 预估可安全释放: 5.9GB看到这份报告，你就对 Codex 的占用结构有了明确认识。有些人跑到这一步就慌了，以为“可以把这 5.9GB 全删了”。别急，先看看里面有没有你想留的会话记录，如果都无所谓，再走下一步。
真正执行删除前，CX Clear 会再让你确认一次，我建议每次都开 dry-run 模式：
cx-clear clean --dry-rundry-run 模式下，它会把“将要删除的文件清单”完整列出来，包括每个文件的具体路径和大小。我建议第一次用的人老老实实过一遍这个清单，确认里面没有自己正在使用的工作目录，然后才执行正式清理：
cx-clear clean正式清理结束后，CX Clear 会生成一份清理报告，记录总共删了多少文件、释放了多少空间、备份文件放在哪个位置。这份报告默认写到~/.cx-clear-report.json，方便你以后追溯。
3.4 实操效果与踩坑记录
我自己第一次跑完整清理时，输出是这样的：
已释放 5.8GB 已备份 328 个文件至 /Users/me/.cx-clear-backups/2025-06-01/ Codex 当前目录占用: 14.3GB五分钟之内把 Codex 的占用从 20GB 打到了 14.3GB。注意，释放的空间主要来自日志和临时文件，因为我的会话记录设置了 14 天保留，最近两周的几千个文件都还在。之后我又把keep_days调到 7 再跑了一次，又多释放了 2.6GB。最终稳定在 11GB 左右。
踩的坑也要说一句：如果你的 Codex 目录路径里有中文或者空格，跑扫描的时候可能会报路径解析错误。遇到这个问题，不用慌，编辑~/.cx-clear.yaml，把codex_home改成绝对路径，同时用引号包起来就行。还有一个常见问题是 Codex 进程正在运行时清理日志文件，Unix 系统下进程依然持有文件句柄，虽然不会删失败，但释放不了磁盘空间。CX Clear 检测到这种情况会在报告中提示你“当前有 3 个日志文件被进程占用”，这时候最稳妥的做法是先退出 Codex，再执行一次清理。
4. 清理后的常见问题与排查实录
4.1 报错：cc switch local proxy failed while handling codex endpoint /responses
最近在社区论坛里看到不少同学在问同一个报错：
cc switch local proxy failed while handling codex endpoint /responses. provided ...先说这个报错的本质。它发生在 Codex 请求/responses接口时，本地代理切换失败，导致网络请求无法继续。很多人问“是不是我清理 Codex 清出了问题”，我可以负责任地说：这个报错跟本地磁盘清理没有直接关系，它属于网络层的环境问题。
排查步骤我按照优先级整理了一下。
第一步，检查 Codex 版本。老版本在代理切换逻辑上确实有 bug，建议把 Codex 升级到最新版再观察。
第二步，检查本机网络代理配置。Codex 会读取系统代理设置和环境变量，如果你的本地代理服务没有正常启动，或者配置的代理地址已经失效，就会出现这个报错。重点看HTTP_PROXY、HTTPS_PROXY、ALL_PROXY这几个环境变量，以及系统网络设置里“代理”那一栏有没有指向一个实际存在的端口。
第三步，检查 Codex 自己的配置文件里有没有设置代理。找到~/.codex/config.toml，看看有没有类似proxy或http_proxy的字段。如果有，先注释掉，让 Codex 走系统默认网络配置，再试一次。
第四步，如果确认是本机代理服务出了问题，那就需要重启代理服务并确保它监听的端口跟 Codex 配置里写的一致。注意，这里讲的是正常的企业代理、本地调试代理这类合法网络工具，别想歪。
第五步，也是最简单的验证办法：临时把代理相关的环境变量全部清空，重新运行 Codex 测试是否恢复正常。如果恢复正常，基本可以确认是代理配置冲突导致的。
unset HTTP_PROXY unset HTTPS_PROXY unset ALL_PROXY codex run这个报错的根源在 Codex 的网络模块，不在清理工具身上。所以别再把锅甩给 CX Clear 了。
4.2 清理后发现自己被登出了、会话记录找不回来
有一类问题是清理之后 Codex 要求重新登录。出现这个情况，大概率不是 CX Clear 的默认操作导致的，而是你手动调整了清理参数，把认证缓存放进了可以清理的范围内。CX Clear 默认会跳过auth_cache，但你如果用了“激进级”清理模式，并且在配置里关了auth_cache: keep，那确实可能清掉登录态。
解决方式很简单：重新登录一次 Codex 就行。如果当时手边没有可用的 token，也可以去 Codex 的官方渠道重新获取。但从效率角度讲，我强烈建议不要动认证缓存这个开关，每次清理都让它稳定跳过，省得给自己找事。
关于会话记录找不回来，我也要强调一下：CX Clear 的清理策略默认是“按保留天数删除”，一旦超过keep_days，文件会进入备份目录而不是立刻物理删除。所以遇到删除重要会话的情况，第一件事是去~/.cx-clear-backups/里找。我自己的备份路径是：
ls ~/.cx-clear-backups/备份目录按日期分文件夹，找到对应日期的文件夹，把里面的文件复制回~/.codex/session/就能恢复。这也是 CX Clear 和其他清理工具最大的区别：不是“删了就没了”，而是“先备份再清理”。
4.3 典型问题速查表
我把这段时间遇到的问题整理成了一张表，留着以后再犯错就翻看一眼。
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
Permission denied | 用户对 Codex 目录没有写权限 | 用chmod -R修改目录权限，或让 CX Clear 以当前用户身份运行 |
| 清理后磁盘没有明显减少 | Codex 进程还在运行，文件句柄未释放 | 退出 Codex 后重新执行cx-clear clean |
| 找不到 Codex 根目录 | codex_home配置错误 | 用which codex或find定位实际目录 |
| 备份目录越来越大 | 每次都开启备份且从未清理 | 定期删除 30 天前的备份文件夹 |
| 日志文件删不干净 | 日志文件还在被工具内部线程写入 | 等 Codex 完全退出后再跑一遍安全级清理 |
| 误删了重要会话 | keep_days设置小于实际需求 | 去备份目录恢复，同时调大keep_days |
这张表我每次看都有新发现。尤其是“清理后磁盘没有明显减少”这一条，很多人的第一反应都是“工具没生效”，其实只是进程还活着，文件没法真正释放。先退出应用再跑清理，是很多场景的万能解。
5. 进阶玩法：把 CX Clear 变成自动化的日常习惯
5.1 用后台任务定时清理
清理工具做得再好，如果每次都要手动跑，你还是会忘记。我自己就把 CX Clear 挂到了后台任务里，每周自动跑一次安全级清理，只删日志和临时文件，保留会话历史。仅供参考的配置如下：
crontab -e加入一行：
0 3 * * 1 /usr/local/bin/cx-clear clean --level safe --non-interactive >> ~/.cx-clear.log 2>&1意思很简单：每周一凌晨 3 点，执行一次安全级清理，不弹交互确认，日志写入文件。
有一个小坑要提醒：如果你的电脑在凌晨 3 点是关机或者睡眠状态，这个任务就错过了。最简单的方式是再写一个 crontab 条目放在工作日的早高峰前。我自己的做法是周一到周五每个工作日早上 9 点都挂了一个安全级清理，反正它跑得很快，释放空间也就几秒钟，根本不打扰我工作。
macOS 用户要注意，如果你开了“电池优化”，后台任务的执行可能会被延迟。我自己没在这个问题上纠结太久，因为只要任务在某个时刻能执行一次，就能把磁盘空间控制住。不追求“必须精确到分钟”，追求“长期稳定执行”。
5.2 保留策略调参心得
想说说keep_days怎么调。我一开始追求极致清理，直接设成keep_days: 1，结果每天都要面对会话历史被清空的问题。后来我把参数放宽到 14 天，不仅满足了复盘需求，日常使用也没再因为磁盘空间报警。
如果你问我“应该保留多少天”，我建议按这个思路来定：先想清楚你多久需要回看一次历史对话。一天对话都不用回看的，设 3 天；偶尔复盘技术方案的，设 7 到 14 天；习惯性追溯细节、经常翻旧账的，设 30 天以上。对应的磁盘占用都在可控范围，因为 CX Clear 会同步清理临时文件和日志，把总量压在一个稳定水平。
最后再分享一个细节：我在 CX Clear 里专门写了“清理前生成报告”的功能。每周定时任务跑完，我会抽空扫一眼~/.cx-clear-report.json，看看最近一周释放了多少空间、备份了多少文件。这不仅帮我把握磁盘的消耗速度，还能让我及时发现 Codex 有没有异常膨胀。如果某周释放量突然翻了三四倍，我就会去翻一下 Codex 本身的日志，排查是不是有重复任务在空转。这个过程用下来，Codex 的占用一直维持在一个健康的范围内，我再也没有经历过“磁盘突然爆红”的惊吓。
说到底，工具再省事，也要解决真实场景里的具体问题。CX Clear 能替我做的，是把 Codex 清理这件“小而不小”的事，从依赖手感和记忆的玄学，变成有规则、有备份、可追溯的日常流程。如果你也在被 Codex 的磁盘占用折腾，顺手装上跑一次扫描，你会回来感谢这篇教程。
