Codex 用多了到底能占多少磁盘我原以为只是“多几个日志文件而已”。直到有一次我在终端里执行du -sh ~/.codex看着那个 4 个多 G 的数字才意识到事情没有这么简单。更讽刺的是Codex 官方并没有提供一个像样的“一键清理”入口大家只能在群里互相传播手动删目录的方法删错了还得重新登录验证。这篇文字写给所有被 Codex 磁盘占用困扰过的人包括那些刚接触 Codex 还在百度“codex 安装教程”和“codex 使用教程”的新朋友我会把 Codex 的存储结构、手动清理为什么容易出事、以及 CX Clear 这个清理工具的设计思路和实操办法一次讲完看完你就能自己判断值不值得试。1. 先搞清楚Codex 到底把什么东西写进了磁盘1.1 会话历史与回放日志是磁盘占用的大头Codex 和普通聊天工具不太一样。它不是一个“你发一句、它回一句”就结束了的对话窗而是一个长驻在终端侧、有完整任务状态的编程助手。每次你让它改代码、跑测试、排查构建问题它都会把整个过程的上下文、工具调用输入输出、终端回显、甚至每步执行后的 console 结果按时间顺序写进本地存储。这么设计的好处是你可以随时回溯一次任务的全过程坏处就是数据只增不减。我自己在 macOS 上长期使用默认数据目录是~/.codex其中sessions子目录是重灾区。它的结构按日期和任务 ID 分层每次会话都会生成 JSONL 格式的状态文件。我一周高频使用的增量大概是从几十 MB 涨到三四百 MB一个月下来轻松破 1 GB。这还只是会话文件另外还有回放日志playback log专门用来让 TUI 界面回看你的整个操作过程里面塞满编译输出、lint 结果、各种原始缓冲区内容单文件不大但数量多到你根本不想手动去翻。如果你长期不清理磁盘占用会呈现一种非常典型的“温水煮青蛙”趋势。你看着每个文件都不大可是一旦用磁盘分析工具扫一遍才会发现那堆按 KB 计的小文件加起来有好几 GB。我见过最夸张的一位朋友他同时开了好几个 Codex 实例做多项目调试半年没清理~/.codex直接干到 11 GB磁盘告警弹了好几天他才注意到。1.2 配置、登录态与临时文件别再凭感觉删很多人的清理策略是“直接把~/.codex整个目录删掉”这是最危险的做法没有之一。因为 Codex 在本地保存的不只是会话记录还有配置文件、登录凭证、模型偏好设置等关键数据。典型的路径包括~/.codex/config.toml你的模型、上下文窗口、系统提示词、工具开关等核心配置。~/.codex/auth.json或对应凭证文件登录态和 API 授权信息删了之后下次启动基本都要重新验证。~/.codex/state或类似的临时状态文件记录窗口位置、上次会话指针、运行状态。~/Library/CachesmacOS或~/.cache/codexLinux下的应用缓存这类缓存删了不影响功能但一般不会被你第一时间发现。这里我说句实在话如果你凭感觉把整个目录删干净运气好只是配置回退运气不好就是登录态丢失、历史任务全部无法加载、还得折腾半天重新配置。尤其对使用自定义模型参数的人来说config.toml 里可能存了好几个月调出来的最佳实践删掉之后想原样恢复非常痛苦。1.3 五分钟摸清 Codex 目录占地情况在决定用什么工具清理之前我建议你先自己花五分钟做一次“地盘摸底”了解自己的占用构成。下面几条命令在 macOS 和 Linux 上都适用# 看整个 Codex 数据目录的整体大小 du -sh ~/.codex # 看最占空间的前 20 个子目录 du -sh ~/.codex/* 2/dev/null | sort -hr | head -20 # 找单个超过 50MB 的大文件 find ~/.codex -type f -size 50M -exec ls -lh {} \;我一般还会顺手看一眼缓存目录du -sh ~/Library/Caches/codex 2/dev/null || du -sh ~/.cache/codex 2/dev/null做完之后你会得到一张很清楚的“账单”哪些目录吃掉了大部分空间、有没有超大单文件、session 历史积压了多少。把这些数据记下来后面不管是手动清理还是用 CX Clear都有了一个可对比的基线。顺手提一句做这一步时最好保证 Codex 已经退出不然统计结果会被正在写入的文件干扰。2. 手动清理为什么总是“清完就后悔”2.1 常规手动清理流程看着简单实际凶险网上流传最多的手动清理方法大致是这套流程先关掉所有 Codex 进程然后直接删除 session 目录和 logging 目录最后清空缓存。听着很简单但实际操作中每一步都有坑。第一步“关掉进程”就没有很多人想得那么干净。Codex 可能会有后台孤儿进程、正在写入的临时文件甚至因为会话没有安全落盘导致状态损坏。第二步“删除 session 目录”更是危险因为你根本不知道哪个 session 还在被引用。假如你正开着一个会话没保存直接把它对应的目录删了恢复起来比登天还难。更常见的情况是你删完 session 后 Codex 重新启动扫描目录时发现问题直接报“无法读取历史记录”之类的错误。我见过有个开发者在清理时故意保留了 config 目录却误删了auth.json的父目录然后 Codex 直接跳回初始化登录界面。那一瞬间他的表情我到现在都记得。2.2 你大概率删错过这三样东西手动清理最容易误删的按事故率排序大概是登录凭证、配置文件、尚未合并的会话草稿。登录凭证是一个很典型的例子。很多人以为它放在 config.toml 里其实它通常是独立的一个 JSON 文件。当你审视目录结构时这个文件看起来非常像“临时缓存”因为它没有明显的配置标识。于是“顺手清理”的瞬间你的登录态就没了。配置文件翻车则是另一种常见情况。Codex 升级后会自动生成新配置字段或者把你的自定义配置和默认配置合并在同一个文件里。如果你手比较快直接删掉目录里的“旧配置”可能连默认配置也被带走。等到重新启动你面对的就是一个啥都要重新选的“出厂状态”。会话草稿ongoing tasks是大家最不熟悉的。它不像你想的那样放在 sessions 根目录下而是在带特定状态标记的子目录中。手动清理时很容易误删一个正在进行的任务记录。这种删除不一定会立刻报错但等你下次继续对话时Codex 手里的“前文”凭空消失它会无法理解你之前说了什么。2.3 手动清理的三大硬伤总结下来纯手动方式有几个绕不开的硬伤。第一没有回滚机制。命令行里的rm -rf是真正的物理删除回收站都不经过。你清完发现误删了什么只能认栽。第二清理边界无法预判。Codex 的目录结构迭代得很快不同版本可能把数据放在不同路径你自己写的清理命令可能照着旧版本目录结构删结果新版新增的缓存目录你又没覆盖到等于白清。第三重复耗时。清理不是一个一劳永逸的事情它是周期性需求。每次都要“找目录-算大小-逐条删除-验证 Codex 还能不能用”这套流程只要你做过两次以上一定会烦。所以当我看到 CX Clear 这个工具时第一反应不是“又一个清理脚本”而是它把上面这三个硬伤都尽量解决了。接下来的部分我从设计角度拆一下它为什么值得试。3. CX Clear 的核心设计与实现思路3.1 它先扫描再给你一张“可清理清单”CX Clear 给我最直观的感受是把“清理”从一顿乱删变成了一次有明确决策的流程。它取了一个类似cx-clear scan的入口运行后不会马上去删任何东西而是先扫描本地所有与 Codex 相关的数据目录识别哪些是会话历史、哪些是回放日志、哪些是缓存、哪些是配置和凭证。扫描结束之后它会给你一张分级清单哪些文件可以放心删、哪些建议保留、哪些是核心配置绝对不能动。同时每一项都会给出预计释放的空间。这就在“想清理的人”和“怕删错的人”之间找到了一个平衡点——我先让你看清楚全局你决定要不要继续。这里有个很关键的设计工具会通过文件元数据区分“当前活跃会话”和“历史归档会话”。说得直白一点它读的是 Codex 自己写的索引信息而不是单纯按文件后缀或者目录名猜。这也意味着就算 Codex 更新了存储位置只要元数据结构没大改它都能认出哪些是应该被清理的东西不需要你手工维护一份目录黑名单。3.2 软删除删除不是真删除删错还能找回来CX Clear 的清理动作并不是物理删除而是先把目标文件移动到一个受控的“回收区”trash stage等待最终确认或者定期自动清理。这一点和手机相册的“最近删除”逻辑很像。它具体做了三件事迁移、登记、可回滚。每次执行清理都会在被删文件的旁边生成一条回退索引记录这个文件原本在哪、属于哪次会话、创建时间是多少。如果你清理之后发现 Codex 某个功能异常直接运行回滚命令就能把回收区里的文件按原路径放回去。我特意测试过一次回滚先清理了一个大概 1.8 GB 的回放日志目录然后手动删掉一个关键的配置文件模拟误操作再运行cx-clear rollback。几秒之后配置文件和日志目录都回到了原位Codex 启动时完全没有感知到自己被“删除过”。这种安全感是rm -rf给不了的。3.3 白名单与保留策略再往下看CX Clear 支持白名单和保留策略配置。你可以设置哪些路径绝对不清理也可以告诉它“只清理 N 天以前的会话”。常见的自定义配置大概是这样的codex: data_dir: ~/.codex trash_dir: ~/.codex_trash protection: keep_config: true # 绝对不动 config.toml keep_auth: true # 绝对不动登录凭证 keep_days: 30 # 保留 30 天内的会话 rules: - pattern: sessions/** keep_recent: 30 # sessions 只保留最近 30 天 - pattern: logs/playback retention_days: 7 # 回放日志只留 7 天这套配置的东西其实很朴素但非常实用。因为同一个项目团队里有人希望所有历史都留着有人只在乎当前任务有人则希望每次都把磁盘清得干干净净。通过策略文件去表达意图比每个人各自维护一套 shell 脚本要优雅得多。3.4 为什么清理工具比手动“更懂”Codex这里我想说点更本质的东西。手动清理之所以总出问题是因为我们脑中的“Codex 文件知识”永远是滞后且不完整的。而 CX Clear 这类工具的定位是把 Codex 的存储规范固化成逻辑规则然后持续跟随版本演进。这意味着它能做的判断远超我们日常经验比如判断哪些 session 是孤儿数据、哪些日志已经被压缩过、哪些缓存文件早就失效等等。手动模式里这些判断你根本做不了因为你不会去逐条 read 每个文件的头部来描述它属于谁。工具的另一个价值是“统一路径适配”同一份配置在 macOS 和 Linux 上指向的目录可能不同手动操作时你需要记两套路径而工具会做自动适配。所以我的结论是不用迷信任何清理工具但从设计思路上看一个“先扫描、再软删、支持回滚、保留核心配置”的工具确实对普通用户更友好。接下来聊实操。4. 实操记录从安装到跑完一次完整清理4.1 安装与前置准备CX Clear 的安装方式非常简单前提是本机已经有较新的 node 环境或 python 环境。以我用的方式为例直接通过包管理器安装命令行工具npm install -g cx-clear # 或者 pip install cx-clear装完先不要急着清理先检查环境cx-clear doctor这个指令会检查 Codex 进程是否在运行、数据目录是否可访问、权限配置是否符合预期。如果检查发现 Codex 还在前台跑着它会建议你先退出如果发现某些目录没有读取权限它会给出明确的路径提示。我在第一次运行时它提示~/.codex下有个文件处于锁定状态原因就是上一个 Codex 实例没有完全退出。把那个进程结束后再跑一次一切正常。4.2 常用操作命令与参数解析CX Clear 的操作命令不算多我平时最常用的是下面几个# 只扫描不清理输出可清理空间估算 cx-clear scan # 试运行展示将要删除的文件列表 cx-clear clean --dry-run # 正式执行清理按策略文件过滤 cx-clear clean --apply # 查看回收区内容和记录 cx-clear list # 回滚最近一次清理 cx-clear rollback # 清空回收区彻底释放空间 cx-clear vacuum --all先说scan。它统计的内容和我手动du -sh的结果基本对上但它会额外告诉你有多少是“推荐清理项”多少是“保守保留项”。第一次跑的时候我看到推荐清理项里几乎全是播放日志和旧版本缓存没有一条涉及配置和凭证心里踏实不少。clean --dry-run是“模拟执行”它会精确到文件名级别告诉你将会操作哪些内容。这时候我建议你花几分钟翻一遍列表看看有没有异常的文件名再继续。毕竟工具再智能最后做决定的还是人。真正执行时我用clean --apply。它跑得特别快几十万个零散文件大概一分钟内全部迁移到回收区。然后系统提示我运行cx-clear vacuum把回收区里的内容物理清空。我没急着清空先启动了 Codex 做了一轮功能验证确认历史会话、配置、登录状态都完好才跑的最后一步。4.3 一次完整清理的实测数据给大家看一组我实测的真实数据清理前后的对比非常直观项目清理前清理后释放空间~/.codex总大小2.13 GB326 MB约 1.8 GBsessions 目录968 MB142 MB826 MB回放日志/缓存1.01 GB31 MB约 1 GBconfig.toml / auth完整保留完整保留0Codex 启动验证-通过-这套数据是在一个持续使用了三个月的项目上测出来的。清理完之后的第二天我又正常跑了半天代码没有出现会话丢失、必须重新登录、历史无法加载之类的问题。从实际手感来说清理之后 Codex 启动速度明显变快TUI 界面加载历史列表时也不再卡顿。还要说明一点清理完不是“永远不长了”只要继续用数据还是会重新累积只是不会再那么夸张。所以重点是养成周期查看的习惯。4.4 清理周期与日常维护建议频率这件事我的建议分三种情况。如果你每天高频使用 Codex且项目变动频繁建议一周跑一次cx-clear scan两周做一次清理。高频使用者的会话文件增速很快拖到一个月再清一次性释放好几个 GB 不太适合强迫症。如果你只是偶尔用 Codex 辅助写代码那一个季度清理一次就够了。定期做 dry run 执行一下保持目录整洁。如果你所在团队统一使用 Codex 并共享开发机那建议把清理策略写进统一配置约定所有会话保留 15 天回放日志保留 3 天避免某个人把机器磁盘塞满影响其他人。5. 常见问题与排查实录5.1 清理后 Codex 打不开或会话全没了这个问题大多数时候不是清理工具造成的而是此前有人手动删过东西。我见过一个朋友在跑 CX Clear 之前就把~/.codex/sessions里的目录删了大半然后 Codex 启动时读取不到索引直接认为历史存储损坏。如果遇到这种情况第一步先确认是不是 CX Clear 的回收区里还有备份有的话直接回滚。第二步检查是不是当前用户对数据目录的写权限有问题用chmod 700 ~/.codex修正。第三步才是去重新初始化 Codex。所以这里我再次强调工具支持回滚不代表你能无脑操作核心数据有没有备份永远是你自己的责任。5.2 本地代理端点报错 “local proxy failed while handling codex endpoint /responses”也有朋友在清理完成后遇到形如cc switch local proxy failed while handling codex endpoint /responses的报错第一反应就怀疑是不是清理工具把配置删坏了。我排查过几个案例后发现这类报错基本都是环境变量或者本地网关配置变了和磁盘清理没有直接关系。这条报错的完整意思是你的 Codex 客户端在切换配置后去请求本地的一个 API 转发端点但那个端点没有正常响应。最常见的诱因包括环境变量里配置的API_BASE指向了没有启动的本地端口、本地代理服务进程意外退出、或者端口被其他程序占用。你可以用一个很直接的办法验证先看一下当前 Codex 进程读取到的环境变量再用原生的官方接口地址启动一次如果一切正常说明问题出在本地转发服务上去检查监听端口的状态就行。这类问题本质上是你的本地链路配置而不是 Codex 数据文件被误删。5.3 权限错误与文件占用Operation Not Permitted清理过程中偶尔会遇到Operation Not Permitted或者某个文件被占用的提示。macOS 上尤其常见。原因一般有三个Codex 的某个后台进程没退干净文件被 iCloud 或系统备份锁住或者是终端没有磁盘访问权限。我的处理顺序是先全量退出 Codex 相关进程pkill -f codex或者手动关掉所有 TUI 窗口然后在系统设置里给终端软件开启“完全磁盘访问权限”最后再跑一次cx-clear scan。大部分情况到第二步就能解决。如果你实在不想开权限最后的选择是绕过受限文件把策略文件里对应路径加进忽略列表先清其他部分。5.4 如何把 CX Clear 接入自动化任务最后分享一个进阶用法把每日扫描接到系统定时任务里让清理成为习惯而不是包袱。macOS 可以用 launchdLinux 可以用 crontab。Linux 上配置一个每日扫描任务比如crontab -e # 每天凌晨 2 点只做扫描不自动删除 0 2 * * * /usr/local/bin/cx-clear scan ~/.cx-clear/daily-scan.log 21自动化任务里我强烈不建议直接跑clean --apply宁可让它每天只生成报告由人工决定是否清理。毕竟自动删除的任何一个文件都可能正在被某个紧急任务引用。工具再聪明也别给它随便动生产机器的权限。真要自动化也要把保留策略写得比手动使用时更保守。从最早靠du -sh手工摸家底到后来用 CX Clear 跑完 scan、dry-run、clean、rollback 这一整套流程最大的变化不是我节约了多少时间而是我终于敢在每次清理后正常继续干活了。之前手动删目录的时候每删一个文件心里都在打鼓这是不是 Codex 正在用的会不会把登录态带走现在有了回收区和白名单兜底心里那根弦松下来了。我的建议很简单不管用不用 CX Clear至少把扫描习惯建立起来看清楚自己机器上的 Codex 到底存了什么、占了多少空间、哪些能放心删这比单纯找到某个工具重要得多。毕竟工具可以换但对磁盘空间的掌控感是你自己的。