Claude Code파였던 내가 Codex로 옮기기 전에 알고 싶었던 것

서론

최근 Claude Code를 사용하는 사람이 상당히 늘어났죠.

저도 처음에는,

"Claude Code 편리하네"

"하지만 Codex도 궁금한데"

"OpenAI 버전의 Claude Code 같은 느낌인가?"

정도의 가벼운 마음으로 Codex를 만져보기 시작했습니다.

하지만 실제로 사용해 보니, 생각했던 것과는 다른 것이었습니다.

물론 둘 다 AI 코딩 에이전트 (AI Coding Agent)입니다.

터미널이나 앱에서 코드를 읽게 하거나, 수정하게 하거나, 테스트를 실행하게 할 수 있습니다.

하지만 Claude Code의 감각 그대로 Codex를 다루면 은근히 헤매게 됩니다.

제가 처음에 걸려 넘어졌던 것은 모델 성능이나 답변 품질이 아니라,

CLAUDE.md는 어디로 가야 하지?

.claude/settings.json은 무엇으로 옮겨야 하지? - permission mode와 sandbox는 무엇이 다르지?

• subagent와 skill은 그대로 생각해도 될까?
• Codex App과 CLI의 설정은 별개인가?

와 같은, 설정과 운용의 대응 관계였습니다.

그래서 "Claude Code 사용자가 Codex를 만지기 전에 알아두면 편해지는 것"을 정리합니다.

TL;DR

요약하자면, Claude Code에서 Codex로 옮길 때 확인해야 할 것은 이 대응표입니다.

Claude Code에서 보던 것	Codex에서 보는 것	대략적인 이해
CLAUDE.md	AGENTS.md	레포지토리 (repo)의 규칙을 적는 곳
.claude/settings.json	~/.codex/config.toml / .codex/config.toml	설정은 TOML로 관리함
.claude/settings.local.json	~/.codex/config.toml의 profile 등	개인 설정은 기본적으로 글로벌 쪽으로 분리
permission mode	approval policy + sandbox mode	"확인할 것인가"와 "접근 가능한 범위"를 분리
Subagents / Skills	Subagents / Skills / Plugins	이름은 비슷하지만 그대로 이식하지 않음

한마디로 말하자면, Codex는 "Claude Code의 OpenAI 버전"이라기보다,

AI 에이전트에게 개발 작업을 넘기기 위한 조작 데스크

같은 감각에 가깝습니다.

이 부분을 이해하고 사용하면 훨씬 덜 헤매게 됩니다.

이 기사에서 다루는 것 · 다루지 않는 것

이 기사는 Codex의 설치 절차를 처음부터 설명하는 글이 아닙니다.

상정하고 있는 대상은 다음과 같습니다.

• Claude Code를 어느 정도 사용하고 있다
• CLAUDE.md나 .claude/settings.json에 익숙하다
• Codex를 써보고 싶지만, 무엇을 어디에 두어야 할지 모르겠다
• CLI뿐만 아니라 Codex App도 사용하고 싶다
• 업무에 사용하기 전에 권한 관련 사고를 피하고 싶다

반대로, 요금제나 모델 성능의 세세한 비교는 깊게 다루지 않습니다.

이 분야는 변화가 너무 빠르기 때문에, 공개 직전에 공식 정보를 확인하는 것이 가장 안전합니다.

이 기사의 전제는 2026년 5월 7일 시점의 공식 문서와 저의 관측 범위 내의 정보입니다.

우선 대전제: Codex는 "Claude Code처럼 사용"하면 미묘하게 어긋난다

가장 먼저 하고 싶은 말은 이것입니다.

Codex는 Claude Code처럼 사용하려고 하면 미묘하게 어긋납니다.

Claude Code는 첫 경험으로서 "터미널에 있는 엄청나게 똑똑한 파트너"라는 느낌이 강합니다.

claude라고 입력하고, 대화하고, 필요하면 파일을 편집해 달라고 합니다.

매우 자연스럽게 사용할 수 있습니다.

반면 Codex는 CLI뿐만 아니라 App이나 IDE를 포함하여,

