ChatGPT Codex 사용법 — 터미널부터 클라우드까지 완전 정리

요즘 개발자 커뮤니티에서 Codex 얘기가 부쩍 많아졌다. OpenAI가 Codex를 단순한 코딩 보조 도구가 아니라 본격적인 "에이전트"로 밀고 있어서다. ChatGPT 안에서, 터미널에서, IDE에서, 심지어 클라우드에서 비동기로 돌아가는 작업까지. 처음 접하면 "이게 다 뭐지" 싶을 정도로 형태가 다양하다.

나도 처음엔 헷갈렸는데, 한번 정리하고 나니 명확해졌다. 오늘은 ChatGPT Codex가 뭔지, 어떻게 쓰는지를 처음부터 정리해본다.

---

Codex가 뭔데

먼저 헷갈리지 말아야 할 게 있다. 2021~2023년에 있던 옛날 "Codex API"와 지금의 Codex는 완전히 다른 제품이다. 옛날 Codex는 2023년에 없어졌고, 지금 말하는 Codex는 2025년에 새로 나온 코딩 에이전트다.

핵심 특징:

• 프로젝트 전체 코드베이스를 읽고 이해한다
• 여러 파일을 동시에 수정한다
• 터미널 명령어(빌드, 테스트, Git 등)를 직접 실행한다
• 샌드박스 안에서 안전하게 동작한다
• 클라우드에서 비동기 작업도 가능하다

Copilot 같은 자동완성 도구와는 결이 다르다. Copilot이 "다음 줄"을 맞춘다면, Codex는 "이 기능을 구현해줘"를 통째로 처리한다.

---

Codex를 쓰는 4가지 방법

Codex는 여러 형태로 제공된다. 본인 작업 스타일에 맞는 걸 고르면 된다.

1. Codex CLI       → 터미널에서 사용
2. IDE 확장        → VSCode, JetBrains 등에 통합
3. ChatGPT 웹/앱   → ChatGPT 안에서 사용
4. Codex Cloud     → 클라우드에서 비동기 작업

이 네 가지가 같은 계정, 같은 설정을 공유한다. 터미널에서 시작한 작업을 클라우드로 넘기는 것도 가능하다.

---

준비물: ChatGPT 유료 구독

Codex는 무료로 못 쓴다. ChatGPT 유료 구독이 필요하다.

ChatGPT Plus       — 기본 사용 가능
ChatGPT Pro        — 더 많은 사용량
Business / Edu     — 팀/교육용
Enterprise         — 기업용

여기서 주의할 점. ChatGPT 구독과 OpenAI API 크레딧은 별개다. Codex는 ChatGPT 구독으로 쓰는 게 기본이다. ChatGPT Plus($20/월)만 있으면 시작할 수 있다.

---

방법 1: Codex CLI 설치하고 쓰기

가장 기본이 되는 형태다. 터미널에서 동작한다.

설치

# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# 또는 npm / Homebrew
npm install -g @openai/codex
brew install openai-codex

# 설치 확인
codex --version

첫 실행

# 프로젝트 폴더로 이동
cd ~/my-project

# Codex 실행
codex

# 처음 실행하면 로그인 프롬프트가 뜬다
# ChatGPT 계정으로 로그인

기본 사용

실행하면 채팅 입력창이 뜬다. 자연어로 요청하면 된다.

"src/api/users.ts에 비밀번호 변경 기능을 추가해줘"

"이 프로젝트의 전체 구조를 설명해줘"

"npm test 돌려서 실패하는 테스트를 고쳐줘"

---

승인 모드 — Codex의 핵심 개념

Codex는 세 가지 모드로 동작한다. 얼마나 자유를 줄지 내가 정한다.

Chat 모드

- 파일을 읽지도, 수정하지도, 명령어를 실행하지도 않음
- 그냥 대화만

설계 논의, 아키텍처 상담할 때 쓴다.

Agent 모드 (기본값)

- 파일 읽기/수정 가능
- 작업 디렉토리 안에서 명령어 실행 가능
- 작업 디렉토리 밖이나 네트워크 접근은 승인 필요

대부분의 작업에서 이 모드를 쓴다. 위험한 작업은 사람 승인을 받으니까 안전하다.

Agent (Full Access) 모드

