Codex 전체 그림 한눈에 보기

먼저 지도를 펼쳐 봅시다

Codex를 처음 만나면 가장 먼저 헷갈리는 지점이 있습니다. "Codex가 좋다는데, 도대체 어디에서 켜야 하지?"라는 질문입니다. 어떤 사람은 ChatGPT 웹에서 Codex를 열라고 하고, 어떤 사람은 데스크톱 앱을 설치하라고 합니다. 또 어떤 사람은 터미널에서 codex를 실행하라고 하고, VS Code 확장을 쓰면 된다고 말합니다.

처음 듣는 입장에서는 마치 같은 목적지로 가는 문이 다섯 개나 있는 것처럼 느껴집니다. 더 헷갈리는 점은, 이 문들이 서로 완전히 다른 제품도 아니라는 사실입니다. 모두 Codex라는 하나의 코딩 에이전트를 사용하는 입구입니다. OpenAI 문서에서도 Codex를 코드 읽기, 수정, 실행을 도와주는 코딩 에이전트로 설명하며, 클라우드와 로컬 환경에서 사용할 수 있다고 안내합니다.¹

여기서 중요한 질문은 "어느 것이 제일 강력한가?"가 아닙니다. 초보자에게 더 중요한 질문은 이것입니다.

"내가 지금 하려는 작업은 어디에서 하는 게 가장 자연스러운가?"

Codex는 하나의 에이전트지만, 실행되는 위치에 따라 성격이 달라집니다. 내 컴퓨터의 프로젝트 폴더를 직접 열고 함께 작업하는 방식이 있고, GitHub 저장소를 연결해 클라우드에 일을 맡기는 방식이 있습니다. 이 차이를 모르고 시작하면, 간단한 수정 하나를 하려고 너무 무거운 도구를 열거나, 반대로 오래 걸리는 작업을 로컬 화면 앞에서 계속 기다리는 일이 생깁니다.

이 장의 목표는 세부 사용법을 외우는 것이 아닙니다. 앞으로 나올 챕터들을 읽기 전에, Codex 세계의 지도를 머릿속에 그려 두는 것입니다.

Codex의 두 세계: 로컬 표면과 클라우드 표면

Codex를 크게 나누면 두 세계가 있습니다. 하나는 로컬 표면이고, 다른 하나는 클라우드 표면입니다.

로컬 표면은 Codex가 내 컴퓨터 안의 프로젝트와 직접 협업하는 방식입니다. 여기에는 Codex App, Codex CLI, IDE 확장이 포함됩니다. 로컬이라는 말은 "내 컴퓨터에서 돌아간다"는 뜻에 가깝습니다. Codex가 내 저장소 폴더를 읽고, 파일을 수정하고, 터미널 명령을 실행하고, 테스트 결과를 확인합니다. 물론 실제 AI 모델 호출이나 계정 인증은 온라인 서비스와 연결될 수 있지만, 작업의 중심은 내 컴퓨터의 프로젝트입니다.

클라우드 표면은 Codex가 OpenAI 쪽의 원격 실행 환경에서 작업하는 방식입니다. 대표적으로 chatgpt.com/codex에서 사용하는 Codex 웹 환경과 Codex Cloud가 있습니다. 이 방식에서는 보통 GitHub 저장소를 연결하고, Codex가 클라우드 환경에서 코드를 가져와 작업한 뒤, 변경 사항을 정리해 보여 주거나 PR까지 이어갈 수 있습니다. OpenAI의 Codex Cloud 문서도 Codex가 자체 클라우드 환경에서 백그라운드 작업을 수행하고, 여러 작업을 병렬로 진행할 수 있다고 설명합니다.²

둘의 차이를 아주 쉽게 말하면 이렇습니다.

앱을 만드는 일은 요리와 비슷합니다. 로컬 표면은 내가 주방에 서 있고, Codex가 옆에서 재료를 손질하고 불 조절을 도와주는 모습에 가깝습니다. 클라우드 표면은 요리사에게 레시피와 냉장고 목록을 넘겨주고, 완성된 접시를 나중에 받아 검수하는 모습에 가깝습니다. 둘 다 유용하지만, 손맛이 필요한 순간과 맡겨 두는 게 편한 순간은 다릅니다.

