migrate-to-codex

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrate to Codex

迁移到Codex

Autonomy

自主性

Keep going until the selected migration is completely done: run the migrator, inspect the report, fix migrated Codex instructions/skills/agents/MCP config, and re-run checks without stopping to ask for confirmation of the next step. If the user has selected a target, do not ask before creating, editing, replacing, or deleting generated Codex artifacts in that target (

AGENTS.md

.codex/

.agents/

, or

~/.codex/

). Preserve unrelated existing Codex config entries in

.codex/config.toml

~/.codex/config.toml

, such as

notify

projects

marketplaces

, or unrelated MCP servers; do not ask about them unless they fail validation or directly conflict with the migration. Do not edit source Claude Code files (

.claude/

~/.claude/

.mcp.json

, or

.claude.json

), unrelated project code, secrets, or another repository.

持续执行直至所选迁移完全完成：运行迁移工具、检查报告、修复已迁移的Codex指令/技能/Agent/MCP配置，并重新运行检查，无需停下来请求下一步确认。如果用户已选定目标，在该目标（

AGENTS.md

、

.codex/

、

.agents/

或

~/.codex/

）中创建、编辑、替换或删除生成的Codex工件前，无需询问。保留

.codex/config.toml

或

~/.codex/config.toml

中无关的现有Codex配置项，例如

notify

、

projects

、

marketplaces

或无关的MCP服务器；除非这些配置项验证失败或与迁移直接冲突，否则无需询问相关问题。请勿编辑源Claude Code文件（

.claude/

、

~/.claude/

、

.mcp.json

或

.claude.json

）、无关项目代码、密钥或其他仓库。

Migration Order

迁移顺序

Run the migration in this order for each selected global or project source:

Start by using Codex's built-in TODO/task list tool. Do not create
```
MIGRATION_TODOS.md
```
or any TODO file unless the user explicitly asks. The TODO list input has a
```
plan
```
array whose items each have
```
step
```
and
```
status
```
; use statuses
```
pending
```
,
```
in_progress
```
, and
```
completed
```
. Make the TODOs specific to the selected artifacts. Use literal source → Codex target labels, for example:
- Inspect
```
.claude/commands
```
  → Codex skills/prompts
- Inspect
```
.claude/agents
```
  →
```
.codex/agents
```
- Inspect
```
.mcp.json
```
  →
```
.codex/config.toml
```
  MCP servers
- Inspect
```
.claude/settings.json
```
  hooks →
```
.codex/hooks.json
```
- Migrate safe selected artifacts → Codex files
- Validate generated
```
.codex/config.toml
```
- Validate generated
```
.codex/agents
```
- Report migrated artifacts and manual-review items
Read
```
references/differences.md
```
(and refresh Codex docs if its
```
Docs last checked
```
date is old).
Scan and inspect before writing:
- ```
--scan-only
```
  lists active and inactive source surfaces.
- ```
--plan
```
  prints staged Codex artifact paths and report rows.
- ```
--doctor
```
  summarizes readiness, manual-review work, and validation risks.
Convert surfaces in the same order the CLI uses:
- instructions:
```
CLAUDE.md
```
  /
```
AGENTS.md
```
  to
```
AGENTS.md
```
- plugins: report Claude plugin trees and marketplaces as manual migration work
- hooks: rewrite supported Claude hooks into
```
.codex/hooks.json
```
  and enable
```
[features].codex_hooks = true
```
- skills and commands: write Codex skills under
```
.agents/skills/
```
- config: write
```
.codex/config.toml
```
  from Claude model/sandbox settings and MCP servers, including
```
personality = "friendly"
```
  when config is generated
- subagents: write Codex custom agents under
```
.codex/agents/
```
Dry-run, then write the selected target. Use
```
--replace
```
only when orphan generated skills or agents should be deleted.
Inspect the terminal output and
```
.codex/migrate-to-codex-report.txt
```
after real runs.
Review generated artifacts in this order:
```
AGENTS.md
```
,
```
.agents/skills/
```
,
```
.codex/config.toml
```
,
```
.codex/hooks.json
```
,
```
.codex/agents/
```
, then report-only plugin items.
Run
```
--validate-target
```
against each target after edits.
Re-run checks and
```
--dry-run
```
after edits.

