OpenAI Codex 완전가이드 1편 — Codex 개요, OS별 설치, 첫 세션까지 따라하기

 

Codex는 2026년 OpenAI가 새로 론칭한 에이전틱 코딩 플랫폼입니다. Claude Code의 직접 경쟁자. ChatGPT Plus $20에 포함되어 있고, 터미널/데스크탑 앱/VS Code/클라우드 네 가지 형태로 씁니다.

1편에서는 "Codex가 뭔지 + OS별 설치 + 첫 실행 + 기본 사용법"까지 — 보면서 그대로 따라할 수 있게 씁니다.

---

핵심 요약

→ Codex = 2026년 OpenAI 에이전틱 코딩 툴 (옛날 Codex API와 완전히 다른 제품)
→ 4가지 형태: CLI(터미널) / App(데스크탑) / IDE 확장(VS Code) / Cloud(OpenAI 서버)
→ ChatGPT Plus $20/월에 포함 — 이미 구독 중이면 추가 비용 없음
→ 기반 모델: GPT-5.4, GPT-5.3-Codex, GPT-5.4 mini (세션 중 전환 가능)
→ 설치: macOS/Linux 원라이너 또는 npm install -g @openai/codex
→ Windows: PowerShell 네이티브 또는 WSL2 둘 다 지원
→ 실행하면 풀스크린 TUI(터미널 UI) 열림 — 자연어로 작업 지시
→ 기본 샌드박스: 네트워크 차단 + 작업 폴더만 쓰기 허용 → 안전한 자율 실행
→ 세션 로컬 저장 → codex resume 으로 이전 작업 이어서 가능
→ 오픈소스 (github.com/openai/codex) — 커스텀/자체 배포 가능

---

실전 1 — Codex 전체 그림 잡기

설치 전에 뭘 설치하는 건지 알고 시작해야 합니다.

Claude Code와 핵심 차이

Claude Code:
→ Anthropic Claude 모델 (Sonnet/Opus)
→ 내 컴퓨터에서 직접 실행
→ 정액제 ($20~$200/월)
→ 터미널 하나에서 순차 작업

Codex CLI:
→ OpenAI GPT 계열 모델
→ 내 컴퓨터 + 클라우드 선택 가능
→ ChatGPT Plus $20에 포함
→ Git Worktree로 병렬 에이전트 가능
→ 샌드박스 격리 기본값 (더 엄격한 보안)

Codex의 4가지 진입점

1. Codex CLI (이번 편 주제)
   → 터미널에서 실행
   → 가장 많이 쓰는 형태
   → 오픈소스

2. Codex App (4편에서 다룸)
   → macOS + Windows 전용 데스크탑 앱
   → 여러 에이전트 병렬 실행 UI

3. VS Code 확장
   → VS Code 안에서 Codex 채팅/에이전트

4. Codex Cloud (chatgpt.com/codex)
   → OpenAI 서버에서 실행
   → PC 꺼도 작업 계속
   → GitHub 연결 필요

---

실전 2 — 사전 요구사항 체크

ChatGPT 계정 또는 OpenAI API 키

둘 중 하나만 있으면 됩니다.

방법 A: ChatGPT Plus 구독 ($20/월)
→ chatgpt.com → 로그인 → Upgrade to Plus
→ Codex CLI, App, IDE 확장 모두 포함
→ 5시간 롤링 윈도우 내 사용 한도 있음

방법 B: OpenAI API 키 (pay-as-you-go)
→ platform.openai.com → API Keys → Create
→ 사용한 토큰만큼만 과금
→ 구독 불필요, 소량 사용자에게 유리

Node.js 22 이상 (npm 설치 방법 선택 시)

# 현재 버전 확인
node --version
# v22.x.x 이상이면 OK

# 22 미만이면 nvm으로 업그레이드
# macOS/Linux:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc   # 또는 ~/.zshrc
nvm install 22
nvm use 22
node --version    # v22.x.x 확인

---

실전 3 — OS별 설치

macOS / Linux — 원라이너 설치 (가장 빠름)

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

터미널에 복붙 후 엔터. 스크립트가 Node.js 확인 → Codex CLI 설치 → 초기 설정까지 자동으로 합니다.

설치 확인

codex --version
# codex/x.x.x 출력되면 성공

macOS / Linux — npm 수동 설치

# ⚠️ 중요: @openai/codex 입력 (앞에 @openai/ 필수)
# 'codex'만 입력하면 2012년산 무관한 패키지 설치됨
npm install -g @openai/codex

# 설치 확인
codex --version

npm 권한 오류 발생 시

# sudo 없이 전역 설치 설정
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 다시 설치
npm install -g @openai/codex

Windows — PowerShell 네이티브 (권장)

PowerShell을 관리자 권한으로 열고:

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

또는 npm으로:

# nvm-windows 먼저 설치: github.com/coreybutler/nvm-windows
nvm install 22
nvm use 22

