2026년 Claude Code에서 Codex로 마이그레이션하는 방법: 단계별 가이드

Ailoot 문서: API, 키, 설정.

Codex 마이그레이션 도구는 왜 필요한가요?#

OpenAI는 2026년 6월 초 Codex에 이 기능을 추가했습니다. 공식 변경 기록은 이를 간략하게 설명합니다.

즉, Codex 앱을 처음 실행하거나 이미 실행 중인 클라이언트의 설정에서 마법사를 시작하면, 다른 에이전트의 로컬 설정을 읽습니다. 현재 Claude Code와 Claude Cowork를 지원합니다.

OpenAI가 이 기능을 만든 이유는 분명합니다. Sites 출시와 2026년 5~6월 Codex 앱 업데이트 이후, Codex는 Claude Code가 이전에 OpenAI보다 앞서 있던 모든 것을 갖췄습니다. 터미널, 플러그인, 장시간 세션, 오케스트레이션입니다. 마이그레이션은 Claude Code를 이미 기술 스택에 통합한 팀의 마지막 장벽을 없앱니다. "지원되는 설정을 가져온 뒤 원래 목록과 대조해 확인할 수 있습니다."

이 기능이 필요한 이유는 그다지 분명하지 않습니다. Codex와 Claude Code 비교 가이드에서 두 도구를 정면으로 비교했습니다. 긴 아키텍처 논의와 Plan Mode에서는 여전히 Claude가 앞서고, 자율 작업과 병렬 PR에서는 Codex가 더 빠릅니다. 완전히 전환하기로 했다면 계속 읽어 보세요. 두 도구를 함께 사용하는 방법을 고민 중이라면 협업 패턴이 더 유용할 수 있습니다.

마이그레이션 도구는 무엇을 자동으로 이전하나요?#

각 항목을 살펴보고 ~/.claude의 각 부분이 정확히 어떻게 처리되는지 설명하겠습니다.

1. 지침과 컨텍스트. 전역 파일인 ~/.claude/의 CLAUDE.md와 저장소의 프로젝트 파일이 AGENTS.md 형식으로 변환됩니다. 전역 파일은 ~/.codex/AGENTS.md에 저장되고, 프로젝트 파일은 저장소 루트와 하위 폴더에 그대로 남습니다. AGENTS.md 형식은 규칙을 담은 같은 종류의 Markdown 파일이라고 보면 됩니다. 차이는 대부분 외형적인 것으로, 섹션 이름과 몇 가지 특정 지시문 정도입니다. AGENTS.md가 무엇인지와 Codex에 왜 필요한지 설명했습니다.

2. 스킬. ~/.claude/skills/ 폴더 전체를 검사합니다. 각 스킬을 Codex 구조에 맞게 조정해 $HOME/.agents/skills에 배치합니다. 저장소의 .claude/skills/에 있는 프로젝트 스킬은 .agents/skills로 이동합니다. 프런트매터가 있는 SKILL.md 형식은 거의 그대로 이전됩니다. 스킬이 Claude 전용 트리거를 사용하는 경우 검토 대상으로 표시됩니다.

3. MCP 서버. .mcp.json 설정(전역 및 프로젝트 수준 모두)을 Codex 형식으로 가져옵니다. 서버 이름, 실행 명령, 경로는 보존됩니다. 이전되지 않는 항목은 토큰과 환경 변수입니다. 보안상 Codex는 마이그레이션 도중 API 키와 비밀번호가 노출되지 않도록 다시 입력하라고 요청합니다. 한 번만 하면 되는 작업입니다. Codex 앱에서 MCP 섹션을 열고 비밀번호 관리자에 저장된 토큰을 입력하면 됩니다.

4. 훅. 이 항목은 복잡합니다. 결정론적 로직을 사용하는 훅(rm -rf 차단, 자격 증명처럼 보이는 경로 알림, 증거 기록)은 모두 이전됩니다. Codex에 동등한 기능이 없는 트리거를 사용하는 훅(예를 들어 Claude Code의 특정 수명 주기 이벤트)은 "수동 검토" 대상으로 표시되고 자동으로 활성화되지 않습니다. 참고로 Claude Code에서 훅이 작동하는 방식을 자세히 설명했습니다. Codex에는 훅 유형이 더 적습니다.

5. 세션 기록. Claude Code 활동 중 최근 최대 30일이 참고 자료로 가져와집니다. 그렇다고 "중단한 지점에서 정확히 이어서 작업한다"는 뜻은 아닙니다. 하지만 이전 대화를 Codex에서 볼 수 있으므로 모든 것을 다시 설명하지 않고도 프로젝트 컨텍스트를 빠르게 떠올릴 수 있습니다.