• 어떤 레포지토리 (repo)에서 실행할 것인가
• 어떤 권한으로 실행할 것인가
• 어떤 모델을 사용할 것인가
• subagent에게 무엇을 맡길 것인가
• skill이나 plugin을 어떻게 사용할 것인가

를 제대로 설계해 나가는 도구라는 인상입니다.

처음에는 조금 번거로워 보일 수 있지만, 이 부분을 정돈하면 매우 쾌적하게 작동합니다.

반대로 말하면, 아무 설정 없이

"Claude Code처럼 알아서 잘 해줘"

라고 던지기만 하면 그 장점을 보기 어렵습니다.

CLAUDE.md는 AGENTS.md로 맞춘다

Claude Code를 사용하는 사람이라면, repo에 CLAUDE.md를 두고 있는 사람도 많을 것입니다.

Codex에서는 이와 유사한 역할로 AGENTS.md를 두는 것이 이해하기 쉽습니다.

예를 들어, Claude Code 측에서 다음과 같은 규칙을 작성했다고 가정해 봅시다.

- 답변은 일본어
- 변경 전에 기존 구현을 읽을 것
- package manager는 pnpm을 사용할 것
...

Codex 측에서는 우선 이런 식으로 AGENTS.md로 옮깁니다.

답변은 일본어로 해주세요.
## 개발 규칙
- 변경 전에 기존 구현을 읽어주세요.
...

이 부분은 상당히 그대로 옮길 수 있습니다.

단, Claude Code 고유의 조작에 의존한 지시는 그대로 가져오지 않는 것이 좋습니다.

예를 들어,

• /permissions를 이렇게 사용한다
• Claude Code의 custom command로 이렇게 한다
• .claude/agents를 전제로 이렇게 동작한다

와 같은 이야기는 Codex에서 그대로 대응하지 않을 수 있습니다.

AGENTS.md에는 우선 "repo로서 지켜주길 바라는 규칙"만 둡니다.

도구 고유의 설정은 config.toml이나 .codex/ 측으로 분리합니다.

이렇게 나누는 것이 가장 사고를 방지하기 쉽다고 생각합니다.

settings.json은 그대로 옮길 수 없다

이 부분에서 저는 처음에 조금 혼란스러웠습니다.

Claude Code 측에서는,

~/.claude/settings.json
.claude/settings.json
.claude/settings.local.json

와 같은 방식으로 배치합니다.

그렇다면 Codex에서는 어디에 작성하는가? 하는 의문이 생기는데, 기본은 TOML입니다.

대략적으로 나누면 다음과 같습니다.

위치	작성 내용
~/.codex/config.toml	개인 기본 설정, 모델, profile, MCP, subagent 상한 등
.codex/config.toml	repo 고유 설정. 신뢰하는 project에서 읽음

Claude Code의 .claude/settings.local.json과 같은 "repo 안에 있지만 개인용" 설정을 Codex에서도 같은 방식으로 만들려고 하면 조금 망설여집니다.

Codex에서는 개인용 차분(diff)은 ~/.codex/config.toml의 profile에 맞추는 것이 더 자연스럽다고 생각합니다.

예를 들어, 개인 개발에서는 조금 가볍게 돌리고 싶지만, 업무 repo에서는 안전하게 운영하고 싶다면 다음과 같습니다.

model = "gpt-5.5"
model_reasoning_effort = "medium"
[profiles.safe]
...

repo 측에는 공유해도 좋은 설정만 둡니다.

approval_policy = "on-request"
sandbox_mode = "workspace-write"

포인트는 Claude Code의 설정 파일을 1대1로 변환하려고 하지 않는 것입니다.

우선,

• 개인의 취향
• repo에서 공유하고 싶은 규칙
• 권한 관련

으로 분해한 뒤 Codex 측으로 가져가는 것이 더 이해하기 쉽습니다.

permission mode는 approval과 sandbox로 나누어 생각하기

Codex에서 가장 중요한 것은 이 부분일지도 모릅니다.

Claude Code의 permission mode에 익숙해져 있으면, Codex의 설정이 처음에는 조금 복잡해 보일 수 있습니다.

하지만 사실은 나누기만 하면 됩니다.

관점	의미
approval policy	Codex가 인간에게 확인하는 타이밍
sandbox mode	Codex가 기술적으로 접근할 수 있는 범위

