codex-provider-sync README

The project's README from github.com/Dailin521/codex-provider-sync. As one markdown file: README.md.

codex-provider-sync

切换 Provider 后,帮助 Codex 旧会话重新可用

CI CLI / Web Releases License Community

中文 · English · 日本語 · 한국어

它解决什么

切换 Provider 后,旧会话可能仍记录着原来的 Provider。本工具将会话文件与 SQLite 聊天索引中的 Provider 信息对齐到当前配置,解决元数据不一致的问题。

不保证跨 Provider / 账号的旧会话一定能继续或压缩,也不处理登录、认证或加密内容。信息已对齐时,无需重复同步。

Provider 元数据同步示意:保持当前配置不变,将会话文件与 SQLite 索引从 Provider A 对齐到 Provider B

什么时候需要它

按你切换 Provider 的方式,选择对应操作:

核心功能

下载 Windows 桌面版

Windows x64,无需 Node.js。未签名;便携版须完整解压。

下载最新正式版:安装版 / 便携 ZIP、版本说明与校验

macOS/Linux Electron 包尚未发布;CLI / Web 的 npm 版本独立发布。

日常使用

  1. 打开“概览”,确认 Provider、存储路径和同步状态。
  2. 已通过 CCSwitch 等工具切换 Provider:点击“预览同步”查看影响,或“直接同步”立即执行。
  3. 查看结果。部分完成时,结束相关占用会话后重试;需要撤销时进入“备份 / 恢复”。

“单独切换 Provider”会修改配置并同步历史 Provider,不改历史模型;自定义 Provider 需预先配置。

修改前自动备份,默认保留最近 2 份,在“备份 / 恢复”中管理;无需修改时不备份,受保护备份不受数量限制。

桌面完整指南 · 旧版迁移说明

本地 Web UI

安装 Node.js 16.20.2+ 后运行,获得 npm 当前已发布的 CLI / Web 版本:

npm install -g @dailin521/codex-provider-sync
codex-provider web

默认只监听本机 127.0.0.1:8791,打开浏览器完成配对。跨设备使用见 Web 指南与 SSH 用法。

CLI

安装同一个 npm 包后,先检查,再同步:

codex-provider status
codex-provider sync

CLI 写命令直接执行。切换 Provider、恢复备份、Watch、路径参数及 JSON 退出码见 CLI 指南;命令是否可用以安装版本的 --help 为准。

一个核心,三个入口

Windows 桌面版、Local Web 和 CLI 使用同一套同步、切换、备份与恢复逻辑;选择入口只影响操作方式,不影响同步结果。

flowchart LR
    subgraph Entry["入口"]
        Desktop["Windows 桌面版"]
        Web["Local Web"]
        CLI["CLI / 脚本 / WSL"]
    end

    subgraph Core["共享 Node Core"]
        Interface["统一操作入口"]
        Operations["状态 / 同步 / 切换<br/>Watch / 修复 / 恢复"]
        Runtime["计划校验 / 并发控制<br/>进度与取消"]
        Interface --> Operations --> Runtime
    end

    Desktop --> Interface
    Web --> Interface
    CLI --> Operations
    Runtime --> Config["Codex 配置"]
    Runtime --> Sessions["会话文件"]
    Runtime --> SQLite["SQLite 索引"]
    Operations --> Backup["备份与恢复"]

普通同步只对齐 Provider;专项修复和恢复需要明确选择。旧 .NET Windows/macOS 版仍作为兼容实现维护。

开发者可查看当前 Node Core 架构和 Electron + Node 架构基线。

同步如何读写,速度取决于什么

同步只解析每个会话的首行元数据,并对齐会话文件和 SQLite 中的 Provider;聊天正文保持不变。

这两种方式会自动选择,无需设置加速选项,也不必把 Provider 名称改成相同长度。

速度主要取决于需要更新的会话数量;Provider 长度不同且历史文件较大时,还需要复制正文,耗时会增加。备份、写前校验、落盘和时间戳恢复也会占用时间。操作日志可查看各步骤耗时。

工作原理与路径解析 · Provider I/O 不变量

常见问题(FAQ)

已经用 CCSwitch 切换了,还需要做什么?

打开本工具,确认当前 Provider 是你要使用的,再点击“同步”。如果会话文件和索引中的 Provider 已经一致,就无需重复同步。

同步会修改聊天内容或登录信息吗?

不会。同步只对齐会话文件和 SQLite 索引中的 Provider,不修改聊天正文、历史模型或会话排序时间,也不读取或修改登录文件 auth.json。

为什么同步后,旧会话仍无法继续?

