codex-sessions

codex-sessions 是一个 Codex 本地会话共享库 CLI。

它会把不同 Codex 账号、不同 provider、本地中转 SK 产生的本机会话收集到同一个本地 library，并在你切换 Codex 账号后，把当前账号缺失的历史会话补回当前 Codex 环境。

核心目标是：换号后，本机 Codex 的历史会话列表仍然连续；选择历史会话 resume 时，原始 rollout-*.jsonl 中的本地上下文记录仍然存在。

重要边界

codex-sessions 会在你明确执行真实同步并确认后，写入 Codex home 中的会话相关数据：

sessions/**/rollout-*.jsonl
session_index.jsonl
state_*.sqlite 中的会话相关表：
  - threads
  - thread_dynamic_tools
  - thread_spawn_edges

除此之外，它不会修改 Codex 工具本身，也不会修改这些内容：

config.toml
认证文件
token / API key / SK / cookie
provider 配置
plugins/
skills/
rules/
Codex CLI 安装文件
shell profile
shell alias
CODEX_HOME 环境变量

卸载时也不会修改 Codex home，不会删除已经同步进 Codex 的会话。

适用场景

适合你，如果你：

• 经常切换多个 Codex 账号。
• 同时使用官方账号、自定义 provider、中转 SK 或代理 provider。
• 希望换号后仍能看到之前账号产生的本机会话。
• 希望保留 Codex resume 所需的本地历史上下文。
• 希望有一个本地、可预览、可回滚、可卸载的会话共享工具。

不适合你，如果你：

• 只使用一个 Codex 账号，且不依赖历史会话。
• 需要云端同步或跨设备自动同步。
• 需要迁移账号权限、额度、登录态或 provider 凭据。

安装

运行环境：

• Node.js >= 18
• 已经安装并使用过 Codex CLI，确保本机存在 Codex home 和本地会话数据库

node --version

SQLite 能力已经随 npm 包内置，不需要单独安装系统 sqlite3 命令。

从 npm 安装

包发布到 npm 后，普通用户推荐全局安装：

npm install -g codex-session-sync

安装后使用：

codex-sessions --help
codex-sessions --version

主命令是 codex-sessions。同时也提供完整别名：

codex-session-sync --help

从 GitHub 或源码本地安装

如果你是从 GitHub 拉取源码，或在 npm 发布前本地试用：

git clone <your-repo-url>
cd codex-session-manage
npm install -g .

验证安装结果：

codex-sessions --version
codex-sessions doctor

如果不想全局安装，也可以在项目目录内直接运行：

node ./bin/codex-sessions.js --help
node ./bin/codex-sessions.js sync --dry-run

更新

从 npm 更新：

npm install -g codex-session-sync@latest

从源码更新：

git pull
npm install -g .

卸载安装包

只卸载 CLI 安装包：

npm uninstall -g codex-session-sync

如果是从源码用 npm install -g . 安装的，也使用同一条卸载命令。

注意：卸载 npm 包只会移除 codex-sessions 命令本身，不会清理定时任务，也不会删除工具自己的 library。完整卸载流程见下方“卸载”章节。

快速开始

首次使用建议先检查环境：

codex-sessions doctor

预览同步会发生什么：

codex-sessions sync --dry-run

确认无误后执行同步：

codex-sessions sync

切换 Codex 账号后，再运行：

codex-sessions sync

--dry-run 是零写入：不会创建目录、不会创建 checkpoint、不会写日志、不会复制文件、不会写 SQLite。

核心概念

Codex home

Codex 自己的数据目录。工具会自动发现，普通用户不需要手动配置。

Tool home

codex-sessions 自己的数据目录，保存 library、checkpoints、logs 和配置。

Library

本地共享会话库。不同账号产生的会话会被收集到 library，再从 library 补回当前 Codex。

Checkpoint

写入 Codex home 前创建的安全检查点。如果同步结果不符合预期，可以用 rollback 恢复最近一次同步前的状态。

Push / Pull / Sync

• push：当前 Codex -> shared library
• pull：shared library -> 当前 Codex
• sync：双向合并

常用命令

命令	作用
codex-sessions doctor	检查 Codex home、schema、library 状态
codex-sessions paths	查看当前解析到的所有路径
codex-sessions sync --dry-run	预览同步计划，不写入
codex-sessions sync	双向同步当前 Codex 和 library
codex-sessions sync --push-only	只把当前 Codex 会话写入 library
codex-sessions sync --pull-only	只从 library 补回当前 Codex
codex-sessions status	查看当前 Codex 与 library 的差异
codex-sessions status --conflicts	查看冲突
codex-sessions list	查看 library 中的会话
codex-sessions list --source current	查看当前 Codex 中的会话
codex-sessions show <id>	查看某个会话的元信息
codex-sessions rollback	回滚最近一次同步
codex-sessions uninstall	卸载工具影响，不修改 Codex 数据

同步命令详解

双向同步：

codex-sessions sync

它会做两件事：

1. 把当前 Codex 中 library 没有的会话写入 library。
2. 把 library 中当前 Codex 缺失的会话补回当前 Codex。

如果会写入 Codex home，交互终端会展示摘要并要求确认。非交互环境必须显式传入 --yes：

codex-sessions sync --yes

只收集当前账号会话：

codex-sessions sync --push-only

只补回共享库会话：

codex-sessions sync --pull-only

查看与诊断

查看差异：

codex-sessions status

查看 library 会话：

codex-sessions list