# Codex 설치
npm install -g @openai/codex

# 확인
codex --version

Windows — WSL2 (Linux 환경 선호 시)

# WSL2 설치 (이미 있으면 스킵)
wsl --install

# WSL2 터미널 열기
wsl

# WSL 안에서 Linux 방식으로 설치
curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows 샌드박스 참고: 네이티브 Windows는 AppContainer 기반 샌드박스 사용. 공식 문서에서 "experimental" 표기 중. 안정적인 샌드박스 원하면 WSL2 권장.

---

실전 4 — 인증: API 키 또는 ChatGPT 로그인

설치 후 인증이 필요합니다. 두 방법 중 하나.

방법 A: ChatGPT 계정 로그인 (Plus/Pro 구독자)

codex login
# → 브라우저 자동 열림
# → chatgpt.com 로그인 화면
# → "Allow" 클릭
# → 터미널로 돌아오면 완료

방법 B: OpenAI API 키

API 키 발급

1. platform.openai.com 접속 → 로그인
2. 좌측 메뉴 → API Keys
3. "Create new secret key" 클릭
4. 이름 입력 (예: my-codex) → Create
5. sk-proj-... 형태의 키 복사
   ⚠️ 한 번만 표시됨 — 지금 반드시 복사

환경변수 설정

# 현재 세션에만 적용 (테스트용)
export OPENAI_API_KEY="sk-proj-여기에키입력"

# 영구 적용 (매번 입력 안 해도 되게)
# zsh 사용자 (macOS 기본):
echo 'export OPENAI_API_KEY="sk-proj-여기에키입력"' >> ~/.zshrc
source ~/.zshrc

# bash 사용자:
echo 'export OPENAI_API_KEY="sk-proj-여기에키입력"' >> ~/.bashrc
source ~/.bashrc

# 설정 확인
echo $OPENAI_API_KEY
# sk-proj-... 출력되면 성공

인증 확인

# 아무 프로젝트 폴더에서
cd ~/Desktop
mkdir test-codex && cd test-codex
codex

# TUI(풀스크린 터미널 UI)가 열리면 인증 성공
# Ctrl+C로 종료

---

실전 5 — TUI 화면 이해하기

codex 실행하면 이런 화면이 뜹니다:

┌─────────────────────────────────────────────────────────┐
│  Codex  ~/projects/my-app  [auto-edit]  gpt-5.4        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  (이전 대화 내용이 여기 표시됨)                          │
│                                                         │
│                                                         │
├─────────────────────────────────────────────────────────┤
│  > 여기에 입력                                          │
│                                                         │
│  /model /review /clear /exit  |  Ctrl+C: 중단          │
└─────────────────────────────────────────────────────────┘

각 영역 설명

상단 헤더:
Codex         → 툴 이름
~/projects/.. → 현재 작업 폴더 (여기 파일만 접근)
[auto-edit]   → 현재 승인 모드
gpt-5.4       → 현재 사용 중인 모델

중간 영역:
→ Codex 응답과 작업 내용 표시
→ 파일 수정 diff도 여기 표시됨

하단 입력창:
→ 여기서 작업 지시 입력
→ Enter로 전송

---

실전 6 — 핵심 단축키

터미널 안에서 마우스 없이 조작합니다. 이 단축키들 알아두면 편합니다.

단축키 동작

Enter	프롬프트 전송
Ctrl+C	현재 작업 중단 (세션 유지)
Ctrl+C (두 번)	세션 종료
Tab	작업 실행 중 다음 프롬프트 미리 입력
↑ / ↓	이전 입력 기록 탐색
Ctrl+R	입력 기록 검색
Ctrl+O	마지막 Codex 출력 클립보드 복사
Ctrl+L	화면 클리어 (대화 유지)

---

실전 7 — 슬래시 명령어

프롬프트 입력창에서 / 입력하면 사용 가능한 명령어 목록 나옵니다.

명령어 동작

/model	모델 전환 (GPT-5.4, GPT-5.3-Codex, GPT-5.4 mini)
/review	현재 변경사항 별도 에이전트가 리뷰
/clear	대화 컨텍스트 초기화 (새 채팅)
/permissions	현재 승인 모드 확인/변경
/theme	TUI 색상 테마 변경
/fast	Fast 모드 토글 (빠른 응답, 품질 트레이드오프)
/personality	응답 스타일 변경
/exit	세션 종료

모델 전환 실전

/model
→ 목록 팝업:
   ● gpt-5.4          (기본, 균형)
   ○ gpt-5.3-codex    (코딩 특화)
   ○ gpt-5.4-mini     (빠르고 저렴)
   ○ gpt-5.5          (최고 성능, 느림)

→ 원하는 모델 선택 → Enter

---

실전 8 — 첫 번째 실전 세션

설치 완료 후 실제로 써봅니다. 예시 프로젝트로 따라해보세요.

Step 1. 테스트 프로젝트 만들기

