2026 年如何從 Claude Code 遷移至 Codex：逐步指南

Ailoot 文件：API、金鑰與設定。

Codex Migration 工具究竟為何需要？#

OpenAI 在 2026 年 6 月上旬將此功能加入 Codex。官方變更紀錄簡短地寫道：

換句話說，第一次啟動 Codex App 時，或從已在執行的用戶端設定中，都可以啟動一個精靈，讀取其他代理的本機設定。目前支援 Claude Code 和 Claude Cowork。

OpenAI 為何這麼做很清楚。Sites 推出以及 Codex App 在 2026 年 5 月至 6 月更新後，Codex 已具備 Claude Code 先前勝過 OpenAI 的所有功能：終端機、外掛程式、長時間工作階段和協作編排。Migration 消除了已將 Claude Code 整合進技術堆疊的團隊所面臨的最後一道門檻：「支援設定可先匯入，再與原清單逐項確認。」

至於你是否需要它，就沒那麼容易判斷了。我在 Codex 與 Claude Code 指南中直接比較過兩者：在長時間的架構討論和 Plan Mode 上，Claude 仍然領先；在自主任務和並行 PR 上，Codex 則較快。如果你已決定完全切換，請繼續閱讀。如果你正在考慮兩者搭配使用，協作模式可能更適合你。

Migration 工具會自動遷移哪些內容？#

我會逐一介紹這些類別，並說明 ~/.claude 的各部分會如何處理。

1. 指示與脈絡。 CLAUDE.md 檔案——包括 ~/.claude/ 中的全域檔案和儲存庫中的專案檔案——都會轉換為 AGENTS.md 格式。全域檔案會放在 ~/.codex/AGENTS.md；專案檔案則保留在儲存庫根目錄和子資料夾中。AGENTS.md 格式本質上是同類型的 Markdown 規則檔案；差異大多只是外觀上的，例如章節名稱和少數特定指示。我曾說明 AGENTS.md 是什麼，以及 Codex 為何需要它。

2. 技能。 ~/.claude/skills/ 資料夾會完整掃描；每項技能都會調整為 Codex 結構，並放入 $HOME/.agents/skills。儲存庫中 .claude/skills/ 的專案技能會移至 .agents/skills。含有 frontmatter 的 SKILL.md 格式幾乎會原樣遷移。若技能使用 Claude 專屬觸發條件，就會標記為需要檢查。

3. MCP 伺服器。 .mcp.json 設定（包括全域和專案層級）會匯入 Codex 格式。伺服器名稱、啟動指令和路徑都會保留。無法遷移的是權杖和環境變數。基於安全考量，Codex 會要求你重新輸入 API 金鑰和密碼，避免它們在遷移期間曝光。這是一次性作業：開啟 Codex App 的 MCP 區段，輸入你已儲存在密碼管理器中的權杖即可。

4. Hooks。 這一類比較複雜。具決定性邏輯的 hooks，例如封鎖 rm -rf、對看似憑證的路徑發出警示、記錄證據，都會完整遷移。觸發條件在 Codex 中沒有對應項目的 hooks（例如 Claude Code 特有的生命週期事件），會標記為「manual review」，且不會自動啟用。我曾詳細說明 Claude Code 中 hooks 的運作方式，可供參考；Codex 的 hooks 類型較少。

5. 工作階段記錄。 最多會匯入 Claude Code 最近 30 天的活動，供參考。這不代表「可以完全從上次中斷的地方繼續」，但你能在 Codex 中看到過去的對話，因此可以快速回想專案脈絡，不必重新解釋所有內容。

Migration 工具不會區分實際使用的檔案和實驗產物，而是全部遷移。遷移後，最好手動清理過去六個月未使用的內容。

哪些內容不會遷移？原因是什麼？#

我會從「遷移之後該怎麼做」的角度逐一說明。

MCP 權杖和 API 金鑰。 這是最容易預期的部分。掃描後，Codex 會列出在 Claude 中找到的所有 MCP 伺服器，並逐一要求提供金鑰和權杖。最好先準備好密碼管理器，一次處理所有伺服器。完成後，MCP 在 Codex 和 Claude Code 中的運作方式相同。請依照你所選 MCP 伺服器的文件，檢查指令和連線參數。

/name 斜線指令。 在 Claude Code 中，你習慣用 /skill-name 呼叫技能。在 Codex 中，標準呼叫方式不同：$skill-name。把 /name 指令當成技能已載入的證據，是常見的遷移錯誤。

遷移後，在 Codex 中用 $skill-name 測試幾項重要技能。如果能正常運作，就表示遷移確實成功。不要只相信精靈中的「skills migrated」核取方塊，請實際呼叫技能來確認。

沒有 Codex 對應項目的 hooks。 如果你為特定 Claude Code 事件設定了 hook，例如針對特定工具組合的 pre-tool-use，該觸發條件在 Codex 中可能不存在。Migration 工具會標記這些 hooks，並讓它們維持未啟用狀態。你必須決定要改寫成 Codex 可用的形式、刪除，或繼續留在 Claude Code 中（如果你會並行使用）。一個很好的原則是：只遷移具決定性的 hooks；其他情況都不值得在新工具中重新複製整套機制。

以子代理為基礎的團隊工作流程。 我曾說明 Claude Code 的子代理是什麼，以及如何使用巢狀子代理。在 Codex 中，子代理透過設定檔和角色組織（見下文）。如果你在 Claude 中有由多個子代理串連而成的複雜流程，就必須圍繞 Codex 的設定檔概念重新編寫。Migration 工具會將這類設定標記為「requires architectural rework」。

