OpenAI의 공식 코딩 에이전트 CLI. 설치·인증·자율 모드·Claude Code와의 차이를 30분 안에 정리.

OpenAI도 자체 코딩 에이전트 CLI를 출시했다. Codex CLI — Anthropic의 Claude Code에 직접 대응하는 OpenAI 표준 도구. GPT-5 (또는 o1/o3 계열) 기반으로 shell 자율 실행, 다파일 편집, 계획-실행 흐름을 제공한다.

이 가이드는 Codex CLI를 셋업하고, 이미 Claude Code 또는 Cursor를 쓰는 사용자가 어떤 작업에 Codex를 쓸지 정리한다. 단독으로 시작하는 사람은 본 글 + Claude Code 셋업 비교를 권장.

TL;DR

Node.js 20+ → npm install -g @openai/codex → codex → 브라우저 인증
OpenAI API 키 또는 ChatGPT Plus/Pro 구독으로 사용
기본은 승인 모드 (각 명령마다 확인) — --auto-edit / --full-auto 로 자율성 조절
모델 선택: --model gpt-5 또는 o3 (성능·비용 트레이드오프)
Claude Code와 역할 분담은 §5 참조

사전 조건

Node.js 20+ (mac/dev-toolchain 또는 windows/initial-setup)
OpenAI 계정 — platform.openai.com 또는 ChatGPT Plus/Pro
Git 관리되는 프로젝트

1. Codex CLI의 위치

OpenAI가 직접 만든 공식 코딩 에이전트 CLI. Cursor·Aider·Continue 같은 third-party 도구가 OpenAI 모델을 호출하는 것과 달리, Codex CLI는 OpenAI가 자체 출시한 표준.

Claude Code와의 공통점

터미널에서 자율 실행
다파일 편집·shell 명령·git 통합
프로젝트 컨텍스트 (codex의 경우 .codex/ 디렉토리)
계획 → 실행 → 검증 워크플로

차이점

항목	Codex CLI	Claude Code
모델	GPT-5 · o3 · o4	Claude Opus / Sonnet / Haiku
Context window	200K (모델별 차이)	1M (Opus/Sonnet 4)
자율성 옵션	`--auto-edit`, `--full-auto`	permission mode + hooks
인증	API key 또는 ChatGPT 구독	API key 또는 Pro/Max 구독
가격	토큰 기반 또는 Plus($20)/Pro($200)	토큰 기반 또는 Pro($20)/Max($100/$200)
MCP 지원	부분 (작업 중)	완전 지원
IDE 통합	별도 IDE 확장	VS Code · JetBrains · CLI

누구한테 적합한가

이미 ChatGPT Plus/Pro 사용자 — 별도 결제 없이 Codex CLI 사용 가능
OpenAI 생태계 이미 사용 — OpenAI Embeddings·DALL·E 등과 키 통합
o3·o4 모델의 reasoning 강점 활용 (긴 사고 작업)
GPT-5 멀티모달 — 이미지·다이어그램 인식 필요 시

2. 설치

2.1 npm 글로벌 설치

npm install -g @openai/codex
codex --version

설치가 안 되거나 permission error → Claude Code 셋업 §1.1 의 npm prefix 변경 절차 참조.

2.2 첫 실행

cd ~/projects/my-repo
codex

브라우저 탭이 열리고 OpenAI 로그인 → 권한 허용 → CLI로 복귀. 토큰은 OS 키체인 저장.

2.3 인증 옵션

세 가지 인증 경로:

# A. ChatGPT Plus/Pro (구독)
codex auth login --use-chatgpt
 
# B. OpenAI API key
codex auth login --use-api
# → OPENAI_API_KEY 환경변수 또는 입력 prompt
 
# C. Codex.com 전용 계정 (베타)
codex auth login --use-codex

확인:

codex auth status
# Account: <email>
# Plan: ChatGPT Plus / API tier 2

3. 자율성 모드

기본은 보수적 — 각 shell 명령·파일 수정마다 확인. 자율성 단계:

플래그	설명	위험도
(기본)	모든 명령·수정에 확인	낮음
`--auto-edit`	파일 수정은 자동, shell은 확인	중
`--full-auto`	모든 것 자동 (위험)	높음

권장: 신뢰가 쌓이기 전에는 기본 모드, 익숙한 프로젝트는 --auto-edit.

codex --auto-edit
> Refactor the auth module into smaller files

4. 핵심 명령

4.1 대화 시작

codex
> Plan: add password reset feature

자연어 입력 → Codex가 계획 제안 → 사용자 승인 → 실행.

4.2 슬래시 명령

대화 안에서:

/help — 명령 목록
/init — 현재 프로젝트 분석 + AGENTS.md 생성
/model gpt-5 — 모델 전환
/clear — 컨텍스트 리셋
/exit — 종료

4.3 `AGENTS.md` — 프로젝트 지침

Codex의 CLAUDE.md 대응 파일. 프로젝트 루트에:

# AGENTS.md
 
## Stack
- Next.js 16 + TypeScript strict
- Supabase + Postgres
- pnpm 11
 
