Claude Code를 Codex (2026)로 마이그레이션하기: 12가지 설정과 1가지 막다른 길

Codex 0.142 /import 명령은 Claude Code 설정의 대부분을 자동으로 이동시킵니다. 매핑된 12가지 요소 전체를 살펴봅니다: 무엇이 전송되고, 무엇이 깨지며, 1가지 막다른 길은 무엇인지, 그리고 해결 방법은 무엇인지 알아봅니다.

Claude Code에서 Codex로 마이그레이션하는 작업은 대부분 이름 변경 및 재형식화(reformat) 작업이며, 이제 Codex는 이 작업의 대부분을 대신 수행해 주는 원클릭 임포터(importer)를 제공합니다. 문제는 무엇이 남겨지는가에 있으며, 그중 한 가지 항목은 설정 파일조차 아닙니다.

30초 마이그레이션 결론

약 20분이면 Claude Code 설정의 거의 전체를 Codex로 옮길 수 있습니다. 스크롤하기 전에 다음 결정을 확인하세요:

질문	답변
대부분의 설정을 옮길 수 있나요?	네. 12개 요소 중 9개가 깔끔하게 전송되거나 재구성됩니다.
...

이 가이드가 테스트된 버전: Codex CLI 0.142.5 (2026년 7월 1일) 및 Claude Code 2.1.178. 만약 이전 버전의 Codex를 사용 중이라면 먼저 업그레이드하세요. /import 명령은 0.140.0 이전에는 존재하지 않았습니다.

오늘 옮길 수 있는 것 (그리고 옮길 수 없는 것)