Provider 一致只是继续会话的一个条件。请查看 Codex 的具体报错;若涉及加密内容或模型兼容问题,可回到原 Provider / 账号,或新建会话。

显示“部分完成”怎么办?

先查看结果或操作日志中的原因。异常会话会跳过并保留关联索引,正常会话继续处理:格式或大小问题需处理数据后重新预览;占用或变化可等会话停止写入后再同步。已完成的修改不会自动全量回滚。

同步错了,如何恢复?

在“备份”中选择对应操作前的备份并恢复;CLI 可使用 codex-provider restore <backup-dir>。具体步骤见桌面指南或 CLI 指南。

路径配置与 WSL 用法见 CLI 指南;同步耗时说明见工作原理。

文档与开发

源码开发使用 Node 24:

npm ci
npm run architecture:check
npm test
npm run web:build
npm run desktop:build

开发时先读当前架构,再查对应合同、ADR 与测试。构建成功不等于完成所有平台的发布验收。

致谢与许可

感谢 @tangquanwei 贡献本地 Web UI、聊天记录浏览和多语言文档基础,并通过 PR #80 带入 v0.5.0;感谢所有参与贡献和问题调查的朋友。

贡献者 · GitHub Contributors · LINUX DO 社区 · MIT License

codex-provider-sync (Dailin521/codex-provider-sync)

Searching Database…

Что это такое?Утилита для восстановления сессий OpenAI Codex: после смены провайдера старые сессии могут по-прежнему ссылаться на прежнего, и этот инструмент приводит метаданные провайдера в файлах сессий и в SQLite-индексе чатов в соответствие с вашей текущей конфигурацией.
Это десктопное приложение, веб-инструмент или CLI?И то, и другое, и третье — с общим ядром: десктопное приложение для Windows, локальный веб-интерфейс и CLI. Отличается только способ работы — синхронизация, смена провайдера, резервное копирование и восстановление работают одинаково везде.
Как его установить?Скачайте десктопную сборку для Windows x64 (установщик или переносимый ZIP) со страницы Releases — Node.js не нужен. Учтите: бинарник не имеет подписи, а переносимый ZIP нужно полностью распаковать. CLI и локальный веб-интерфейс распространяются отдельно через npm.
Нужен ли установленный Node.js для какого-то из вариантов запуска?Только для npm-вариантов: локальному веб-интерфейсу и CLI нужен Node.js 16.20.2 или новее, а десктопная сборка для Windows всё включает сама. Для сборки из исходников используется Node 24.
Если я запущу синхронизацию, мои старые сессии точно снова заработают?Гарантии нет — совпадение метаданных провайдера лишь одно из условий. Инструмент не занимается входом, аутентификацией и зашифрованным содержимым, поэтому сессия с другого провайдера или другого аккаунта может по-прежнему не работать; смотрите ошибку, которую выдаёт сам Codex.
Десктопное приложение работает на macOS или Linux?Пока нет — сборки Electron для macOS и Linux ещё не выходили, так что текущая десктопная версия только для Windows x64. npm-CLI и локальный веб-интерфейс работают на любых платформах, а старая сборка на .NET для Windows и macOS всё ещё поддерживается.
Он сам умеет менять провайдера или только чинит сессии после того, как я воспользовался CCSwitch?Работают оба сценария. Если вы уже сменили провайдера через CCSwitch или похожий инструмент, просто запустите синхронизацию с текущей конфигурацией; либо смените провайдера прямо в этом инструменте — он сначала обновит конфигурацию, а затем приведёт файлы сессий и индекс в соответствие. Пользовательские провайдеры должны быть заранее настроены.
Почему синхронизация на аккаунте с большой историей может идти долго?Время в основном зависит от того, сколько сессий нужно обновить. Когда имя нового провайдера отличается по длине в байтах, а старые файлы большие, инструмент записывает неизменённое тело в новый файл, а не правит старый на месте; своё время также занимают резервные копии, проверка перед записью и сброс на диск. В журнале операций видно, сколько длится каждый шаг.
Как он не даёт повредить мои файлы сессий?Он разбирает только первую строку каждой сессии и переписывает там метаданные провайдера. Если длины имён провайдеров совпадают, правка идёт на месте; иначе тело файла записывается потоково в новый файл, который заменяет исходный. Содержимое чатов никогда не меняется.
Что ещё он умеет, кроме починки сессий?Можно просматривать сессии по проектам, смотреть результаты и длительность операций, задавать своё место хранения, а также запускать диагностику или точечный ремонт. Режим автосинхронизации поддерживает сессии в актуальном состоянии без ручных нажатий.
Creator
Dailin521
Size
12.2 MB
Stars
3.6K
Age
6mo
Commits · 90 Days