Codex 101 — OpenAI Codex Complete Guide

01 Codex 에코시스템 개요

OpenAI Codex는 2025년 5월에 codex-1(o3 기반)으로 재출시된 후, 2026년 2월 현재 GPT-5.3-Codex까지 진화한 에이전틱 코딩 플랫폼입니다.

"단순 코드 생성 → 소프트웨어 엔지니어 팀원"

Codex는 코드 자동완성 도구가 아닙니다. 여러 파일을 동시에 수정하고, 테스트를 실행하고, 결과를 검증하며, 스스로 디버깅하는 자율 에이전트입니다.

타임라인

시기	이벤트
2025.04	Codex CLI 오픈소스 공개 (TypeScript, Apache 2.0)
2025.05	Codex-1 출시 (o3 아키텍처), 클라우드 샌드박스 도입
2025.06	Codex CLI Rust 리라이트 베타 공개
2025.10.06	DevDay 2025에서 GPT-5 Codex GA 발표
2025.12.18	GPT-5.2-Codex 출시 (멀티파일 최적화, 컨텍스트 압축)
2025.08.27	Codex IDE Extension(Visual Studio Code) 변경로그 첫 공개
2026.02.02	Codex macOS App 출시
2026.02.05	GPT-5.3-Codex 출시
2026.02.12	Codex-Spark 리서치 프리뷰 공개

02 Codex 제품군 한눈에 보기

CLI

Codex CLI

터미널 기반(TUI) 로컬 에이전틱 코딩 및 CI/CD 자동화. 2025.04 출시.

App

Codex App

macOS 데스크톱 앱. 멀티에이전트 커맨드 센터, 내장 워크트리. 2026.02 출시.

IDE

Codex IDE Extension

VS Code 사이드바에서 AI 코딩. 클라우드 위임 지원. 2025.08~09 변경로그 기준 공개.

Web

Codex Web

ChatGPT 웹 대시보드. GitHub 연동, 자동 PR/코드 리뷰. 2025.05 출시.

03 지원 모델

04 시스템 요구사항 & 가격

시스템 요구사항

OS	macOS 12+, Ubuntu 20.04+, Windows 11 (WSL2)
Node.js	v18+
Git	강력히 권장
계정	ChatGPT Free / Go / Plus / Pro / Business / Edu / Enterprise

ChatGPT 구독 요금 (2026.02)

플랜	가격	Codex
Free	$0	✅*
Go	$8/mo	✅*
Plus	$20/mo	✅**
Pro	$200/mo	✅**
Business	$25~30/user/mo	✅**
Enterprise	맞춤 가격	✅**

* Free/Go도 한시적으로 Codex 접근 가능. ** Plus 이상(및 Edu/Enterprise) 한시적 2x Codex rate limits 제공.

05 설치 및 인증

CLI 설치

# npm
npm install -g @openai/codex

# Homebrew (macOS)
brew install codex

# Update
npm update -g @openai/codex

인증

# ChatGPT 계정 로그인 (권장)
codex login

# 또는 API 키 사용
export OPENAI_API_KEY="your-api-key-here"

macOS App 설치

openai.com/codex 에서 다운로드
.dmg 파일 실행 → Applications 폴더로 이동
ChatGPT 계정 또는 API 키로 로그인

현재 macOS App만 사용 가능합니다. Windows는 WSL 가상환경으로 CLI 사용 가능.

Windows/Linux App Waitlist 등록

IDE Extension 설치

VS Code 확장 마켓플레이스에서 "OpenAI Codex" 검색
설치 후 사이드바에서 Codex 패널 활성화
ChatGPT 계정으로 인증

06 Codex CLI 사용법

Codex CLI v0.104 running in terminal — Codex CLI v0.104.0 — 터미널에서 GPT-5.3-Codex xhigh 모델로 코드 작업

# 인터랙티브 모드
codex

# 프롬프트와 함께
codex "explain this codebase"

# 특정 디렉토리
codex --cd /path/to/project

# 파일 참조
@src/components/Button.tsx 리팩토링해줘

# 쉘 명령어 실행
!npm test

2026.02 신기능

Mid-Turn Steering /feedback 슬래시 명령어 퍼지 파일 검색 모든 파일 타입 첨부 향상된 리뷰 패인 WebSocket 프록시 실험적 JS REPL