默认显示最近 50 条，按更新时间倒序。显示全部：

codex-sessions list --all

查看当前 Codex 会话：

codex-sessions list --source current

查看某个会话：

codex-sessions show 019e8767

show 默认只显示元信息，不打印完整对话内容，避免泄露敏感信息。

CWD 和 provider

会话仍然对应原来的项目目录。工具会原样保留 threads.cwd，不会自动映射路径。

如果原项目目录不存在，历史记录仍能恢复，但 resume 后涉及文件读取、编辑、命令执行时可能失败。

provider 名称只作为普通字符串保存。工具不会判断 provider 是否有效，也不会复制 provider 凭据。当前机器缺少对应 provider 时，历史会话仍可恢复；继续发送新消息是否成功，取决于当前 Codex 配置。

冲突处理

如果同一个 session id 在当前 Codex 和 library 中都存在，但 rollout 文件内容不同，会被标记为 conflict。

codex-sessions 不会覆盖任何一边。

查看冲突：

codex-sessions status --conflicts

回滚与 checkpoint

每次真实写入 Codex home 前，工具都会创建 checkpoint。

回滚最近一次同步：

codex-sessions rollback

查看 checkpoint：

codex-sessions checkpoints list

恢复指定 checkpoint：

codex-sessions checkpoints restore latest

checkpoint 只保存会话相关数据，不保存认证文件、token、API key、SK 或 config.toml。

定时同步

安装定时同步：

codex-sessions schedule install --preset normal

内置 preset：

preset	频率
light	每 6 小时
normal	每 1 小时
active	每 15 分钟
daily	每天 02:00

自定义间隔：

codex-sessions schedule install --every 30m

高级 cron：

codex-sessions schedule install --cron "*/10 * * * *"

查看定时任务：

codex-sessions schedule status

立即测试定时行为：

codex-sessions schedule run-now

卸载定时任务：

codex-sessions schedule uninstall

定时任务运行时更保守：如果检测到 Codex 正在运行、SQLite 被锁定或 schema 不兼容，将跳过写入 Codex home，只记录日志。

清理 library

library 默认不会自动删除会话。

预览可清理内容：

codex-sessions library prune --dry-run --older-than 1y

真实清理：

codex-sessions library prune --older-than 1y --yes

library prune 只清理工具自己的 library，不会清理 Codex home。

卸载

只移除定时任务和工具注册信息：

codex-sessions uninstall

删除工具自己的数据：

codex-sessions uninstall --remove-tool-data --yes

卸载 npm 包：

npm uninstall -g codex-session-sync

注意：

• 卸载不会删除已经同步进 Codex 的会话。
• 卸载不会修改 Codex home。
• 卸载不会修改 state_*.sqlite、session_index.jsonl、config.toml 或认证文件。

跨平台路径

普通用户不需要手动配置路径。查看实际路径：

codex-sessions paths

Codex home 解析优先级：

1. --codex-home
2. CODEX_HOME
3. 用户目录下的 .codex

Tool home 解析优先级：

1. --tool-home
2. CODEX_SESSIONS_HOME
3. 平台应用数据目录

默认 tool home：

• macOS: ~/Library/Application Support/codex-sessions
• Linux: $XDG_DATA_HOME/codex-sessions 或 ~/.local/share/codex-sessions
• Windows: %LOCALAPPDATA%\codex-sessions

安全与隐私

codex-sessions 会读取和保存本地 Codex 会话内容。会话内容可能包含代码、业务信息、命令输出或其他敏感信息。

请不要把 tool home、library、checkpoints 提交到 GitHub。

工具不会同步：

• token
• API key
• SK
• cookie
• Codex 登录态
• config.toml
• provider 配置

常见问题

切换账号后 resume 的上下文还在吗？

在本地记录层面还在。工具会同步 rollout 文件和 threads 索引。Codex resume 时可以读取这些本地历史记录。

但下一轮模型实际使用多少历史，取决于 Codex 自身的上下文策略。

会同步 API Key 或 SK 吗？

不会。

卸载后会影响 Codex 吗？

不会。uninstall 不修改 Codex home，不删除 Codex 会话，不修改配置和认证文件。

如果当前账号没有旧会话使用的 provider，还能继续吗？

历史记录仍然能恢复。继续发新消息是否成功，取决于当前 Codex 配置中是否有可用 provider。

library 会自动删除旧会话吗？

不会。library 默认长期保留。需要清理时，用户手动运行 library prune。

故障排查

找不到 Codex home

运行：

codex-sessions paths
codex-sessions doctor

如果你使用了自定义 Codex home：

CODEX_HOME=/path/to/.codex codex-sessions doctor

schema 不兼容

说明当前 Codex 本地数据库结构暂不支持真实写入。你仍可以运行：

codex-sessions sync --dry-run

但不能执行真实同步，直到工具升级适配。

SQLite 依赖加载失败

SQLite 能力随 npm 包安装。如果提示内置 SQLite 依赖加载失败，通常是 npm 包安装不完整、Node 版本过低或 npm registry 下载异常。

建议先确认 Node 版本：

node --version

然后重新安装：

npm install -g codex-session-sync@latest

不需要单独安装系统 sqlite3 命令。

Codex 正在运行

为了避免 SQLite 写入冲突，请关闭 Codex 后再执行真实 sync。

发现 conflict

查看：

codex-sessions status --conflicts

工具不会覆盖任何一边。

开发

运行测试：

npm test

本项目不应提交真实 Codex 会话、SQLite 数据库、认证文件或 token。