mkdir codex-test && cd codex-test
git init
echo "# Codex Test" > README.md
git add . && git commit -m "init"

Step 2. Codex 실행

codex

TUI 열립니다.

Step 3. 프로젝트 파악

> 이 폴더 구조 파악하고 README.md 내용 기반으로 어떤 프로젝트인지 설명해줘

Codex가 파일 읽고 답변합니다.

Step 4. 파이썬 유틸 함수 만들기

> Python으로 문자열 처리 유틸리티 파일 만들어줘.
  파일명: utils.py
  
  포함할 함수:
  - is_email(s): 이메일 형식 검사, True/False 반환
  - truncate(s, max_len, suffix="..."): 최대 길이로 자르고 suffix 붙이기
  - slugify(s): 공백/특수문자 → 하이픈, 소문자로 변환
  
  각 함수에 docstring과 타입 힌트 포함

auto-edit 모드라면 utils.py 파일이 자동으로 생성됩니다.

Step 5. 생성된 파일 확인

# 다른 터미널에서 또는 /exit 후 확인
cat utils.py

Step 6. 테스트 코드 추가 요청

> 방금 만든 utils.py의 모든 함수에 대한 pytest 테스트 코드 만들어줘.
  파일명: test_utils.py
  경계값 케이스도 포함해줘

Step 7. 테스트 실행

> pytest test_utils.py 실행해서 실패하면 수정해줘

auto-edit 모드에서 파일 수정은 자동, 터미널 명령(pytest 실행)은 승인 창이 뜹니다:

Codex wants to run:
  pytest test_utils.py

[Run]  [Don't run]

Run 선택하면 실행 → 결과 보고 실패한 테스트 자동 수정.

---

실전 9 — 세션 저장 및 재개

작업하다 터미널 닫아도 나중에 이어서 할 수 있습니다.

세션 목록 확인

codex resume
# 최근 세션 목록 표시:
# [1] 2026-06-01 14:32  utils.py 구현
# [2] 2026-06-01 10:15  README 작성
# ...

가장 최근 세션 재개

codex resume --last

특정 세션 재개

codex resume <SESSION_ID>

세션 데이터 저장 위치

ls ~/.codex/
# sessions/    ← 세션 기록
# config.toml  ← 전역 설정

---

실전 10 — 자주 쓰는 실전 프롬프트 패턴

바로 복붙해서 쓸 수 있습니다.

프로젝트 파악

이 레포 구조 파악해서 다음을 알려줘:
1. 어떤 기술 스택인지
2. 핵심 파일 5개와 각 역할
3. 개선이 필요해 보이는 부분

버그 수정

아래 에러가 발생합니다. 원인 파악하고 수정해줘.

파일: src/api/auth.js
에러 메시지:
TypeError: Cannot read property 'token' of null
  at verifyUser (auth.js:45)

재현 방법: 로그아웃 상태에서 /profile 접근

리팩토링

src/utils/date.js 파일을 리팩토링해줘:
- var → const/let 교체
- 콜백 패턴 → async/await
- 중복 코드 제거
- 기존 동작은 유지

기능 추가 + 테스트까지

users.js API에 아래 기능 추가하고 테스트 코드도 작성해줘:
- GET /users/:id/activities — 유저 활동 내역 조회
- page, limit 파라미터 지원
- 정렬: 최신순 기본
- 응답: { data: [...], total, page, totalPages }

코드 리뷰

/review

추가 기준:
- 보안 취약점 특히 체크해줘
- SQL injection, XSS 가능성
- 민감 정보 로그 노출 여부

---

마무리

항목 상태

✅ macOS/Linux 원라이너 설치	curl -fsSL https://chatgpt.com/codex/install.sh | sh
✅ Windows PowerShell	네이티브 지원 (experimental)
✅ ChatGPT Plus $20에 포함	이미 구독 중이면 바로 사용
✅ 오픈소스	github.com/openai/codex
✅ 세션 로컬 저장	codex resume 으로 이어서 가능
⚠️ Node.js 22 필요	npm 설치 방법 선택 시
⚠️ Windows 샌드박스 experimental	안정적 환경은 WSL2 권장
❌ Claude 모델 없음	GPT 계열만

2편에서는 승인 모드 3가지(suggest/auto-edit/full-auto)와 샌드박스 설정을 실전으로 다루고, AGENTS.md를 프레임워크별로 직접 작성하는 방법까지 씁니다.

---

관련 글

• OpenAI Codex 완전가이드 1편 — 설치부터 첫 실행까지
• OpenAI Codex 완전가이드 2편 — 승인 모드, 샌드박스, AGENTS.md
• OpenAI Codex 완전가이드 3편 — Git Worktree 병렬 에이전트
• OpenAI Codex 완전가이드 4편 — Codex App, Cloud, MCP 연동
• OpenAI Codex 완전가이드 5편 — 가격, CI/CD 자동화, Claude Code vs Codex 최종 비교