Claude Code 설정을 Codex로 옮기는 마이그레이션 구조

설정 자산은 파일 복사만으로 옮겨지지 않는다

OpenAI의 migrate-to-codex는 로컬 머신에 쌓인 Claude Code 설정을 찾아 Codex 형식으로 이전한다. 탐색 대상은 instructions, skills, hooks, MCP 서버, subagents, instruction 파일과 최근 30일 세션 기록이다. OpenAI의 큐레이션 스킬인 openai/skills 저장소의 .curated/migrate-to-codex로 배포되며 Codex CLI와 데스크톱 앱에서 호출할 수 있다.

이 도구가 겨냥하는 문제는 설정 파일 몇 개를 옮기는 일이 아니다. 코딩 에이전트를 수개월간 사용하면 사용자별 명령과 스킬, 도구 연결, 자동화 hook, 작업별 에이전트가 하나의 워크플로로 축적된다. 새로운 도구에서 이를 처음부터 다시 구성해야 하는 부담이 전환의 가장 큰 장벽이 된다.

Claude Code와 Codex는 설정 모델이 다르다. 따라서 마이그레이션의 본체는 파일 이동이 아니라 구조가 달라도 동작 의도를 유지하는 의미 보존 변환이다. 기계적으로 대응할 수 있는 항목은 바로 이전하고, 대응 관계가 없는 항목은 후속 스레드에서 AI가 잔여 작업을 안내한다.

원본 Claude Code 파일인 .claude/, ~/.claude/, .mcp.json, .claude.json은 읽기 전용 소스로 취급한다. 변환 과정에서 원본을 변경하지 않으므로 실패하더라도 기존 설정으로 돌아갈 수 있다.

변환은 설정 의존성을 따라 진행된다

마이그레이션 파이프라인은 다음 순서로 아티팩트를 만든다.

CLAUDE.md와 기존 AGENTS.md를 통합 AGENTS.md로 변환한다.
Claude hooks를 .codex/hooks.json으로 옮기고 [features].codex_hooks = true를 활성화한다.
슬래시 커맨드와 스킬을 .agents/skills/ 마크다운으로 변환한다.
모델·샌드박스 설정과 MCP 서버 정의를 .codex/config.toml에 배치한다.
커스텀 에이전트를 .codex/agents/로 이전한다.

⤢✕

Claude Code가 JSON 중심의 여러 파일에 책임을 나눠 둔다면 Codex는 config.toml을 중심으로 설정을 모은다. 변환기는 이 구조 차이를 흡수하면서 사용자 스코프와 프로젝트 스코프의 우선순위를 보존해야 한다.

프로젝트의 .mcp.json과 사용자 영역의 ~/.claude.json에 있던 MCP 설정은 ~/.codex/config.toml의 [mcp_servers.<name>] 테이블로 이동한다. 다층 CLAUDE.md는 표준 AGENTS.md라는 진입점으로 수렴한다. 이 문법은 Cursor와 Copilot 등에서도 공유된다.

이름, 이벤트, 경로의 대응 관계는 매핑 테이블에 정의한다. 같은 입력이 같은 결과를 만들도록 변환을 결정론적으로 유지하기 위해서다. 대응할 수 없는 항목은 조용히 버리지 않고 가이드 블록으로 드러낸다.

자산 유형마다 다른 어댑터가 필요하다

슬래시 커맨드와 커스텀 스킬은 .agents/skills/ 규약에 맞게 다시 배치하되 마크다운 본문과 메타데이터를 보존한다. 커스텀 에이전트 정의는 .codex/agents/ 디렉터리 구조로 옮긴다.

hooks는 지원되는 이벤트를 .codex/hooks.json 스키마로 바꾸고 codex_hooks 기능 플래그를 켠다. 다만 Claude 고유 이벤트인 Notification hook처럼 Codex에 등가 이벤트가 없는 항목은 묵시적으로 누락되거나 다른 이벤트로 재매핑될 수 있다. 변환 결과에서 이 비대칭을 추적해야 한다.