마이그레이션 도구는 실제로 쓰는 파일과 실험용 산출물을 구분하지 않고 전부 이전합니다. 마이그레이션 후에는 지난 6개월간 사용하지 않은 항목을 직접 정리하는 것이 좋습니다.

이전되지 않는 항목과 그 이유는 무엇인가요?#

각 항목을 "마이그레이션 후 무엇을 해야 하는가"라는 관점에서 살펴보겠습니다.

MCP 토큰과 API 키. 가장 예상하기 쉬운 항목입니다. 스캔 후 Codex는 Claude에서 발견한 MCP 서버 목록을 표시하고 각각의 키와 토큰을 요청합니다. 비밀번호 관리자를 곁에 두고 한 번에 모든 서버를 확인하는 것이 가장 편합니다. 그다음에는 Codex와 Claude Code에서 MCP가 똑같이 작동합니다. 선택한 MCP 서버의 명령 및 연결 매개변수는 해당 문서와 대조해 확인하세요.

슬래시 명령 /name. Claude Code에서는 /skill-name으로 스킬을 호출하는 데 익숙할 것입니다. Codex에서는 표준 호출 방식이 다릅니다. $skill-name입니다. /name 명령을 스킬이 로드되었다는 증거로 여기는 것은 흔한 마이그레이션 실수입니다.

마이그레이션 후에는 Codex에서 $skill-name을 사용해 중요한 스킬 몇 개를 시험해 보세요. 작동하면 마이그레이션이 제대로 된 것입니다. 마법사의 "스킬 마이그레이션 완료" 확인란을 그대로 믿지 말고 직접 호출해 확인하세요.

Codex에 동등한 기능이 없는 훅. 특정 Claude Code 이벤트에 대한 훅이 있었다면, 예를 들어 특정 도구 조합을 위한 pre-tool-use 훅이라면 Codex에는 해당 트리거가 없을 수 있습니다. 마이그레이션 도구는 이를 표시하고 비활성 상태로 둡니다. Codex에 맞는 방식으로 다시 작성할지, 삭제할지, 아니면 Claude Code를 병행 실행하면서 그대로 둘지 결정해야 합니다. 좋은 원칙은 결정론적 훅만 이전하라는 것입니다. 그 외의 항목은 새 도구에 복잡한 계층 구조를 그대로 복제하지 말아야 할 이유입니다.

서브에이전트 기반 팀 워크플로. Claude Code의 서브에이전트가 무엇인지와 중첩 서브에이전트를 사용하는 방법을 설명했습니다. Codex에서는 프로필과 역할을 통해 서브에이전트를 구성합니다(아래 참조). Claude에서 여러 서브에이전트를 연결한 복잡한 파이프라인을 사용했다면 Codex의 프로필 개념에 맞춰 다시 작성해야 합니다. 마이그레이션 도구는 이런 설정을 "아키텍처 재작업 필요"로 표시합니다.

대규모 Claude 전용 CLAUDE.md 파일. 프로젝트별 섹션이 들어 있는 파일이 2,000–3,000줄로 늘어났더라도 Codex가 받아들일 수는 있지만 좋은 방식은 아닙니다. AGENTS.md는 간결하고 분산된 구성을 위해 설계되었습니다. 전역 규칙은 ~/.codex/AGENTS.md에, 프로젝트별 규칙은 저장소 루트에, 좁은 범위의 재정의는 하위 폴더에 둡니다. 마이그레이션 후 CLAUDE.md를 "거대한 지침 파일"로 남겨 두지 말고 여러 수준으로 나누세요. CLAUDE.md를 올바르게 설정하는 방법을 설명했으며, 같은 접근 방식을 AGENTS.md에도 적용할 수 있습니다.

단계별 안내: Codex 앱에서 4단계 실행#

구체적인 체크리스트는 다음과 같습니다.

1. 1단계: Codex 앱을 26.608 이상으로 업데이트

   마이그레이션 도구는 26.608 버전에서 처음 등장했습니다(2026년 6월 9일 출시). macOS에서는 Codex 앱을 열어 업데이트를 확인하세요. Windows에서도 같은 작업을 하세요. Codex CLI를 실행한다면 현재 앱과 호환되는지 확인하세요. 최신 버전이 아니면 설정에 "다른 에이전트 설정 가져오기"가 표시되지 않습니다.

2. 2단계: 설정에서 가져오기 시작

   Codex 앱에서 설정을 열고 "다른 에이전트 설정 가져오기"를 찾으세요. Codex 앱을 방금 설치했다면 온보딩 중에 마법사가 마이그레이션을 제안합니다. 시작하면 마법사가 파일 시스템을 검사합니다. ~/.claude/와 CLAUDE.md 또는 .claude/가 포함된 저장소를 살펴봅니다. 파일 수에 따라 검사에는 30초에서 몇 분이 걸립니다.