즉,

• approval = "해도 돼?"라고 물어볼 것인가
• sandbox = 애초에 접근 가능한가

입니다.

이 둘을 섞으면 혼란이 생깁니다.

예를 들어, approval_policy = "never"로 설정하더라도, sandbox_mode = "read-only"라면 편집할 수 없습니다.

반대로, sandbox_mode = "danger-full-access"로 설정하면 접근 범위가 넓어지므로, approval과는 별개로 리스크가 올라갑니다.

처음 사용하신다면, 저는 이 정도가 무난하다고 생각합니다.

approval_policy = "on-request"
sandbox_mode = "workspace-write"

workspace 내의 작업은 진행하기 쉽지만, workspace 외부나 네트워크가 연관된 부분에서는 멈추기 쉽습니다.

처음에는 이 정도로 충분합니다.

갑자기 너무 강하게 자동화해 버리면, 무엇이 위험한 조작이었는지 모르는 채로 진행되기 때문에 그 점은 조금 무섭습니다.

Plan mode는 「안전 설정」이 아니라 「진행 방식」

이것도 처음에 오해하기 쉬운 포인트입니다.

Plan mode라고 하면, 「멋대로 편집하지 않는 안전 모드」처럼 보입니다.

하지만 Codex에서는 approval이나 sandbox와는 별개로 생각하는 것이 좋습니다.

제 이해로는, Plan mode는 「먼저 사고방식을 내놓게 하는 모드」입니다.

예를 들어, 다음과 같이 구분해서 사용합니다.

상황	사용법
사양이 모호함	우선 Plan mode로 방침만 내놓게 한다
...
「건드리지 않았으면 좋겠다」라면, Plan mode에만 의존하기보다 read-only나 approval로 제어합니다.

「먼저 방침을 보고 싶다」라면 Plan mode를 사용합니다.

이렇게 구분해 두면 훨씬 편해집니다.

AGENTS.md는 얇아도 괜찮다

처음 Codex를 repo에 넣을 때, 처음부터 완벽한 AGENTS.md를 쓰려고 하면 힘듭니다.

처음에는 이 정도면 충분하다고 생각합니다.

답변은 일본어로 해주세요.
## 작업 방침
- 변경 전에 기존 구현, README, package.json을 확인해 주세요.
...

처음부터 무엇이든 너무 많이 채워 넣으면, 오히려 다루기 어려워집니다.

저는 이런 규칙 계열은,

• 우선 얇게 둔다
• Codex가 몇 번 같은 실수를 한다
• 그 실수만
  AGENTS.md에 추가한다

이 정도가 딱 적당하다고 생각합니다.

Claude Code에서 Codex로 옮기는 순서

갑자기 전부 옮기려고 하면 아마 혼란스러울 것입니다.

저라면 이 순서로 하겠습니다.

CLAUDE.md를 AGENTS.md로 옮기기

Step 1. 우선은 이것만으로도 OK입니다.

옮기는 것은 툴 고유의 이야기가 아니라, repo의 개발 규칙입니다.

• 말투·언어
• 가장 먼저 읽을 파일
• test / lint / format 명령어
• 하지 않았으면 하는 일

이런 부분들을 옮깁니다.

Step 2. 권한은 안전한 쪽부터 시작하기

처음부터 완전 자동화 쪽으로 기울이지 않는 것이 좋습니다.

특히 처음 접하는 repo나 업무용 repo라면, 우선은 이렇게 시작합니다.

approval_policy = "on-request"
sandbox_mode = "workspace-write"

몇 번 사용해 보고,

「여기는 매번 확인받는 게 귀찮네」

라고 생각되는 부분만 조금씩 완화하는 것이 안전합니다.

Step 3. 자주 쓰는 작업만 프롬프트화하기

Claude Code에서 custom command를 사용하던 분들은, Codex에서도 금방 비슷한 것을 만들고 싶어질 것입니다.

다만, 처음에는 일반적인 프롬프트로도 충분합니다.

예를 들어 리뷰라면, 다음과 같은 고정 문구를 만들어 둡니다.

