用了一段时间 Codex 做日常编码辅助之后迟早会撞上一个特别现实的问题磁盘空间肉眼可见地往下掉。我把 Codex 的安装目录、会话记录、日志、认证信息全部摊开看了一眼整理出一条规律Codex 用完之后的“残留”远比你想象的分散而其中sessions和log这两个目录往往占据最大头。手动清理当然也能做但很容易踩坑删错配置导致下次启动回到“新手状态”或者把某个项目的会话上下文误删让之前的断点续跑全部失效。CX Clear 就是专门解决这个问题的清理工具核心思路不是“把~/.codex整个删掉”而是通过诊断、分级、dry-run 确认、再执行清理把该留的和该删的分开处理。这篇文章我会从 Codex 本地数据到底存在哪里讲起再拆解 CX Clear 的设计逻辑、完整实操流程和常见的坑。无论你用的是 Codex CLI、桌面版还是 VSCode 插件只要被磁盘占用问题困扰过这篇内容都值得看完。1. 先搞清楚问题Codex 到底把空间吃在了哪里1.1 Codex 本地目录的整体结构先说结论Codex 的所有本地数据基本围绕一个家目录展开。在 macOS 和 Linux 上通常是~/.codexWindows 上对应的大致位置是%USERPROFILE%\.codex。里面一般能看到这些关键内容config.toml主配置文件模型映射、服务地址、行为开关都在这。auth.json登录凭证用于验证你的账号身份。log/启动日志、请求日志、工具调用记录。sessions/每次对话的完整历史与会话状态。各种缓存目录模型上下文缓存、临时文件、索引数据等。很多用户只盯着安装包本身却忽略了一个事实Codex 作为一个 AI 编程代理每次会话都会把系统提示、用户消息、工具调用记录、文件补丁等内容持久化到本地这是它能够“接着上次继续干”的基础。你每跑一个 Agent 任务它就会同步写一大批日志每处理一次较大的仓库它就会读取并缓存大量文件内容。所以只要你持续使用这些本地数据就一定会持续增长而且增长速度跟任务复杂度强相关。1.2 日志和缓存是占用最猛的两块日志是我实测下来增长最快的一部分。Codex 在跑一个中等复杂度的重构任务时可能触发几百次内部工具调用每一次调用都会在log目录留下一份 JSON 请求记录。一次完整流程跑完日志体积从几 MB 涨到几十 MB 太常见了。如果你像我一样习惯同时挂多个任务窗口日志累积几个 G 是很轻松的事。缓存则更隐蔽。Codex 会对上下文片段做本地缓存尤其是反复读取的文件内容、模型 prompt 模板、工具返回结果。这些缓存往往没有直观的“会话”概念而是散落在各类临时目录中普通用户根本不会注意到。但它们的体积同样不容小觑尤其是当你长期使用同一个大型代码仓库时缓存会在后台一点点膨胀。1.3 会话历史与断点续跑不能随便删的部分与日志、缓存不同sessions目录保存的是你和 Codex 的对话历史以及任务现场。一旦删掉之前任务的上下文就没了。这里要特别提醒Codex 的会话不只是聊天记录它承载了工作现场。比如一个执行时间较长的 Agent 任务Codex 可能依赖本地会话上下文来恢复执行状态。如果你手动清理时“一刀切”轻则重新登录重则下一个计划任务直接失去上下文。真正安全的清理逻辑应该是日志可以定期清缓存可以按保留时间清会话保留最近 N 条、只清理超出保留策略的旧会话认证信息默认绝不能动。这才是清理工具应该做的分层策略。1.4 为什么手动清理容易误伤手动清理最大的问题不是“删不干净”而是“删不准”。很多人习惯用rm -rf ~/.codex/log直接怼日志目录表面上释放了空间下一次会话启动时 Codex 会重建日志目录看起来没什么影响。问题出在顺手动了config.toml或auth.json时Codex 会直接抛出unrecognized configuration setting之类的告警或者要求你重新登录。我在各种讨论里看到“无法加载组织设置”“正在重新连接”“某个模型在当前账号下不被支持”这类报错很多都是在配置或缓存半残状态下产生的。手动清理说到底是碰运气CX Clear 的价值就在于把清理动作变成可控、可回看、可筛选的工程操作而不是开盲盒。2. CX Clear 的核心设计按安全等级清理而不是简单删除2.1 按安全等级分组的原则CX Clear 把 Codex 本地数据分成几个安全等级组可清理组日志、临时文件、旧缓存删掉不影响功能。受保护组会话目录保留最近 N 条。敏感组auth.json、config.toml默认跳过除非你显式指定。扩展数据组VSCode 插件、桌面版产生的额外数据。这种分组方式解决了一个核心矛盾同一个目录下不同文件的安全含义完全不同。比如sessions目录里的当前会话和三个月前的历史任务风险等级就不一样。手动清理时根本没人会逐文件判断CX Clear 通过扫描规则替你做这个判断。为什么强调“分组”而不是“目录级”因为 Codex 的目录结构在不同版本和不同安装方式下并不固定。CLI 版、桌面版、VSCode 插件版各自维护着类似但不同的数据目录。如果按目录硬删很容易漏掉某个隐藏配置或者误伤另一个版本的数据。2.2 dry-run 先行先看再删CX Clear 最让我满意的功能之一就是 dry-run。它会在清理前扫描所有目标文件按分类统计数量和大小然后输出一份“如果执行清理会删除哪些文件释放多少空间哪些文件会被跳过”的报告但不会真正动手。这个设计的逻辑非常朴素让用户先看到后果再确认。很多人不愿意用清理工具就是怕它“太聪明”自作主张。dry-run 把决策权交回用户手里。我每次实际清理前都跑一遍既能掌握这次清理的量级又能确认扫描结果里没有auth.json这类敏感数据心里踏实很多。2.3 保留策略与审计输出把维护固化下来CX Clear 支持通过配置文件设置保留策略。比如sessions可以设置“保留最近 20 次会话”缓存可以设置“仅清理超过 7 天未访问的文件”。这个机制相当于把你平时手动判断的逻辑固化下来以后每次清理都自动应用同一套标准不会因为某天心情好就多删一点、某天赶时间就少删一点。另外每次清理它都会输出审计日志记录清理时间、清理对象、释放空间大小和跳过的敏感项。这个细节对长期维护价值很大一旦清理后出现问题你可以回溯到底是哪一类文件被动过而不是凭记忆猜测。2.4 多端数据一并纳入扫描很多人不知道Codex 桌面版的数据路径和 CLI 版并不完全重叠有些数据甚至会写到不同的用户级目录。CX Clear 的目标不是只清理~/.codex下的文件而是把 CLI、桌面版、VSCode 插件产生的缓存、日志、临时文件统一纳入扫描范围。我第一次用它的扫描功能时就发现光 VSCode 插件的扩展日志就占了几百 MB这是手动清理时很容易漏掉的部分。3. 实操记录从安装到清理的完整流程3.1 安装与初始化安装很简单一般用包管理器一条命令就能搞定比如通过 npm 全局安装。装上之后先跑一次初始化命令它会自动探测 Codex 的数据目录把当前目录结构和可清理项列出来。第一次跑的时候它会提示发现了多个 Codex 数据源包括 CLI 配置目录和桌面版数据目录这时候直接用默认全选即可。这里有个注意点如果初始化时提示版本不匹配通常是因为本机同时存在多个 Codex 入口比如 CLI 是 npm 版桌面版是独立安装的正式版导致版本标记不一致。解决办法是先确认你平时主要用哪个入口再让清理工具以那个版本为准避免误判。3.2 先跑一次诊断像看体检报告一样初始化完成后的下一步是扫描。执行扫描命令后输出会按分组列一张明细表分组路径示例当前大小建议策略日志~/.codex/log/*.log1.8 GB可清理临时缓存缓存目录520 MB可清理7天以上会话历史~/.codex/sessions/940 MB保留最近 20 条认证数据~/.codex/auth.json微量跳过扩展日志VSCode 插件日志320 MB可清理我实际跑完最惊讶的是日志部分本机四个多 G 的占用里日志和扩展日志合起来就占了一大半。这也解释了为什么之前手动清理总觉得没效果只清sessions目录根本动不了大头真正的增长源在日志体系里。3.3 执行清理先用 dry-run 确认再动手建议的习惯是先跑一次 dry-run 查看报告确认没有意外项尤其是敏感组必须显示跳过。之后才执行实际清理一般几十秒内完成结束时输出释放空间总量。我实测清理后Codex 冷启动速度有一定提升因为启动时要加载的日志和缓存变小了磁盘释放幅度则取决于两次清理的间隔我隔一个月清理一次单次释放 2~4 GB 很常见。如果只想清理某一类数据可以通过分组参数控制。比如只清日志就指定日志组想连同旧会话一起清理就指定会话组并加上保留数量参数。这个保留数量参数很关键它会让你保留最近 N 次会话避免一次性把历史全干掉。3.4 清理后的健康验证清理完不要立刻关终端建议做两步验证。第一步用健康检查命令重新检查目录结构确认关键文件还在第二步启动一次 Codex 并随便问一句话确认能正常加载配置。我踩过几次坑之后养成了习惯清理完一定先跑一次真实会话而不是只看目录大小有没有变小。如果清理后发现登录失效先别急着重新登录。检查auth.json是否还在如果文件存在大概率只是缓存被清掉后 Codex 要重新握手重跑一次登录流程就能恢复。核心原则是少删凭证多留心跳。3.5 长期维护定时任务与日常习惯手动清理最大的问题不是工具不行而是人会忘。所以我在体验稳定后把清理做成了定期任务。在 macOS 和 Linux 上可以用 cron 跑每周一次 dry-run、每月一次实际清理Windows 上用计划任务也能达到同样效果。脚本逻辑很简单先扫描结果输出到日志文件超过设定阈值才真正执行清理。这样既能防止磁盘悄悄占满又不会因为清理太频繁而降低缓存命中率。坚持这个习惯两三个月之后我的 Codex 目录基本能稳定在 1 GB 以下而以前动不动冲到 5 GB 以上。把清理自动化比临到磁盘告急再到处找大文件要省心太多。4. 常见问题与排查技巧实录4.1 清理后 Codex 重新要求登录这个问题出现频率不低原因很简单清理时把auth.json之外的认证状态文件比如某些临时 token 缓存或握手状态当成“可清理”对象处理了。解决办法是保留auth.json原样并在清理时使用排除参数把敏感组永久跳过。如果已经发生登录失效直接重新登录 Codex 即可不会影响历史项目文件最多丢一些本地缓存状态。更稳妥的做法是默认不给清理工具放开认证相关目录的权限养成“默认不删凭证”的习惯。我第一次用的时候吃过亏后来再没踩过。4.2 清理完了占用还是很大如果清理完磁盘占用依然很高通常是三个原因之一第一只清了 CLI 目录桌面版和 VSCode 插件的数据没有纳入扫描第二Codex 正在后台运行部分日志和缓存文件被进程占用清理工具只能跳过它们第三某些系统缓存目录下还散落着 Codex 相关的临时数据。排查顺序建议这样先退出所有 Codex 相关进程包括 VSCode 里加载的扩展再跑一次扫描。如果依然很大就用系统磁盘工具看大文件分布找到几个异常大的目录手动确认。就我的经验来说进程没退出是最常见的原因这个最容易被忽略。4.3 清理后出现 “unrecognized configuration setting” 报错这类报错通常不是清理导致的而是 Codex 升级后旧的config.toml里写了新版不认识的字段。但清理动作有时会让人误以为是自己把配置改坏了。遇到时先打开config.toml把可疑字段注释掉再重新启动。如果不确定哪些字段有效最省事的方式是让 Codex 重新生成默认配置然后把你自己的关键项一条条加回去。这里想特别提醒一句不要为了解决报错直接删配置。配置文件里往往写着你接入各个模型服务的地址映射、密钥信息、模型列表删了之后要花更多时间恢复。遇到报错先备份再小步修改。4.4 多账号、多用户场景下的边界如果你的电脑上配置了多个账号或者多个 Codex 实例清理前要注意数据目录归属。CX Clear 扫描会把检测到的数据源都列出来但默认不一定细分到用户维度。我建议在多账号环境下优先清理公共缓存和日志会话目录只处理当前主账号对应路径下的内容避免误删另一个账号的上下文。尤其是团队共用一台开发机的情况这种边界问题更要留意。4.5 排查速查表现象大概率原因首选处理磁盘占用突然暴涨日志目录累积 / 插件扩展日志先退出进程再清理日志清理后要求重新登录认证状态文件被误清保留 auth.json重新登录即可清理后任务上下文丢失会话被过度清理保留最近 20 条会话再清理登录正常但配置报错config.toml 与新版本不兼容备份后注释可疑字段Codex 启动明显变慢缓存过多 / 索引过大定期清理缓存保留最近会话说实话CX Clear 并不算什么很复杂的工具它做的事情本质上是把“整理房间”变成了“请一个会先问你要不要扔东西的管家”。对我个人来说最有价值的是 dry-run 和保留策略这两个功能让我敢清理、敢自动化同时不用担心删掉不该删的东西。如果你还在被 Codex 的磁盘占用困扰又想保留完整的会话记录我的建议是从一次诊断扫描开始。别急着执行清理先跑两轮 dry-run你会发现那些平时看不见的数据体量比自己想象中大得多。我给自己定的规矩是每个月最后一个周末清理一次清理前必看报告清理后必跑一次真实会话。这套流程稳定跑了两三个月再也没有出现过磁盘告急。