07 Codex App (macOS)

Codex macOS App interface — Codex macOS App — 멀티에이전트 커맨드 센터와 워크트리 관리

2026년 2월 2일 출시. 에이전틱 코딩의 "커맨드 센터". 여러 AI 에이전트를 동시에 관리하는 macOS 전용 데스크톱 앱.

쓰레드 모드

모드	실행 위치	설명
Local	내 맥	현재 프로젝트 디렉토리에서 직접 작업
Worktree	내 맥	Git Worktree로 변경사항 격리. 병렬 작업에 적합
Cloud	클라우드	원격 클라우드 환경에서 실행

핵심 기능

—멀티에이전트 병렬 실행

—내장 Git 도구 (diff, commit, PR)

—Skills 지원 (CLI/IDE 공유)

—Automations (정기 작업 자동화)

—Voice Dictation (Ctrl+M)

—플로팅 팝아웃 창

—IDE Extension 실시간 동기

—이미지 입력 (Drag & Drop)

—내장 터미널 (쓰레드별)

—작업 중 절전 방지

08 Codex IDE Extension

Codex VS Extension marketplace page — Codex VS Extension — 마켓플레이스 (4.6M+ 다운로드)

VS Code, Cursor, Windsurf, JetBrains IDE에 통합되는 AI 코딩 에이전트.

모드	파일 접근	코드 수정	명령 실행
Chat	△ 수동 컨텍스트만 (@file/열린 파일/선택 영역)	❌	❌
Agent	✅	✅ (승인 필요)	✅ (승인 필요)
Agent (Full Access)	✅	✅	✅

Chat 모드는 자동으로 파일을 탐색/수정하지 않지만, @file·열린 파일·선택 영역을 컨텍스트로 포함해 질문할 수 있습니다.

핵심 기능

—@file 에디터 컨텍스트 자동 참조

—클라우드 위임 (Cloud Delegation)

—추론 노력 조절 (low/medium/high)

—JetBrains IDE 지원

—Cursor, Windsurf 호환

—App 실시간 동기 (Auto Context)

09 Codex Web (ChatGPT 대시보드)

Codex Web Dashboard in ChatGPT — Codex Web - ChatGPT 웹 대시보드에서 GitHub 연동 작업

ChatGPT 웹 인터페이스에서 Codex를 사용하여 클라우드 환경에서 코딩 작업을 할 수 있습니다.

1GitHub 계정 연결 → 레포 선택

2작업 설명 입력

3클라우드 샌드박스에서 자동 작업

4결과 diff 확인

5GitHub PR로 제안 또는 머지

자동 코드 리뷰

Codex Web에서 GitHub 연결 후 리뷰 대상 저장소를 선택하고 "Automatic reviews"를 활성화하면 새 PR마다 자동 리뷰됩니다. AGENTS.md 규칙 기반 커스터마이징 가능.

10 승인 모드 (Approval Modes)

모드	파일 읽기	파일 수정	명령 실행	네트워크
Suggest 기본	✅	❌	❌	❌
Auto-Edit	✅	✅	❌	❌
Full Auto	✅	✅	✅	❌

codex --approval-mode suggest
codex --approval-mode auto-edit
codex --approval-mode full-auto

보안: macOS는 Apple Seatbelt, Linux는 Docker 컨테이너 샌드박싱. Full Auto에서도 네트워크 기본 차단.

11 슬래시 명령어 & 단축키

플랫폼별 슬래시 명령어

아래 목록은 CLI / IDE / App 공식 문서를 교차 확인해 분리한 명령어입니다. 서로 이름이 비슷해도 동작이 다를 수 있습니다.

CLI (터미널)

CLI

`/model`	활성 모델 변경 (가능한 경우 reasoning effort 포함)
`/permissions`	승인/권한 정책 변경
`/agent`	활성 에이전트 스레드 전환
`/plan`	플랜 모드 전환 (선택적으로 인라인 프롬프트 포함)
`/compact`	대화 요약으로 컨텍스트 토큰 절약
`/status`	세션 설정/토큰 사용량 확인
`/review`	워크트리 코드 리뷰 실행
`/feedback`	진단 로그와 피드백 전송

