codexx - 跨 Provider 找回丢失的 Codex CLI 会话工具
codexx 是一款专为 Codex CLI 设计的实用小工具，旨在解决一个困扰许多用户的典型痛点：当你切换了 provider（模型提供商）之后，之前辛苦创建的会话，在 resume 列表里就再也找不到了。
实际上，这些会话并没有凭空消失。它们依然完好地保存在 ~/.codex/sessions 目录下。只是 Codex 原生的 resume 列表会受当前 model_provider 配置的影响，导致某些会话看上去突然“失踪”了。codexx 的处理思路非常直接：它会直接从本地 session 的元数据中，找出所有与当前项目相关的会话——无论它们当初使用的是哪个 provider。
它能帮你解决什么问题
在实际开发过程中，你很可能需要在同一个项目里来回切换不同的 provider：
model_provider = "openai"
model_provider = "custom"
切换之后，再执行：
codex resume
你就会发现，一些旧的会话从列表里消失了。这时，codexx resume 会直接扫描 ~/.codex/sessions/**/*.jsonl，按照当前工作目录 cwd 进行过滤，然后把所有 provider 下的匹配会话全部列出来。
默认情况下，codexx 会隐藏 helper/subagent 这类子线程，让列表更加清爽，只展示你真正关心的用户会话。如果你确实需要查看这些底层线程，可以加上 --include-subagents 参数。
安装方式
安装过程非常简洁，一行命令即可完成：
npm install -g @meta v_xly/codexx
不过需要满足两个前提条件：Node.js 版本在 18 或以上，并且官方的 codex CLI 已经存在于 PATH 环境变量中。
快速上手
在你的项目目录下直接执行：
codexx resume
你会看到类似下面的输出：
Matched cwd: C:\path\to\project
Found 3 sessions.
1. 2026-06-03T01:19:15.977Z [custom] 为什么 resume 找不到旧会话 019e8b10-...
2. 2026-06-02T03:07:57.494Z [openai] 分析当前架构 019e864d-...
3. 2026-06-01T10:17:09.954Z [openai] 检验飞书 CLI adapter 019e82af-...
Select session number:
选中你需要的会话后，codexx 会使用该 session 记录中的 provider，自动调用官方 Codex 进行恢复：
codex -c model_provider="openai" resume
原生选择界面模式
默认的 codexx resume 提供的是轻量级列表，方便跨 provider 快速定位 session。如果你希望进入 Codex 原来的 resume 界面，使用原生的展开、预览等交互操作，可以启用这个模式：
codexx resume --native
该模式会先让你选择一个 provider，然后在每个 provider 下展示最多 3 条最近的会话摘要：
1. [openai] 3 sessions
- 2026-06-02T03:07:57.494Z 分析当前架构
- 2026-06-01T10:17:09.954Z 检验飞书 CLI adapter
- 2026-06-01T07:46:12.435Z 生成架构图
2. [custom] 1 sessions
- 2026-06-03T01:19:15.977Z 修复 resume 找不到旧会话
Select provider number:
选定之后，就会进入 Codex 自己的选择界面：
codex -c model_provider="openai" resume
如果你已经明确知道要用哪个 provider，也可以直接指定，跳过外层选择：
codexx resume --native --provider openai
常用命令一览
codexx resume
codexx --version
codexx -v
codexx resume --latest
codexx resume --latest --dry-run
codexx resume --provider openai
codexx resume --include-subagents
codexx resume --cwd C:\path\to\project
codexx resume --native
codexx resume --native --provider custom
参数详解
| 参数 | 说明 |
|---|---|
-v, --version | 显示当前安装的 codexx 版本号。 |
--cwd | 指定需要匹配的工作目录，默认为当前目录。 |
--provider | 只显示特定 provider 的会话；在 --native 模式下会跳过 provider 选择步骤。 |
--include-subagents | 显示 helper/subagent 这类子线程，默认隐藏，防止底层的线程干扰普通 resume 列表。 |
--latest | 直接恢复最近更新的匹配会话。 |
--native | 先选择 provider，再进入 Codex 原生的 resume 界面。 |
--dry-run | 仅打印将要执行的 codex 命令，不实际执行恢复操作。 |
--no-provider-override | 使用 session id 恢复，但不会传入 model_provider=... 参数。 |
--codex-command | 指定 Codex 可执行文件的名称或完整路径，默认为 codex。 |
--codex-home | 指定 Codex 的 home 目录，默认使用 CODEX_HOME 环境变量或 ~/.codex。 |
标题的提取逻辑
codexx 会优先读取 Codex 的 session_index.jsonl 中记录的标题。如果某个新创建的 session 尚未写入该索引，它就会从对应的 JSONL 文件里提取第一条真实的用户消息作为标题。
为了防止标题变成冗长的系统上下文，codexx 会跳过以下自动注入的内容：
AGENTS.md instructions
environment_context
skill payload
plugins payload
turn_aborted marker
注意事项
codexx 本身不会对 Codex 的 session 文件做任何修改。它只负责读取本地的元数据，然后将实际的恢复操作交还给官方的 codex CLI 来处理。
