codex-session-manager

本地 Codex Session 管理器。既可以作为命令行工具使用，也可以通过 npx 启动浏览器管理页面；支持活动会话和已经归档的会话。

Web 管理页面

发布到 npm 后，直接运行：

npx @gushiyu/codex-session-manager web

服务默认监听 http://127.0.0.1:3210，并自动打开系统默认浏览器。在终端按 Ctrl+C 停止服务。

页面支持：

• 查看活动、已归档或全部 Sessions
• 按标题、Session ID、工作目录和内容摘要搜索
• 查看会话元数据和完整对话
• 切换显示 developer/system 等内部记录
• 单个或批量导出 Markdown、JSON、JSONL 或原始 rollout 文件
• 归档活动会话，或将已归档会话移回活动目录
• 安全删除到本地回收站
• 永久删除
• 查看回收站、恢复会话和永久清空回收站
• 读取 .jsonl 与 .jsonl.zst 会话文件

Web 批量导出支持两种模式：

1. 在会话列表勾选任意多条记录，点击“导出已选”。选择会在状态筛选和搜索切换后保留，因此可以混合选择 active 和 archived 会话。
2. 点击“导出当前结果”，直接导出当前状态筛选和搜索匹配的全部会话。

浏览器会下载一个 ZIP，每个 Session 对应一个导出文件，并包含 manifest.json 清单。

指定端口或禁止自动打开浏览器：

npx codex-session-manager web --port 4321
npx codex-session-manager web --no-open

指定其他 CODEX_HOME：

npx codex-session-manager web --codex-home 'D:\backup\.codex'

ui 是 web 的别名：

npx codex-session-manager ui

从源码拉取并本地运行

以下示例使用 PowerShell。首次运行前请准备：

• Git
• Node.js 22.15.0 或更高版本（安装 Node.js 时会同时安装 npm）

1. 拉取代码

在准备存放项目的目录中执行：

git clone https://github.com/gushiyu01/codex-session-manager.git
cd .\codex-session-manager

如果已经克隆过仓库，只需要进入仓库并拉取最新代码：

cd .\codex-session-manager
git pull

2. 检查运行环境

node --version
npm --version

node --version 应显示 v22.15.0 或更高版本。本项目运行时没有第三方 npm 依赖，因此不需要执行 npm install。

3. 运行测试（推荐）

npm test
npm run pack:check

测试通过后再启动管理页面，可以先确认当前 Node.js 环境和本地源码均可正常工作。

4. 启动 Web 管理页面

推荐使用下面的命令模拟包发布后的 npx 入口：

npm exec --package=. -- codex-session-manager web

也可以直接运行入口文件：

node .\bin\codex-session-manager.js web

服务默认监听 http://127.0.0.1:3210 并自动打开系统默认浏览器。在终端按 Ctrl+C 停止服务。

如果浏览器没有自动打开，请手动访问：

http://127.0.0.1:3210

5. 常用启动参数

指定其他端口：

npm exec --package=. -- codex-session-manager web --port 4321

禁止自动打开浏览器：

npm exec --package=. -- codex-session-manager web --no-open

指定其他 Codex 数据目录：

npm exec --package=. -- codex-session-manager web --codex-home 'D:\backup\.codex'

组合使用参数：

npm exec --package=. -- codex-session-manager web --port 4321 --no-open --codex-home 'D:\backup\.codex'

然后手动访问 http://127.0.0.1:4321。

默认会读取当前用户的 ~/.codex。浏览和导出是只读操作；测试归档、删除、恢复或清空回收站时，建议使用备份或临时 CODEX_HOME，不要直接对重要的真实会话做破坏性测试。

macOS / Linux

命令基本相同，仅目录分隔符不同：

git clone https://github.com/gushiyu01/codex-session-manager.git
cd codex-session-manager
node --version
npm test
npm exec --package=. -- codex-session-manager web

CLI 用法

列出 Sessions

默认同时包含 active 和 archived：

npx codex-session-manager list
npx codex-session-manager list --json
npx codex-session-manager list --limit 20
npx codex-session-manager list --search springboot

按状态过滤：

