Codex는 어디서 써야 할까: CLI, App, Cursor, Claude Code 정리#

2026-04-12

Codex 사용 환경 가이드 커버

요즘 Codex가 좋다는 이야기가 자주 들립니다. 그런데 막상 써보려고 하면 바로 헷갈리기 시작합니다.

  • Codex CLI로 쓰는 것이 맞는지
  • Codex App이 따로 있는지
  • Cursor 안에서 Codex 확장을 깔아 쓰면 되는지
  • 아니면 Cursor 채팅에서 그냥 Codex 모델만 고르면 되는지
  • Claude Code에 플러그인으로 붙이는 것이 맞는지

필자도 비슷한 궁금증이 생겨서 공식 문서를 기준으로 하나씩 정리해 봤습니다. 이 글은 개발자뿐 아니라, AI 코딩 도구가 어떻게 구성되는지 잘 모르는 분도 따라올 수 있도록 최대한 쉽게 설명하려고 했습니다.

결론부터 먼저 짧게 말하면 이렇습니다.

  • Codex CLI / App / Web / IDE Extension은 대체로 OpenAI Codex 자체를 쓰는 환경입니다.
  • Cursor 채팅에서 Codex 모델 선택은 Codex 모델은 쓰지만, Codex 에이전트 자체를 쓰는 것은 아닙니다.
  • Claude Code + codex-plugin-cc는 Claude Code를 메인으로 두고, 필요할 때만 Codex를 불러오는 구조에 가깝습니다.

먼저, 세 단어만 구분하면 이해가 쉬워집니다#

이 주제가 헷갈리는 가장 큰 이유는 모델, 에이전트, 클라이언트가 한꺼번에 섞여서 이야기되기 때문입니다.

필자는 이 셋을 아래처럼 이해하면 편하다고 생각합니다.

  • 모델: 생각하는 두뇌입니다. 예를 들어 GPT-5.3 Codex 같은 것이 여기에 해당합니다.
  • 에이전트: 두뇌를 실제로 일하게 만드는 작업 방식입니다. 파일을 읽고, 코드를 고치고, 명령을 실행하고, 중간 상태를 관리하는 흐름까지 포함합니다.
  • 클라이언트: 사람이 에이전트를 사용하는 창구입니다. 터미널, 앱, 웹, IDE 확장 같은 것이 여기에 해당합니다.

쉽게 비유하면 이렇습니다.

  • 모델은 엔진
  • 에이전트는 운전 방식과 변속기
  • 클라이언트는 운전석

겉으로는 같은 차처럼 보여도, 엔진만 같고 운전 방식이 다르면 체감이 꽤 달라질 수 있습니다.

Codex 공식 문서가 말하는 핵심#

공식 문서를 보면, Codex IDE extension은 꽤 분명하게 설명되어 있습니다.

“The Codex IDE extension gives you access to Codex directly in VS Code, Cursor, Windsurf, and other VS Code-compatible editors. It uses the same agent as the Codex CLI and shares the same configuration.”

이 문장은 중요합니다. Cursor에 Codex 확장 설치는 단순히 Codex 모델만 IDE에 붙여 놓은 것이 아니라, CLI와 같은 Codex agent를 IDE 안에서 쓰는 쪽이라는 뜻이기 때문입니다.

반면 Codex App 관련 문서에는 이런 문구가 나옵니다.

“The Codex app and Codex CLI use the same underlying Codex agent and configuration but might rely on different versions of the agent at any time and some experimental features might land in the Codex CLI first.”

즉, App도 Codex를 제대로 쓰는 환경이 맞지만, CLI와 항상 완전히 동일한 버전 / 기능이라고 장담할 수는 없다는 의미입니다.

또 Codex SDK 문서와 저장소 README를 보면, SDK는 단순한 모델 API 래퍼가 아니라 이렇게 설명됩니다.

“The TypeScript SDK wraps the codex CLI from @openai/codex. It spawns the CLI and exchanges JSONL events over stdin/stdout.”

즉 SDK도 그냥 모델 호출이 아니라, 로컬 Codex CLI를 감싸서 프로그램에서 Codex agent를 제어하는 방식에 가깝습니다.

환경별로 보면 이렇게 나뉩니다#

이제 각각을 쉬운 말로 정리해 보겠습니다.

1. Codex CLI#

Codex CLI는 터미널에서 Codex를 직접 쓰는 방식입니다.

공식 문서 기준으로 CLI는 다음과 같은 특징이 있습니다.

  • 로컬 디렉토리에서 파일을 읽고 수정할 수 있습니다
  • 명령 실행을 할 수 있습니다
  • review, subagents, web search, cloud, MCP 같은 기능을 사용할 수 있습니다
  • codex exec를 이용해 비대화형 자동화도 할 수 있습니다