## Commands
- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`
 
## Conventions
- No `any` types
- Routes: kebab-case
- Commits: `[Project] type: description`
 
## Working principles
- Plan before 5+ file changes
- Tests + lint + build must pass before "done"
- Never commit secrets

세션 시작 시 자동 로드. CLAUDE.md와 거의 동일 역할.

Claude Code와 같이 쓸 때: 같은 내용을 CLAUDE.md와 AGENTS.md 양쪽에. 또는 AGENTS.md만 두고 CLAUDE.md에서 @AGENTS.md 참조.

5. Claude Code vs Codex CLI — 작업 매핑

작업	권장	이유
1M context 다파일 작업	Claude Code	Opus/Sonnet 4의 1M
긴 추론 (디버깅·아키텍처)	Codex CLI (o3)	reasoning 강점
코드 + 이미지 (스크린샷 분석)	Codex CLI (GPT-5 멀티모달)	이미지 입력
코드 변경 후 자율 검증	Claude Code	hooks + verify 체계
OpenAI 생태계 통합 (embeddings 등)	Codex CLI	키 통합
MCP 서버 연동 (Linear, Notion 등)	Claude Code	MCP 풀 지원
비용 최소화	둘 다 (구독 보유한 쪽)	API 토큰 회피

두 도구 모두 같은 repo에서 사용 가능. 충돌 안 일어남 (둘 다 git 기반).

6. 비용 (2026-05 기준)

API 가격 (Codex CLI)

모델	Input	Output	1k 토큰 단가
GPT-5	$1.25 / 1M	$10 / 1M	입력 비용 낮음
o3	$2 / 1M	$8 / 1M	reasoning 효율
o4-mini	$0.3 / 1M	$1.2 / 1M	가성비

플랜	가격	Codex CLI 사용량
ChatGPT Plus	$20/월	GPT-5 제한적, o3 일부
ChatGPT Pro	$200/월	거의 무제한

실제 사용량은 작업 패턴 차이가 큼. 평균적 풀스택 개발자: API 직접 사용 시 월 $30-100 추정. 무거운 사용자는 ChatGPT Pro 구독이 더 저렴.

7. 검증

# 1. 설치 확인
codex --version
 
# 2. 인증
codex auth status
 
# 3. 프로젝트 셋업 파일
ls -la AGENTS.md .codex/
 
# 4. 첫 명령 테스트
echo "create a hello.py that prints 'hello'" | codex --auto-edit

4단계가 모두 통과하면 셋업 완료.

8. 트러블슈팅

`codex: command not found`

npm prefix 확인: npm config get prefix 결과의 /bin이 PATH에
새 터미널 열어 재시도

Browser auth 안 열림

WSL2/SSH 등 헤드리스 환경: CLI에 표시된 URL을 브라우저에 수동 복사
그래도 안 되면 ~/.codex/auth.json 삭제 후 codex auth login --use-api 로 API key 사용

"Insufficient quota"

OpenAI 계정의 사용량 한도 초과 — platform.openai.com/usage
Free tier는 매우 제한적. Tier 1+ 권장 ($10 결제 후 활성)

Codex가 Claude Code랑 동시에 같은 파일 편집

한 도구가 작업 중일 때 다른 도구 멈춤
또는 .gitignore에 .codex-lock 같은 임시 파일 추가해 충돌 방지

`--full-auto`로 너무 공격적 변경

즉시 Ctrl+C로 중단
git reset --hard HEAD 또는 git stash로 복구
다음부터 --auto-edit 까지만 사용

MCP 서버 연결 안 됨

Codex CLI는 2026-05 시점 MCP 부분 지원 (베타)
풀 MCP 통합이 필요하면 Claude Code 사용 권장

9. 다음 단계

Claude Code 셋업 — /ai-agents/claude-code
Cursor 셋업 — /ai-agents/cursor-setup
Copilot 셋업 — /ai-agents/github-copilot
다중 도구 워크플로 — /ai-agents/multi-tool-workflow

참고

변경 이력

2026-05-16: 첫 작성. Codex CLI 설치 + 인증 3종 + 자율성 모드 + AGENTS.md + Claude Code 비교 표 + 트러블슈팅 6종.

OpenAI Codex CLI 셋업 — Claude Code · Cursor와 비교

TL;DR

사전 조건

1. Codex CLI의 위치

Claude Code와의 공통점

차이점

누구한테 적합한가

2. 설치

2.1 npm 글로벌 설치

2.2 첫 실행

2.3 인증 옵션

3. 자율성 모드

4. 핵심 명령

4.1 대화 시작

4.2 슬래시 명령

4.3 `AGENTS.md` — 프로젝트 지침

5. Claude Code vs Codex CLI — 작업 매핑

6. 비용 (2026-05 기준)

API 가격 (Codex CLI)

구독

7. 검증

8. 트러블슈팅

`codex: command not found`

Browser auth 안 열림

"Insufficient quota"

Codex가 Claude Code랑 동시에 같은 파일 편집

`--full-auto`로 너무 공격적 변경

MCP 서버 연결 안 됨

9. 다음 단계

참고

변경 이력

댓글

OpenAI Codex CLI 셋업 — Claude Code · Cursor와 비교

TL;DR

사전 조건

1. Codex CLI의 위치

Claude Code와의 공통점

차이점

누구한테 적합한가

2. 설치

2.1 npm 글로벌 설치

2.2 첫 실행

2.3 인증 옵션

3. 자율성 모드

4. 핵심 명령

4.1 대화 시작

4.2 슬래시 명령

4.3 AGENTS.md — 프로젝트 지침

5. Claude Code vs Codex CLI — 작업 매핑

6. 비용 (2026-05 기준)

API 가격 (Codex CLI)

구독

7. 검증

8. 트러블슈팅

codex: command not found

Browser auth 안 열림

"Insufficient quota"

Codex가 Claude Code랑 동시에 같은 파일 편집

--full-auto로 너무 공격적 변경

MCP 서버 연결 안 됨

9. 다음 단계

참고

변경 이력

댓글

4.3 `AGENTS.md` — 프로젝트 지침

`codex: command not found`

`--full-auto`로 너무 공격적 변경