이 차이점(diff)을 리뷰해 주세요.
우선순위는 correctness / security / regression / missing tests 입니다.
style-only 지적은 버그로 이어질 경우에만 해주세요.
...

이것을 반복해서 사용하게 된다면, 그때 비로소 skill이나 subagent로 분리합니다.
처음부터 너무 시스템화하지 않는 것이 운영에 맞는 형태를 찾는 데 도움이 됩니다.

Step 4. subagent는 「병렬로 맡기고 싶은 작업」부터 사용하기

subagent라고 하면 바로 「리뷰 담당」, 「구현 담당」, 「조사 담당」처럼 만들고 싶어집니다.

그 자체는 나쁘지 않지만, 처음부터 커스텀 agent를 공들여 만들 필요는 없다고 생각합니다.

Codex에는 default, worker, explorer와 같은 built-in agent가 있습니다.

우선은 그것으로 충분합니다.

subagent가 효과적인 것은 예를 들어 다음과 같은 상황입니다.

• 기존 코드의 영향 범위를 조사할 때
• 공식 문서를 확인할 때
• UI 구현과 테스트 수정을 나눌 때
• PR 리뷰의 관점을 나눌 때

요컨대, 부모의 대화를 더럽히지 않고 별도로 진행하고 싶은 작업입니다.

「전문가스러운 이름을 붙이기」보다는, 「병렬로 진행할 의미가 있는가」로 생각하면 사용하기 쉽습니다.

「Codex가 미묘할지도」라고 느꼈을 때 확인하는 곳

Codex를 사용하면서,

「어쩐지 생각보다 똑똑하지 않네」

「의도와 다르게 동작하네」

라고 느꼈을 때, 모델 성능보다 설정이 원인인 경우가 꽤 많습니다.

먼저 확인해야 할 곳은 여기입니다.

• working directory (작업 디렉토리)가 repo root (저장소 루트)로 되어 있는가
• AGENTS.md가 읽히는 위치에 있는가
• .codex/config.toml이 신뢰할 수 있는 project (프로젝트)로서 읽히고 있는가
• sandbox (샌드박스)가 너무 엄격해서 필요한 파일을 읽지 못하고 있는가
• approval (승인)이 너무 느슨해서 확인하고 싶은 조작까지 그냥 흘러가 버리는가
• 필요한 MCP나 connector (커넥터)가 활성화되어 있는가
• 매번 같은 설명을 하고 있다면, AGENTS.md로 옮겨야 하지 않는가
• 매번 같은 전문 작업을 요청하고 있다면, subagent (서브에이전트)화해야 하지 않는가

특히 흔히 발생하는 패턴은,

「지시가 잘못된」 것이 아니라, 「repo (저장소)의 전제를 Codex에 전달하지 못한」

경우입니다.

이 점은 Claude Code에서도 마찬가지지만, Codex는 설정 레이어 (layer)가 많은 만큼 어디에 무엇을 쓰느냐에 따라 결과가 상당히 달라집니다.

마치며

Claude Code에서 Codex로 옮길 때 봐야 할 것은, 결국 「어느 쪽 모델이 더 똑똑한가」만이 아니라고 생각합니다.

실제로 효과를 발휘하는 것은,

• repo (저장소)의 지시를 어디에 둘 것인가
• 어떤 권한으로 작업하게 할 것인가
• 어디에서 인간의 확인을 거칠 것인가
• 어떤 작업을 subagent (서브에이전트)에게 넘길 것인가
• 어떤 작업을 skill (스킬)이나 prompt (프롬프트)로 고정할 것인가

이런 부분들입니다.

Codex는 환경을 제대로 구축하면 상당히 기분 좋게 작동합니다.

반대로, 대충 실행해서 대충 「알아서 잘 해줘」라고 부탁하기만 하면 장점이 보이기 어렵습니다.

우선 AGENTS.md를 가볍게 배치한다.

권한은 안전한 쪽으로 설정한다.

하나의 repo (저장소)에서 며칠간 사용해 본다.

그 후에 자주 사용하는 작업만 subagent (서브에이전트)나 skill (스킬)로 분리한다.

이동은 이 정도로 수수하게 시작하는 것이 가장 강력하다고 생각합니다!

그럼 다음에 만나요!