플러그인은 자동 변환 대상이 아니다. 수동 설정 항목으로 따로 처리해야 한다. 의미를 100% 보존할 수 없는 설정은 가장 가까운 등가 구조로 근사한 뒤 사용자 확인을 요청한다.

자산별 전용 어댑터를 두면 한 유형의 실패를 다른 변환과 분리할 수 있다. hooks 변환 문제가 skills나 subagents 이식까지 오염시키지 않도록 경계를 두는 방식이다.

MCP 설정에서는 시크릿을 따로 다룬다

MCP 서버의 명령, 인자, 전송 방식은 config.toml의 [mcp_servers.<name>] 테이블로 이전된다. JSON 객체를 TOML 테이블로 바꾸는 과정에서 중첩 구조와 배열 표현의 차이는 어댑터가 정규화한다.

API 키와 환경 변수는 보안상 이전하지 않는다. 해당 값은 의도적으로 비워 두고 사용자가 다시 입력해야 한다. 생성된 MCP 설정은 validate-target 단계에서 구조 정합성을 확인한 뒤 확정한다.

MCP는 세 도구가 공유하는 공통 분모지만 설정 파일의 형식과 위치는 서로 다르다. 프로토콜이 같다는 이유만으로 자격 증명이나 실행 환경까지 자동으로 이어진다고 보면 안 된다.

최근 작업 맥락을 이어받는 방식

세션 기록은 최근 30일을 범위로 스캔한다. 자동 변환할 수 있는 기록은 바로 이전하고, 형식이 맞지 않는 기록은 후속 스레드에서 안내할 대상으로 분리한다.

범위를 최근 30일로 제한하면 변환 부하와 노이즈를 줄이면서 현재 진행 중인 작업 맥락에 집중할 수 있다. 도구를 바꾼 직후 발생하는 콜드 스타트 비용을 낮추려는 선택이다.

설정 파일과 세션 기록은 변환 성격이 다르다. 설정은 대응 규칙을 이용한 결정론적 변환이 가능하지만, 세션에는 대화와 도구 호출 같은 비정형 이력이 포함된다. 그만큼 손실 가능성이 있으며 핵심 설정 자산보다 변환 보장 수준도 낮다. 이전 후에는 별도 검증이 필요하다.

실제 전환은 점검과 검증을 반복한다

⤢✕

먼저 --plan이나 --doctor로 변환 대상과 위험 항목을 식별한다. 이어서 --dry-run을 실행하면 원본을 변경하지 않고 생성 예정 아티팩트를 확인할 수 있다.

실제 변환이 끝나면 수동 가이드 블록의 조치를 반영하고 --validate-target으로 다시 검사한다. 이 과정을 반복해 조치 가능한 생성 아티팩트에 더 이상 수정할 내용이 없는 상태에 도달하면 변환을 끝낸다.

검증은 instructions, hooks, skills, config, agents의 각 목적지를 개별적으로 확인해야 한다. hook 이벤트 누락과 MCP 시크릿 공란처럼 알려진 비대칭도 상시 검사 항목에 포함한다. 이 검증 단계는 파이프라인으로 구성해 설정이 바뀔 때 자동으로 재검사하는 CI 워크플로와 연결할 수 있다.

Claude Code와 Codex를 함께 운영할 때 생기는 경계

Claude Code는 CLAUDE.md, Codex는 AGENTS.md를 읽으며 서로의 파일로 폴백하지 않는다. 병행 운영 중에는 두 파일이 함께 존재할 수밖에 없다.

중복을 줄이려면 MCP와 skills처럼 공유할 수 있는 자산을 AGENTS.md, .agents/skills/ 같은 공통 규약에 둔다. 반면 도구 고유 기능은 별도 설정으로 남긴다. 한 도구에는 대규모 리팩터를, 다른 도구에는 대화형 설계를 맡기는 식으로 강점에 따라 작업을 나눌 수도 있다.

양쪽 설정을 독립적으로 변경하면 드리프트가 생긴다. 공통 자산을 단일 진실 원천으로 관리하고 두 도구의 설정 차이를 주기적으로 동기화·검증해야 한다.

도구를 바꿔도 남아야 할 자산