다섯 개의 입구를 한눈에 보기

초보자가 기억해야 할 Codex의 주요 입구는 다섯 가지입니다.

여기서 "표면"이라는 단어가 조금 낯설 수 있습니다. 표면은 사용자가 Codex를 만나는 화면 또는 실행 위치라고 생각하면 됩니다. 같은 사람에게 전화, 이메일, 화상회의로 연락할 수 있듯이, 같은 Codex도 앱, 터미널, 편집기, 웹에서 만날 수 있습니다. 연락 방식이 달라지면 대화의 리듬도 달라지는 것처럼, Codex도 어디에서 쓰느냐에 따라 강점이 달라집니다.

Codex App: 초보자에게 가장 좋은 감독형 작업 공간

초보자라면 Codex App을 가장 먼저 이해하는 것이 좋습니다. 이유는 단순합니다. Codex가 무엇을 읽고, 무엇을 바꾸고, 어떤 명령을 실행하고, 결과가 어떻게 달라졌는지를 비교적 한눈에 보기 쉽기 때문입니다. OpenAI의 빠른 시작 문서도 클라우드에서는 chatgpt.com/codex를, 로컬 프로젝트 작업에는 Codex App을 사용하라고 안내합니다.³

Codex App은 전통적인 코드 편집기라기보다 감독형 작업 공간에 가깝습니다. 여기서 감독형이라는 말은, 내가 직접 모든 코드를 한 줄씩 타이핑하기보다 Codex에게 일을 맡기고 진행 상황을 확인한다는 뜻입니다. 마치 작은 개발팀을 이끄는 팀장처럼, 여러 작업을 열어 두고 "이 작업은 어디까지 됐지?", "어떤 파일이 바뀌었지?", "테스트는 통과했나?"를 살펴보는 방식입니다.

Codex App이 특히 좋은 순간은 프로젝트의 전체 흐름을 익힐 때입니다. 예를 들어 처음 내려받은 할 일 관리 앱 프로젝트가 있다고 해 봅시다. 초보자는 파일 이름만 봐도 당황할 수 있습니다. src, components, api, package.json, tsconfig.json 같은 이름이 줄줄이 보이면, 어디부터 열어야 할지 막막합니다.

이때 Codex App에서 다음처럼 요청할 수 있습니다.

이 프로젝트를 처음 보는 초보자에게 설명해줘.
아직 파일은 수정하지 말고, 주요 폴더와 실행 방법, 먼저 읽으면 좋은 파일을 알려줘.

좋은 첫 작업은 "만들어줘"가 아니라 "읽고 설명해줘"입니다. Codex App은 이런 탐색 작업에 잘 맞습니다. 파일을 읽고, 구조를 정리하고, 필요한 경우 실행 명령까지 안내해 줍니다.

또 하나의 강점은 여러 작업을 나누어 맡기는 흐름입니다. 예를 들어 날씨 대시보드 앱을 만들고 있다면, 한 작업에서는 "날씨 API 연결 구조 조사", 다른 작업에서는 "UI 카드 컴포넌트 개선", 또 다른 작업에서는 "README 실행 방법 정리"를 맡길 수 있습니다. 앱 화면에서 각 작업의 진행 상태와 변경 내용을 확인하면, 터미널 창을 여러 개 띄워 놓고 정신없이 오가는 것보다 훨씬 덜 혼란스럽습니다.

다만 Codex App이 모든 것을 대체하지는 않습니다. 코드 한 줄을 직접 고치고, 함수 내부를 섬세하게 만지고, 자동완성이나 디버거를 쓰는 작업은 여전히 IDE가 더 편합니다. 그래서 Codex App은 "코드 편집기 대신 쓰는 도구"라기보다 "Codex가 하는 일을 관리하는 관제실"로 이해하는 편이 좋습니다.

Codex CLI: 터미널을 좋아한다면 가장 빠른 손