npx codex-session-manager list --active
npx codex-session-manager list --archived
npx codex-session-manager list --status archived

查看 Session 内容

可以使用完整 ID 或唯一 ID 前缀：

npx codex-session-manager show 019f63ac
npx codex-session-manager show 019f63ac --json
npx codex-session-manager show 019f63ac --include-internal
npx codex-session-manager show 019f63ac --raw
npx codex-session-manager show 019f63ac --max-messages 20

归档和移除归档

归档会将 rollout 移到 ~/.codex/archived_sessions；移除归档会根据文件名日期恢复到 ~/.codex/sessions/YYYY/MM/DD，并同步 SQLite 中的归档状态、时间和 rollout 路径。

npx codex-session-manager archive 019f63ac
npx codex-session-manager unarchive 019f63ac

删除和恢复

默认删除是安全删除：rollout 文件会移动到 ~/.codex/session-manager-trash，同时更新 SQLite thread 和 session_index.jsonl。

npx codex-session-manager delete 019f63ac
npx codex-session-manager delete 019f63ac --yes
npx codex-session-manager delete 019f63ac --dry-run

永久删除：

npx codex-session-manager delete 019f63ac --permanent --yes

管理回收站：

npx codex-session-manager trash list
npx codex-session-manager trash restore 019f63ac
npx codex-session-manager trash empty --yes

恢复时会尽量同时恢复：

1. 原 active 或 archived rollout 路径
2. state_*.sqlite 中的 thread 记录
3. session_index.jsonl 中的索引记录

导出 Sessions

npx codex-session-manager export 019f63ac --format markdown
npx codex-session-manager export 019f63ac --format json -o .\session.json
npx codex-session-manager export 019f63ac --format jsonl -o .\session.jsonl
npx codex-session-manager export 019f63ac --format raw -o .\raw-session.jsonl

批量导出，默认包含已归档会话：

npx codex-session-manager export all -o .\codex-export
npx codex-session-manager export all --format jsonl -o .\codex-export
npx codex-session-manager export all --archived -o .\archived-export

| 格式 | 内容 | | --- | --- | | markdown | 会话元数据和可读对话 | | json | 结构化元数据、消息；配合 --include-internal 包含原始 records | | jsonl | 解压后的原始 JSONL | | raw | 原始 rollout；.jsonl.zst 会保持压缩格式 |

存储健康检查

npx codex-session-manager doctor
npx codex-session-manager doctor --json

Web 服务安全模型

• 只允许监听 127.0.0.1，不会暴露到局域网
• 使用随机服务令牌和 HttpOnly; SameSite=Strict Cookie 保护本地 API
• 删除、恢复、清空等修改请求还必须携带 Web 页面专用请求头
• 不启用 CORS
• 设置 CSP、禁止 iframe、禁止浏览器缓存敏感 API 响应
• Session 内容不会上传到远端服务

这不是多用户认证系统。如果计算机账号本身不可信，请不要在该账号下运行管理服务。

开发验证

npm test
npm run pack:check

测试全部使用临时 CODEX_HOME fixture，不会删除真实 Codex Sessions。覆盖范围包括：

• active + archived 发现
• SQLite + rollout 合并
• .jsonl.zst 解压
• CLI list/show/archive/unarchive/export/delete/trash/restore
• Web 静态页面与 Cookie 鉴权
• Web 会话查看和压缩归档读取
• Web 归档、移除归档、单会话导出、批量 ZIP 导出、删除、回收站和恢复闭环

发布 npm

npm login
npm test
npm run pack:check
npm publish --access public

本包发布为公开 scope 包 @gushiyu/codex-session-manager，可直接运行：

npx @gushiyu/codex-session-manager web

兼容性

当前实现针对 Node.js >=22.15.0，使用 Node 内置 node:sqlite 和 Zstandard API。会自动扫描：

• state_<generation>.sqlite 的 threads 表
• sessions/**/*.{jsonl,jsonl.zst}
• archived_sessions/**/*.{jsonl,jsonl.zst}
• session_index.jsonl

SQLite 不可读时会降级到 rollout 文件发现模式。