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 的数据目录默认是~/.codex，Windows 桌面版则更多落在%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 的所有常见版本。

所以你看，直接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，仅供参考。

细看释放空间的构成，大头通常是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 2>&1

Windows 用户可以在任务计划程序里配置，操作项填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 的磁盘占用搞得头疼，按这个流程试一次，应该能让你省下不少手动翻目录的时间。