前言¶
2026 年的开发者很少只绑定一款 AI 编程工具。Cursor 写前端、Claude Code 跑长任务、Codex 接 CI——来回切换时，最耗时间的往往不是学新界面，而是把规则、Skill、MCP 服务器、子 Agent 重新搭一遍。同一套「项目记忆」散落在 .claude/、.cursor/、AGENTS.md、.mcp.json 等路径里，格式各说各话，手动对照文档改配置，半天就过去了。
OpenAI 在官方 openai/skills 仓库里维护了一个精选 Skill：migrate-to-codex。它自带 Python 迁移脚本和差异对照表，能把 Claude Code 侧已支持的指令文件、Skill、子 Agent、Hooks、MCP 配置，转换成 Codex 的项目级或全局级产物（AGENTS.md、.agents/skills/、.codex/config.toml、.codex/agents/ 等）。如果你是从 Cursor 迁过来，Codex CLI 0.145 的 /import 命令可以先把 Cursor 侧的设置批量导入；遇到 /import 无法自动处理的边角，再交给这个 Skill 做细粒度补迁。
这是什么¶
migrate-to-codex 是 OpenAI 出品的 Agent Skill，遵循通用的 SKILL.md 格式，可在 Codex CLI、Cursor、Claude Code 等支持 Skill 的工具里启用。
一句话定位：把 Claude Code 的配置面，按 Codex 官方目录规范做结构化迁移，并输出可审查的迁移报告。
它解决的核心问题是：Claude Code 与 Codex 虽然都基于 Agent Skills 开放标准，但配置文件名、Hooks 运行时、MCP 字段、子 Agent 权限模型并不完全等价。手工对照两份文档改 TOML，既容易漏项，也难追踪「哪些已迁、哪些需人工确认」。migrate-to-codex 用脚本扫描源目录、干跑预览、正式写入、校验目标，把这件事流程化。
核心功能与亮点¶
1. 覆盖完整的 Claude Code 配置面¶
官方 references/differences.md 列出了迁移映射关系，主要覆盖以下源 → 目标：
| 源（Claude Code） | 目标（Codex） | 迁移行为 |
|---|---|---|
CLAUDE.md / AGENTS.md |
根目录 AGENTS.md |
内容中性时自动 symlink；含 Claude 专有语义时断开 symlink 并生成需人工审查的副本 |
.claude/commands/*.md |
.agents/skills/source-command-*/SKILL.md |
斜杠命令转为单文件 Skill |
.claude/skills/*/SKILL.md |
.agents/skills/*/SKILL.md |
转换 Skill，并复制 scripts/、references/、assets/ |
.mcp.json / .claude.json 的 mcpServers |
.codex/config.toml 的 [mcp_servers.*] |
映射 stdio / HTTP 等可对应字段 |
.claude/agents/*.md |
.codex/agents/*.toml |
子 Agent 转为 Codex 自定义 Agent |
settings.json 中的 hooks |
.codex/hooks.json + [features].codex_hooks = true |
部分 Hook 类型可转换，语义差异需审查 |
插件树（.claude/plugins/）和市场配置不会自动复制，会在报告里标记为 manual_fix_required，需要手动处理。
2. 自带 CLI 迁移工具，支持「先看再写」¶
Skill 目录下的 scripts/migrate-to-codex.py 提供完整命令行接口，典型工作流是：
--scan-only：只扫描源目录，列出活跃与未启用的配置面--plan：打印将要生成的 Codex 产物路径，不写文件--doctor：汇总就绪度、风险项和需人工审查的内容--dry-run：模拟迁移--validate-target：对已迁移的 Codex 目录做 TOML 解析、Skill frontmatter、MCP 命令可用性等校验
迁移完成后，报告写入 .codex/migrate-to-codex-report.txt，Agent 还会按规范输出 Markdown 表格，逐条标注 Added、Check before using、Not Added 三种状态。
3. 自治式迁移循环（Self-Healing Loop）¶
启用该 Skill 后，Agent 会按官方指引持续跑完整个迁移，而不是每步都停下来问你：
- 用 Codex 内置 TODO 工具列出具体步骤
- 读取
references/differences.md（文档标注「Docs last checked: 2026-04-20」，过期时需对照最新 Codex 文档） - 先
--plan/--doctor，再--dry-run，确认后正式写入 - 修复生成文件里带
## MANUAL MIGRATION REQUIRED标记的块 --validate-target通过后，输出最终报告
重要约束：不会修改源 Claude Code 文件（.claude/、~/.claude/、.mcp.json、.claude.json），也不会动无关项目代码或密钥；已有 Codex 配置里与迁移无关的条目（如 notify、projects、其他 MCP 服务器）会保留。
4. 与 Codex /import 互补¶
Codex CLI 0.145（2026-07-21 发布）扩展了 /import 命令，可从 Cursor 和 Claude Code 批量导入设置、MCP、插件、会话、命令等。migrate-to-codex 则更擅长Claude Code → Codex 的细粒度转换和无法 1:1 映射时的语义改写（例如 allowed-tools 降级为 prompt 指引、PreToolUse Hook 在 Codex 里仅对 shell 命令生效等）。
实际操作建议：先用 /import 做批量粗迁，再用 migrate-to-codex 处理报告里的 Check before using 和 Not Added 项。
安装与启用¶
在 Codex 中安装¶
官方文档推荐用内置安装器拉取精选 Skill：
$skill-installer migrate-to-codex
也可以手动克隆到用户级或仓库级 Skill 目录（Codex 会从 $HOME/.agents/skills/ 以及仓库内 .agents/skills/ 等路径自动发现）：
git clone --depth 1 https://github.com/openai/skills.git /tmp/openai-skills
cp -r /tmp/openai-skills/skills/.curated/migrate-to-codex ~/.agents/skills/migrate-to-codex
安装后，迁移脚本通常位于：
.codex/skills/migrate-to-codex/scripts/migrate-to-codex.py
（具体路径取决于 Skill 安装位置；Skill 内用环境变量 MIGRATE_TO_CODEX 指向该脚本。）
若修改了 ~/.codex/config.toml 中的 Skill 开关，需重启 Codex 生效。
在 Cursor 中启用¶
Cursor 支持通用 Skill 格式。将 migrate-to-codex 目录（含 SKILL.md、scripts/、references/）复制到项目的 .cursor/skills/migrate-to-codex/，或在对话里 @migrate-to-codex 显式调用。Cursor 侧不会自动执行 Codex 迁移脚本——更适合用来生成迁移计划、对照 differences.md 做人工改写。
在 Claude Code 中启用¶
同理，放到 ~/.claude/skills/migrate-to-codex/ 或项目 .claude/skills/ 下即可。在 Claude Code 里调用此 Skill，主要是提前预览迁到 Codex 后会变成什么样，源环境本身不会被改动。
典型用法示例¶
场景 A：全局 Claude Code 配置迁到 Codex 用户目录¶
先扫描、规划，再干跑：
MIGRATE_TO_CODEX='python3 .codex/skills/migrate-to-codex/scripts/migrate-to-codex.py'
$MIGRATE_TO_CODEX --source ~/.claude/ --scan-only
$MIGRATE_TO_CODEX --source ~/.claude/ --target ~/.codex/ --plan
$MIGRATE_TO_CODEX --source ~/.claude/ --target ~/.codex/ --doctor
$MIGRATE_TO_CODEX --source ~/.claude/ --target ~/.codex/ --dry-run
确认无误后去掉 --dry-run 正式迁移，并校验：
$MIGRATE_TO_CODEX --source ~/.claude/ --target ~/.codex/
$MIGRATE_TO_CODEX --validate-target ~/.codex/
场景 B：单个仓库的项目级迁移¶
$MIGRATE_TO_CODEX --source ./.claude/ --target ./.codex/ --dry-run
$MIGRATE_TO_CODEX --source ./.claude/ --target ./.codex/
$MIGRATE_TO_CODEX --validate-target ./.codex/
若希望清理迁移产生的孤儿 Skill 或 Agent，可加 --replace（会删除目标侧不再对应的生成物，使用前请备份）。
场景 C：在 Codex 里用自然语言触发¶
安装 Skill 后，在 Codex CLI 或 IDE 扩展中输入类似提示：
请用 migrate-to-codex 把 ~/.claude/ 的配置迁移到 ~/.codex/。
先 --doctor 看风险，再 dry-run，我确认后再正式写入，最后 validate 并给我迁移报告表格。
Skill 的 description 写明「Migrate supported instruction files, skills, agents, and MCP config into Codex project and global files」，Codex 会在任务匹配时隐式加载；也可显式用 $migrate-to-codex 调用。
迁移报告长什么样¶
官方要求最终输出 Markdown 表格，例如：
| Status | Item | Notes |
|---|---|---|
Added |
Slash command pr-review |
Converted into a Codex skill |
Added |
Subagent release-lead |
Added as a Codex subagent |
Check before using |
Hook PreToolUse |
Converted, but some Claude hook behavior differs in Codex |
Not Added |
Hook Notification |
Codex does not have an equivalent notification hook |
Not Added |
Plugin team-macros |
Plugin needs manual setup |
看到 Check before using 时，打开对应生成文件，搜索 ## MANUAL MIGRATION REQUIRED 按提示修改。
适用场景与注意事项¶
适合谁用¶
- 已在 Claude Code 里沉淀大量 Skill、斜杠命令、子 Agent、MCP 配置，计划切到 Codex 的团队或个人
- 跑过 Codex
/import后，报告里仍有一批「需人工审查」项，希望有脚本和 Agent 协助逐项落地 - 需要在两套工具之间并行维护一段时间，想先把 Codex 侧目录结构搭齐
已知限制（务必读）¶
- 参考文档范围：
references/differences.md标题写明「Claude Code to Codex migration only」。Cursor Rules（.cursor/rules）不在该 Skill 的自动扫描范围内；Cursor 用户应优先用 Codex/import，或手工把规则合并进AGENTS.md。 - 不是语义等价保证：
allowed-tools、permissionMode、部分 Hook 类型等会被改写为 prompt 指引或部分映射；Claude 的Notification、PermissionRequest等 Hook 在 Codex 中没有直接对应。 - MCP 传输差异：Claude 的
type: sse不被 Codex 支持；Bearer 认证会转为bearer_token_env_var，但${VAR:-default}形式的默认值不会保留。 - 插件需手工：Claude 插件目录和市场配置只报告、不复制；需按 Codex 插件规范（
.agents/plugins/marketplace.json等）自行适配。 - 先备份再
--replace：正式写入前建议备份~/.codex/config.toml和项目.codex/；--replace可能删除目标侧孤儿 Skill/Agent。 - 凭证不会自动重认证：MCP 服务器名和连接参数会迁过去，OAuth 令牌等仍需在新环境里重新登录或配置环境变量。
结尾¶
多工具切换已是 2026 年开发者的常态。migrate-to-codex 的价值，在于把「Claude Code → Codex」这条路上最繁琐的配置对照工作，变成可扫描、可预览、可校验、可报告的流水线；再配合 Codex /import 处理 Cursor 侧的批量导入，换工具时的「搬家成本」会低很多。
官方 Skill 地址：github.com/openai/skills/tree/main/skills/.curated/migrate-to-codex
Codex Skills 文档：developers.openai.com/codex/skills