Return the final migration report as one markdown table per scope that has rows. The tables cover only the non-native follow-up migration work you performed, such as skills created from slash commands, subagents, MCP servers, hooks, unsupported/local plugin notes, and manual-review caveats. Include programmatic native import rows for config, instructions, skills, or supported plugins only if you personally migrated them in this follow-up run.

If only one scope has rows, render only the table with no heading. If multiple scopes have rows, render one heading before each table. Use

**User Config**

for user-scope rows. For project-scope rows, use the actual project folder name as the heading, for example

**northstar-support-portal**

; do not use

Current Project

as the heading. Do not add prose before or after the table output.

Use exactly these columns:

northstar-support-portal

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

Status

must be

Added

Check before using

, or

Not Added

. Use

Added

when a Codex-facing artifact was created or changed and needs no special review. Use

Check before using

when a Codex-facing artifact was created or changed but the migration changed semantics, inferred behavior, preserved tool rules as guidance, or dropped unsupported behavior. Use

Not Added

when a source artifact was detected but no Codex-facing artifact was created.

Item

combines the artifact type and concrete item name in one cell. Artifact type must be singular:

Skill

Slash command

Subagent

MCP

Hook

, or

Plugin

. Wrap the artifact type in inline code; write the item name as plain text after it.

Notes

is always required; never leave it empty. Keep notes short, plain, and literal. Avoid internal implementation terms such as runtime expansion. Prefer phrases like

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

, or

Plugin marketplace needs manual setup

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

首先使用Codex内置的TODO/任务列表工具。除非用户明确要求，否则不要创建
```
MIGRATION_TODOS.md
```
或任何TODO文件。TODO列表输入包含一个
```
plan
```
数组，其中每个项都有
```
step
```
和
```
status
```
；使用状态值
```
pending
```
、
```
in_progress
```
和
```
completed
```
。使TODO项与所选工件相关联。使用字面的源→Codex目标标签，例如：
- 检查
```
.claude/commands
```
  → Codex skills/prompts
- 检查
```
.claude/agents
```
  →
```
.codex/agents
```
- 检查
```
.mcp.json
```
  →
```
.codex/config.toml
```
  MCP服务器
- 检查
```
.claude/settings.json
```
  hooks →
```
.codex/hooks.json
```
- 将安全的选定工件迁移到Codex文件
- 验证生成的
```
.codex/config.toml
```
- 验证生成的
```
.codex/agents
```
- 报告已迁移的工件和需人工审核的项
阅读
```
references/differences.md
```
（如果其
```
Docs last checked
```
日期较旧，请刷新Codex文档）。
先扫描检查再写入：
- ```
--scan-only
```
  列出活跃和非活跃的源内容。
- ```
--plan
```
  打印待处理的Codex工件路径和报告行。
- ```
--doctor
```
  总结就绪情况、人工审核工作和验证风险。
按照CLI使用的相同顺序转换内容：
- 指令：将
```
CLAUDE.md
```
  /
```
AGENTS.md
```
  转换为
```
AGENTS.md
```
- 插件：将Claude插件树和市场报告为需人工迁移的工作
- 钩子：将受支持的Claude钩子重写为
```
.codex/hooks.json
```
  并启用
```
[features].codex_hooks = true
```
- 技能和命令：将Codex技能写入
```
.agents/skills/
```
  下
- 配置：根据Claude模型/沙箱设置和MCP服务器写入
```
.codex/config.toml
```
  ，生成配置时需包含
```
personality = "friendly"
```
- 子Agent：将Codex自定义Agent写入
```
.codex/agents/
```
  下