CLI에는 이외에도 /personality, /experimental, /init, /mention, /mcp, /diff, /fork, /resume, /new, /quit 등이 있습니다. /approvals는 별칭으로 동작하지만 팝업 목록에는 표시되지 않습니다.

IDE Extension

IDE

`/auto-context`	자동 컨텍스트 포함 토글
`/cloud`	클라우드 모드로 전환
`/cloud-environment`	클라우드 환경 선택 (cloud 모드에서만)
`/local`	로컬 모드로 전환
`/review`	변경사항 리뷰 모드 시작
`/status`	스레드 ID/컨텍스트/레이트리밋 확인
`/feedback`	피드백 다이얼로그 열기

Codex App (macOS)

APP

`/plan-mode`	멀티스텝 계획용 plan mode 토글
`/mcp`	연결된 MCP 서버 상태 열기
`/review`	변경사항 리뷰 모드 시작
`/status`	스레드 ID/컨텍스트/레이트리밋 확인
`/feedback`	피드백 다이얼로그 열기

App 문서 기준으로 명령은 환경/권한에 따라 달라질 수 있으며, 활성화된 skill은 슬래시 목록에 추가될 수 있습니다.

키보드 단축키 (CLI)

아래 단축키는 CLI(TUI) 기준입니다. App은 Cmd 기반 단축키를, IDE는 각 IDE 키맵을 사용합니다.

`Esc` ×2	입력창이 비었을 때 이전 사용자 메시지 편집
`Ctrl+C`	세션 종료 (/exit)
`Ctrl+G`	프롬프트 에디터 열기 (VISUAL/EDITOR)

공식 문서: CLI slash commands · IDE slash commands · App commands

12 AGENTS.md 설정 가이드

Codex에게 프로젝트 맥락과 규칙을 알려주는 핵심 파일. CLI, App, IDE, Web 모두에서 참조합니다.

# AGENTS.md 위치 및 우선순위
AGENTS.override.md  → 최우선
./AGENTS.md         → 가장 가까운 파일
../AGENTS.md        → 상위 디렉토리
~/.codex/AGENTS.md  → 전역 개인 설정

작성 5원칙

전문가 역할 지정 코드로 보여주기 구체적 명령 Always / Ask / Never 살아있는 문서

# 자동 생성
codex init

13 config.toml 설정

# ~/.codex/config.toml
model = "gpt-5.3-codex"
model_provider = "openai"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"

# 프로필
[profiles.fast]
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "low"

[profiles.deep]
model = "gpt-5.3-codex"
model_reasoning_effort = "high"

codex --profile fast
codex --profile deep

14 MCP (Model Context Protocol)

AI 모델과 외부 도구(브라우저, DB, 파일시스템 등)를 연결하는 표준 프로토콜.

# MCP 서버 추가
codex mcp add playwright -- npx @playwright/mcp

# config.toml
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp"]

서버	용도	패키지
Playwright	웹 브라우저 제어	`@playwright/mcp`
Filesystem	파일 시스템 접근	`@mcp/server-filesystem`
GitHub	GitHub API 연동	`@mcp/server-github`
Postgres	DB 쿼리 실행	`@mcp/server-postgres`
Memory	세션 간 기억 유지	`@mcp/server-memory`

15 세션 관리

codex resume --last     # 마지막 세션
codex resume            # 목록에서 선택
codex resume <ID>       # 특정 세션

# 세션 내 명령
/permissions  /mcp  /status  /review  /feedback  /compact

16 비대화형 자동화 & CI/CD

# codex exec - 실행 후 자동 종료
codex exec "Review this PR" --output stdout
codex exec "Fix all TODOs" --approval-mode full-auto

Codex Web 자동 리뷰

GitHub 연결 + 리뷰 대상 저장소 선택 후 "Automatic reviews" 활성화 → 새 PR마다 자동 리뷰, AGENTS.md 규칙 기반 커스터마이징.

17 프롬프트 엔지니어링 팁

@reach_vb (Vaibhav Srivastav, OpenAI DevRel) 포스팅 기반 정리

⚙️ 기본 설정 및 모델 선택

AGENTS.md 생성 필수