3. 3단계: 마이그레이션 계획 확인

   스캔이 끝나면 Codex가 인벤토리를 표시합니다. 발견한 스킬 수, MCP 서버 수, CLAUDE.md 파일 수, 마이그레이션 대상에 포함되는 훅, 사용 가능한 세션 기록 일수 등을 확인할 수 있습니다. 이전하고 싶지 않은 항목은 선택을 해제할 수 있습니다. 기본적으로 Codex가 안전하게 가져올 수 있다고 판단한 항목은 모두 선택되어 있습니다.

4. 4단계: 완료를 기다리고 토큰 입력

   가져오기는 1–5분이 걸립니다. 완료되면 Codex가 후속 창을 엽니다. "자동으로 이전하지 못한 항목입니다. 직접 확인하세요." 보통 토큰이 필요한 MCP 서버 목록이 표시됩니다. 비밀번호 관리자를 열고 Codex 양식에 키를 입력하세요. 그러면 마이그레이션의 주요 부분이 완료됩니다.

그다음 결과를 확인합니다. Claude Code에서 자주 작업하던 프로젝트를 열고 다음을 확인하세요.

• cat ~/.codex/AGENTS.md — 전역 규칙이 들어 있나요?
• 아무 스킬이나 실행합니다: $skill-name. 스킬이 로드되어야 합니다.
• 프로젝트의 .mcp.json을 열고 필요한 서버가 실행 중인지 확인합니다.
• 평소 작업 방식을 반영하는 대화를 시작합니다. Codex는 가져온 훅 중 사용할 수 없는 항목을 보여 줍니다. 이는 직접 처리할 구체적인 목록 항목이며 고정된 잔여 비율은 없습니다.

훅과 서브에이전트: Codex의 대응 기능과 다시 작성할 항목#

훅. Claude Code에서는 각 수명 주기 이벤트(pre-tool-use, post-tool-use, on-error, on-context-load 등)에 셸 명령을 연결할 수 있습니다. Codex의 이벤트 종류는 더 적습니다. 실행 전 검사, 증거 기록, 위험한 명령 차단을 할 수 있습니다. 특정 조합을 필터링하는 pre-tool-use 훅이 있었다면 Codex에서는 이를 일반적인 실행 전 검사로 감싸거나 제거해야 합니다. Claude Code 훅의 아키텍처를 자세히 설명했습니다. 훅을 광범위하게 사용했다면 트리거와 필요한 효과를 각각 나열하고 지원되는 대안을 찾아 활성화 전에 검증하세요.

서브에이전트. Claude Code에서 서브에이전트는 자체 시스템 프롬프트를 가진 별도 컨텍스트로, /command를 통해 또는 기본 대화에서 실행됩니다. Codex에는 프로필이라는 비슷한 개념이 있습니다. 특정 스킬, 권한, 승인 정책으로 프로필을 정의할 수 있습니다. 프로필은 특정 유형의 작업을 위해 컨텍스트를 분리한다는 점에서 대략 같은 문제를 해결하지만, 명시적으로 에이전트를 호출하는 대신 설정을 통해 처리합니다.

실제로는 다음과 같습니다.

• 자체 프롬프트가 있는 "security-reviewer" 서브에이전트를 사용했다면, 필요한 권한과 더 높은 추론 수준을 지정한 security-review 프로필을 Codex에 만드세요.
• "feature-developer" 서브에이전트를 사용했다면 이는 기본 작업 프로필에 해당하므로 특별히 할 일이 없습니다.
• 중첩 서브에이전트를 사용했다면 Codex에서 그대로 작동하지 않습니다. 프로필 체인이나 명시적인 스킬을 사용하도록 다시 구상하세요.

마이그레이션 도구는 서브에이전트 이름을 사용해 프로필을 만들고 이전되지 않은 트리거를 표시하려고 합니다. 필요한 작업량은 역할, 트리거, 권한, 의존성 수에 달려 있습니다. 이전 완료로 간주하기 전에 필요한 파이프라인을 각각 시험하세요.

완전히 마이그레이션할 때와 두 도구를 함께 사용할 때#

간단한 의사결정 기준은 다음과 같습니다.

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를 함께 사용하는 가이드에서 작동 방식을 더 설명했습니다.

마이그레이션에 대해 가장 하고 싶은 말은 이것입니다. 마이그레이션 도구는 전환의 기술적 장벽을 없애지만, 애초에 전환이 필요한지에 대해서는 답해 주지 않습니다. 먼저 어떤 종류의 일을 하는지 결정하세요. 그런 다음 도구를 선택하세요.

Ailoot를 통해 신경망에 접근해야 한다면 Ailoot를 확인해 보세요.