说到 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_HOME=D:\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 执行策略 | 至少为 RemoteSigned | Get-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 配置备份，我建议你今天就做三件事：确认配置目录位置、做一次手工全量备份、把这个备份复制到非系统盘。这三件事加起来十分钟都不到，但真到出事那天，你会感谢这十分钟。如果之后你用上了小怪工具，也记得定期做一次“恢复演练”——我就是在演练中发现了路径兼容性和进程占用这两个问题，总比真的丢了配置再手忙脚乱要好得多。