프로젝트마다 AGENTS.md를 생성하세요. 핵심 지침을 저장하면 모델이 읽어 컨텍스트를 유지합니다. /init으로 자동 생성 가능.

Reasoning Effort 전략

복잡한 계획/설계: High 또는 XHigh. 구현/반복 작업: Medium 또는 Low로 속도와 비용 최적화.

모델 조합 전략

gpt-5.3-codex-spark: 짧은 반복 작업과 빠른 시도에 적합한 리서치 프리뷰.
gpt-5.3-codex: 멀티파일 에이전틱 코딩의 메인 모델.

📋 워크플로 및 계획

기본부터 시작, 반복적 빌드

복잡한 작업은 단순하게 시작하고 점진 확장. Codex에게 결과를 검증(Verify)하도록 요청하면 최적 성능.

/plan(/plan-mode) → 실행 → /review

/plan(CLI) 또는 /plan-mode(App)로 계획을 세운 뒤 작업을 실행하고, 마지막에 /review로 결과를 점검하세요.

큐잉 & 병렬 처리

아이디어가 떠오를 때마다 Codex에 큐를 쌓아 병렬 처리. 여러 에이전트를 동시 투입하면 거의 모든 것을 달성 가능.

AGENTS.md 적극 업데이트

Codex가 실수할 때마다 즉시 AGENTS.md 업데이트. 압축(Compaction) 후에도 모델이 다시 읽어 컨텍스트 유지. 문서가 곧 기억.

🔧 스킬 및 도구 통합

워크트리 & 백그라운드

워크트리 모드로 변경 격리, 병렬 작업 시 충돌 방지. 백그라운드 터미널에서 테스트/린트/Git 실행. 결과를 인박스로 전달.

IDE 싱크 & Git 리뷰

현재 보고 있는 파일에 자동 컨텍스트 제공. 내장 Git 리뷰로 Diff 확인, hunk 스테이징/되돌리기, 인라인 댓글 가능.

💻 앱 / CLI / 웹 팁

CLI 우선 빌드

에이전트가 검증하기 쉬운 CLI부터 시작하고, UI 등 다른 표면을 추가. 코드가 일회성이라면 아이디어 테스트 후 브랜치 폐기.

앱 편의 기능

여러 프로젝트/스레드를 하나의 앱에서 관리. Ctrl+M으로 음성 입력. /persona로 응답 스타일 조정.

웹 활용

Codex Web에서 GitHub를 연결하고 자동 PR 리뷰를 활성화하면 비동기 검증 흐름을 만들기 좋습니다.

🚀 고급 조언

구체적이고 명확한 프롬프트

❌ "코드를 고쳐줘" → ✅ "@src/utils/date.ts의 formatDate에서 KST 처리 버그를 Intl.DateTimeFormat으로 수정해"

검증 포함 요청

"이 기능을 구현하고 단위 테스트도 작성해. 린팅 통과 확인하고 기존 테스트도 돌려봐." - 검증을 포함하면 성공률 대폭 상승.

Mid-Turn Steering

Codex 작업 중 "잠깐, Zod 스키마를 대신 사용해줘"처럼 추가 지시를 보내면 작업 방향을 중간에 조정할 수 있습니다.

프로토타이핑에 강함

"수정 → 확인 → 재수정" 사이클이 빠른 작업에서 Codex가 특히 효율적입니다. Spark 모델은 빠른 반복 실험에 유리합니다.

18 고급 활용 기법

# 추론 수준 조절
/model gpt-5.3-codex-spark  # 초고속
/model gpt-5.3-codex        # 복잡한 작업

# 멀티 디렉토리
codex --add-dir /path/to/libs

# 웹 검색(인터랙티브에서 --search 전역 옵션 사용)
codex --search "optimize with Next.js 15"

# 컨텍스트 압축
/compact

19 Codex vs Cursor vs Claude Code

