Claude Code에서 Codex로 이전하기

이 문서는 Claude Code에서 사용하던 설정과 작업 습관을 Codex로 옮길 때 확인할 내용을 정리한 것입니다. Codex 앱에는 다른 에이전트의 설정을 찾아 가져오는 import 기능이 있으며, 이 흐름은 특히 Claude Code의 CLAUDE.md, 설정 파일, MCP 서버, hooks, skills, slash commands, subagents 같은 항목을 Codex 형식으로 옮기는 상황을 염두에 둔 기능입니다.

두 도구는 모두 코딩 에이전트이지만 설정 파일 이름, 권한 모델, 도구 실행 방식, 재사용 가능한 작업 단위의 표현 방식이 다릅니다. 따라서 단순히 파일을 복사하는 것보다 Codex의 형식에 맞게 가져오고, 가져온 내용을 한 번 검토하는 과정이 필요합니다.

이전 전에 확인할 것

먼저 현재 Claude Code에서 어떤 설정을 사용하고 있는지 확인하는 것이 좋습니다. 대표적으로 다음 항목이 이전 대상이 될 수 있습니다.

프로젝트 또는 사용자 단위의 지시 파일입니다. Claude Code에서는 보통 CLAUDE.md가 여기에 해당합니다.
Claude Code의 settings.json에 들어 있는 모델, 권한, 도구, hooks 관련 설정입니다.
MCP 서버 설정입니다.
재사용 가능한 skills, slash commands, subagents입니다.
최근 작업 세션과 프로젝트 기록입니다.
플러그인 또는 marketplace 설정입니다.

Codex가 모든 항목을 완전히 같은 의미로 가져올 수 있는 것은 아닙니다. 예를 들어 Claude Code의 특정 hook 동작이나 command 템플릿이 Codex에서 그대로 실행되지 않을 수 있습니다. 이런 항목은 자동 import 후에 별도로 검토해야 합니다.

Codex 앱에서 가져오기

Codex 앱의 import 기능을 사용하면 Claude Code 설정을 자동으로 탐지하고, Codex가 바로 변환할 수 있는 항목을 가져올 수 있습니다.

Codex 앱을 엽니다.
Settings로 이동합니다.
General 페이지에서 Import other agent setup을 찾습니다.
Import 또는 Import again을 선택합니다.
Codex가 찾은 항목을 확인하고, 가져올 항목을 선택합니다.
import가 끝나면 View imported files를 눌러 결과를 확인합니다.

자동 import는 사용자 수준 설정과 현재 열려 있는 프로젝트 수준 설정을 함께 확인합니다. 사용자 수준 설정은 보통 홈 디렉터리에 있는 Claude Code 관련 파일에서 오고, 프로젝트 수준 설정은 현재 저장소 안의 CLAUDE.md나 .claude 관련 파일에서 옵니다.

Codex가 가져오는 방식

Codex는 import를 실행할 때 다음 순서로 작업합니다.

현재 컴퓨터와 열린 프로젝트에서 이전 가능한 설정을 탐지합니다.
사용자가 선택한 항목 중 바로 변환할 수 있는 항목을 Codex 형식으로 가져옵니다.
import가 끝난 뒤 다시 확인해 남은 항목이 있는지 검사합니다.
자동 변환이 어려운 항목이 있으면 새 Codex thread에서 이어서 처리할 수 있게 안내합니다.

이 방식의 장점은 Claude Code의 설정을 한 번에 모두 옮기려고 무리하지 않는다는 점입니다. 명확히 매핑되는 항목은 자동으로 처리하고, 사람이 판단해야 하는 항목은 별도 작업으로 남깁니다.

AGENTS.md

가장 중요한 항목은 CLAUDE.md에서 AGENTS.md로 넘어가는 지시 파일입니다. Claude Code에서 CLAUDE.md에 프로젝트 규칙, 테스트 방법, 코딩 스타일, 금지 사항을 적어 두었다면 Codex에서는 AGENTS.md가 비슷한 역할을 합니다.

다만 두 파일을 완전히 같은 문서로 생각하면 안 됩니다. Codex의 AGENTS.md는 Codex가 작업을 시작할 때 읽는 지시 파일이며, 전역 지시와 프로젝트 지시가 계층적으로 적용됩니다. 이전 후에는 실제 Codex에게 "현재 적용된 지시를 요약해 달라"고 요청해 의도대로 읽히는지 확인하는 것이 좋습니다.