大型的 Claude 專屬 CLAUDE.md 檔案。 如果檔案已成長到 2,000–3,000 行，並且包含各專案的章節，Codex 可能會接受，但這不是好做法。AGENTS.md 的設計原則是保持精簡並分層配置：全域規則放在 ~/.codex/AGENTS.md，專案專屬規則放在儲存庫根目錄，範圍較窄的覆寫規則放在子資料夾。遷移後，不要讓 CLAUDE.md 繼續當作「巨型指示檔」；請將內容拆分到不同層級。我曾說明如何正確設定 CLAUDE.md；同樣做法也適用於 AGENTS.md。

逐步操作：在 Codex App 中完成 4 個動作#

以下是具體的檢查清單。

1. 步驟 1：將 Codex App 更新至 26.608 或更新版本

   Migration 工具出現在 26.608 版（2026 年 6 月 9 日發布）。在 macOS 上開啟 Codex App 並檢查更新。Windows 上也一樣。如果你使用 Codex CLI，請確認它與目前的 App 相容。沒有最新版本時，Settings 中不會出現「Import other agent setup」。

2. 步驟 2：從 Settings 開始匯入

   在 Codex App 中開啟 Settings，找到「Import other agent setup」。如果你剛安裝 Codex App，精靈會在初始設定期間提供遷移選項。開始後，精靈會掃描檔案系統：~/.claude/，以及含有 CLAUDE.md 或 .claude/ 的儲存庫。掃描時間從 30 秒到數分鐘不等，視檔案數量而定。

3. 步驟 3：確認遷移計畫

   掃描完成後，Codex 會顯示清單：找到多少技能、多少 MCP 伺服器、多少個 CLAUDE.md 檔案、哪些 hooks 符合遷移資格，以及可用多少天的工作階段記錄。你可以取消勾選不想遷移的類別。預設會選取 Codex 認為可安全匯入的所有內容。

4. 步驟 4：等待完成並輸入權杖

   匯入需要 1–5 分鐘。完成後，Codex 會開啟後續視窗：「以下是無法自動遷移的項目，請手動檢查。」通常這是一份需要權杖的 MCP 伺服器清單。開啟密碼管理器，並在 Codex 表單中輸入金鑰。完成後，遷移的主要部分就完成了。

接著驗證結果。開啟你平常在 Claude Code 中使用的專案，檢查以下項目：

• cat ~/.codex/AGENTS.md — 全域規則是否在其中？
• 執行任一技能：$skill-name。它應該會載入。
• 開啟專案中的 .mcp.json，確認必要的伺服器正在執行。
• 開始一段符合你平常工作方式的對話。Codex 會顯示無法使用的已匯入 hooks；這些是需要手動處理的具體項目，沒有固定剩餘比例。

Hooks 和子代理：Codex 中的對應功能，以及需要改寫的部分#

Hooks。 在 Claude Code 中，你可以為每個生命週期事件（pre-tool-use、post-tool-use、on-error、on-context-load 等）附加 shell 指令。Codex 支援的事件較少：可以在執行前檢查、記錄證據，以及封鎖危險指令。如果你有用來篩選特定組合的 pre-tool-use hook，在 Codex 中就得改用一般的執行前檢查，或直接移除。我曾詳細說明 Claude Code hooks 的架構；若大量使用，請逐項列觸發與必要效果，找支援的替代方式，驗證後才啟用。

子代理。 在 Claude Code 中，子代理是擁有自己系統提示的獨立脈絡，可透過 /command 或從主要對話啟動。Codex 的設定檔有類似概念：你可以定義具備特定技能、權限和核准政策的設定檔。設定檔大致解決相同問題——隔離特定任務類別的脈絡——但它是透過設定而非明確呼叫代理來實現。

實際上，這代表：

• 如果你有帶有獨立提示的「security-reviewer」子代理，就在 Codex 中建立 security-review 設定檔，並設定所需權限和較高的推理力度。
• 如果你有「feature-developer」子代理，那只是一般的工作設定檔；不需要特別設定。
• 如果你使用巢狀子代理，在 Codex 中無法一對一運作；請改以設定檔串連或明確的技能重新設計。

Migration 工具會嘗試使用子代理名稱建立設定檔，並標記哪些觸發條件未能遷移。工作量取決於角色、觸發、權限與相依數量，每條必要流程都需測試後才算遷移。

何時應完全遷移，何時應繼續使用兩種工具#

簡單的判斷方式：

完全切換到 Codex適合以下情況：

• 你主要處理自主 PR 和並行任務。
• 你的 GitHub 工作流程整合度很高，而且 Codex Cloud Agent 負責 80% 的工作。
• 你不會花太多時間進行架構討論或使用 Plan Mode。
• 你只想付費使用一種工具，而不是兩種。

繼續搭配使用 Claude Code 和 Codex適合以下情況：

• 你經常使用 Plan Mode 進行長時間的架構決策。
• 你需要並行工作：Codex 在雲端處理一項任務，同時 Claude Code 保留另一項任務的脈絡。
• 你經常進行一次性的小技巧和微型專案，使用 Plan Mode 會顯得過於繁複。
• 你有複雜的子代理流程，無法在一個晚上改寫完成。

我自己兩種工具都用：Claude Code 負責保留長時間的對話脈絡，Codex 則用來「並行修復 N 個錯誤」或「審查 PR」。我在Claude Code 和 Codex 協作指南中更深入地說明了這種用法。

關於遷移，我最想說的是：Migration 工具消除了切換的技術障礙，卻不能回答你是否真的需要切換。先判斷自己從事哪類工作，再選擇工具。

如果你需要透過 Ailoot 存取神經網路，請參考 Ailoot。