开源一个 Codex 本地历史管理 CLI:从 list 到安全 purge

Codex 用久之后,本地对话历史会慢慢堆起来。这个问题本身不复杂,但清理起来并不适合靠手动改文件解决:本地数据可能分布在 SQLite、JSON、JSONL 和其他状态文件里,漏删会留下残留,误删又会破坏 Codex 的本地状态。

我最近开源了一个小工具 codex-history,它解决的是一个很具体的问题:先找到本地 Codex 对话,再用可确认、可验证的方式清理受支持的本地数据。

它不是服务端删除工具,也不是用来绕过 Codex 官方能力的工具。我的目标更保守:在本机数据结构受支持时,提供一个比手动编辑 ~/.codex 更清晰的本地清理流程。

为什么要做这个工具

我遇到的场景是:想清理某个项目相关的 Codex 会话,但不想打开本地数据库和状态文件一点点找。更麻烦的是,Codex 本地历史不是单个文件能概括的。对话列表、会话记录、全局状态、日志和一些派生文件之间可能存在引用关系。

所以我没有把这个工具设计成"传一个路径然后递归删除"的脚本,而是拆成几个明确步骤:

  1. 先检查当前数据结构是否支持。
  2. 再列出可读的本地会话。
  3. 用标题、首条用户消息、预览或 cwd 缩小范围。
  4. 删除前展示计划并要求确认。
  5. 删除后扫描受支持的本地存储,确认已知引用是否移除。

这就是 codex-history 的主线。

安装和第一步检查

安装方式:

bash 复制代码
npm install -g @liuyoumi/codex-history

也可以不安装直接运行:

bash 复制代码
npx @liuyoumi/codex-history doctor

我建议第一步永远先跑:

bash 复制代码
codex-history doctor

下面的示例截图来自临时 demo --codex-home,不包含真实用户数据:

doctor 的作用是确认当前 Codex 本地数据结构是否被这个版本支持。如果不支持,删除命令会拒绝执行,而不是猜测数据应该怎么删。

用 list 找到目标

最基础的命令是:

bash 复制代码
codex-history list

默认输出会尽量保持短,一行一条:

如果本地历史很多,可以先用关键词缩小范围:

bash 复制代码
codex-history list --grep "Purge"

这里有一个刻意的限制:--grep 只匹配显示标题、首条用户消息和预览,不匹配 thread id 或 cwd,也不会搜索完整对话正文。

原因很简单:这个工具首先是清理工具,不是全文检索工具。删除前的筛选应该足够可解释,不应该因为某个完整上下文里隐藏的词,把用户没有意识到的会话带进删除计划。

按项目路径筛选可以用 --cwd:

bash 复制代码
codex-history list --cwd codex-history --pretty=medium

--cwd 支持路径片段,所以可以输入完整路径,也可以输入项目名的一部分。

purge 为什么要确认

删除单条会话:

bash 复制代码
codex-history purge 019e7047

交互式流程会先展示解析到的目标,并要求输入短 id:

这个确认不是形式主义。purge 是不可撤销的本地破坏性操作,所以工具会要求用户在最后一步重新确认"我要删的就是这一条"。

多条删除和过滤式删除也支持:

bash 复制代码
codex-history purge 019e6885 019e6874
codex-history purge --cwd /Users/me/Projects/example
codex-history purge --grep "Astro"
codex-history purge --archived

批量或过滤式删除要求输入 purge-selected。如果任意一个目标不存在、不唯一,或者命中当前 active thread,整个批量计划会在修改数据前拒绝执行,不会部分删除。

脚本里可以加 --force:

bash 复制代码
codex-history purge 019e6885 --force

但 --force 只跳过交互确认,不会跳过数据结构校验、active thread 保护和删除后的验证。

purge-orphans 解决什么

除了正常会话,有时本地还可能留下孤儿数据。比如 threads 表还记录着某个会话,但 rollout 文件已经不存在;或者日志数据库里还有 thread id,但主线程记录已经没有了。

对应命令是:

bash 复制代码
codex-history purge-orphans

它会先展示计划、影响的 SQLite 行数、将删除的文件数量和估算的本地磁盘空间影响。确认时需要输入 purge-orphans。

发布前可以补一张计划截图,但不要为了截图去真实用户目录里制造破坏性场景。建议使用 fixture、复制后的沙盒数据,或显式临时 --codex-home。

设计取舍

第一,未知数据结构直接 fail closed。Codex 本地数据结构可能随版本变化,工具不能在未知结构上猜测删除。

第二,不做模糊删除。传入 id 或短 id 前缀时,必须解析到唯一目标。删除命令里"差不多匹配到了"是危险设计。

第三,--grep 不做全文检索。筛选删除目标时,我更看重结果可解释,而不是尽可能多地匹配。

第四,删除后做引用验证。删除执行完不代表清理成功,工具还会扫描受支持的本地存储,看目标 thread id 是否仍有已知引用。

适合群体

  • 经常使用 Codex Desktop 或 Codex CLI 的用户。
  • 想按项目或关键词清理本地 Codex 历史的人。
  • 不想手动编辑 ~/.codex 的人。
  • 希望删除前能看到明确目标和确认流程的人。

项目地址

GitHub: github.com/liuyoumi/co...

npm: www.npmjs.com/package/@li...

如果你也在用 Codex,并且遇到过本地历史不好清理的问题,可以试试看。更欢迎提 issue,尤其是不同平台或 Codex 版本下的反馈;觉得这个方向有用的话,也欢迎给个 Star 支持后续维护。

相关推荐
ndz2 小时前
GPT-6.2 API 接入笔记:Sol / Astra 怎么选,思考强度和调用示例
openai
AAA修煤气灶刘哥1 天前
为什么你的Codex 重连到 5/5 才开始工作?理解重试、协议回退与代理链路
人工智能·架构·openai
大西瓜瓜瓜3 天前
使用 AutoDL/RTX4090/QWeb7B
aigc·openai
沉默王二5 天前
官方点名,DeepSeek Harness 的 4 个神级插件。
openai·agent·ai编程
夕阳_醉了6 天前
Codex 客户端从装好到跑通:第三方 API 接入与配置避坑指南
人工智能·gpt·openai·codex·ai 编程
threerocks7 天前
一个人指挥一支 AI 剧组:Gemini 4 + Omni 1.2 剧情短片制作保姆级教程
aigc·openai·ai编程
东姬AI8 天前
挖出948个内核漏洞、自动写补丁:GPT-6 Cyber把AI推进“实战岗“,内容行业还卡在哪一关?
人工智能·网络安全·openai·gpt-6
LV技术派8 天前
我的《成为 AI Native Builder》开源小册,全量开放了!
aigc·openai·ai编程
ServBay9 天前
OpenAI大规模封号?ChatGPT 用户该如何应对
chatgpt·openai·ai编程
沉默王二9 天前
Hy4正式发布一手实测,腾讯这波起飞了。
openai·agent·vibecoding