CLI는 Command Line Interface의 줄임말입니다. 쉽게 말해 마우스로 버튼을 누르는 앱이 아니라, 터미널에 글자로 명령을 입력해서 사용하는 방식입니다. macOS의 Terminal, Windows의 PowerShell, Linux의 셸 같은 화면을 떠올리면 됩니다.

Codex CLI는 터미널 안에서 Codex와 협업하는 도구입니다. OpenAI의 CLI 문서는 Codex CLI를 로컬에서 실행하는 코딩 에이전트로 안내하며, 코드 읽기와 수정, 명령 실행, 자동화 흐름에 사용할 수 있도록 설명합니다.⁴

CLI의 가장 큰 장점은 속도와 제어감입니다. 터미널에 익숙한 사람은 프로젝트 폴더로 이동한 다음 바로 codex를 실행하고, 지금 필요한 작업을 짧게 요청할 수 있습니다.

codex "테스트를 실행하고 실패 원인을 요약해줘. 아직 파일은 수정하지 마."

또는 다음처럼 작은 수정을 맡길 수 있습니다.

codex "README에 로컬 실행 방법을 추가해줘. package.json을 확인해서 정확한 명령어를 써줘."

CLI는 기존 개발 도구와 붙이기 좋습니다. npm test, pnpm build, pytest, git diff 같은 명령을 평소에 쓰고 있다면, Codex가 그 흐름 안으로 들어옵니다. 특히 반복 작업에서 강합니다. 테스트를 돌리고, 실패 로그를 읽고, 작은 수정을 하고, 다시 테스트를 돌리는 루프를 빠르게 반복할 수 있습니다.

하지만 초보자에게 CLI는 약간 무섭게 느껴질 수 있습니다. 검은 화면에 글자를 입력해야 하고, 명령 하나가 파일을 바꾸거나 패키지를 설치할 수 있기 때문입니다. 그래서 이 책에서는 CLI를 곧바로 첫 출발점으로 삼기보다, Codex App에서 전체 흐름을 익힌 뒤 CLI로 넘어가는 순서를 추천합니다.

CLI를 한 문장으로 정리하면 이렇습니다.

터미널에 익숙한 사람에게 Codex CLI는 가장 빠르고 세밀한 로컬 작업 도구입니다.

IDE 확장: 코드를 보면서 바로 옆에서 대화하기

IDE는 Integrated Development Environment의 줄임말로, 코드를 작성하고 실행하고 디버깅하는 편집기 환경을 말합니다. 대표적으로 VS Code, Cursor, Windsurf, JetBrains 계열 IDE가 있습니다.

Codex IDE 확장은 이런 편집기 안에서 Codex를 사용하는 방식입니다. OpenAI의 IDE 확장 문서는 VS Code 계열 편집기 등에서 Codex를 열고, 현재 작업 중인 코드 맥락을 바탕으로 협업할 수 있다고 안내합니다.⁵

IDE 확장의 장점은 맥락이 자연스럽다는 점입니다. 내가 지금 LoginForm.tsx 파일을 열어 두고 있고, 특정 함수나 오류 줄을 선택해 둔 상태라면, Codex에게 길게 설명하지 않아도 됩니다.

선택한 함수에서 로그인 실패 처리가 왜 두 번 실행되는지 설명해줘.
가능하면 최소 수정으로 고쳐줘.

이런 작업은 웹보다 IDE가 훨씬 자연스럽습니다. 왜냐하면 내가 보고 있는 코드, 선택한 영역, 오류 표시, 파일 트리 자체가 이미 대화의 배경이 되기 때문입니다.

IDE 확장은 특히 다음 흐름에 잘 맞습니다.

초보자에게 IDE 확장은 "Codex와 함께 코드를 읽는 돋보기"라고 볼 수 있습니다. 전체 프로젝트 관리는 Codex App이 편하고, 코드 한가운데 들어가서 살펴보는 일은 IDE 확장이 편합니다.

