恢复 codex 会话记录备份时，必须严格按照指定路径和步骤操作，因为该过程会直接覆盖当前的 SQLite 状态文件与索引文件；建议先确认备份是否有效，再根据需求选择全量恢复或按项目恢复，最后通过 CodexDesktop 界面、codex resume 以及 codex-provider-sync 三个步骤完成恢复结果验证。

如果你已经使用 codexbak 工具完成了本地会话记录备份，现在需要恢复某次历史会话或整个项目状态，就一定要严格按正确路径执行。原因在于，恢复备份会覆盖当前的 SQLite 状态和索引文件，一旦操作出错，新的会话记录可能无法正常加载，甚至导致 CodexDesktop 无法正确显示历史内容。

确认备份有效性

先打开 CodexBak.exe → 点击「检查状态」→ 等待底部显示「可用备份：X 个」，并确认右侧至少列出了一个带时间戳的备份条目。如果提示「无可用备份」，通常说明之前没有成功执行过备份，或者备份目录曾被手动清空。

接着双击任意一条备份记录 → 在弹窗中查看「会话数量」「项目数量」是否与自己的预期一致。比如你只备份过 frontend 项目，但这里却显示 12 个会话、3 个项目，那么就说明这份备份属于全量备份，而不是单个项目的快照备份。

恢复完整备份

方法一：一键全量恢复
先在备份列表中选中目标备份条目，然后点击「恢复完整备份」；随后会弹出提示窗口，明确告知「将覆盖当前所有会话索引和 SQLite 状态」——【在点击确定之前，务必先关闭 CodexDesktop】。确认后只需等待进度条执行完成即可，通常耗时约 8～25 秒。恢复流程结束后，工具会自动重启 CodexDesktop，并刷新左侧的会话列表。

方法二：仅恢复指定项目
勾选目标备份条目 → 点击「恢复选中项目」→ 在弹出窗口中勾选需要恢复的项目路径（如 C:workmy-api）→ 注意：该操作不会影响其他项目的会话内容，但会重写全局 session_index.jsonl 与 state_5.sqlite 中对应的字段信息 → 恢复完成后，需要手动重启 CodexDesktop 才能正式生效。

验证恢复结果

第一步，先打开 CodexDesktop，然后查看左侧面板中是否已经出现预期的会话标题。如果这里依然是空白，不要急着立即重新恢复，先检查右下角状态栏，确认是否显示「Provider: custom」或你当前配置的 provider 名称——【如果 provider 不一致，即使会话数据已经恢复成功，也可能不会在界面中显示出来】。

第二步：打开终端 → 进入项目根目录 → 执行 codex resume → 查看列表中是否出现 ID 带有熟悉时间戳的会话（如 2026-07-15T14-22-33）。如果能够列出来，说明备份文件已经恢复成功；如果无法列出，通常问题出在索引同步这一步。

第三步：如果 codex resume 可以看到会话，但桌面端仍然不可见，就运行 codex-provider-sync 工具修复元数据映射 → 它会扫描 sessions/ 目录下的所有 rollout 文件，并将 provider 字段批量更新为当前 config.toml 中设置的值 → 同步完成后，再重启 CodexDesktop。