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…

3.6K ·GitHub
Codex-provider-sync
这是干什么的？一个修复 OpenAI Codex 会话的工具：切换服务商后，旧会话可能仍然指向之前的服务商，这个工具会把会话文件和 SQLite 聊天索引中的服务商元数据重新对齐到你当前的配置。
它是桌面应用、网页工具，还是命令行工具？三种都是，共用同一个核心：Windows 桌面应用、本地 Web 界面和命令行工具。入口只改变你的操作方式——同步、切换服务商、备份和恢复在任何入口里的表现都一样。
怎么获取它？从 Releases 下载 Windows x64 桌面版（安装包或便携版 ZIP）——不需要 Node.js。注意该程序没有数字签名，便携版 ZIP 必须完整解压后再运行；命令行工具和本地 Web 界面则单独发布在 npm 上。
哪个入口需要安装 Node.js？只有基于 npm 的入口需要：本地 Web 界面和命令行工具要求 Node.js 16.20.2 或更新版本，而 Windows 桌面版是独立运行的，不依赖任何环境。从源码开发则使用 Node 24。
如果我执行一次同步，旧的会话就一定能恢复使用吗？不保证——服务商元数据匹配只是其中一个条件。这个工具不处理登录、身份验证或加密内容，所以跨服务商或跨账号的会话仍可能失败；请查看 Codex 本身报出的错误信息。
桌面应用能在 macOS 或 Linux 上运行吗？暂时不能——macOS 和 Linux 的 Electron 安装包还没有发布，目前桌面版只支持 Windows x64。npm 命令行工具和本地 Web 界面可以跨平台使用，另外还有一个面向 Windows 和 macOS 的旧版 .NET 版本仍在维护。
它能自己切换服务商，还是只能在我用 CCSwitch 切换之后修复会话？两种用法都支持。如果你已经用 CCSwitch 或类似工具切换过了，直接同步到当前配置即可；也可以在这个工具里切换——它会先更新配置，再对齐会话文件和索引。自定义服务商需要事先配置好。
为什么在历史记录很多的账号上同步可能比较慢？耗时主要取决于需要更新的会话数量。当新服务商名称的字节长度不同且旧文件很大时，工具会把未变化的内容流式写入一个新文件，而不是原地修改；备份、写入前校验以及刷盘也会增加耗时。操作日志会显示每一步的用时。
它如何避免损坏我的会话文件？它只解析每个会话的第一行并重写其中的服务商元数据。长度相等的服务商直接原地修改；否则会把正文流式写入一个新文件来替换原文件。聊天内容永远不会被改动。
除了修复会话，它还能做什么？它可以按项目浏览会话、显示操作结果和耗时、使用自定义存储位置，还可以运行诊断或针对性修复。自动同步模式能让会话保持对齐，无需手动点击。
What are similar projects?codex-command-center, ImageGlass, casbin-gateway, codex-keysmith, jev-router, stop-that-shit, raft-source, skills-manager
Which topics is it in?session-management, winforms, avalonia, openai-codex, codex-cli, backup, dotnet, sqlite, openai, codex, desktop-app, terminal
Creator
Dailin521
Size
12.2 MB
Stars
3.6K
Updated
CommitSep 28Releasev1.0.4Sep 28
Age
7mo
Commits · 90 Days