先执行试运行，再写入选定目标。仅当需要删除孤立的生成技能或Agent时才使用
```
--replace
```
。
在实际运行后检查终端输出和
```
.codex/migrate-to-codex-report.txt
```
。
按以下顺序审核生成的工件：
```
AGENTS.md
```
、
```
.agents/skills/
```
、
```
.codex/config.toml
```
、
```
.codex/hooks.json
```
、
```
.codex/agents/
```
，然后是仅报告的插件项。
编辑后针对每个目标运行
```
--validate-target
```
。
编辑后重新运行检查和
```
--dry-run
```
。

返回最终迁移报告，每个有内容的范围对应一个Markdown表格。表格仅涵盖您执行的非原生后续迁移工作，例如从斜杠命令创建的技能、子Agent、MCP服务器、钩子、不支持/本地插件说明以及人工审核注意事项。仅当您在本次后续运行中亲自迁移了配置、指令、技能或受支持插件时，才将程序化原生导入行包含在内。

如果只有一个范围有内容，仅渲染表格，无需标题。如果多个范围有内容，在每个表格前添加一个标题。用户范围的行使用

**User Config**

作为标题。项目范围的行使用实际项目文件夹名称作为标题，例如

**northstar-support-portal**

；不要使用

Current Project

作为标题。表格输出前后不要添加散文内容。

必须使用以下列：

northstar-support-portal

状态	项	说明
`Added`	`Slash command` pr-review	已转换为Codex skill
`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

为必填项；切勿留空。保持说明简短、直白、准确。避免使用内部实现术语，例如运行时扩展。优先使用以下表述：

已转换为Codex skill

、

已添加为Codex子Agent

、

已添加到Codex配置

、

已转换为Codex钩子

、

已转换，但部分Claude钩子行为在Codex中有所不同

、

Codex没有等效的通知钩子

、

插件需要手动设置

或

插件市场需要手动设置

。

Self-Healing Loop

自我修复循环

Keep looping until the selected migration is complete:

Run
```
--plan
```
or
```
--doctor
```
.
Run the migration with
```
--dry-run
```
.
Run the migration for real.
Fix every generated
```
## MANUAL MIGRATION REQUIRED
```
block and every
```
manual_fix_required
```
or
```
skipped
```
report row that can be resolved inside Codex artifacts.
Run
```
--validate-target
```
.
Re-run the migrator and validator until the report and validator have no actionable generated-artifact fixes left.

Do not edit source Claude Code files, unrelated project code, secrets, or another repository during this loop. If a report row requires source-provider changes or product judgment, leave the generated Codex artifact with clear manual guidance instead of changing the source.

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

运行
```
--plan
```
或
```
--doctor
```
。
使用
```
--dry-run
```
运行迁移。
实际运行迁移。
修复所有生成的
```
## MANUAL MIGRATION REQUIRED
```
块以及所有可在Codex工件内解决的
```
manual_fix_required
```
或
```
skipped
```
报告行。
运行
```
--validate-target
```
。
重新运行迁移工具和验证工具，直到报告和验证工具中没有可处理的生成工件修复项为止。

在此循环过程中，请勿编辑源Claude Code文件、无关项目代码、密钥或其他仓库。如果报告行需要源提供者更改或产品判断，请在生成的Codex工件中保留清晰的人工指导，而非修改源文件。

Commands

命令

Choose the migrator command.

bash

MIGRATE_TO_CODEX='python3 .codex/skills/migrate-to-codex/scripts/migrate-to-codex.py'

Inspect the migration before writing.

bash

$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, then run without

--dry-run

, for global and project.

bash

$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/

Run the post-migration validator against each target after edits.

bash

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

Run

$MIGRATE_TO_CODEX --help

for flags (

--scan-only

--plan

--doctor

--validate-target

, defaults, and so on). Deep tables and more links are in

references/differences.md

选择迁移工具命令。

bash

MIGRATE_TO_CODEX='python3 .codex/skills/migrate-to-codex/scripts/migrate-to-codex.py'

在写入前检查迁移情况。

bash

$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

运行，针对全局和项目。

bash

$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/

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

bash

$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

中。