예를 들어 할 일 관리 앱에서 체크박스를 눌러도 완료 상태가 저장되지 않는 버그가 있다고 해 봅시다. Codex App에서는 "상태 저장 흐름을 조사해줘"라고 큰 단위로 맡길 수 있습니다. 반면 IDE에서는 TodoItem.tsx나 useTodos.ts를 열어 놓고 "이 부분에서 localStorage 저장이 빠진 것 같은데 확인해줘"라고 구체적으로 요청하기 좋습니다.

Codex Cloud와 chatgpt.com/codex: 맡겨 두고 나중에 검토하기

이제 클라우드 쪽을 봅시다. Codex Cloud와 chatgpt.com/codex는 작업을 내 컴퓨터가 아니라 원격 환경에 맡기는 흐름입니다. OpenAI는 Codex Cloud가 자체 클라우드 환경에서 백그라운드로 작업할 수 있고, 병렬 작업도 가능하다고 설명합니다.²

이 방식이 빛나는 순간은 "지금 당장 화면 앞에서 기다릴 필요가 없는 작업"입니다. 예를 들어 다음과 같은 요청을 생각해 볼 수 있습니다.

이 GitHub 저장소를 조사해서 로그인 관련 테스트가 부족한 부분을 찾아줘.
필요한 테스트를 추가하고, 변경 사항을 PR로 만들 수 있게 정리해줘.

로컬에서 이 작업을 하려면 저장소를 열고, 테스트를 돌리고, 파일을 찾고, 수정 결과를 확인해야 합니다. 물론 Codex App이나 CLI로도 가능합니다. 하지만 작업이 오래 걸리거나, 여러 저장소를 동시에 봐야 하거나, 노트북을 닫아도 계속 진행되기를 원한다면 클라우드가 더 편합니다.

웹 환경의 장점은 설치 부담이 적다는 점입니다. ChatGPT에 로그인하고 Codex로 들어가 작업을 시작할 수 있습니다. OpenAI 도움말에 따르면 Codex는 ChatGPT Plus, Pro, Business, Enterprise/Edu 플랜에 포함되며, 플랜과 시점에 따라 Free나 Go에서도 제한적으로 제공될 수 있습니다.⁶ 다만 실제 사용 가능 여부와 한도는 계정, 플랜, 조직 설정에 따라 달라질 수 있으므로, 책을 읽는 시점에는 화면에 표시되는 안내를 우선 확인해야 합니다.

Codex Cloud는 GitHub와 함께 쓸 때 특히 자연스럽습니다. 저장소를 연결하고, 작업을 맡기고, Codex가 만든 변경 사항을 diff나 PR 형태로 검토하는 식입니다. PR은 Pull Request의 줄임말로, "이 변경 사항을 프로젝트에 합쳐도 될지 검토해 주세요"라고 제출하는 GitHub의 절차입니다. 초보자에게는 다소 낯설지만, 협업 개발에서는 매우 중요한 흐름입니다.

클라우드 방식에도 단점은 있습니다. 로컬에서 바로 버튼을 눌러 앱을 실행하고, 브라우저에서 화면을 보며 즉시 고치는 감각은 약합니다. "지금 이 로그를 보고 바로 한 줄 바꿔서 다시 실행"하는 루프는 CLI나 IDE가 더 빠릅니다. 클라우드는 즉석 조리대가 아니라, 주문서를 넘기고 완성품을 검수하는 주방에 가깝습니다.

ChatGPT 웹과 Codex 웹은 어떻게 다른가

많은 초보자가 여기서 한 번 더 헷갈립니다. ChatGPT 웹에서 질문하는 것과 chatgpt.com/codex에서 Codex를 쓰는 것은 무엇이 다를까요?

일반 ChatGPT 대화는 생각을 정리하거나 설명을 듣는 데 좋습니다. 예를 들어 "React에서 상태가 뭐야?", "로그인 기능을 만들 때 필요한 개념을 설명해줘", "이 에러 메시지가 무슨 뜻이야?"처럼 물어보는 데 적합합니다.

반면 Codex 웹은 작업을 실행하는 쪽에 더 가깝습니다. GitHub 저장소를 연결해 코드베이스를 읽고, 파일 변경을 만들고, 테스트를 실행하고, 변경 결과를 검토하는 흐름으로 이어질 수 있습니다. 즉 ChatGPT가 "상담실"이라면 Codex 웹은 "작업실"에 더 가깝습니다.