특성	Codex	Cursor	Claude Code
인터페이스	CLI+App+IDE+Web	CLI(beta) + IDE + Background Agents	CLI + IDE + Web/iOS(리서치 프리뷰) + Slack
오픈소스	✅ (CLI)	❌	❌
주요 모델	GPT-5.3-Codex	선택한 제공 모델에 따라 다름	Claude Opus/Sonnet/Haiku 계열 (플랜별)
클라우드 실행	✅	✅ Cloud/Background Agents	✅ Web/iOS(리서치 프리뷰) + GitHub/GitLab CI 러너
GitHub 통합	✅ 자동 PR/리뷰	✅ GitHub App	✅ GitHub Actions + GitLab CI/CD
멀티에이전트	✅ (App)	✅ 비동기 Background Agents	✅ Subagents(위임형 멀티에이전트)
MCP	✅	✅	✅
가격	ChatGPT 플랜 포함(사용량 한도)	Hobby Free, Pro $20, Pro+ $60, Ultra $200, Teams $40/user, Enterprise custom	Pro/Max/Team/Enterprise 포함 또는 Console API 종량제

20 FAQ

Codex CLI / App / IDE / Web의 차이는?

모두 같은 Codex App Server 프로토콜을 사용하지만 인터페이스가 다릅니다. CLI는 터미널, App은 macOS 멀티에이전트, IDE는 VS Code 통합, Cloud는 브라우저에서 GitHub 연동.

무료로 사용할 수 있나요?

네! ChatGPT 무료 계정으로도 Codex CLI, App, Web 모두 한시적 무료 접근이 가능합니다 (5시간당 약 10~30회). 안정적 사용을 위해서는 Plus($20/월) 이상을 권장하며, API Key 종량제도 지원됩니다.

Full Auto 모드가 안전한가요?

OS 수준 샌드박싱 + 네트워크 차단이 적용됩니다. Git으로 관리하면 언제든 되돌릴 수 있습니다.

GPT-5.3-Codex-Spark는 뭔가요?

2026.02 리서치 프리뷰로 공개된 텍스트 중심 코딩 모델입니다. 빠른 반복 작업에 초점을 둔 옵션이며, 최신 제공 범위는 플랜/문서 기준으로 확인하세요.

오프라인에서 사용 가능한가요?

Codex CLI는 오픈소스(Rust)이며, 타사 모델 프로바이더(Ollama 등)를 연결할 수 있지만, 품질은 OpenAI 모델보다 떨어집니다.

21 참고 자료

OpenAI Codex GitHub Repo Release Notes agents.md Spec MCP Marketplace

목차

01 Codex 에코시스템 개요

타임라인

02 Codex 제품군 한눈에 보기

Codex CLI

Codex App

Codex IDE Extension

Codex Web

03 지원 모델

최신 모델 (2026.02 기준)

⭐ 추천 모델

🔄 대안 모델

🛠️ 모델 설정 팁

04 시스템 요구사항 & 가격

시스템 요구사항

ChatGPT 구독 요금 (2026.02)

05 설치 및 인증

CLI 설치

인증

macOS App 설치

IDE Extension 설치

06 Codex CLI 사용법

2026.02 신기능

07 Codex App (macOS)

쓰레드 모드

핵심 기능

08 Codex IDE Extension

핵심 기능

09 Codex Web (ChatGPT 대시보드)

10 승인 모드 (Approval Modes)

11 슬래시 명령어 & 단축키

플랫폼별 슬래시 명령어

CLI (터미널)

IDE Extension

Codex App (macOS)

키보드 단축키 (CLI)

12 AGENTS.md 설정 가이드

작성 5원칙

13 config.toml 설정

14 MCP (Model Context Protocol)

15 세션 관리

16 비대화형 자동화 & CI/CD

17 프롬프트 엔지니어링 팁

⚙️ 기본 설정 및 모델 선택

AGENTS.md 생성 필수

Reasoning Effort 전략

모델 조합 전략

📋 워크플로 및 계획

기본부터 시작, 반복적 빌드

/plan(/plan-mode) → 실행 → /review

큐잉 & 병렬 처리

AGENTS.md 적극 업데이트

🔧 스킬 및 도구 통합

추천 스킬

워크트리 & 백그라운드

IDE 싱크 & Git 리뷰

💻 앱 / CLI / 웹 팁

CLI 우선 빌드

앱 편의 기능

웹 활용

🚀 고급 조언

구체적이고 명확한 프롬프트

검증 포함 요청

Mid-Turn Steering

프로토타이핑에 강함

18 고급 활용 기법

19 Codex vs Cursor vs Claude Code

20 FAQ

21 참고 자료