Claude Code에서 Codex CLI로 — 마이그레이션 가이드

 

AI 코딩 도구 시장이 빠르게 변하고 있습니다. Anthropic의 Claude Code를 잘 쓰고 있었는데, OpenAI가 Codex CLI를 내놓으면서 선택지가 하나 더 생겼습니다.

또한 카카오톡이 chatGPT 프로모션을 하면서 묵혀뒀던 코덱스를 써야할 때입니다.

문제는, 어느 한쪽을 선택한다고 기존 환경을 버릴 수는 없다는 점입니다.

Claude Code를 오래 쓴 사람일수록 설정 파일, MCP 서버, 커스텀 스킬, 에이전트 등 축적된 환경이 상당합니다. 이걸 Codex CLI에서도 동일하게 쓰려면 수작업으로 하나하나 변환해야 하는데, 포맷이 완전히 다릅니다.

이 글에서는 실제로 53개 스킬, 11개 MCP 서버, 387줄의 프로젝트 지침을 마이그레이션한 경험을 바탕으로, 체계적인 이전 방법을 정리합니다.

---

0. 왜 마이그레이션이 필요한가

Claude Code와 Codex CLI는 "터미널에서 AI와 코딩한다"는 목적은 같지만, 내부 구조가 완전히 다릅니다. 설정 파일 포맷부터 디렉토리 구조, 스킬 호출 방식까지 호환되는 것이 하나도 없습니다.

양쪽을 동시에 사용하거나, 한쪽에서 다른 쪽으로 완전히 이전하려면 이 차이를 정확히 이해하고 변환해야 합니다.

도구 매핑 테이블

항목	Claude Code	Codex CLI
설정 디렉토리	~/.claude/	~/.codex/
프로젝트 지침	CLAUDE.md	AGENTS.md
설정 파일	settings.json (JSON)	config.toml (TOML)
MCP 서버	mcp.json	config.toml [mcp_servers.*]
스킬 파일	skill.md (소문자)	SKILL.md (대문자)
스킬 디렉토리	~/.claude/skills/	~/.codex/skills/
서브 에이전트	~/.claude/agents/*.md	config.toml [profiles.*]
권한 모드	acceptEdits	sandbox_mode = "workspace-write"
스킬 호출	/skill-name	$skill-name

표에서 보듯, 단순히 파일을 복사하는 것으로는 해결되지 않습니다. JSON은 TOML로, 소문자 파일명은 대문자로, 슬래시 호출은 달러 호출로 — 전부 변환이 필요합니다.

---

1. Phase 1 — 기존 환경 감사 (Audit)

마이그레이션의 첫 단계는 현재 Claude Code 환경에 무엇이 있는지 정확히 파악하는 것입니다. 의외로 이 단계를 건너뛰는 경우가 많은데, 나중에 "이거 빠졌는데?" 하는 상황을 막으려면 꼭 해야 합니다.

# 설정 파일 확인
cat ~/.claude/settings.json

# MCP 서버 목록
cat ~/.claude/mcp.json

# 스킬 목록 (심볼릭 링크 포함)
ls -la ~/.claude/skills/

# 에이전트 목록
ls ~/.claude/agents/

여기서 특히 주의할 점은 심볼릭 링크입니다. 스킬 중 일부가 외부 디렉토리(예: ~/.agents/skills/)를 참조하고 있을 수 있습니다. ls -la로 확인하면 -> 로 연결된 경로가 보입니다. 이런 스킬은 원본 파일이 실제로 존재하는지, 내용이 비어 있지는 않은지 반드시 확인해야 합니다.

---

2. Phase 2 — 설정 변환 (Transform)

핵심 변환은 세 가지입니다.

2-1. settings.json → config.toml

Claude Code의 권한 설정은 JSON의 permissions.defaultMode 필드에 있습니다. Codex CLI에서는 TOML의 최상위 sandbox_mode로 변환합니다.

# Claude Code (settings.json)
{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

# Codex CLI (config.toml)
sandbox_mode = "workspace-write"

2-2. MCP 서버 (JSON → TOML)

MCP 서버 설정은 가장 까다로운 부분입니다. JSON의 중첩 객체를 TOML의 섹션 구조로 풀어야 합니다. 특히 env 필드는 별도 섹션으로 분리해야 합니다.

# Claude Code (mcp.json)
{
  "mcpServers": {
    "postgres-dev": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/dev"
      }
    }
  }
}

# Codex CLI (config.toml)
[mcp_servers.postgres-dev]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]

[mcp_servers.postgres-dev.env]
DATABASE_URL = "postgresql://user:pass@localhost:5432/dev"

env를 같은 섹션 안에 인라인으로 넣으면 파싱 에러가 납니다. 반드시 [mcp_servers.이름.env]로 별도 섹션을 만들어야 합니다.

2-3. CLAUDE.md → AGENTS.md

프로젝트 지침 파일은 내용 자체는 대부분 그대로 가져갈 수 있지만, 도구 특화 기능은 제거해야 합니다.

• 포함: 사용자 프로필, 커밋 규칙, 코드 스타일, TDD 규칙, 프레임워크 패턴, DB 규칙, 금지 사항
• 제외: Claude Code 전용 기능 (예: Co-Authored-By 관련 규칙)
• 치환: /command → $command (스킬 호출 문법 변경)

---

3. Phase 3 — 스킬 일괄 변환 (Batch Convert)

스킬이 몇 개 안 되면 수동으로 해도 되지만, 수십 개가 넘어가면 스크립트가 필수입니다. 아래 스크립트는 Claude Code의 모든 스킬을 Codex CLI 형식으로 일괄 변환합니다.

for d in ~/.claude/skills/*/; do
  n=$(basename "$d")
  [ "$n" = ".DS_Store" ] && continue

  # 대상 디렉토리 생성
  mkdir -p ~/.codex/skills/$n

  # skill.md 또는 SKILL.md 찾기
  src=""
  [ -f "$d/skill.md" ] && src="$d/skill.md"
  [ -f "$d/SKILL.md" ] && src="$d/SKILL.md"

  # allowed-tools 라인 제거 후 SKILL.md로 복사
  [ -n "$src" ] && grep -v '^allowed-tools:' "$src" \
    > ~/.codex/skills/$n/SKILL.md

  # 부속 파일 복사 (skill.md 제외)
  for f in "$d"/*; do
    b=$(basename "$f")
    [ "$b" = "skill.md" ] || [ "$b" = "SKILL.md" ] || \
    [ "$b" = ".DS_Store" ] && continue
    cp -r "$f" ~/.codex/skills/$n/
  done
done

핵심은 allowed-tools 라인 제거입니다. Claude Code의 frontmatter에는 allowed-tools: Bash, Read, Write 같은 도구 제한이 있는데, Codex CLI에는 이 개념이 없으므로 제거해야 합니다.

---

4. Phase 4 — 검증 (Verify)

마이그레이션 후 반드시 검증 단계를 거쳐야 합니다. TOML 문법 오류 하나가 전체 설정을 무용지물로 만들 수 있습니다.

# 1. TOML 문법 검증
python3 -c "import tomllib; \
  tomllib.load(open('$HOME/.codex/config.toml','rb')); \
  print('TOML OK')"

# 2. MCP 서버 수 확인
grep -c '^\[mcp_servers\.' ~/.codex/config.toml

# 3. 변환된 스킬 수 확인
ls -d ~/.codex/skills/*/ | wc -l