물론 경계가 항상 칼같이 나뉘지는 않습니다. Codex에서도 질문할 수 있고, ChatGPT에서도 코드 조언을 받을 수 있습니다. 하지만 초보자에게는 이렇게 구분하는 편이 안전합니다.

예를 들어 "할 일 앱에 어떤 기능을 넣으면 좋을까?"는 ChatGPT에 물어봐도 충분합니다. 하지만 "이 저장소에 필터 기능을 추가하고 테스트까지 만들어줘"는 Codex 쪽이 더 잘 맞습니다.

같은 작업도 도구에 따라 흐름이 달라집니다

이제 실제 상황을 하나 놓고 다섯 도구가 어떻게 달라지는지 살펴봅시다. 우리가 만들 앱은 간단한 할 일 관리 앱입니다. 버그는 이렇습니다.

"할 일을 완료 처리한 뒤 새로고침하면 완료 상태가 사라진다."

Codex App을 사용한다면 먼저 프로젝트를 열고 Codex에게 전체 상태 저장 흐름을 조사하게 할 수 있습니다.

이 할 일 앱에서 완료 상태가 어디에 저장되는지 조사해줘.
아직 수정하지 말고 관련 파일과 데이터 흐름을 설명해줘.

이 방식은 초보자에게 좋습니다. Codex가 프로젝트 구조를 읽고, 어떤 파일이 관련 있는지 알려 주며, 이후 수정까지 같은 흐름에서 이어갈 수 있기 때문입니다.

CLI를 사용한다면 조금 더 빠르고 명령 중심으로 접근합니다.

codex "완료 상태가 새로고침 후 사라지는 원인을 찾아줘. 관련 테스트가 있으면 실행하고, 수정 전 계획을 먼저 보여줘."

터미널에 익숙하다면 이 흐름이 가장 가볍습니다. 테스트 명령을 곧바로 돌리고, 실패 결과를 보고, 수정까지 빠르게 이어갈 수 있습니다.

IDE 확장을 사용한다면 관련 파일을 직접 열어 둔 상태에서 요청합니다.

현재 열려 있는 TodoList와 useTodos 파일을 보고,
완료 상태가 localStorage에 저장되지 않는 원인을 찾아줘.
최소 변경으로 고쳐줘.

이 방식은 내가 코드와 변경 사항을 직접 눈으로 확인하면서 진행하기 좋습니다. 초보자라도 "어떤 파일이 바뀌는지"를 바로 볼 수 있어 학습 효과가 큽니다.

Codex Cloud를 사용한다면 GitHub 저장소에 작업을 맡깁니다.

완료 상태가 새로고침 후 유지되지 않는 버그를 수정해줘.
가능하면 재현 테스트를 추가하고, 변경 내용을 PR로 정리해줘.

이 흐름은 내가 다른 일을 하는 동안 Codex가 원격 환경에서 작업하도록 맡길 때 좋습니다. 작업이 끝나면 diff와 PR 설명을 검토하면 됩니다.

ChatGPT 일반 웹 대화에서는 코드 변경보다 이해와 설계에 집중합니다.

할 일 앱에서 완료 상태가 새로고침 후 사라지는 일반적인 원인은 뭐야?
React 초보자 기준으로 상태와 localStorage 개념을 설명해줘.

이렇게 보면 같은 문제라도 도구마다 역할이 다릅니다. Codex를 잘 쓴다는 것은 무조건 하나의 도구만 고집하는 것이 아니라, 작업 성격에 맞는 입구를 고르는 일입니다.

초보자에게 추천하는 확장 순서

이 책에서는 초보자에게 다음 순서를 추천합니다.

물론 이미 VS Code나 Cursor에 익숙한 독자라면 IDE 확장부터 시작해도 괜찮습니다. 터미널을 매일 쓰는 개발자라면 CLI가 더 편할 수도 있습니다. 하지만 완전 초보자라면 Codex App에서 시작하는 편이 혼란이 적습니다.

이유는 세 가지입니다.

