旧项目在新版本Codex中失败主因是配置结构、字段契约和缓存状态不兼容；需检查skill目录路径、manifest.json的api_version字段、config.toml字段迁移、API响应中间件及清理legacy缓存。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在新版本Codex中运行旧项目时，发现技能包加载失败、config.toml字段被忽略、API调用报错或历史会话无法恢复，问题往往不出在代码本身，而是旧版残留的配置结构、字段契约和缓存状态与新版运行时不匹配。
确认旧版代码是否真被加载
打开终端，执行：codex exec --debug list-skills。若输出中缺失你明确安装过的技能名，说明它们未被识别——不是技能损坏，而是新版默认跳过旧版技能目录~/.codex/skills/，只扫描~/.codex/skills/v2/及子目录。
检查技能包内是否存在manifest.json。旧版技能可能只有skill.py和README.md，而新版强制要求manifest.json中定义api_version字段，值必须为"v2"或"v3"。缺少该字段或值为"v1"将直接导致跳过加载。
【旧版manifest.json中"api_version": "v1"必须手动改为"v2"，否则技能永不启用】
修复旧版配置字段兼容性
方法一：字段映射重写（推荐用于config.toml）
旧版常用model = "gpt-4"，新版已弃用该顶层字段，改由[models.default]块声明。需将：
model = "gpt-4"<br>temperature = 0.7
替换为：
[models.default]<br>name = "gpt-4"<br>temperature = 0.7
方法二：保留旧字段但禁用冲突（适用于临时过渡）
在~/.codex/config.toml顶部添加：legacy_mode = true。该开关仅对v1.4.0+生效，会启用兼容层解析旧字段，但不支持混合使用新旧语法——一旦出现[models]块，legacy_mode自动失效。
通过本地 Codex 或 OpenClaw OAuth 凭证直接调用 ChatGPT/Codex Responses 的 image_generation 工具来生成或编辑光栅图像，然后保存
处理API响应字段不兼容
第一步：识别断点位置
在旧客户端中捕获返回体，对比新旧响应结构。常见断裂点是choices[0].message.content变为response.choices[0].delta.content，或usage.total_tokens移至根级metadata.usage.total_tokens。
第二步：注入兼容中间件
在项目根目录新建codex-compat.js，写入：
module.exports = (raw) => {<br> if (raw.response && raw.response.choices) {<br> return { choices: raw.response.choices, usage: raw.metadata?.usage || {} };<br> }<br> return raw;<br>};
第三步：注册中间件
编辑~/.codex/config.toml，在[exec]下添加：response_transformer = "./codex-compat.js"。Codex启动后将自动加载并包装所有API响应。
注意：该文件路径必须为相对~/.codex/的路径，不能用绝对路径或~/缩写。
清理旧版缓存避免静默覆盖
执行：rm -rf ~/.codex/cache/legacy/*。该目录存放v0.x时代生成的SQLite索引和AST快照，新版不再读取，但若存在且权限异常，会阻塞codex import命令的初始化流程。
Windows用户请手动进入%APPDATA%\Codex\cache\legacy\，删除全部内容。若提示“文件正在使用”，先在任务管理器中结束所有codex.exe进程，再删除。
这一步不做，后续导入旧项目时可能卡在“Building symbol index…”长达2分钟以上，且无任何错误提示。