벤더 락인을 줄이려면 에이전트 설정을 도구 내부 상태가 아니라 버전 관리 가능한 텍스트 파일로 유지해야 한다. 그래야 변경 이력을 추적하고 같은 환경을 재현하거나 다른 도구로 이식할 수 있다.

AGENTS.md는 Codex, Copilot, Cursor, Antigravity가 공유하는 이식 가능 포맷이다. 외부 도구 연결은 벤더별 API에 직접 묶기보다 MCP에 맡긴다. 현재의 Claude Code에서 Codex로 가는 단방향 이전뿐 아니라 반대 방향의 전환 가능성도 자산 구조에 반영할 수 있다.

다만 모든 기능을 공통 규약으로만 제한하면 도구별 강점이 희석된다. 공유 가능한 자산과 특정 도구에만 필요한 자산을 의도적으로 분리하는 편이 이식성과 기능성을 함께 확보하기 쉽다.

Codex·Claude Code·Antigravity CLI의 설정 차이

항목	Codex	Claude Code	Antigravity CLI
주 설정 파일	`AGENTS.md`	`CLAUDE.md`	`AGENTS.md`(+`GEMINI.md`)
MCP 설정 위치	`~/.codex/config.toml` `[mcp_servers]`	`.mcp.json`/`~/.claude.json`	독립 `mcp_config.json` 프로필
skills 경로	`.agents/skills/`	`.claude/`(커맨드·스킬)	`.agents/skills/`
hooks	`.codex/hooks.json`(기능 플래그)	네이티브 이벤트 hooks	하니스 공통 설정
이식 표준성	높음(공유 규약)	중간(Anthropic 특화)	높음(suite 공통 하니스)
런타임 기반	-	Node 계열	Go 기반

Codex와 Antigravity는 AGENTS.md를 중심으로 이식성을 우선한다. Claude Code는 다층 설정, 정책 강제, 네이티브 hooks처럼 기능의 깊이에 무게를 둔다. Claude Code는 CLAUDE.md만 읽고 Codex는 AGENTS.md만 읽으므로 한쪽 파일이 다른 쪽을 대신하지 않는다.

Antigravity는 CLI, IDE, 2.0이 공통 하니스를 사용해 MCP와 skills의 단일 진실 원천을 유지한다. 공유 규약을 따르는 Codex와 Antigravity는 도구 간 이동에 유리하고, Claude Code는 설정 자산의 깊이에서 강점이 있다.

세 도구 모두 MCP를 채택하므로 외부 연동 자산은 사실상 이식할 수 있다. 차이는 주로 설정 파일의 포맷과 저장 위치에 있다. 단일 벤더 의존을 줄이는 일이 우선이라면 AGENTS.md 표준을 따르는 도구가 맞고, 정책 강제와 세밀한 hook 제어가 필요하다면 Claude Code를 우선 고려할 수 있다.

조직 표준으로 관리할 지점

에이전트 설정은 형상 항목으로 식별하고 버전 관리해야 변경 추적성을 확보할 수 있다. 조직 차원에서는 AGENTS.md와 MCP를 사실상 상호운용 표준으로 삼아 도구 비종속 정책을 세울 수 있다.

마이그레이션 과정의 위험도 운영 표준에 포함해야 한다. 시크릿 비이전, hook 누락, plugins 미지원 항목을 사전에 확인하고 타깃 검증을 자동화한다. 여러 에이전트 도구를 병행한다면 설정 드리프트를 정기 검증 절차로 관리한다.

2026년에는 AGENTS.md와 MCP를 축으로 설정 상호운용성이 강화되는 흐름이 나타난다. 자동 이전은 도구 전환 비용을 낮추고, 자가 치유와 타깃 검증 루프는 설정 변경 관리의 패턴으로 자리 잡는 방향이다.

설정, 스킬, 서브에이전트도 조직이 재사용할 수 있는 지식 자산으로 인식되는 추세다. 운영의 중심이 특정 도구에서 설정 자산으로 이동하면 단방향 마이그레이션을 넘어 도구 간 양방향 동기화와 변환도 다루게 된다. 이 흐름은 벤더 종속 비용을 구조적으로 낮추는 방향으로 이어진다.