codex-auth的registry.json是如何版本演进的Schema v2到v4迁移完整指南【免费下载链接】codex-authA CLI tool to switch and manage Codex accounts项目地址: https://gitcode.com/gh_mirrors/co/codex-authcodex-auth是一个用来切换和管理多个 Codex 账号的命令行工具而它的核心数据都存放在~/.codex/accounts/registry.json这个文件里。这篇指南带你完整看懂registry.json从 Schema v2 到 v4 的版本演进每个版本改了什么、codex-auth 是如何在启动时自动完成迁移的以及迁移过程中数据如何被备份保护。registry.jsoncodex-auth 账号管理的核心存储codex-auth 把每个 Codex 账号的身份信息 本地状态集中记录在一个 JSON 文件里路径固定为~/.codex/accounts/registry.json路径的构造逻辑见 registryPath而写入时采用的是先备份、再原子替换的安全流程实现位于 saveRegistry。理解版本演进前先分清两个容易混淆的概念官方定义见 docs/schema-migration.md概念含义app_versioncodex-auth 的 CLI 发布版本如 v0.3.0schema_versionregistry.json文件的格式版本只和迁移有关current_schema_version 4、min_supported_schema_version 2两个常量定义在 src/registry/common.zig。Schema 演进时间线v2 → v3 → v4 一图看懂版本账号身份标识关键特性v2version字段邮箱email最原始的形态按邮箱做 key用active_email记录当前激活账号v3schema_version字段account_key记录键引入chatgpt_account_id/chatgpt_user_id双标识active_account_key取代active_email新增每账号last_local_rollout遗留顶层api块被忽略v4当前格式同 v3顶层新增interval_secondsLive 刷新间隔和previous_active_account_key支持codex-auth -一键切回上个账号套餐命名收敛为最终产品名三个版本之间最大的质变发生在 v2 → v3账号身份从邮箱换成了平台侧的account_key。这是因为同一个邮箱在 ChatGPT 侧可能对应多个账号上下文而 v3 起每个账号都带有独立的 chatgpt_account_id 与 chatgpt_user_id快照文件也随之从按邮箱命名改为按 account_key 命名。自动迁移如何工作升级一次直达 v4很多工具要求用户逐级安装中间版本codex-auth 不需要。它的迁移策略是规则见 docs/schema-migration.md 的Upgrade Behavior章节加载即检测每次命令运行都会读取registry.jsondetectSchemaVersion 会优先读schema_version字段兼容旧文件里的version字段甚至能识别没有任何版本字段但有active_email的 v2 老文件检测到旧版本就直接升到位v2 和 v3 文件都会一次性改写为最终的 v4 格式用户无需安装任何中间版本的 codex-auth只向前兼容不向下猜测如果文件里的schema_version比当前版本更大比如被未来版本写成了 5codex-auth 会报UnsupportedRegistryVersion并拒绝写入防止覆盖未来格式的数据。 这里有个容易忽略的细节即使是schema_version 4的文件如果还残留旧字段如旧的全局last_attributed_rollout形状、auto_switch块、live.interval_seconds加载时也会被规范化重写一次。判断逻辑在 currentLayoutNeedsRewrite。以 v2 老文件为例迁移时 loadLegacyRegistryV2 会遍历每个按邮箱存储的旧账号从磁盘快照文件中读出真实的account_key与chatgpt_*标识再把旧快照文件复制为按新 key 命名的新文件——账号数据在这个过程中被完整保留。v4 相比 v3 的四个关键变化Live 刷新间隔上移从嵌套的live.interval_seconds变为顶层interval_seconds旧的auto_switch配置块在重写时直接省略后台自动切换功能已在 v0.3.0 移除新增previous_active_account_key支撑codex-auth -/switch -切回上一个账号能力设计文档见 docs/brainstorm/2026-05-31-previous-account-switch-design.md套餐语义收敛为产品名遗留的team统一改为business旧business改为enterprise账号级last_usage.plan_type同样适用。解析入口是 parseStoredPlanType可以明显看到它对schema_version 4和≥ 4走了两套解析逻辑顶层旧version字段规范化写成version: 3的旧文件加载后会重写成schema_version: 4。迁移过程中的数据安全备份机制自动迁移虽然省心但改动用户凭证文件这件事必须可回滚。codex-auth 做了三层保护迁移前先备份任何一次改写都会先调用 backupRegistryIfChanged 生成带时间戳的registry.json.bak.时间戳备份文件备份数量上限最多保留 5 份max_backups 5见 src/registry/common.zig超出后自动裁剪最旧的写入是原子的新内容先写入临时文件成功后才替换原文件Windows 上用临时文件 重命名模拟原子替换避免写一半损坏 registry兜底恢复路径如果 registry 损坏或版本过旧低于 v2可以手动用codex-auth import --purge从导入源重建这是官方文档明确保留的恢复手段。迁移与备份行为都有对应的自动化测试覆盖例如v3 文件加载后落盘为 v4plan 值team/business迁移为规范名未知高版本号如 999拒绝迁移等用例集中在 tests/registry_test.zig。什么时候该给 schema_version 升号如果你是项目的贡献者docs/schema-migration.md 的When To Bumpschema_version给出了清晰的判断标准必须升号的情形增删、重命名任何持久化字段变更字段类型或重定义已有字段语义如active_email→active_account_key这种身份键变更改变快照文件命名规则等找到持久化文件所需的任何规则不需要升号的情形CLI 输出、帮助文案、文档变化纯内存逻辑或运行时行为调整不影响落盘数据并且文档特别强调升号前必须先问用户不要悄悄地 bump。总结codex-auth 版本演进速查问题答案registry.json 在哪~/.codex/accounts/registry.json当前 schema 版本v4最低支持 v2需要手动迁移吗不需要加载时自动升级直达 v4有备份吗每次改写前生成registry.json.bak.*保留最近 5 份遇到更新版本的文件拒绝读写报UnsupportedRegistryVersion损坏了怎么救手动codex-auth import --purge重建一次版本升级用户几乎无感——这正是 v2 到 v4 三次演进始终坚持的设计目标迁移对使用者完全透明数据永远可回滚。【免费下载链接】codex-authA CLI tool to switch and manage Codex accounts项目地址: https://gitcode.com/gh_mirrors/co/codex-auth创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考