migrate-to-codex

迁移到 Codex

自主性

持续执行，直到所选迁移完全完成：运行迁移器、检查报告、修复迁移后的 Codex 指令/技能/Agent/MCP 配置，并重新运行检查，不要停下来询问是否继续下一步。如果用户已选择目标，则无需事先询问，即可在该目标中创建、编辑、替换或删除生成的 Codex 产物（AGENTS.md、.codex/、.agents/ 或 ~/.codex/）。保留 .codex/config.toml 或 ~/.codex/config.toml 中无关的现有 Codex 配置项，例如 notify、projects、marketplaces 或无关的 MCP 服务；除非这些配置项无法通过验证或与迁移直接冲突，否则不要询问。不要编辑源 Claude Code 文件（.claude/、~/.claude/、.mcp.json 或 .claude.json）、无关的项目代码、密钥或其他仓库。

迁移顺序

针对每个选定的全局或项目源，按以下顺序执行迁移：

1. 首先使用 Codex 内置的 TODO/任务列表工具。除非用户明确要求，否则不要创建 MIGRATION_TODOS.md 或任何 TODO 文件。TODO 列表的输入包含一个 plan 数组，其中每个项目都有 step 和 status；状态使用 pending、in_progress 和 completed。TODO 内容要针对所选产物。结束前，更新 TODO 列表，将所有已完成的步骤标记为 completed，且不留任何 in_progress 状态的步骤。使用源 → Codex 目标的字面标签，例如：

   • 检查 .claude/commands → Codex 技能/提示词
   • 检查 .claude/agents → .codex/agents
   • 检查 .mcp.json → .codex/config.toml MCP 服务
   • 检查 .claude/settings.json 钩子 → .codex/hooks.json
   • 将选定的安全产物迁移到 Codex 文件
   • 验证生成的 .codex/config.toml
   • 验证生成的 .codex/agents
   • 报告已迁移的产物及需人工审查的项目

2. 阅读 references/differences.md（如果其中的 Docs last checked 日期已过时，则更新 Codex 文档）。

3. 写入前先扫描并检查：

   • --scan-only 列出活跃和非活跃的源内容。
   • --plan 输出分阶段生成的 Codex 产物路径和报告行。
   • --doctor 汇总就绪状态、需人工审查的工作和验证风险。

4. 按 CLI 使用的相同顺序转换各类内容：

   • 指令：将 CLAUDE.md / AGENTS.md 转换为 AGENTS.md
   • 插件：将 Claude 插件树和市场列为需人工迁移的工作
   • 钩子：将支持的 Claude 钩子改写为 .codex/hooks.json，并启用 [features].codex_hooks = true
   • 技能和命令：在 .agents/skills/ 下编写 Codex 技能
   • 配置：根据 Claude 模型/沙盒设置和 MCP 服务编写 .codex/config.toml；生成配置时包括 personality = "friendly"
   • 子 Agent：在 .codex/agents/ 下编写 Codex 自定义 Agent

5. 先进行试运行，再写入所选目标。只有在需要删除孤立的生成技能或 Agent 时才使用 --replace。

6. 实际运行后，检查终端输出和 .codex/migrate-to-codex-report.txt。

7. 按以下顺序审查生成的产物：AGENTS.md、.agents/skills/、.codex/config.toml、.codex/hooks.json、.codex/agents/，最后检查仅在报告中列出的插件项目。

8. 编辑后，针对每个目标运行 --validate-target。

9. 编辑后，重新运行检查和 --dry-run。

10. 最终迁移报告中，每个有行的范围各提供一个 Markdown 表格。表格仅涵盖你执行的非原生后续迁移工作，例如从斜杠命令创建的技能、子 Agent、MCP 服务、钩子、不受支持/本地插件说明以及人工审查注意事项。只有在本次后续运行中由你亲自迁移了配置、指令、技能或受支持插件时，才包含这些项目的程序化原生导入行。 如果只有一个作用域有行，则仅呈现表格，不添加标题。如果多个作用域都有行，则在每个表格前添加一个标题。用户作用域的行使用 **User Config**。项目作用域的行使用实际项目文件夹名称作为标题，例如 **northstar-support-portal**；不要使用 Current Project 作为标题。不要在表格输出前后添加说明文字。

    列必须严格如下：

    northstar-support-portal

    Status	Item	Notes
    Added	Slash command pr-review	已转换为 Codex 技能
    Added	Subagent release-lead	已添加为 Codex 子 Agent
    Check before using	Hook PreToolUse	已转换，但 Claude 的部分钩子行为在 Codex 中有所不同
    Not Added	Hook Notification	Codex 没有等效的通知钩子
    Not Added	Plugin team-macros	插件需要手动设置

    Status 必须是 Added、Check before using 或 Not Added。当已创建或更改面向 Codex 的产物，且不需要特别审查时，使用 Added。当已创建或更改面向 Codex 的产物，但迁移改变了语义、推断了行为、将工具规则保留为指导，或舍弃了不受支持的行为时，使用 Check before using。当检测到源产物，但未创建面向 Codex 的产物时，使用 Not Added。Item 在一个单元格中组合产物类型和具体项目名称。产物类型必须使用单数：Skill、Slash command、Subagent、MCP、Hook 或 Plugin。产物类型使用行内代码格式；项目名称作为普通文本写在其后。Notes 为必填项；不得留空。备注应简短、直白且客观。避免使用 runtime expansion 等内部实现术语。优先使用以下表述：Converted into a Codex skill、Added as a Codex subagent、Added to Codex config、Converted into a Codex hook、Converted, but some Claude hook behavior differs in Codex、Codex does not have an equivalent notification hook、Plugin needs manual setup 或 Plugin marketplace needs manual setup。

自愈循环

持续循环，直到所选迁移完成：

1. 运行 --plan 或 --doctor。
2. 使用 --dry-run 运行迁移。
3. 正式运行迁移。
4. 修复每个生成的 ## MANUAL MIGRATION REQUIRED 区块，以及所有可在 Codex 产物中解决的 manual_fix_required 或 skipped 报告行。
5. 运行 --validate-target。
6. 重新运行迁移工具和验证器，直到报告和验证器都不再指出需要修复的生成产物。

在此循环中，不要编辑 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

先试运行，再在不带 --dry-run 的情况下运行，分别处理全局和项目范围。

$MIGRATE_TO_CODEX --source ~/.claude/ --target ~/.codex/ --dry-run
$MIGRATE_TO_CODEX --source ~/.claude/ --target ~/.codex/
$MIGRATE_TO_CODEX --source ./.claude/ --target ./.codex/ --dry-run
$MIGRATE_TO_CODEX --source ./.claude/ --target ./.codex/

编辑后，针对每个目标运行迁移后验证器。

$MIGRATE_TO_CODEX --validate-target ~/.codex/
$MIGRATE_TO_CODEX --validate-target ./.codex/

运行 $MIGRATE_TO_CODEX --help 查看标志（--scan-only、--plan、--doctor、--validate-target、默认值等）。更多详细表格和链接见 references/differences.md。