# CodexCleaner

**Repository Path**: hhxcaz/codex-cleaner

## Basic Information

- **Project Name**: CodexCleaner
- **Description**: 为 Codex / ChatGPT 桌面版打造的本地会话清理与数据空间管理工具。 自动定位 Codex 数据目录与 CLI，安全删除、归档本地会话，清理日志数据库，删除前自动备份。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-04
- **Last Updated**: 2026-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CodexCleaner · Codex 会话管家

> 为 Codex / ChatGPT 桌面版打造的本地会话清理与数据空间管理工具。
> 自动定位 Codex 数据目录与 CLI，安全删除、归档本地会话，清理日志数据库，删除前自动备份。

---

## 项目简介

CodexCleaner 是一套面向 Codex 与 ChatGPT 桌面版本地数据的运维管理工具，提供**图形界面**与**命令行**两种使用方式。它解决了一个常见痛点：会话从表面上被删除后，Codex 侧边栏仍然能看到历史会话，点击后数据依然可以加载。

原因是 Codex 桌面版的会话列表并非只依赖 `session_index.jsonl`，真正驱动侧边栏的是 `~/.codex/state_5.sqlite` 中的 `threads` 状态表，以及 `sessions/` 目录下的 rollout 会话文件。只清理索引而不清理状态库和 rollout 文件，会话就会继续存在。

CodexCleaner 以官方状态库为真实数据源，自动合并 `state_5.sqlite` 与 `session_index.jsonl`，并通过官方 `codex delete / archive` 命令执行操作，既保证清理完整，也尽量避免直接修改 Codex 内部文件。

## 核心特性

- **自动路径识别**：优先读取 `CODEX_HOME`，未设置时自动使用 `~/.codex`；CLI 自动探测 `CODEX_CLI`、PATH、`%LOCALAPPDATA%\OpenAI\Codex\bin`、WinGet、WindowsApps 及主流 Unix 安装路径，无硬编码用户路径。
- **双模式使用**：原生 Tkinter 图形界面，无需额外依赖；同时提供完整命令行工具，适合脚本化与自动化。
- **完整会话识别**：以 `state_5.sqlite` 的 `threads` 表为主，合并 `session_index.jsonl`，不会再漏掉 Codex 侧边栏可见的会话。
- **官方命令执行**：删除与归档均调用官方 Codex CLI，删除后同时移除状态记录与 rollout 文件。
- **删除前自动备份**：每次删除前将对应 rollout 文件复制到备份目录，误删后可手动恢复。
- **日志数据库清理**：支持清空并压缩 `logs_2.sqlite`，显著回收磁盘空间。
- **安全保护**：检测到 ChatGPT / Codex 正在运行时默认拒绝执行，避免状态不一致；确认风险后可手动强制继续。
- **跨平台**：Windows、macOS、Linux 均可运行，兼容本地安装的 Codex CLI 与桌面版应用。

## 快速开始

### 方式一：直接使用 EXE（Windows）

1. 下载并运行 `CodexCleaner.exe`。
2. 启动后自动检测 Codex CLI 与数据目录。
3. 勾选需要清理的会话，执行归档或删除。
4. 删除前程序会先备份，操作完成后可在备份目录中找回。

### 方式二：源码运行

要求 Python 3.8+，仅使用标准库，无需安装第三方依赖。

```bash
# 图形界面
python outputs/codex_cleaner_gui.py

# 命令行查看会话
python outputs/clear_codex_sessions.py list
```

## 命令行说明

| 命令 | 说明 |
| --- | --- |
| `list` | 列出 Codex 本地保存的全部会话 |
| `delete` | 永久删除指定会话，删除前自动备份 |
| `archive` | 归档指定会话 |
| `clear-logs` | 清空并压缩日志数据库 `logs_2.sqlite` |
| `info` | 查看数据目录、会话数量、磁盘占用摘要 |

常用示例：

```bash
# 查看全部会话
python clear_codex_sessions.py list

# 删除 30 天前创建的会话（自动确认）
python clear_codex_sessions.py delete --older-than 30 --yes

# 删除全部会话（自动确认）
python clear_codex_sessions.py delete --all --yes

# 归档指定会话
python clear_codex_sessions.py archive 019fxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# 清空日志数据库
python clear_codex_sessions.py clear-logs --yes

# 查看磁盘占用
python clear_codex_sessions.py info
```

## 数据来源说明

Codex 桌面版与 CLI 的本地数据主要存放在 `~/.codex`（或 `CODEX_HOME` 指向的目录）：

| 文件 / 目录 | 作用 |
| --- | --- |
| `state_5.sqlite` | 会话状态库，`threads` 表是 Codex 侧边栏的主要数据源 |
| `session_index.jsonl` | CLI 会话索引，本工具会与之合并 |
| `sessions/` | 未归档会话的 rollout JSONL 文件 |
| `archived_sessions/` | 已归档会话的 rollout JSONL 文件 |
| `logs_2.sqlite` | Codex 运行日志数据库，通常占用较大空间 |

本工具会自动查找 `state_*.sqlite`，兼容 Codex 未来版本切换状态库文件名的情况。

## 备份与恢复

删除操作前，程序会把 rollout 文件复制到：

```text
~/.codex/.codex-cleanup-backups/<时间戳>/sessions/<会话ID>/rollout-*.jsonl
```

恢复步骤：

1. 完全退出 Codex / ChatGPT 桌面版。
2. 将备份的 rollout 文件复制回原来的目录结构，例如：
   `~/.codex/sessions/2026/08/04/rollout-2026-08-04T09-52-28-xxxx.jsonl`
3. 重新打开 Codex，会话即可重新出现。

## 项目结构

```text
CodexCleaner/
├── outputs/
│   ├── clear_codex_sessions.py   # 命令行核心工具
│   ├── codex_cleaner_gui.py      # 图形界面
│   └── CodexCleaner.exe          # Windows 打包程序（Release 提供）
├── README.md
├── LICENSE
└── .gitignore
```

## 路线图

- [ ] 支持清理 ChatGPT 云端会话
- [ ] 定时自动清理策略
- [ ] 多 Codex 数据目录 / 多用户支持
- [ ] 磁盘占用趋势报表
- [ ] 国际化界面
- [ ] GitHub Actions / Gitee Go 自动构建

## 常见问题

### 为什么清理后 Codex 里还能看到会话？

旧版本工具只读取 `session_index.jsonl`，而 Codex 侧边栏读取 `state_5.sqlite`。当前版本已改为合并读取状态库，删除后建议关闭并重新打开 Codex，确保界面刷新。

### 可以清理 ChatGPT 云端会话吗？

不能。本工具只处理 Codex 本地会话；云端会话需要登录 ChatGPT 后在应用内删除。

### 删除会损坏 Codex 数据吗？

工具使用官方 `codex delete --force` 执行删除，并在删除前备份 rollout 文件。正常情况下不会损坏其余会话；如果担心风险，请先使用 `list` 查看，再小范围测试。

### EXE 被安全软件拦截？

打包程序基于 PyInstaller，部分杀毒软件可能误报。可从源码运行校验行为，或在杀毒软件中添加信任。

## 开源协议

本项目使用 [MIT License](LICENSE)。

## 免责声明

本项目与 OpenAI 无官方关联。使用本工具前请自行备份重要数据，作者不对因误操作造成的会话或文件丢失承担责任。