자동으로 끝나지 않는 항목

일부 Claude Code 설정은 Codex에 일대일로 대응되지 않을 수 있습니다. 이런 경우 Codex는 남은 설정을 보여 주고 Continue in Codex를 통해 새 thread에서 이어서 처리할 수 있게 합니다.

이 새 thread에는 남은 이전 작업이 미리 채워집니다. Codex는 사용자 수준 설정과 프로젝트 수준 설정을 구분해서 보여 주므로, 어떤 항목을 개인 설정으로 둘지, 어떤 항목을 저장소에 포함할지 판단하기 쉽습니다.

자동 변환이 어려울 수 있는 대표적인 항목은 다음과 같습니다.

shell interpolation이나 인자 치환에 의존하는 slash command입니다.
특정 Claude Code hook 실행 순서에 의존하는 설정입니다.
인증 토큰, 환경 변수, 커스텀 header가 포함된 MCP 서버 설정입니다.
Claude Code 플러그인이나 marketplace에 강하게 묶인 설정입니다.
특정 파일 경로나 로컬 도구 설치 상태를 가정하는 skill입니다.

이런 항목은 Codex에서 그대로 실행하기보다, 의도와 동작을 먼저 확인한 뒤 Codex 형식으로 다시 정리하는 것이 안전합니다.

가져온 뒤 검토할 것

import가 끝났다고 바로 모든 작업을 맡기는 것은 좋지 않습니다. 최소한 다음 항목은 확인해야 합니다.

AGENTS.md에 불필요하거나 Claude Code에만 맞는 표현이 남아 있지 않은지 확인합니다.
config.toml에 권한, sandbox, approval 관련 설정이 의도대로 들어갔는지 확인합니다.
MCP 서버가 필요한 환경 변수와 인증 정보를 제대로 참조하는지 확인합니다.
hooks가 Codex에서 실행될 때 위험한 명령을 실행하지 않는지 확인합니다.
skills와 subagents가 Codex의 작업 방식에 맞게 충분히 구체적인 설명을 갖고 있는지 확인합니다.
slash command에서 인자, 파일 경로, shell 문법이 깨지지 않았는지 확인합니다.

특히 자동으로 가져온 지시 파일은 한 번 다듬는 것이 좋습니다. Claude Code에서 자연스럽던 표현이 Codex에는 불필요하거나 모호할 수 있기 때문입니다. 예를 들어 특정 명령을 "항상 실행하라"고 적어 두었다면, Codex에서는 "관련 파일을 수정한 경우 실행하라"처럼 조건을 더 명확히 적는 편이 안전합니다.

간단한 확인 절차

이전 후에는 작은 작업으로 설정이 잘 적용되는지 확인합니다.

현재 프로젝트에서 Codex가 읽은 지시 파일과 중요한 작업 규칙을 요약해 줘.
아직 파일은 수정하지 마.

그다음 테스트나 빌드가 필요한 작은 작업을 맡겨 봅니다.

이 프로젝트의 테스트 실행 방법을 확인하고, 실행 가능한 가장 작은 검증 명령을 알려 줘.
가능하면 명령을 실행해 보고 결과를 요약해 줘.
파일은 수정하지 마.

이 두 요청에서 Codex가 AGENTS.md, 설정, MCP 도구, 권한 요청 방식을 의도대로 사용하는지 확인할 수 있습니다.

이전 후 작업 흐름

이전이 끝나면 기존 Claude Code 프로젝트를 Codex 프로젝트로 열고 평소 작업을 이어갈 수 있습니다. 처음 며칠은 Codex가 어떤 파일을 읽고 어떤 명령을 실행하는지 조금 더 자주 확인하는 것이 좋습니다.

새 기능 구현이나 큰 리팩터링을 바로 맡기기보다, 프로젝트 설명, 테스트 실행, 작은 버그 수정처럼 영향 범위가 좁은 작업부터 시작하는 편이 안정적입니다. 설정이 충분히 정리되면 기존 Claude Code에서 쓰던 작업 패턴을 Codex 앱, IDE 확장, CLI, Cloud 흐름 중 자신에게 맞는 방식으로 옮겨 갈 수 있습니다.