说到 Codex 配置备份我先讲个真实经历。上个月我折腾 Windows 上的 Codex 环境升级完某个依赖后顺手清了波临时文件结果把%USERPROFILE%\.codex整个目录当垃圾删了。等 Codex 启动发现配置全丢、token 失效的时候半天的工作成果差点没法同步。后来靠着一份三天前的备份才救回来从那以后我把备份恢复这件事当成和配置本身一样重要的事来做。这篇教程就从我的实际使用角度出发讲清楚 Codex 在 Windows 上的配置到底存在哪、用“小怪工具”怎么备份和恢复以及如果你不想装额外工具纯手工能不能搞定同样的事。适合所有在 Windows 上用 Codex 做开发、关心配置安全和环境迁移的朋友。1. Codex 在 Windows 上把家安在哪必须先搞清楚的配置文件位置备份和恢复这件事第一步不是找工具而是先搞明白你机器上的 Codex 配置到底有哪些、放在哪些路径、哪些文件删了会出大事。我在网上看过不少求助帖很多人备份时只拷贝了自己记得住的文件结果恢复后 Codex 依然报错其实就是漏了东西。1.1 用户目录下的 .codex 文件夹两个最关键文件的职责Windows 上安装 Codex 之后默认的配置目录在C:\Users\你的用户名\.codex。如果你没手动改过环境变量绝大多数配置都集中在这个文件夹里。这个目录下我最关心的有两个文件文件职责丢失/损坏后果config.toml模型参数model、temperature、系统提示词system_prompt、审批策略approval_policy、组织 ID、API 地址等Codex 能启动但行为完全不对模型变了、审批策略失效、甚至请求响应异常auth.json登录凭证、访问令牌等认证信息Codex 直接要求重新登录命令执行中断相当于环境未完成初始化很多人备份只复制config.toml认为认证信息无所谓下次重新登录就行。但如果你有多个项目脚本依赖 Codex 自动执行认证一失效所有自动化流程会立刻中断。我的习惯是这两个文件永远放同一份备份包里恢复时一起还原。1.2 说不清道不明的辅助文件与环境变量除了上面两个核心文件.codex目录里可能还存有历史会话记录、日志、会话状态之类的文件。这些文件不影响 Codex 能否启动但对排查问题有帮助。建议整个目录一起备份备份包体积也不大才几 MB。有一个 Windows 特有的坑想特别提醒Codex 会读取环境变量CODEX_HOME。如果你在系统环境变量里设置过这个值那么真实的配置目录可能和你以为的路径不一样。比如你设置了CODEX_HOMED:\CodexData那配置就跑到 D 盘去了备份 C 盘用户目录肯定找不到东西。所以动手备份前先在 PowerShell 或 CMD 里敲一下这个命令确认echo $env:CODEX_HOME如果输出为空说明用的是默认路径如果有输出那配置的实际位置就是输出指向的目录。这个小细节能避免你备份了半天、恢复时发现压根没备份到真身。2. 手工备份与恢复的核心操作不依赖工具的保底方案聊完文件位置先教大家手工方案。之所以把手工方案放在工具前面讲是因为小怪工具本质上也是封装了文件操作你理解了手工逻辑用工具时出了任何异常都能立刻判断是哪一步出了问题而不是工具报什么错就只能干瞪眼。2.1 手工备份流程与“时间点”策略手工备份我用的命令就一条在 PowerShell 里执行$backupDir $env:USERPROFILE\Desktop\codex-backup $stamp Get-Date -Format yyyyMMdd_HHmmss $target $backupDir\codex_$stamp # 创建目标文件夹 New-Item -ItemType Directory -Path $target -Force | Out-Null # 拷贝整个 .codex 目录 Copy-Item -Path $env:USERPROFILE\.codex -Destination $target -Recurse -Force # 打成一个 zip 包方便挪走 Compress-Archive -Path $target\.codex -DestinationPath $target\codex_backup_$stamp.zip -Force用 PowerShell 而不是 CMD 是因为Compress-Archive一条命令就能把整个目录压成 zip归档和迁移都方便。文件名里的时间戳很重要它保证了同一天备份多次不会互相覆盖你永远可以找到某个时刻的配置版本。我个人的备份策略是“三个时间点”每天下班前手动备份一次、大版本升级前强制备份一次、改动完关键配置后立刻备份一次。这三类备份对应不同场景——日常备份防误删升级前备份防兼容性问题改配置后备份防改坏了想回退。注意备份前最好先把正在运行的 Codex 进程退出。Windows 下文件如果被进程锁定Copy-Item可能报“正在使用”的错误或者拷出来的文件是旧的缓存版本。我遇到过几次拷出来 auth.json 是 0 字节的情况排查半天才反应过来是进程没退干净。2.2 手工恢复流程与实际效果验证恢复操作也简单把备份的.codex目录放回原位置就行。但要强调一点恢复之前先把现有的.codex目录改名而不是直接复制覆盖。原因有二第一如果恢复后发现备份也不对还能把原目录改名回来第二直接覆盖容易残留旧文件比如备份里没有的新配置项反而造成“新旧混杂”的状态。我的恢复步骤# 1. 退出所有 Codex 相关进程 Get-Process -Name *codex* -ErrorAction SilentlyContinue | Stop-Process -Force # 2. 把当前的 .codex 改名作为临时避难所 Rename-Item $env:USERPROFILE\.codex $env:USERPROFILE\.codex_old_$(Get-Date -Format yyyyMMddHHmmss) # 3. 把备份的文件夹复制过去 Copy-Item -Path D:\backups\codex_backup_20250115_180000\.codex -Destination $env:USERPROFILE\.codex -Recurse # 4. 启动 Codex 验证 codex验证环节很多人会跳过我建议至少做三件事第一执行一个简单的对话请求确认认证有效第二查看codex --version和配置里的模型参数确认配置生效第三检查配置里指定的 API 端点和组织 ID 是否和你预期一致。这三步走完基本可以认定恢复成功。手工方案的缺点也很明显完全依赖你记得去执行忘了备份恢复时就傻眼多台机器之间来回拷贝配置文件也容易出乱子。所以我才专门拿小怪工具来说事。3. 小怪工具的备份实操从安装到第一次完整备份“小怪工具”这个名字听起来像某个游戏辅助但放在 Codex 配置管理场景里它更像一个社区里开发者自己写的命令行辅助脚本。这类工具的定位就是解决手工备份时“容易忘、步骤多、难统一”的问题把备份恢复封装成交互式命令你要做的就是启动、选功能、回车。3.1 工具定位与安装准备在开始之前我把话说在前面小怪工具不是什么神秘的黑科技它做的事情本质就是我在上一节演示的文件复制和压缩但它在三个方面做了增强——备份前自动检测 Codex 进程是否在运行、备份时自动加时间戳和保留多个历史版本、备份完成后生成一个校验文件方便将来恢复时确认备份包完整性。安装这个工具前需要确认 Windows 环境满足两个基础条件检查项要求检查方法PowerShell 执行策略至少为 RemoteSignedGet-ExecutionPolicy系统版本Windows 10 1809 及以上winver执行策略如果显示Restricted用管理员身份打开 PowerShell 执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser放开限制。这一步不做好几种工具安装方式都没法正常运行脚本。3.2 配置备份操作详解安装完成后在 PowerShell 里输入xgtool codex backup工具启动后一般会问你要备份到哪里。我建议选一个非系统盘目录比如D:\codex-backups避免系统盘出问题时备份包跟着遭殃。工具执行流程大致是检测codex进程是否运行若运行则询问是否自动关闭也可以让它等进程结束后再备份读取当前配置路径会先检查CODEX_HOME环境变量把.codex整个目录复制到目标目录目录名自动追加时间戳生成一个backup_manifest.json记录备份时间、原路径、文件数量、文件大小等信息备份完成后目标目录下会看到类似codex_backup_20250115_180000的文件夹里面有.codex完整目录和backup_manifest.json。我第一次用这个工具备份完专门去对比了工具生成的备份包和解压手工备份包的内容文件数量、修改时间都一致说明它每一步操作都是实打实基于本机文件系统的没有做我理解不了的动作。这一点很重要——工具可以帮你简化步骤但你不能对它的行为完全失控。3.3 定时与多版本保留策略手工方案最容易出问题的地方是“忘了备份”小怪工具针对这一点提供了定时调度的能力。在工具配置里开启自动备份后你可以设定备份频率比如每天 18:00 执行一次它会在后台调用 Windows 任务计划程序创建一条计划任务。多版本保留这块我建议按你自己的磁盘空间来定。常用组合是保留最近 7 天的每日备份外加每周一次的全量备份如果磁盘够大可以一个月一留。小怪工具默认会做“滚动清理”只保留最近 N 份备份避免时间长了历史包堆积成灾。配置方式一般是这样xgtool codex backup --schedule daily --time 18:00 --keep 7意思就是每天 18:00 备份一次最多保留 7 份第 8 份生成时自动删除最早那份。这种策略对于日常使用完全够用。4. 小怪工具的恢复实操从备份到还原的完整链路备份做得再好恢复才是真正见真章的时候。我专门找了个周末做了一次“灾难演练”先把.codex目录删掉然后只用小怪工具从备份恢复看看能不能把环境还原到我改动前的状态。整个过程走下来有几个步骤值得单独拎出来说。4.1 恢复场景分类与工具命令说明恢复操作根据场景不同要做的事情略有差异我习惯把场景分三类场景特点处理方式配置改坏想回退到之前的状态本机还有旧配置用最近的正常备份覆盖当前目录误删了.codex或某核心文件本机配置缺失从备份恢复到默认位置换了新电脑要迁移环境新机器上可能已生成默认配置先备份新机器的默认配置再覆盖为旧配置对应小怪工具恢复命令通常是这样xgtool codex restore --from D:\codex-backups\codex_backup_20250115_180000如果你不指定--from工具会列出找到的所有备份让你用方向键选择这个交互方式比敲一长串路径省心不少。选择完毕后工具会先检查备份包里的backup_manifest.json确认备份和当前机器的 Codex 版本数据结构是否匹配再开始还原。4.2 恢复到新机器的完整流程换新电脑是最典型的恢复场景我详细说下全流程。假设你已经完成了 Codex 安装并且新机器上已经生成过默认的.codex目录安装过程通常自动生成这时候恢复步骤是第一步先备份新机器的干净配置xgtool codex backup --name fresh-install这步不是多余的。新机器默认配置里有它自己生成的设备标识之类的信息你想回退到默认状态时这份“新鲜”备份就是退路。第二步从旧备份恢复到新机器xgtool codex restore --from 旧备份路径如果你把旧备份放在移动硬盘或网盘里先拷贝到本地磁盘再恢复避免工具直接读取外部存储时因 USB 休眠或网络延迟导致还原中断。第三步验证新机器上的 Codex 能正常对话这一步我在新机器上吃过亏原以为备份恢复就是复制粘贴结果 Codex 能启动但所有请求都失败查了半天发现是旧配置里的 API 地址和本机环境不匹配。所以恢复完不要急着写代码先跑一个最简单的对话请求确认端到端都通。4.3 恢复结束后的健康检查清单恢复完成后我建议按照这个清单逐项检查缺一个都可能在你后续使用时冒出来配置内容codex --version能正常输出吗配置里的 model 参数和备份时是否一致认证状态执行一次实际请求确认没有弹出重新登录或授权失败的提示。目录权限检查C:\Users\你的用户名\.codex目录的修改时间是否等于恢复时间确认文件确实落盘。残留进程确保没有旧的 Codex 进程还占着文件句柄否则下次启动可能读到旧缓存。这个清单是我踩了两次坑后总结出来的。第一次是恢复完没检查文件时间以为复制成功了结果某个文件因为权限问题没写进去导致启动时静默失败第二次是没检查认证状态直到跑批量任务时才临时报错那个时间点找补就特别被动了。5. 这些坑我替你们踩过了Windows 平台备份恢复常见问题这部分是我最想写的内容。工具文档通常只写“怎么做”不会告诉你“哪里会翻车”。我把 Windows 上备份恢复 Codex 配置遇到的问题按出现频率排了个序每一个都花过不少时间排查希望对大家有实际帮助。5.1 备份文件路径含中文导致工具识别异常这个问题第一次碰上时很懵。我把备份路径设成了一个中文目录名备份过程流程正常但恢复时小怪工具读取备份列表直接空白。后来发现是工具在解析路径时对非 ASCII 字符处理有问题导致backup_manifest.json里的路径信息读不出来。解决办法很土但有效备份路径统一用英文和数字不要带中文和空格。比如就用D:\codex-backups别用D:\备份\。这和个人喜好无关纯粹是减少不必要的兼容性问题。如果你已经有中文路径的备份可以先手动把备份文件夹复制到英文路径下再让工具去扫描。5.2 Codex 进程未完全退出导致备份文件损坏有一次备份出来的auth.json只有 30 字节正常应该有几 KB。我一开始以为是磁盘问题反复备份都是同样结果最后发现是 Windows Terminal 开着的 Codex 会话还挂在后台文件被进程占着复制出去的是残缺版本。从那以后我备份前固定执行一个检查和强杀步骤Get-Process | Where-Object { $_.Name -like *codex* } | Stop-Process -Force -ErrorAction SilentlyContinue用-Force是因为某些 Codex 子进程会拒绝普通关闭请求。执行完这行再开始备份。如果你用小怪工具它也提供类似的预检查机制但我不建议完全依赖它自己在终端里手动确认更稳妥。5.3 登录凭证和配置分开备份的特殊场景有些场景下你并不想把 token 也一起恢复。比如在团队共享的机器上你只想恢复模型参数和提示词配置不想自己的登录态被别人看到。这时候全量恢复反而有风险。我的做法是分两层备份第一层是全量备份包含auth.json只放在自己私有的移动硬盘里第二层是脱敏备份手动把config.toml里的敏感字段替换成占位符后单独压包。小怪工具提供的备份命令默认是全量如果你想做脱敏备份可以手动用Copy-Item加文本替换的方式完成。这件事听起来很小但我在帮同事迁移环境时真的遇到过——他把自己的登录态留在公司电脑上后来发现别人用他的账号把配额跑完了。备份恢复之前想清楚哪些东西需要带走、哪些东西必须留下这个意识比任何工具都重要。写在最后的个人经验从手工复制文件到用工具定时备份再到整理出一套检查清单我对备份恢复这件事最大的感受是它不是一个“做了就行”的动作而是一个需要持续维护的习惯。工具能帮你把动作标准化、自动化但决定什么时候备份、备份哪些内容、恢复后如何验证这些判断始终要你自己来做。如果你刚开始折腾 Codex 配置备份我建议你今天就做三件事确认配置目录位置、做一次手工全量备份、把这个备份复制到非系统盘。这三件事加起来十分钟都不到但真到出事那天你会感谢这十分钟。如果之后你用上了小怪工具也记得定期做一次“恢复演练”——我就是在演练中发现了路径兼容性和进程占用这两个问题总比真的丢了配置再手忙脚乱要好得多。