필자는 CLI를 Codex의 기준점으로 보는 편이 좋다고 생각합니다. 이유는 간단합니다. 가장 먼저 나오는 기능이 많고, 자동화와 저수준 제어가 가장 풍부하기 때문입니다.

예를 들어 아래 같은 기능들은 CLI 성격이 강합니다.

  • codex exec: 스크립트 / CI / 자동화용
  • codex mcp-server: Codex를 다른 도구가 호출할 수 있게 노출
  • codex app-server: rich client용 프로토콜 서버
  • codex completion: 셸 자동완성
  • codex features: feature flag 제어

즉 Codex를 가장 제대로 경험해 보고 싶다면, 가장 먼저 써볼 환경은 보통 CLI라고 볼 수 있습니다.

CLI가 좋은 상황#

  • 디버깅을 오래 붙잡고 있을 때
  • 테스트를 반복 실행하며 수정할 때
  • 터미널 기반 작업이 익숙할 때
  • CI / 자동화에 붙이고 싶을 때
  • “Codex가 본래 어떤 도구인지"부터 느껴보고 싶을 때

2. Codex App#

Codex App은 OpenAI가 따로 제공하는 데스크톱 앱입니다.

처음에는 “그냥 CLI를 감싼 GUI 아닌가?“라고 생각할 수 있는데, 공식 문서를 보면 생각보다 더 적극적인 제품입니다. 아래 기능이 명시되어 있습니다.

  • 여러 프로젝트를 병렬로 다루기
  • worktree 지원
  • 내장 Git 도구
  • diff pane
  • 내장 terminal
  • automations
  • IDE extension과 thread / context 동기화

즉, Claude 데스크탑 앱 안의 Code 탭처럼 메신저 앱 안에 들어간 부가 기능에 가깝다기보다, Codex 자체를 위한 전용 코딩 앱에 더 가깝습니다.

다만 공식 문서가 직접 말하듯, App은 CLI와 완전히 같은 속도로 진화하지 않을 수 있습니다.

“some experimental features might land in the Codex CLI first”

이 문장을 풀어 말하면, CLI에서 되는 게 App에서는 아직 안 될 수도 있다는 뜻입니다.

그래서 필자는 App을 이렇게 보는 편이 맞다고 생각합니다.

  • Codex를 제대로 쓰는 전용 GUI
  • 하지만 최신 기능의 기준점은 여전히 CLI일 가능성이 높음

App이 좋은 상황#

  • 여러 작업을 병렬로 굴리고 싶을 때
  • 작업을 worktree로 깔끔하게 분리하고 싶을 때
  • Git diff와 thread를 한 화면 안에서 보고 싶을 때
  • CLI보다는 GUI가 편할 때

App보다 CLI가 더 강한 영역#

  • 스크립트 자동화
  • CI 연동
  • JSONL 이벤트 스트림 처리
  • 셸 파이프와 조합하는 작업
  • 실험 기능을 가장 먼저 확인하는 용도

3. Codex Web#

Codex Web은 ChatGPT 안에서 Codex를 쓰는 흐름에 가깝습니다.

공식 문서는 chatgpt.com/codex에서 GitHub를 연결해 리포지토리 작업과 PR 생성까지 이어질 수 있다고 설명합니다. 또 Codex cloud를 사용해 백그라운드 병렬 작업을 돌릴 수 있다고도 말합니다.

이 환경은 내 로컬 편집기 안에서 바로 고치는 느낌보다는, 클라우드에서 작업을 위임하고 결과를 받는 느낌이 강합니다.

Web이 좋은 상황#

  • GitHub와 연결된 작업을 길게 돌리고 싶을 때
  • 로컬 머신을 점유하지 않고 백그라운드 작업을 돌리고 싶을 때
  • 이슈 / PR 흐름과 자연스럽게 연결하고 싶을 때

4. Cursor + Codex IDE Extension#

이 조합은 초반에 가장 많이 헷갈리는 부분입니다.

질문은 대개 이렇게 바뀝니다.

Cursor에 Codex 확장을 설치하면, 그건 Codex를 제대로 쓰는 것인가?

필자의 답은 대체로 예입니다.

왜냐하면 공식 문서가 이미 CLI와 같은 agent를 쓰고 같은 설정을 공유한다고 말하기 때문입니다.

즉 이 경우는:

  • Codex 모델만 가져오는 것이 아니라
  • Codex agent를 IDE 안에서 사용하는 것

에 더 가깝습니다.

또 IDE extension에는 아래 기능도 공식적으로 나와 있습니다.

  • Agent / Chat / Agent (Full Access) 모드
  • reasoning effort 조절
  • cloud delegation
  • web search
  • 이미지 입력
  • /review
  • auto context