# 4. 빈 파일 탐지
for f in ~/.codex/skills/*/SKILL.md; do
  [ ! -s "$f" ] && echo "EMPTY: $f"
done

# 5. 제거 안 된 allowed-tools 탐지
grep -rl '^allowed-tools:' ~/.codex/skills/*/SKILL.md \
  || echo "clean"

특히 빈 파일 탐지가 중요합니다. 심볼릭 링크로 연결된 스킬 중 원본이 0바이트인 경우가 있었는데, 일괄 변환 스크립트가 이 빈 파일을 그대로 복사해서 Codex CLI 쪽에도 빈 SKILL.md가 생성되는 문제가 있었습니다. 실제로 8개 스킬에서 이 문제가 발생했고, YAML frontmatter를 수동으로 추가하여 해결했습니다.

---

5. 실제 마이그레이션 결과

이 과정을 거쳐 실제 마이그레이션한 결과입니다.

항목	수량	비고
MCP 서버	11개	PostgreSQL, Notion, Figma, Context7 등
스킬	53개	52개 기존 + 1개 general-task-executor
AGENTS.md	387줄	CLAUDE.md에서 변환
빈 파일 수정	8개	심볼릭 링크 원본이 0바이트

전체 과정에 약 30분이 소요되었는데, 이 중 절반은 빈 파일 문제를 디버깅하는 데 쓰였습니다. 스킬로 자동화하면 검증까지 포함해서 훨씬 빠르게 처리할 수 있습니다.

---

6. 스킬로 자동화하기

위 과정을 매번 수동으로 하기엔 번거롭습니다. 그래서 이 마이그레이션 과정 자체를 Claude Code 스킬로 만들었습니다.

설치

# Claude Code에서 실행
npx claude-code skill install greekr4/claude2codex-migration

사용

# Claude Code 대화창에서
/claude2codex-migration

스킬을 실행하면 4단계(Audit → Transform → Batch Convert → Verify)를 순서대로 안내하며, 각 단계에서 필요한 스크립트와 변환 규칙을 자동으로 적용합니다.

GitHub: github.com/greekr4/claude2codex-migration

---

7. 알려진 이슈와 해결책

이슈	원인	해결
SKILL.md에 YAML frontmatter 누락	원본 skill.md가 0바이트	--- frontmatter에 name, description 수동 추가
MCP env 변수 미적용	TOML 인라인 형식 사용	[mcp_servers.name.env] 별도 섹션으로 분리
심볼릭 링크 스킬 내용 누락	원본 디렉토리에 skill.md 자체가 없음	readlink -f로 실제 경로 확인 후 수동 복사
기존 Codex 스킬 덮어쓰기	일괄 변환 스크립트가 무조건 덮어씀	변환 전 ~/.codex/skills/ 백업 권장

---

마치며

AI 코딩 도구 간 마이그레이션은 생각보다 손이 많이 갑니다. 단순히 "다른 도구 써보자"가 아니라, 그동안 쌓아온 개발 환경 전체를 이식하는 작업이기 때문입니다.

하지만 한 번 구조를 이해하고 나면 어렵지 않습니다. JSON과 TOML의 차이, 파일명 컨벤션, 호출 문법 — 이 세 가지만 정확히 알면 대부분의 변환은 기계적으로 처리할 수 있습니다.

양쪽 도구를 동시에 운영하든, 완전히 이전하든, 이 가이드가 시행착오를 줄이는 데 도움이 되길 바랍니다.