두 도구가 서로 다른 파일 형식으로 동일한 문제를 해결하기 때문에 거의 모든 것이 이동합니다. Claude Code는 JSON (settings.json, .mcp.json)과 Markdown (CLAUDE.md, .claude/agents/*.md)에 의존합니다. Codex는 단일 TOML 파일 (~/.codex/config.toml)과 AGENTS.md에 의존합니다. 마이그레이션은 기본적으로 이 두 방언(dialects) 간의 번역 작업입니다.

이동 가능한 항목:

• 레포지토리(Repo) 및 개인 지침 (CLAUDE.md 내용)
• MCP 서버, 명령 및 인자(args) 그대로 유지
• 이미 공유된 Agent Skills 컨벤션을 따르는 스킬(Skills)
• 슬래시 명령(Slash commands) 및 재사용 가능한 프롬프트
• 커스텀 API 엔드포인트 및 키

우회 방법 없이는 이동할 수 없는 항목:

• Claude Code의 명령별 권한 허용 목록 (per-command permission allowlist): Codex에는 직접적인 대응 기능이 없음
• ConfigChange 훅 이벤트 (Codex에는 PreCompact/PostCompact는 있지만, 설정 파일 변경 시 실행되는 이벤트는 없음)
• 출력 스타일 (Output styles): Codex는 이를 모델링하지 않음
• Anthropic 모델 자체: 이것이 진정한 장애물이며 마지막 섹션의 이유임

다음은 전체 표면 지도(surface map)입니다. 이 표를 저장해 두세요. 한 화면에 마이그레이션의 모든 내용이 담겨 있습니다.

#	Claude Code	Codex 대응 항목	판결
1	CLAUDE.md 메모리	AGENTS.md (또는 대체 파일명)	이전 가능
...

9번과 11번 행은 외관상의 차이입니다. outputStyle은 없어도 상관없으며, ConfigChange는 세션 중간에 설정 파일이 변경되는 것에 반응하는 자동화 도구를 구축한 경우에만 중요합니다. 12번 행이 사람들을 멈추게 만드는 항목이며, 대부분의 마이그레이션 가이드가 생략하는 명확한 해결책이 존재합니다.

결정 프레임워크: 언제 마이그레이션할 것인가 (그리고 언제 유지할 것인가)

업무가 태스크 형태(task-shaped)이고 더 엄격한 샌드박싱 (sandboxing)을 원한다면 마이그레이션하십시오. 업무가 대화 형태(conversation-shaped)이고 훅(hook) 기반이라면 Claude Code를 유지하십시오. 두 도구는 서로 다른 멘탈 모델 (mental models)을 가지고 있으며, 설정의 차이는 거기에서 비롯됩니다.

마이그레이션해야 하는 경우

• CI에서 에이전트를 비대화형(non-interactively)으로 실행하며, 기본 설정으로 read-only 또는 workspace-write 샌드박스를 원하는 경우.
• 팀에서 settings.json과 수많은 settings.local.json 오버라이드(overrides) 대신, 위험 수준별 프로필이 포함된 하나의 커밋된 config.toml을 원하는 경우.
• OpenAI의 현재 Codex 모델 (gpt-5.5)을 기본 드라이버로 사용하고자 하는 경우. 이전의 gpt-5.3-codex는 2026-05-26에 사용자가 선택 가능한 Codex 모델에서 지원 중단(deprecated)되었으므로, gpt-5.5 또는 gpt-5.4를 선택하십시오.

마이그레이션하지 말아야 하는 경우

• ConfigChange 훅 (hooks) 또는 출력 스타일 (output styles)에 의존하는 경우입니다. 이러한 요소들은 Codex에서 지원되지 않으므로, 재작업 시간을 할당하거나 기존 상태를 유지하십시오.
• 전체 워크플로가 긴 대화형 페어링 (interactive pairing) 세션인 경우입니다. Claude Code의 대화형 모델은 Codex의 작업 및 검토 (task-and-review) 루프보다 이러한 방식에 더 적합합니다.
• 수동으로 세밀하게 조정된 권한 허용 목록 (permission allowlist)을 보유하고 있는 경우입니다. Codex의 거친 샌드박스 계층 (sandbox tiers)은 투박하게 느껴질 수 있으며, 그 의도를 이식하는 데는 상당한 고민이 필요합니다 (단계 5 참조).

중단 규칙 (The Stop Rule)

만약 유일한 목표가 기존 저장소 (repo)에 대해 Codex의 모델들을 테스트해보는 것이라면, 설정을 전혀 마이그레이션할 필요가 없습니다. Codex를 저장소로 지정하고, /import를 실행한 뒤 멈추십시오. 이 가이드의 나머지 내용은 Codex를 기본 도구로 사용하려는 사람들을 위한 것입니다.

시스템 요구 사항 (System Requirements)

설정을 건드리기 전에, 아래의 네 가지 전제 조건을 확인하십시오. 오래된 버전의 Codex를 사용하는 것은 /import 명령과 [features] 블록이 아무런 동작을 하지 않는 가장 흔한 원인입니다.

• Codex CLI 0.140.0 이상. codex --version으로 확인하십시오. /import 명령은 0.140.0 버전에서 도입되었으며, 이 가이드는 0.142.5 버전에서 테스트되었습니다.
• 기존의 Claude Code 프로젝트, .claude/ 디렉토리와 CLAUDE.md가 온전하게 유지되어 있어야 합니다. 마이그레이션이 확인될 때까지 이를 삭제하지 마십시오.
• API 키. Codex를 구동할 제공업체의 키가 필요합니다. 기본적으로는 OpenAI이며, Claude 모델을 계속 사용하는 경우 게이트웨이 키 (gateway key)가 필요합니다.
• ~/.codex/에 대한 쓰기 권한. Codex는 호출될 때마다 ~/.codex/config.toml을 읽으며, 신뢰할 수 있는 프로젝트의 경우 저장소 루트의 .codex/config.toml을 읽습니다.

전체 마이그레이션 경로는 다음과 같습니다:

flowchart LR
    A[CLAUDE.md + settings.json 감사] --> B[codex /import 실행]
    B --> C[충돌 보고서 검토]
...

단계별 가이드: 모든 설정 영역 매핑하기 (Mapping Every Config Surface)

먼저 자동 임포터 (automated importer)를 실행한 다음, 임포터가 완전히 처리할 수 없는 다섯 가지 영역을 직접 점검하십시오. 수동 점검 단계를 건너뛰지 마십시오. 임포터는 남겨진 요소들에 대해 정직하게 알려주지만, 어쨌든 무언가를 남겨두기는 합니다.

단계 1: 임포터 실행

프로젝트에서 Codex를 시작하고 임포트하십시오.

cd my-project
codex
# 그 다음, 세션 내부에서:
...

Codex 0.140 버전에서는 OpenAI Codex changelog에 따라 Claude Code로부터 설정(setup), 프로젝트 구성(project configuration), 최근 채팅(recent chats)을 선택적으로 가져올 수 있는 /import 기능이 추가되었습니다. 원하는 항목들을 선택하십시오. 예상 결과: 데이터가 채워진 ~/.codex/config.toml, AGENTS.md 초안, 그리고 건너뛰었거나 충돌(conflict)로 표시된 항목을 나열한 짧은 보고서가 생성됩니다.

Step 2: Instructions, CLAUDE.md에서 AGENTS.md로

Codex는 CLAUDE.md가 아닌 AGENTS.md를 읽습니다. 만약 임포터(importer)가 아직 파일을 생성하지 않았다면, 기존 파일의 이름을 변경하거나 Codex가 이전 이름을 계속 읽도록 설정하십시오.

# ~/.codex/config.toml
project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]
project_doc_max_bytes = 32768

예상 결과: 다음 실행 시 저장소(repo) 수준의 지침(instructions)이 Codex 컨텍스트(context)로 로드됩니다. 내용은 변경 없이 그대로 유지되며, 파일 이름과 로드 경로만 달라집니다. 이것이 바로 도구 전반에 걸쳐 AGENTS.md 관례가 존재하는 이유입니다.

Step 3: MCP Servers, JSON에서 TOML로

MCP 프로세스는 동일합니다. 선언(declaration) 방식만 바뀝니다. 다음과 같은 Claude Code의 .mcp.json 항목은:

{
  "mcpServers": {
    "github": {
...

~/.codex/config.toml 내의 TOML 테이블로 변환됩니다:

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

예상 결과: codex 실행 시 github MCP 도구들이 목록에 나타납니다. 서버에 환경 변수(environment variables)가 필요한 경우, 인라인으로 추가하십시오: env = { "GITHUB_TOKEN" = "..." }. 두 가지 전송(transport) 방식 모두 유지됩니다. Codex는 Claude Code에서 실행했던 것과 동일한 STDIO 명령 기반 서버를 수용하며, 동일한 테이블 내에서 스트리밍 HTTP 서버도 지원하므로 원격으로 호스팅되는 MCP 엔드포인트(endpoint)를 로컬 프로세스를 생성하지 않고도 그대로 옮겨올 수 있습니다.

Step 4: Subagents를 .codex/agents/로

Claude Code는 서브에이전트(subagents)를 .claude/agents/ 내의 Markdown 형식으로 저장합니다. 반면 Codex는 각 서브에이전트를 ~/.codex/agents/(개인용) 또는 .codex/agents/(프로젝트 범위) 아래에 에이전트당 하나의 TOML 파일로 저장합니다. 서브에이전트는 기본적으로 활성화되어 있으므로, 별도로 전환할 기능 플래그(feature flag)는 없습니다.

# .codex/agents/reviewer.toml
name = "reviewer"
description = "Reviews diffs for correctness and style"
...

예상 결과: reviewer 역할이 Codex의 서브에이전트 워크플로(workflow)를 통해 사용 가능해지며, Codex는 사용자가 명시적으로 요청할 때만 이를 호출합니다. 기존 Markdown 파일의 프롬프트 본문은 developer_instructions로 이동하며, 변경되는 부분은 래퍼(wrapper)입니다. 서브에이전트가 많다면 이 과정이 가장 지루한 수동 작업이 되겠지만, 기계적인 작업입니다.

Step 5: 샌드박스(Sandbox) 및 승인(Approval) 권한

이 부분은 실제로 문제가 발생하는 지점입니다. 두 도구가 안전성(safety)을 모델링하는 방식이 다르기 때문입니다. Claude Code는 glob 규칙을 사용하는 명령별 허용 목록(allowlist)을 사용합니다. Codex는 파일 시스템 샌드박스(filesystem sandbox)와 승인 정책(approval policy)이라는 두 가지 거친 조절 장치를 사용합니다. 깔끔한 일대일 매핑은 존재하지 않으므로, 규칙이 아닌 의도(intent)를 이식해야 합니다.

Claude Code
allow: ["Bash(npm run test *)"]
...

Codex 의도
저장소 내에서 묻지 않고 명령 실행
...

Codex 설정
sandbox_mode = "workspace-write", approval_policy = "on-request"
...

# ~/.codex/config.toml, 합리적인 기본값
approval_policy = "on-request"
sandbox_mode = "workspace-write"

예상 결과: Codex는 저장소 내부에서 자유롭게 실행되며, 저장소 외부를 건드리거나 네트워크에 접속하기 전에 요청을 보냅니다. Claude Code에서 가졌던 세밀한 명령별 제어 기능은 유지되지 않습니다. 만약 길고 정밀한 허용 목록에 의존했다면, Codex의 모델은 설계상 더 투박하다는 점을 받아들여야 합니다. 전체 옵션 세트는 Codex configuration reference에서 확인할 수 있습니다.

Step 6: 훅(Hooks)

Codex에는 이제 기본적으로 활성화되는 훅 (Hooks) 기능이 있으며, 이는 Claude Code의 대부분의 이벤트를 커버합니다. config.toml 파일 내에 array-of-tables 블록으로 선언할 수 있으며, 시스템 전체를 끄려면 [features] hooks = false로 설정하면 됩니다.

# ~/.codex/config.toml
[[hooks.PreToolUse]]
matcher = "^Bash$"          # Claude Code의 PreToolUse 매처(matcher)와 동일한 개념
...

예상 결과: JSON 핸들러를 TOML로 변환하면, Claude Code에서와 마찬가지로 PreToolUse, PostToolUse, SessionStart, Stop, 그리고 심지어 PreCompact/PostCompact까지 실행됩니다. 유일한 공백은 ConfigChange인데, Codex에는 이에 해당하는 이벤트가 없습니다. 따라서 세션 중간에 설정 파일이 변경되는 것에 반응하도록 구축했던 자동화 기능은 훅 설정 중 유일하게 따라오지 못하는 부분입니다. Claude Code의 훅들이 어떤 역할을 했는지 다시 확인하려면, 당사의 Claude Code hooks, subagents, and skills guide를 참조하세요.

대응 기능이 없는 항목: Claude 모델 (및 해결 방법)

네이티브한 해결책이 없는 단 하나의 마이그레이션 단계는 기존의 Claude 모델을 유지하는 것입니다. 순정(vanilla) Codex는 OpenAI를 통해 인증하며 gpt-5.5 및 gpt-5.4와 같은 OpenAI 모델을 구동하기 때문입니다. Claude Opus 또는 Sonnet을 선택할 수 있는 내장 스위치는 없습니다. 만약 샌드박스(sandbox)와 워크플로(workflow) 때문에 Codex로 마이그레이션했지만, 여전히 Opus가 코드를 작성하기를 원한다면 브릿지(bridge)가 필요합니다.

그 브릿지는 커스텀 model_provider입니다. Codex는 모든 OpenAI 호환 게이트웨이(gateway)와 통신할 수 있으므로, 게이트웨이를 등록하고 프로필을 Claude 모델로 지정하면 됩니다. ~/.codex/config.toml에 프로바이더를 추가하세요:

[model_providers.ofox]
name = "ofox.ai gateway"
base_url = "https://api.ofox.ai/v1"
...

사람들이 실수하기 쉬운 두 가지 세부 사항이 있습니다. 첫째, wire_api = "responses"로 설정하십시오. Codex는 2026년 2월에 이전의 chat 프로토콜 지원을 중단했으므로, wire_api = "chat" 상태로 남겨둔 제공자(provider)는 이제 시작 시 오류가 발생합니다. ofox는 동일한 /v1 베이스 URL(base URL) 하에 Responses 호환 엔드포인트(endpoint)를 제공하므로, 실제로 연결되는 것은 responses입니다. 둘째, requires_openai_auth = false로 설정하여 Codex가 sk- 키 접두사를 기대하지 않도록 하십시오. 그런 다음 ~/.codex/claude.config.toml 경로에 프로필 파일을 생성합니다:

model = "anthropic/claude-opus-4.8"
model_provider = "ofox"

codex --profile claude 명령어로 실행하십시오. 이제 Codex의 태스크 루프(task loop)와 샌드박스(sandbox)가 Anthropic의 anthropic/claude-opus-4.8을 구동하며, 두 번째 프로필에서 model = "openai/gpt-5.5"로 교체하면 인증을 변경하지 않고도 두 모델을 A/B 테스트할 수 있습니다. 재시도(retries) 및 헤더(headers)를 포함한 제공자 블록(provider block)에 대한 단계별 절차는 Codex의 커스텀 모델 제공자(custom model providers in Codex) 가이드에 있으며, 전체 ofox 문서(ofox docs)에서 주요 설정을 다룹니다. 이것은 게이트웨이(gateway)가 편의를 위한 도구가 아니라, 원래 의도했던 기능을 유지하기 위한 유일한 방법인 마이그레이션 영역입니다.

마이그레이션 중 발생하는 일반적인 오류 (및 해결 방법)

여섯 가지 실패 사례가 중단된 마이그레이션의 거의 모든 경우를 포괄합니다. 패턴은 매번 동일합니다. 바로 Claude Code의 가정이 Codex에는 적용되지 않는다는 점입니다.

증상	원인	해결 방법
Codex가 CLAUDE.md를 무시함	Codex는 AGENTS.md를 읽음	파일 이름을 변경하거나, project_doc_fallback_filenames를 설정하십시오
...

만약 프로젝트의 .codex/config.toml이 완전히 무시되고 있다면, 해당 프로젝트가 신뢰할 수 있는(trusted) 상태로 표시되어 있는지 확인하십시오. Codex는 신뢰할 수 있는 디렉토리 내에서만 프로젝트 범위(project-scoped)의 설정을 로드하며, 프로젝트 파일이 제공자(provider), 인증(auth), 또는 프로필 선택을 덮어쓰도록 허용하지 않습니다.

팀 / 다중 개발자 마이그레이션