그래서 Codex를 IDE 안에서 제대로 쓰고 싶다면 꽤 좋은 선택지입니다.

다만 여전히 CLI와 완전히 동일하다고 생각하면 안 됩니다. 예를 들어 아래 같은 것은 CLI 색채가 더 강합니다.

  • codex exec
  • codex mcp-server
  • codex app-server
  • codex completion
  • codex features

즉, 에이전트의 핵심 역량은 상당 부분 공유하지만, 저수준 제어와 자동화 면에서는 CLI가 더 넓다고 이해하면 됩니다.

이런 분께 추천#

  • Cursor를 메인 IDE로 계속 쓰고 싶은 분
  • Codex를 별도 앱보다 IDE 안에서 쓰고 싶은 분
  • 실제 Codex agent를 쓰고 싶지만, 터미널보다 에디터가 편한 분

5. Cursor native agent + Codex 모델#

이건 위의 Codex IDE Extension과 완전히 다른 이야기입니다.

여기서 말하는 것은 보통 Cursor 채팅 패널에서 모델을 Codex 계열로 선택하는 것입니다.

즉 구조는 이렇습니다.

  • 운전석: Cursor
  • 에이전트 구현: Cursor
  • 모델: Codex

이 경우는 Codex 모델은 쓰지만, OpenAI Codex의 agent / harness를 그대로 쓰는 것은 아닙니다.

Cursor의 공식 블로그도 이 점을 보여줍니다. Cursor는 Codex 모델을 자사 환경에서 더 잘 작동하게 하려고, 도구 정의와 프롬프트 하네스를 따로 튜닝했다고 설명합니다.

이 말은 곧, 같은 모델을 써도 아래 요소가 달라질 수 있다는 뜻입니다.

  • 어떤 도구를 주는지
  • 어떤 순서로 컨텍스트를 넣는지
  • 중간 사용자 업데이트를 어떻게 보여주는지
  • 승인 정책을 어떻게 잡는지
  • lint 읽기와 수정 루프를 어떻게 설계했는지

그래서 Codex를 제대로 경험하려면 Codex 모델만이 아니라 Codex 에이전트도 써야 하지 않나?라는 질문에는, 필자는 그렇다고 답하고 싶습니다.

이 환경은 이런 목적에 더 가깝습니다.

  • Cursor라는 훌륭한 IDE agent 환경은 유지하고
  • 모델만 Codex로 바꿔서 성능을 체험해 보는 것

이런 분께 추천#

  • Cursor를 계속 메인으로 쓰고 싶고
  • Codex의 모델 성향만 먼저 맛보고 싶은 분
  • 별도 도구를 더 늘리고 싶지 않은 분

6. Claude Code + codex-plugin-cc#

이 조합은 Codex를 메인으로 쓴다기보다, Claude Code 안에서 필요할 때 Codex를 불러 쓴다는 표현이 더 맞습니다.

공식 README를 보면 이 플러그인은 아래 명령을 제공합니다.

  • /codex:review
  • /codex:adversarial-review
  • /codex:rescue
  • /codex:status
  • /codex:result
  • /codex:cancel

여기서 핵심은 기본 흐름입니다.

  • 평소에는 Claude Code를 사용합니다
  • 리뷰가 필요하면 Codex review를 돌립니다
  • 막히는 문제가 생기면 Codex rescue로 위임합니다

즉, 기본적으로는 명시적으로 부를 때 개입하는 구조에 가깝습니다.

공식 문서 기준으로 자동 개입과 가장 가까운 기능은 review gate입니다.

/codex:setup --enable-review-gate

이 기능을 켜면 Stop hook을 통해 Claude의 응답을 기반으로 Codex 리뷰를 돌려서, 문제가 있으면 흐름을 막을 수 있습니다.

다만 이것은 Codex가 언제나 옆에서 알아서 같이 일하는 상시 동료 모드라기보다, 자동 리뷰 게이트 쪽으로 이해하는 것이 더 정확합니다.

이런 분께 추천#

  • Claude Code를 메인으로 유지하고 싶은 분
  • 다른 모델 관점의 리뷰를 붙이고 싶은 분
  • shipping 전에 한 번 더 의심해 보는 리뷰어가 필요한 분

7. Codex SDK#

SDK는 비개발자 분들이 가장 오해하기 쉬운 지점입니다.

처음 들으면 “그냥 OpenAI API 부르는 라이브러리 아닌가?“라고 생각하기 쉽습니다. 그런데 공식 문서와 저장소를 보면 성격이 더 진합니다.

