前言¶
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