- 파일/명령어/네트워크 전부 자유
- 승인 없이 다 함

완전 자율 모드. 편하지만 신뢰할 수 있는 환경에서만 쓰자.

---

방법 2: IDE 확장으로 쓰기

VSCode나 JetBrains IDE에 Codex를 통합할 수 있다.

VSCode: 마켓플레이스에서 "Codex" 검색 → 공식 확장 설치
JetBrains: AI Assistant 플러그인 또는 OpenAI 공식 IDE 통합

IDE에서 쓰면 변경사항을 diff로 보고, 선택한 코드를 자동으로 Codex에게 공유하고, 에러까지 실시간으로 넘겨준다. 코드 작업이 주라면 IDE 통합이 편하다.

---

방법 3: ChatGPT 웹/앱에서 쓰기

ChatGPT 안에서도 Codex를 쓸 수 있다. GitHub 저장소를 연결하면 ChatGPT가 코드를 읽고 작업한다. 가벼운 작업이나, 이동 중에 모바일로 코드를 확인할 때 유용하다.

---

방법 4: Codex Cloud — 비동기 클라우드 작업

이게 Codex의 킬러 피처 중 하나다. 시간 오래 걸리는 작업을 클라우드에 던져놓을 수 있다.

1. 작업 요청 ("이 프로젝트 테스트 커버리지를 80%까지 올려줘")
2. "Run in the cloud" 선택
3. 환경 설정
4. Codex Cloud에서 작업 실행
5. 나는 다른 일을 함
6. 완료되면 결과 리뷰 + 적용

내 컴퓨터가 몇 시간 끙끙댈 작업을 클라우드가 알아서 처리한다.

---

AGENTS.md — 프로젝트 규칙 알려주기

프로젝트 루트에 AGENTS.md 파일을 두면 Codex가 항상 이 파일을 읽고 작업한다.

# AGENTS.md

## 프로젝트
Next.js 14 + TypeScript + Prisma 기반 서비스

## 명령어
- 개발: pnpm dev
- 테스트: pnpm test
- 빌드: pnpm build

## 코딩 규칙
- 함수형 컴포넌트만 사용
- Tailwind CSS만 사용
- 작업 완료 전 반드시 pnpm test 통과 확인

이렇게 해두면 "pnpm 써", "테스트 돌려" 같은 말을 매번 반복하지 않아도 된다.

---

실전 활용 예시

기능 추가

"사용자 프로필 수정 API를 추가해줘. 이름, 이메일, 프로필 사진 변경을 지원하고,
이메일 변경 시에는 인증 메일을 보내는 흐름으로."

버그 수정

"앱 실행하면 TypeError가 나는데, @src/components/Cart.tsx 여기서 발생하는 것 같아.
원인 찾아서 고쳐줘."

리팩토링

"src/utils/ 폴더의 모든 함수에 타입스크립트 타입을 추가해줘."

코드 이해

"이 프로젝트에서 결제 처리가 어떻게 흘러가는지 설명해줘."

---

슬래시 명령어

채팅창에서 /를 입력하면 유용한 명령어를 쓸 수 있다.

/permissions   — 승인 모드 변경
/model         — 모델 변경
/clear         — 대화 초기화
/compact       — 대화 기록 압축 (컨텍스트 절약)

---

자주 겪는 문제

"codex: command not found"

which codex  # 안 나오면 PATH 문제
source ~/.zshrc  # 또는 ~/.bashrc

환경 진단

codex doctor  # 환경, Git, 인증 상태 전부 체크

뭔가 안 되는데 원인을 모르겠으면 이걸 먼저 돌려보자.

---

마무리

ChatGPT Codex는 단순 코딩 도구가 아니라, 형태가 다양한 코딩 에이전트다. 정리하면:

• ChatGPT 유료 구독(Plus 이상)이 필요하다
• CLI, IDE 확장, ChatGPT 웹, Codex Cloud 네 가지 방법으로 쓸 수 있다
• 세 가지 승인 모드(Chat/Agent/Full Access)를 상황에 맞게 쓰자
• 기본은 Agent 모드. 위험한 작업은 승인을 거친다
• AGENTS.md로 프로젝트 규칙을 미리 알려두자
• 오래 걸리는 작업은 Codex Cloud로 비동기 처리하자