SDK가 다루는 항목에는 이런 것들이 있습니다.

  • thread
  • run()
  • runStreamed()
  • command_execution
  • file_change
  • mcp_tool_call
  • web_search
  • todo_list

즉 SDK는 그냥 텍스트 생성 API가 아니라, Codex agent 세션을 코드로 제어하는 인터페이스에 가깝습니다.

그런데도 왜 “대화형 사용성과는 다르다"고 말하느냐 하면, SDK는 기본적으로 제품이 아니라 재료이기 때문입니다.

CLI / App / IDE extension은 이미 완성된 사용자 경험을 제공합니다.

  • 대화창
  • 승인 UI
  • diff 보기
  • thread 관리
  • Git 연동
  • worktree 흐름
  • slash command

반면 SDK는 이런 완성된 사용자 경험을 그대로 주지 않습니다. 대신:

  • 앱 안에 Codex를 내장하거나
  • CI에서 Codex를 돌리거나
  • 사내 툴에 붙이거나
  • 별도 오케스트레이션 시스템을 만들 때

직접 제어할 수 있게 해 줍니다.

즉 능력이 약한 것이 아니라, 쓰는 목적이 다른 것입니다.

이런 분께 추천#

  • Codex를 제품 / 내부 도구 / 자동화에 넣고 싶은 팀
  • CI나 배치 작업에 붙이고 싶은 분
  • 멀티 에이전트 오케스트레이션을 코드로 구성하고 싶은 분

그래서 무엇을 써야 할까#

여기까지 읽으면 이런 생각이 들 수 있습니다.

그래서 나는 뭘 먼저 써야 하는가?

필자는 아래처럼 정리하는 것이 가장 실용적이라고 생각합니다.

1. Codex를 가장 제대로 이해해 보고 싶다면#

Codex CLI부터 써보는 것이 좋습니다.

이유는 간단합니다.

  • 공식 기능의 기준점에 가깝고
  • 자동화 / 저수준 제어까지 가장 넓게 열려 있으며
  • 나중에 App / Extension / SDK를 이해할 때도 기준이 됩니다

2. Cursor를 메인 IDE로 쓰고 있다면#

두 갈래로 나눠 생각하면 됩니다.

  • Codex 자체를 IDE 안에서 쓰고 싶다 → Codex IDE Extension
  • Cursor 경험은 그대로 두고 모델만 Codex로 바꾸고 싶다 → Cursor native agent + Codex 모델

이 둘은 비슷해 보여도 꽤 다릅니다.

3. Claude Code를 메인으로 쓰고 있다면#

codex-plugin-cc는 꽤 좋은 보조 장치가 될 수 있습니다.

다만 이 경우의 Codex는 주력 엔진이라기보다:

  • 리뷰어
  • 반대편 시각의 검사자
  • 구원투수

에 더 가깝습니다.

4. 병렬 작업과 GUI가 중요하다면#

Codex App이 좋은 선택입니다.

특히 여러 스레드 / worktree / Git diff를 한 화면에서 다루고 싶다면 App의 장점이 큽니다. 다만 최신 기능 기준점은 CLI라는 점은 염두에 두는 편이 좋겠습니다.

필자의 현재 결론#

필자가 지금 시점에 주변 사람에게 가장 무난하게 추천한다면, 아래 순서가 될 것 같습니다.

  1. Codex CLI로 본체 감각부터 익힙니다.
  2. 메인 IDE가 Cursor라면 Codex IDE Extension을 붙여 봅니다.
  3. Cursor에서 그냥 모델만 바꾸는 방식도 비교해 봅니다.
  4. Claude Code를 많이 쓴다면 codex-plugin-cc를 리뷰어로 붙여 봅니다.
  5. 병렬 작업이 많아지면 Codex App까지 확장합니다.

즉, 처음부터 모든 표면을 한꺼번에 쓰기보다, 기준점 하나(CLI)를 먼저 잡고 나머지를 역할별로 붙여 보는 방식이 덜 헷갈립니다.

짧은 요약#

  • Codex CLI는 기준점입니다.
  • Codex App은 전용 GUI이지만, CLI보다 늦게 들어오는 기능이 있을 수 있습니다.
  • Codex IDE Extension은 실제 Codex agent를 IDE 안에서 쓰는 쪽에 가깝습니다.
  • Cursor native + Codex 모델은 Codex 모델을 쓰는 것이지, Codex agent 자체를 쓰는 것은 아닙니다.
  • Claude Code + codex-plugin-cc는 필요할 때 Codex를 호출하는 보조 구조에 가깝습니다.
  • Codex SDK는 단순 모델 API가 아니라, Codex agent를 코드로 제어하는 인터페이스에 가깝습니다.

참고 자료#