codex 项目变更后 config.toml 与 session jsonl 的无损修正与历史线程找回

1. 项目路径一变codex 的会话就“失联”了如果你用 codex 桌面端做过一段时间开发大概率遇到过这种场景项目 A 原本放在/Users/you/work/demo-a某天你把它挪到了/Users/you/projects/demo-a或者换了台机器、改了用户名、把项目从外置盘搬回本地盘。重新打开 codex项目列表里那个条目点开就报错右侧“在 Finder 中打开”直接失败新建对话时 agent 也一脸茫然地找不到项目根目录。更让人难受的是历史会话。你之前跟 codex 聊了几十轮的 session全都不见了。重新导入新路径的项目codex 会当成一个全新项目原来的线程记录一条都不带过来。上下文断了之前让它记住的架构约定、命名规范、踩过的坑全部要重新讲一遍。这个问题的本质不复杂codex 把“项目路径”当成项目的唯一身份标识写在了三个地方——config.toml的信任配置、.codex-global-state.json的全局状态、以及~/.codex/sessions下每个.jsonl会话文件里。路径一改这三处全部对不上于是项目打不开、会话找不回。这篇就聚焦这个场景给你一套可复制的无损修正流程先备份再改config.toml骨架然后修全局状态最后逐个修正 session jsonl 里的路径重启后项目和历史线程一起回来。全程不丢上下文不需要重新导入项目。适合谁看用 codex 桌面端做长期项目、改过项目目录、换过机器或用户名的开发者。下面所有命令我都实测过路径按你自己的实际情况替换即可。2. 动手前TaoToken 前置与备份纪律在改任何文件之前先说清楚两件事一是模型接入侧的准备二是文件备份。这两件事顺序不能反。codex 本身是客户端真正跑推理的模型服务需要单独配置。我这边习惯用 TaoToken 做统一接入它的 API 地址是https://taotoken.net/api兼容主流模型调用格式配置进 codex 后不用来回切换 key。如果你还没配可以先到官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content了解一下然后在控制台生成一个 API Key地址是https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite。这个 Key 后面会写进 codex 的配置里属于“改文件”之前就该准备好的东西。注意改~/.codex下的文件前务必先整体备份。路径修正一旦改错会话文件可能直接损坏历史线程就真找不回来了。备份命令很简单把整个.codex目录复制一份带时间戳的副本cp -r ~/.codex ~/.codex.bak.$(date %Y%m%d%H%M%S)执行完确认一下副本存在ls -d ~/.codex.bak.*看到类似~/.codex.bak.20260418223000的输出就说明备份成功。这一步花不了几秒但能救命。我试过一次没备份直接批量替换结果把某个 session 里的正常文本也替换了只能从备份里捞回来。另外改文件前必须完全退出 codex 桌面端。codex 在运行时会持有这些文件你改了它可能在你保存的瞬间又写回旧值甚至覆盖你的修改。macOS 上从菜单栏退出或者osascript -e quit app codex确认进程没了再动手pgrep -fl codex没有输出就说明退干净了。3. 可复制配置config.toml 骨架与路径映射修正~/.codex/config.toml是 codex 的主配置项目信任级别、模型接入参数都在这里。先看一个可以直接抄的骨架把里面的路径和 key 换成你自己的# ~/.codex/config.toml # 模型接入配置以 TaoToken 为例 model_provider taotoken model claude-sonnet-4-5 [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY # 项目信任配置路径变了这里必须同步改 [projects./Users/you/projects/demo-a] trust_level trusted [projects./Users/you/projects/demo-b] trust_level trusted关键点在于[projects....]这一段。codex 用这个绝对路径作为项目的身份键。你原来的项目在旧路径比如/Users/you/work/demo-a配置里就是[projects./Users/you/work/demo-a] trust_level trusted项目挪到新路径后要把它改成[projects./Users/you/projects/demo-a] trust_level trusted如果你有多个项目都改过路径逐个改。改完可以用 grep 确认旧路径已经不存在grep -n work/demo-a ~/.codex/config.toml没有输出就说明config.toml里已经清干净了。这一步只解决了“项目能不能被信任、能不能打开”的问题会话记录还躺在旧路径的索引下接着往下走。4. 修正全局状态与 session jsonl 里的路径config.toml改完项目条目能打开了但历史会话还是空的。原因有两个全局状态文件.codex-global-state.json里还记着旧路径以及每个 session 的.jsonl文件内部也写死了旧路径。先处理全局状态。这个文件在~/.codex/.codex-global-state.json用 vim 做全局替换最省事vim ~/.codex/.codex-global-state.json进入后执行替换命令把旧路径换成新路径:%s#/Users/you/work/demo-a#/Users/you/projects/demo-a#g:wq保存退出。这里用#作为分隔符是因为路径里可能带/用/当分隔符会转义到崩溃。接着是重头戏~/.codex/sessions下的会话文件。它们按年月日分层存放结构大概是这样~/.codex/sessions └── 2026 └── 04 └── 18 ├── rollout-2026-04-18T22-00-20-019da0e4-76e2-79e1-865b-aff381f4c59a.jsonl └── rollout-2026-04-18T22-15-56-019da0f2-c0db-70b1-9511-366c2c11c197.jsonl每个.jsonl就是一个 session里面每一行是一条消息记录其中包含项目路径字段。会话少的话可以逐个打开替换会话多就用命令行批量处理。先确认哪些文件包含旧路径grep -rl /Users/you/work/demo-a ~/.codex/sessions这条命令会列出所有命中旧路径的 jsonl 文件。确认无误后批量替换grep -rl /Users/you/work/demo-a ~/.codex/sessions | while read -r f; do sed -i s#/Users/you/work/demo-a#/Users/you/projects/demo-a#g $f donemacOS 的sed需要-i Linux 上直接sed -i即可。替换完再跑一次 grep 验证grep -rl /Users/you/work/demo-a ~/.codex/sessions没有输出说明所有 session 的路径都指向新位置了。这一步做完历史线程的“归属”就正确了。5. 验证请求重启后确认项目与历史线程都回来了文件改完重启 codex 桌面端。打开后先看项目列表原来那个项目应该能正常点开右侧“在 Finder 中打开”也能跳转到新路径。然后重点验证历史会话。进入项目看左侧线程列表之前那些 session 应该重新出现。随便点开一个检查两件事一是对话内容完整没有丢消息二是继续在这个线程里发一条消息agent 能正确读到项目上下文而不是报“找不到项目路径”。如果你想把验证做得更硬核一点可以直接查 session 文件确认路径字段已经更新head -n 1 ~/.codex/sessions/2026/04/18/rollout-2026-04-18T22-00-20-019da0e4-76e2-79e1-865b-aff381f4c59a.jsonl | python3 -m json.tool | grep -i path\|cwd输出里如果显示的是新路径说明修正生效。再发一条测试消息比如让它读一下项目里的README.md能正常返回内容就说明上下文链路是通的。到这一步项目路径、全局状态、会话记录三处全部对齐无损修正完成。整个过程没有重新导入项目也没有丢失任何历史线程。6. 本篇常见错排查错误一改完文件重启路径又变回旧的。九成是 codex 没退干净。改文件时它还在后台运行退出时把内存里的旧状态写回了磁盘。解决改之前用pgrep -fl codex确认无进程必要时kill掉残留进程再改。错误二config.toml改了但项目还是打不开。检查路径是否写成了相对路径或带了~。codex 的[projects....]需要绝对路径~不会被展开。写成/Users/you/projects/demo-a这种完整形式。错误三session 文件替换后会话能显示但内容错乱。大概率是替换范围过大把消息正文里恰好出现的旧路径字符串也改了。这就是为什么强调先备份。从~/.codex.bak.*里恢复对应文件改用更精确的替换比如只替换 JSON 字段值而不是全文。错误四批量替换时sed报invalid command code。macOS 和 Linux 的sed -i语法不同。macOS 用sed -i Linux 用sed -i。脚本里可以判断系统或者干脆手动逐个改。错误五改完发现 API 调用失败。这通常和路径无关是模型接入配置的问题。检查config.toml里的base_url和env_key确认环境变量TAOTOKEN_API_KEY已经导出。可以在终端里echo $TAOTOKEN_API_KEY看有没有值。如果 key 没配好到https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite重新生成一个写进 shell 配置后source一下。错误六会话列表里出现重复项目。说明旧路径的[projects....]条目没删干净新路径又加了一条。回到config.toml把旧路径那整段删掉只保留新路径。7. 后续接入与长期使用建议路径修正只是把历史找回来日常用 codex 做长期项目还有几个习惯能少踩坑。第一项目目录尽量别频繁挪动。如果一定要挪挪完立刻按这篇的流程改三处文件别拖到会话攒了几百条再处理批量替换的风险和成本都更高。第二模型接入统一走一个入口。我这边长期用 TaoToken 的 Coding Plan 跑编码类任务配置一次多个项目共用不用每个项目单独配 key。地址是https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite适合需要长期跑 agent、做多轮编码的场景。如果你只是想先验证模型对话效果可以用模型对话页https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite快速试一下。第三定期备份~/.codex。会话文件是纯文本 jsonl体积不大但丢了就真没了。可以写个 cron 每周打包一次tar -czf ~/codex-backup-$(date %Y%m%d).tar.gz ~/.codex第四改任何配置文件前先cp一份。这条纪律比任何技巧都管用。我现在的习惯是只要动~/.codex下的东西第一步永远是备份第二步才是编辑。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite配置参数、模型列表、常见问题都在里面遇到接入层的报错先去这里查比到处搜快得多。