• 프로젝트 단위로 작업을 바라보기 쉽습니다.

• Codex가 바꾼 파일과 실행 결과를 한 흐름에서 확인하기 좋습니다.

• 나중에 CLI, IDE, Cloud로 확장할 때 기준점이 됩니다.

처음부터 모든 도구를 설치하고 비교하려고 하면 피곤해집니다. 첫 목표는 "완벽한 세팅"이 아니라 "Codex가 내 프로젝트를 읽고, 작은 수정을 하고, 결과를 확인하는 경험"입니다. 이 경험을 한 번 해 보면, 나머지 도구의 필요성은 자연스럽게 느껴집니다.

선택을 도와주는 실전 기준

도구 선택이 막힐 때는 아래 질문을 스스로에게 해 보면 됩니다.

실전에서는 하나만 쓰지 않습니다. 예를 들어 미니 SaaS 앱을 만든다고 해 봅시다. 처음에는 ChatGPT에서 기능 목록을 정리합니다. 그다음 Codex App에서 프로젝트를 만들고 전체 흐름을 관리합니다. 로그인 폼의 작은 오류는 IDE 확장에서 고칩니다. 테스트 반복 실행은 CLI로 처리합니다. 마지막으로 "결제 설정 문서 정리"나 "관리자 페이지 리팩터링"처럼 오래 걸리는 작업은 Cloud에 맡길 수 있습니다.

이것이 Codex를 도구 하나가 아니라 작업 흐름으로 이해해야 하는 이유입니다.

지금은 용어만 가볍게 알고 지나가도 됩니다

앞으로 자주 나올 용어 몇 개만 미리 잡고 가겠습니다. 지금 완벽히 이해할 필요는 없습니다. 이후 챕터에서 실습하면서 다시 만날 것입니다.

이 중에서 초보자가 가장 먼저 기억해야 할 단어는 diff입니다. Codex가 아무리 멋진 요약을 보여 줘도, 실제로 무엇이 바뀌었는지는 diff에 들어 있습니다. 앞으로 어떤 도구를 쓰든, Codex의 결과를 받을 때는 "요약을 읽고 끝"이 아니라 "diff를 확인하고 결정"하는 습관을 들여야 합니다.

이 장의 결론: Codex를 켜기 전에 작업의 위치를 정하자

Codex는 하나의 코딩 에이전트입니다. 하지만 그 에이전트를 어디에서 실행하느냐에 따라 경험은 크게 달라집니다. Codex App은 전체 흐름을 관리하는 관제실이고, CLI는 터미널 중심의 빠른 작업 도구입니다. IDE 확장은 코드를 보며 바로 옆에서 협업하는 방식이고, Codex Cloud와 웹 환경은 GitHub 저장소를 연결해 원격으로 일을 맡기는 방식입니다.

초보자는 먼저 Codex App에서 시작하는 것이 좋습니다. 프로젝트를 열고, Codex에게 읽게 하고, 작은 수정을 맡기고, 실행 결과와 diff를 확인하는 기본 루프를 익히기 쉽기 때문입니다. 그다음 반복 명령은 CLI로, 세밀한 코드 수정은 IDE 확장으로, 오래 걸리거나 맡겨 두는 작업은 Cloud와 웹으로 확장하면 됩니다.

한 줄로 정리하면 이렇습니다.

전체 흐름은 Codex App, 빠른 로컬 명령은 CLI, 편집 중 협업은 IDE 확장, 오래 걸리는 위임은 Codex Cloud와 웹입니다.

이제 지도를 봤으니 다음 장부터는 실제 길을 걸어갈 차례입니다. 먼저 개발 환경을 준비하고, Codex가 안전하게 프로젝트 안으로 들어올 수 있도록 기본 도구들을 갖춰 보겠습니다.

참고

¹Codex Cloud - OpenAI Developers

²Codex Cloud - OpenAI Developers

³Quickstart - Codex | OpenAI Developers

⁴Codex CLI - OpenAI Developers

⁵IDE extension - Codex | OpenAI Developers

⁶ChatGPT 플랜에서 Codex 사용하기 - OpenAI Help Center