1. Codex 为什么越用越占清之前先搞清楚病根1.1 先从一个我上周遇到的报错说起如果你是 Codex 的日常使用者大概率见过这种画面用着用着终端突然弹出一条cc switch local proxy failed while handling codex endpoint /responses或者更让人头疼的the gpt-5.6-sol model is not supported。我当时的第一反应是去翻配置、重装插件折腾了半天都没解决。直到打开磁盘工具才发现根因根本不是代码问题——C盘只剩 3GB~/.codex目录已经膨胀到 1.7GB日志文件和会话记录快把磁盘塞满了。这个场景太典型了。Codex 作为本地运行的 AI 编程代理会把每次会话的历史、调试日志、临时缓存全部落在磁盘上。它不会像清理临时文件那样自动轮转时间一长你的磁盘就被这些“看不见的垃圾”吃掉了。有人习惯直接跑rm -rf ~/.codex但那样会把登录态、配置项一起干掉属于饮鸩止渴。后来我在折腾中接触到了 CX Clear一个专门针对 Codex 本地数据做精细化清理的命令行工具。这篇文章就把我的使用过程、踩坑记录、清理原理和常用参数完整写出来希望能帮你省掉这些弯路。无论你是刚装 Codex 的新手还是已经把本地数据跑出好几个 GB 的老用户应该都能在里面找到可用的方案。1.2 拆解 Codex 的本地存储结构要理解 CX Clear 的价值得先知道 Codex 在本地到底存了什么。以 macOS 和 Linux 为例Codex CLI 的数据目录默认是~/.codexWindows 桌面版则更多落在%USERPROFILE%\.codex或 AppData 相关目录下。这个目录里躺着几类关键文件。第一类是config.toml相当于 Codex 的“总开关”里面写着默认模型、组织 ID、是否开启自动执行、各种开关项。很多人遇到的codex is ignoring 1 unrecognized configuration setting报错就是因为这个文件里出现了新版本已经不认识的老键名。第二类是sessions和recordings目录这是占空间的大头。Codex 会把每一轮跟模型交互的完整上下文、工具调用过程、代码改动记录全量落盘方便你随时--resume恢复现场。第三类是log目录里面既有普通日志也有崩溃堆栈、debug 级别的详细记录。第四类是auth.json或由系统钥匙串托管的登录凭据这个文件一旦丢失你就得重新做一遍 OAuth 登录。下面是我整理的一份典型路径清单几乎适用于 Codex CLI 的所有常见版本。目录/文件内容占用趋势~/.codex/config.toml模型、组织、自动化开关极小但报错率高~/.codex/sessions/*会话上下文与断点记录增长快~/.codex/recordings/*.jsonl完整交互轨迹大头重度使用可达 GB 级~/.codex/log/*.log运行日志与崩溃堆栈持续累积~/.codex/cache/*本地缓存与模型元数据随版本更新变化~/.codex/auth.json登录凭据尺寸小但极其重要所以你看直接rm -rf虽然能清出大量空间代价却是把 config 和 auth 一起带走。你会发现自己刚改好的模型配置没了账号要重新登录之前能恢复的会话也全部归零。CX Clear 能在这个场景里发挥作用靠的不是“暴力删除”而是“分类清理”。2. CX Clear 到底做了什么清理逻辑与安全边界2.1 它和“手动删目录”的核心区别我一开始对 CX Clear 的态度是怀疑的——清理工具多的是专门给一个 CLI 写清理脚本能有什么区别真正用它跑完一次之后我发现它的设计思路跟手删确实不是一个路子。CX Clear 本质上是一个带策略的清理脚本它会先解析~/.codex下所有文件的时间戳、大小、类型然后只针对“会话快照”“日志”“崩溃转储”“临时缓存”这类可再生的数据做处理。它会跳过config.toml、auth.json和正在被使用中的会话目录。这意味着清理完之后你的 Codex 还能认得你是谁模型配置也原封不动。它的工作流程是先进入“审计模式”把将要删除的文件逐条打印出来并估算可释放的空间确认后再进入“执行模式”按照你给定的保留天数、备份选项来处理数据。整个过程可以用一句话概括配置不动、登录不动、只清可再生垃圾。我在实际使用中最喜欢的是--dry-run参数。它不会删除任何文件只输出一份类似“这些文件已超过 30 天总计 842MB建议清理”的报告。这让你在动手之前就能心里有底。相比我过去那种先备份再盲目清理的原始做法这个机制明显更安全也更符合“先审计、后执行”的运维习惯。2.2 三条安全边界是怎么设计的CX Clear 的安全设计可以拆成三条边界。第一条边界保护配置类文件。config.toml和auth.json默认永远不进入清理名单除非你显式传入--include-config否则它们会被跳过。这样设计的原因很明显登录态一旦丢失你要花时间重新认证配置一旦丢失你之前调好的模型参数、组织 ID 全部作废。清理工具如果连这些都要动那就是在帮倒忙。第二条边界按时间保留会话。会话记录不是越老越没用很多人会回头查看几周前的上下文。CX Clear 默认只处理超过 7 天的会话同时保留最近若干条活跃会话避免把正在使用的断点记录一并清掉。你可以用--keep-sessions 30把保留周期拉长到 30 天也可以缩短到 1 天来激进清理。第三条边界备份分流。在执行清理前工具会把准备清理的内容先打包成压缩文件放到你指定的备份目录等确认 Codex 正常运行后再手动删除备份。这意味着即使误清了某个重要会话你还能从备份里捞回来。这三条边界叠加起来覆盖了绝大多数误删场景。我自己的使用习惯是--dry-run先看报告--backup留后路只有确认没风险后才执行真正的清理。这套流程走下来我没有一次因为清理工具而出现配置丢失或者登录失效的问题。3. 实操记录从安装到跑通一次干净清理3.1 安装 CX Clear 的三种方式CX Clear 是个社区维护的开源项目安装方式不复杂但不同平台略有差异。如果你的环境里有 Node.js最直接的安装方式是全局安装 npm 包npm install -g cx-clear安装完成后直接运行cx-clear --help验证是否成功。如果终端提示找不到命令多半是 npm 的全局 bin 目录没有加入 PATH可以把/usr/local/bin或%APPDATA%\npm加进去。macOS 用户如果更习惯 Homebrew也可以查看仓库里是否提供了 formula用brew install cx-clear安装。不过这取决于维护者的发布节奏有时 npm 包的更新版本会更快一些。第三种方式是直接拉取源码运行。这种方法适合想要深度定制清理规则的进阶用户git clone https://github.com/你的源路径/cx-clear.git cd cx-clear npm install node index.js --dry-run我比较推荐 npm 方式因为它能自动处理依赖后续更新也方便。Windows 用户在安装时要注意尽量在 PowerShell 或 Windows Terminal 中运行不要在 cmd 下执行如果遇到权限问题检查执行策略必要时以当前用户身份运行不要轻易使用管理员权限避免清理工具拿到过高权限后误伤系统文件。3.2 清理前的备份与预检先 dry-run 再动手跑清理工具之前有一步我必须强调先关掉正在运行的 Codex 进程。这不是小题大做而是为了文件一致性。Codex 在运行时会持续往recordings和log目录写入数据如果清理工具刚好扫到正在写入的文件轻则清理失败重则产生一个半截的 JSONL 文件影响后续会话读取。正确顺序是这样的。第一步退出所有 Codex 会话。如果你在 VSCode 里用了 Codex 插件也一并关掉。第二步运行 dry-run 模式看清理报告cx-clear --dry-run --keep-sessions 14这条命令会列出所有超过 14 天的会话文件、30 天前的缓存、按策略判定为可清理的日志并输出预计释放的空间。我在一台重度使用的开发机上跑出来的结果大概是这样的[审查] 可清理的会话快照231 个约 612MB [审查] 可清理的日志文件89 个约 94MB [审查] 可清理的缓存文件26 个约 41MB [审查] 不可触碰项config.toml, auth.json, 最近会话 x7 预计释放空间747MB第三步执行带备份的清理。我推荐加上--backup参数把可能误删的数据先安全存放。cx-clear --keep-sessions 14 --backup ~/codex-clear-backup执行完之后你会看到一个清单写清楚删除了哪些文件、备份到了哪里。此时不要急着删备份先打开 Codex 随便跑一个简单任务确认能正常登录、正常对话再手动清理备份目录。3.3 正式清理与常用参数组合跑通第一次清理之后你会发现参数组合的重要性。CX Clear 提供了一批很有用的控制参数这里列几个我日常使用频率最高的。--keep-sessions指定保留的会话天数默认是 7 天。如果你是个重度依赖历史上下文的人建议设置 30 天。--keep-logs单独控制日志保留天数日志这种东西堆起来很快但实用价值低我一般设置 3 天。--compact是一个很巧妙的选项它不会删除 JSONL 文件而是把多个碎片化的记录压缩合并成一个既能降低文件数量、减少磁盘占用又保留了全部历史信息。--force则是用来跳过所有交互确认适合在脚本和定时任务中调用。比较稳妥的一套组合是这样的cx-clear --keep-sessions 30 --keep-logs 3 --compact --backup ~/codex-clear-backup --force这条命令的意思很明确保留 30 天会话和 3 天日志对会话文件做压缩合并执行前把准备清理的内容备份到指定目录全程不需要人工确认。我一般在周末跑一次跑完顺手清一下旧的备份目录磁盘空间能稳定控制在一个合理范围。如果你设置了多个模型的切换比如在多个模型之间来回试验codex目录里的config.toml还会记录大量模型相关的元数据。这种情况不建议手动改配置而是用codex config命令先查看当前配置再针对性地通过 CX Clear 的”配置检查“模式去发现无效键名。很多人在清理后遇到的unrecognized configuration setting报错根源就在于旧键名残留在配置里工具不一定能完全帮你清理干净但至少能提示你检查。4. 清理之后效果对比与高频报错排查4.1 一次清理能释放多少空间这个问题没有标准答案但可以根据会话频率和日志级别估算大致区间。以我自己的多台机器为例轻度使用偶尔编码频率在一周两次左右的机器~/.codex可能在 200MB 上下中度使用每天都写代码、频繁切换会话的机器半年下来能到 800MB 到 1GB重度使用长时间挂机、跑自动化流程、保留海量历史的机器超过 2GB 非常正常。CX Clear 一次清理能释放的比例直接取决于你设置了多长的保留周期。下表是我在几台不同机器上跑出来的典型结果环境分别是 macOS、Linux 和 Windows仅供参考。机器环境清理前体积清理后体积释放空间使用强度macOS 开发机1.45GB180MB1.27GB重度Linux CI 镜像800MB130MB670MB中等Windows 桌面环境640MB95MB545MB中等细看释放空间的构成大头通常是recordings目录里的历史 JSONL 文件其次是日志目录里的 debug 级别记录。这两类文件都是纯过程性数据删掉或压缩合并并不会影响 Codex 的正常运行。相比之下cache目录占用的比例不算高但偶尔会因为模型元数据更新不及时导致版本兼容类报错这类问题留到下一节细讲。4.2 清理后最容易踩的三类报错清理完之后Codex 大概率会提示重新登录或者重新初始化这是正常现象不用紧张。但有三个高频报错我建议你记下来遇到了能少走弯路。第一个报错是the gpt-5.6-sol model is not supported when using codex with a chatgpt account。这个报错跟清理工具本身关系不大多半是 Codex CLI 版本落后导致本地缓存的模型列表不认识新的模型 ID。解决办法很直接升级 Codex CLI 到最新版本同时检查config.toml里的model字段是否写了一个当前账号根本不支持的模型。如果发现是配置里写了敏感环境变量或自定义模型名把配置改回官方支持的模型即可。第二个报错就是我们开头提到的cc switch local proxy failed while handling codex endpoint /responses。很多人在清理完磁盘后看到它会误以为是删坏了什么。实际上这个报错的触发点在本地代理转发层跟~/.codex目录数据没有直接强关联。它的常见成因是本地代理进程没有启动或者端口被其他服务占用。如果你并没有使用本地代理只是装了相关插件那这个报错多半来自插件配置里的 endpoint 指到了本地转发地址。处理顺序是先检查相关进程状态再确认端口占用情况最后看插件配置里 endpoint 是否还指向一个已经不存在的地址。如果你完全没有代理需求直接在插件或配置文件里移除相关配置项就能绕过。第三个报错是codex is ignoring 1 unrecognized configuration setting. check for typos。这类报错虽然不影响核心功能但会让人很不舒服。它通常出现在你从旧版本升级到新版本后config.toml里还残留着已经被废弃的键名。我的排查方法是先备份config.toml再用 CX Clear 的“配置检查”子命令逐行校验最后手动注释掉报错指向的键名。注意不要轻易整段重写配置文件否则你可能把org、model这些关键参数一起弄丢。4.3 把清理变成自动化定时任务配置清理这种重复性工作跑一次两次容易长期坚持很难。我目前的做法是把 CX Clear 挂进定时任务让它每周自动执行一次配合保留策略把磁盘占用稳定在同一水位。macOS 和 Linux 可以用 cron下面是我在开发机上用的一个简单示例每周日凌晨 2 点执行清理并输出一份报告0 2 * * 0 /usr/local/bin/cx-clear --keep-sessions 30 --keep-logs 3 --compact --backup ~/codex-clear-backup --force ~/codex-clear.log 21Windows 用户可以在任务计划程序里配置操作项填cx-clear参数填--keep-sessions 30 --keep-logs 3 --compact --force。有一点特别提醒定时任务尽量以当前用户身份运行不要设置“以最高权限运行”。清理工具处理的是用户级数据用不着管理员权限反而可能在跑批时把其他临时文件一并卷入。定时任务跑了一段时间后我摸索出一个经验不要把清理频率设得太高。Codex 的会话恢复能力依赖历史记录如果你每天都把超过 1 天的会话清掉遇到紧急问题需要翻之前的上下文时会非常被动。我现在固定为每周一次保留 30 天会话日志只留 3 天既能满足日常复盘需求又不会让磁盘持续膨胀。另外如果你在 Windows 上使用桌面版 Codex清理完之后可能会遇到“设置未完成”的提示。这种情况多半是桌面版的内部状态没刷新重启一次应用基本就能解决不用重新安装也不必去动注册表。我个人在实际操作中的体会是CX Clear 不是一个“一键加速”的花哨工具它更像是一个把清理策略固化下来的执行器。它最值钱的设计不是那条删除命令而是--dry-run和--backup这两个前置动作让你每一次清理都处于可控状态。最后再分享一个小技巧清理完的备份目录建议用日期命名比如codex-clear-backup-2025-06-15等确认 Codex 稳定运行一周后再整体删除给误删留一个充分的后悔时间。如果你也被 Codex 的磁盘占用搞得头疼按这个流程试一次应该能让你省下不少手动翻目录的时间。