前两天准备导出一份演示录像系统突然提示“磁盘空间不足”。我打开存储一看好家伙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 21意思很简单每周一凌晨 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 的磁盘占用折腾顺手装上跑一次扫描你会回来感谢这篇教程。