Codex Session Doctor

在 Codex 会话大到拖慢、卡住或消失之前，先做一次只读体检。

Codex Session Doctor 是一个小型、跨平台、严格只读的本地命令行工具。它会找到 Codex Desktop 的会话文件，列出最大的会话，检查首行 session_meta，并可选择以流式方式逐行验证 JSONL。

它不会删除、移动、截断、修复或上传任何会话，也不会显示你的提示词、回答或代码。

Built by ConfigCrate.

演示视频

• 18.8 秒竖屏演示视频（无配音）
• 3:4 中文封面
• 视频号配音文案

为什么需要它

Codex 的一个长任务可能持续写入同一个 JSONL 文件。社区已有报告显示，超大的会话文件可能造成明显卡顿、全局冻结或启动崩溃；损坏的首行元数据也可能让任务从历史记录中消失。

这些问题通常等到 Codex 已经很难打开时才被发现。本工具先回答四个简单问题：

• 本机有多少 Codex 会话，总共占用多少空间？
• 哪几个会话最大，是否正在接近已报告的危险大小？
• 每个文件是否以有效的 session_meta 开始？
• JSONL 中是否存在真正损坏的 JSON 行？

当前功能

• 自动发现 ~/.codex/sessions 和 ~/.codex/archived_sessions
• 默认快速扫描：文件大小 + 首行元数据
• --deep 深度扫描：逐行验证 JSONL，整个文件采用流式读取
• 内存保护：超过 4 MiB 的单行只计为“未验证长行”，不会误报为损坏
• 大小等级：安全、留意、警告、危险
• 中文和英文终端输出
• --json 机器可读输出
• Windows、macOS 和 Linux 单文件程序

快速开始

从 Releases 下载适合系统的压缩包并解压。

Windows PowerShell：

.\codex-session-doctor.exe --lang zh

macOS / Linux：

./codex-session-doctor --lang zh

示例结果：

Codex Session Doctor 0.1.0
只读扫描，不修改任何会话 · 模式: 快速（大小 + 首行元数据）

总计: 44 个会话 · 467.8 MiB
大小风险: 安全 42 | 留意 2 | 警告 0 | 危险 0
文件健康: 元数据异常 0 | 非法 JSON 0 | 未验证长行 0 | 读取失败 0

做完整的逐行检查：

.\codex-session-doctor.exe --deep --lang zh

输出 JSON，方便脚本处理：

.\codex-session-doctor.exe --json > codex-session-health.json

如果 Codex 数据不在默认位置：

.\codex-session-doctor.exe --codex-home D:\my-codex-data --lang zh

大小等级

等级	文件大小	含义
安全	小于 100 MiB	暂未达到提醒线
留意	100–299 MiB	建议关注增长速度
警告	300–499 MiB	已经很大，建议尽快结束长任务并新建任务
危险	500 MiB 及以上	接近社区报告的崩溃区间

这些是保守的预警线，不代表每台电脑都会在同一大小出现问题。工具不会根据等级自动处理文件。

选项

--codex-home PATH   Codex 数据目录；默认读取 CODEX_HOME 或 ~/.codex
--deep              流式逐行验证所有 JSONL
--json              输出 JSON
--lang auto|en|zh   输出语言；默认 auto（英文）
--top N             显示最大的 N 个会话；默认 10，设为 0 可隐藏列表
--version           显示版本

退出代码：0 表示没有警告、危险或文件异常；1 表示发现需要留意的问题；2 表示参数或扫描失败。单纯超过 100 MiB 的“留意”不会令退出代码变为 1。

隐私和安全

• 只以读取方式打开 .jsonl 文件。
• 不修改 Codex 文件、不读取或修改 Codex 的 SQLite 索引。
• 不显示提示词、回答、代码或 JSONL 内容。
• 不联网、不上传、不含遥测，也不需要 API key。
• 默认输出相对于 .codex 的路径，避免暴露用户主目录。

深度模式会验证正常大小的 JSON 行。为了让内存占用有明确上限，超过 4 MiB 的单行会被计入 未验证长行，而不是被判定为非法 JSON。这类长行常见于包含图片的会话。

已知需求证据

• openai/codex#22004：报告约 512 MB 的 rollout JSONL 触发 Codex Desktop 崩溃。
• openai/codex#24948：报告 sessions 目录达到 91 GB，单个文件约 700 MB–2 GB。
• openai/codex#21948：报告约 173 MB 的会话引发全局冻结。
• openai/codex#24425：报告损坏的首条 session metadata 让任务无法出现在历史记录中。

Codex Session Doctor 是独立社区项目，与 OpenAI 无隶属或官方认可关系。

从源码构建

需要 Go 1.24 或更新版本：

go test ./...
go build ./cmd/codex-session-doctor

---

English

Codex Session Doctor is a small, cross-platform, strictly read-only health checker for local Codex Desktop sessions. It finds oversized session files, validates the first session_meta record, and can stream through JSONL files to detect malformed records.

It never deletes, moves, truncates, repairs, or uploads a session. Prompts, answers, code, and raw session content are never printed.

Quick start

Download a package from Releases, extract it, and run:

codex-session-doctor
codex-session-doctor --deep
codex-session-doctor --json

Use --codex-home PATH for a non-default data directory and --lang zh for Chinese output.

What it checks

• ~/.codex/sessions and ~/.codex/archived_sessions
• session count, total size, and largest files
• conservative size bands at 100 MiB, 300 MiB, and 500 MiB
• valid first-line session_meta
• malformed JSONL records in opt-in deep mode
• unreadable files, without ever printing their contents

Deep mode uses bounded memory. A single line over 4 MiB is reported as skipped—not corrupt—because image-bearing sessions can legitimately contain very long JSON records.

Privacy

The tool makes no network requests, contains no telemetry, requires no API key, and opens session files only for reading. It does not touch Codex indexes or configuration files.

Codex Session Doctor is an independent community project and is not affiliated with or endorsed by OpenAI.

Built by ConfigCrate.