Codex CLI 설치 및 사용 방법 (2026)

Codex CLI 설치 및 사용법 (2026)

OpenAI의 Codex CLI는 터미널 기반 AI 코딩 에이전트로, OpenAI의 모델을 사용하여 커맨드 라인에서 직접 코드를 작성, 편집, 디버깅 및 리팩토링할 수 있게 해줍니다. Anthropic의 Claude Code에 대응하는 OpenAI의 도구로 생각하면 됩니다. 전체 IDE가 필요 없는 터미널 내에서 작동하는 가볍고 강력한 도구입니다.

이 가이드에서는 2026년 기준 Codex CLI의 설치, 설정, 일상적인 사용법 및 활용 팁을 다룹니다.

Codex CLI란 무엇인가요?

Codex CLI는 OpenAI에서 개발한 오픈 소스 커맨드 라인 도구입니다. OpenAI의 API에 연결되어 다음과 같은 기능을 제공합니다:

• 터미널 내 대화형 코딩 세션
• AI 지원을 통한 파일 읽기 및 편집
• 자연어 설명을 통한 코드 생성
• 기존 코드의 디버깅 및 리팩토링
• AI 가이드 워크플로우를 통한 쉘 명령어 실행
• 다중 파일 프로젝트 이해

기능	Codex CLI	Claude Code	Aider
제공자	OpenAI	Anthropic	기타 (직접 키 입력)
기본 모델	o4-mini	Claude Sonnet	설정 가능
오픈 소스	예	아니오	예
샌드박스 모드	예	예	아니오
파일 편집	예	예	예
쉘 명령어	예	예	제한적임
비용	API 사용량 기준	구독 또는 API	API 사용량 기준
IDE 통합	터미널 전용	터미널 전용	터미널 전용

사전 요구 사항

Codex CLI를 설치하기 전에 다음이 필요합니다:

• Node.js 22+ (LTS 버전 권장)
• npm 또는 yarn
• o4-mini 또는 GPT-4o 접근 권한이 있는 OpenAI API key
• Git (버전 관리 프로젝트 권장)
• macOS 또는 Linux (Windows는 WSL을 통해 지원)

설치 방법

방법 1: npm을 통한 설치 (권장)

# 전역 설치
npm install -g @openai/codex

# 설치 확인
codex --version

방법 2: 소스에서 설치

# 저장소 복제
git clone https://github.com/openai/codex.git
cd codex

# 의존성 설치
npm install

# 빌드 및 링크
npm run build
npm link

방법 3: 설치 없이 실행

# npx를 사용하여 전역 설치 없이 실행
npx @openai/codex "explain this project"

설정

API Key 설정

# 옵션 1: 환경 변수 (권장)
export OPENAI_API_KEY="sk-your-api-key-here"

# 지속성을 위해 쉘 프로필에 추가
echo 'export OPENAI_API_KEY="sk-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

# 옵션 2: 인라인 전달
OPENAI_API_KEY="sk-your-key" codex "your prompt"

설정 파일

지속적인 설정을 위해 설정 파일을 생성합니다:

# 설정 디렉토리 생성
mkdir -p ~/.codex

# ~/.codex/config.yaml
model: o4-mini
approval_mode: suggest  # suggest, auto-edit, 또는 full-auto

승인 모드 (Approval Modes)

Codex CLI는 AI에게 부여되는 자율성 수준에 따라 세 가지 안전 수준을 가집니다:

모드	플래그	동작 방식
Suggest (기본값)	--suggest	제안된 변경 사항을 보여주고, 편집 전 승인을 요청함
Auto-edit	--auto-edit	파일 편집은 자동으로 적용하고, 쉘 명령어는 승인을 요청함
Full-auto	--full-auto	모든 것을 자동으로 실행 (샌드박스 환경에서만 사용 권장)

# suggest 모드 사용 (가장 안전)
codex --suggest "refactor this function"

# auto-edit 모드 사용
codex --auto-edit "add error handling to all API calls"

# full-auto 모드 사용 (주의 필요)
codex --full-auto "set up a new Express.js project with TypeScript"

기본 사용법

대화형(Interactive) 모드

프로젝트 디렉토리에서 대화형 세션을 시작합니다:

cd /path/to/your/project
codex

프롬프트를 입력할 수 있는 채팅 인터페이스가 열리며, Codex가 파일을 읽고 변경 사항을 제안하며 명령어를 실행합니다.

단일 명령(One-Shot Commands)

대화형 모드에 진입하지 않고 단일 프롬프트를 보냅니다:

# 코드에 대해 질문하기
codex "what does the handleAuth function do?"

# 코드 생성하기
codex "create a Python script that monitors CPU usage and sends a Slack alert when it exceeds 90%"

# 에러 디버깅
codex "I'm getting a TypeError: Cannot read property 'map' of undefined in UserList.tsx. Fix it."

# 리팩토링
codex "refactor the database queries in models/user.js to use prepared statements"

입력 파이핑(Piping Input)

파일 내용이나 명령어 출력을 Codex에 전달합니다:

# 에러 로그 설명 요청
cat error.log | codex "explain what went wrong and how to fix it"

# diff 리뷰
git diff | codex "review these changes for bugs or issues"

# 파일 분석
cat src/utils/auth.ts | codex "are there any security vulnerabilities in this code?"

주요 활용 사례

1. 새 파일 생성

codex "다음 사항을 포함하는 사용자 등록용 REST API 엔드포인트를 생성해줘:
- 이메일/비밀번호 유효성 검사
- bcrypt 비밀번호 해싱
- JWT 토큰 생성
- 적절한 에러 처리
src/routes/auth.ts로 저장해줘"

2. 에러 디버깅

# 에러 직접 전달
codex "이 에러를 해결해줘:
Error: ECONNREFUSED 127.0.0.1:5432
src/db/connection.ts에서 PostgreSQL 연결이 실패하고 있어"

3. 테스트 코드 작성

codex "Jest를 사용하여 src/utils/validation.ts의 유닛 테스트를 작성해줘. 모든 예외 케이스를 포함해줘."

4. 코드 리팩토링

codex "src/components/Dashboard.tsx를 다음 프로젝트로 리팩토링해줘:
1. 차트 로직을 커스텀 훅으로 분리
2. 적절한 TypeScript 타입 추가
3. any 타입을 구체적인 타입으로 교체"

5. 코드 설명

codex "이 프로젝트의 인증 흐름을 설명해줘. 관련된 각 파일을 하나씩 짚어줘."

6. 문서 작성

codex "src/utils/에 있는 모든 export된 함수에 대해 JSDoc 주석을 생성해줘"

7. 쉘 자동화

codex "다음 작업을 수행하는 bash 스크립트를 작성해줘:
1. PostgreSQL 데이터베이스 백업
2. gzip으로 백업 압축
3. S3에 업로드
4. 30일이 지난 백업 삭제"

고급 설정

다른 모델 사용하기

# 복잡한 작업을 위해 GPT-4o 사용
codex --model gpt-4o "architect a microservices system for an e-commerce platform"

# 빠른 작업을 위해 o4-mini 사용 (기본값, 저렴함)
codex --model o4-mini "fix the typo in the README"

커스텀 지침 (Custom Instructions)

프로젝트별 지침 파일을 생성합니다:

<!-- 프로젝트 루트의 codex.md -->
# Codex 지침

## 프로젝트 컨텍스트
이 프로젝트는 TypeScript, Tailwind CSS, Prisma ORM을 사용하는 Next.js 15 애플리케이션입니다.

## 코딩 표준
- hook을 사용하는 함수형 컴포넌트 사용
- 모든 함수는 TypeScript 타입을 가져야 함
- 런타임 유효성 검사에 Zod 사용
- 기존 파일 명명 규칙(kebab-case) 준수
- 모든 새로운 유틸리티 함수에 대한 테스트 작성

## 금지 사항
- 요청 없이 데이터베이스 스키마를 수정하지 말 것
- 승인 없이 새로운 의존성을 설치하지 말 것
- .env 파일을 수정하지 말 것

Codex CLI는 프로젝트 디렉토리에서 작업할 때 이 파일을 자동으로 읽습니다.

환경별 설정

# .env를 통해 프로젝트별 모델 설정
echo 'CODEX_MODEL=gpt-4o' >> .env

# 프로젝트별 승인 모드 설정
echo 'CODEX_APPROVAL_MODE=auto-edit' >> .env

Codex CLI vs. Claude Code

둘 다 터미널 기반 AI 코딩 에이전트입니다. 비교 결과는 다음과 같습니다:

비교 항목	Codex CLI	Claude Code
모델	OpenAI (o4-mini, GPT-4o)	Claude (Sonnet, Opus)
가격 정책	토큰당 지불 (API)	구독 ($20/월) 또는 API
오픈 소스	예 (Apache 2.0)	아니오
샌드박싱	네트워크 차단 샌드박스	권한 기반
컨텍스트 윈도우	최대 128K 토큰	최대 200K 토큰
파일 편집	Diff 기반 패치	인라인 편집
MCP 지원	제한적임	전체 지원
추천 사용자	OpenAI 생태계 사용자	Claude 생태계 사용자
커뮤니티	GitHub issues	Anthropic 지원

Codex CLI를 사용해야 할 때

• OpenAI 모델을 선호하는 경우
• 직접 수정할 수 있는 오픈 소스 도구를 원하는 경우
• 복잡한 로직을 위해 o4-mini 추론 모델이 필요한 경우
• 이미 OpenAI API key를 보유하고 있는 경우

Claude Code를 사용해야 할 때

• Claude 모델을 선호하는 경우 (특히 긴 컨텍스트)
• MCP 서버 통합이 필요한 경우
• 토큰당 지불보다 구독 모델을 원하는 경우
• 복잡한 리팩토링을 위해 Anthropic의 확장된 사고(extended thinking) 기능이 필요한 경우

비용 관리

비용 추산

모델	입력 (1M 토큰당)	출력 (1M 토큰당)	일반적인 세션 비용
o4-mini	$1.10	$4.40	$0.05 - $0.50
GPT-4o	$2.50	$10.00	$0.10 - $2.00
GPT-4o-mini	$0.15	$0.60	$0.01 - $0.10

비용 절감 팁

1. 대부분의 작업에 o4-mini(기본값) 사용
2. 대화를 줄이기 위해 프롬프트를 구체적으로 작성
3. 설정에서 max_tokens를 설정하여 응답 길이 제한
4. 실행 전 변경 사항을 확인하여 낭비되는 재시도를 방지하기 위해 suggest 모드 사용
5. OpenAI 대시보드에서 지출 한도 설정

문제 해결

문제	해결 방법
command not found: codex	npm install -g @openai/codex를 다시 실행하고 PATH 설정 확인
OPENAI_API_KEY not set	키 내보내기: export OPENAI_API_KEY="sk-..."
model not found	OpenAI 계정에서 해당 모델에 대한 접근 권한이 있는지 확인
느린 응답	더 빠른 출력을 위해 o4-mini 또는 gpt-4o-mini로 전환
파일 편집이 미적용됨	파일 권한 및 올바른 디렉토리에 있는지 확인
Node.js version too old	Node.js 22 이상으로 업그레이드: nvm install 22
샌드박스 에러	샌드박스 없이 실행 시도: codex --no-sandbox

자주 묻는 질문 (FAQ)

Codex CLI는 무료인가요? 도구 자체는 무료이며 오픈 소스입니다. 사용한 토큰에 따라 OpenAI API 사용료를 지불하게 됩니다.

OpenAI 키 없이 Codex CLI를 사용할 수 있나요? 아니오. Codex CLI는 OpenAI API key가 반드시 필요합니다. 무료 대안을 찾는다면 Google이나 Groq의 무료 티어 API 키를 사용하는 Aider를 고려해 보세요.

Codex CLI가 Windows에서 작동하나요? 네이티브로는 작동하지 않습니다. Windows에서 실행하려면 WSL (Windows Subsystem for Linux)을 사용하세요.

Codex CLI가 내 시스템의 모든 파일을 수정할 수 있나요? Suggest 모드(기본값)에서는 변경 전 항상 권한을 묻습니다. Full-auto 모드에서는 안전을 위해 네트워크 액세스가 차단된 샌드박스 환경에서 실행됩니다.

GitHub Copilot과 어떻게 다른가요? Copilot은 인라인 제안을 위한 IDE 확장 프로그램입니다. Codex CLI는 복잡하고 다중 파일이 연관된 작업을 위한 터미널 에이전트입니다. 용도가 다르므로 함께 사용할 수 있습니다.

마무리

Codex CLI는 특히 OpenAI 생태계를 이미 이용 중인 개발자에게 견고한 터미널 기반 AI 코딩 에이전트입니다. 오픈 소스 특성, 샌드박스 안전 기능 및 추론 모델 지원은 터미널 작업을 선호하는 개발자에게 강력한 선택지가 됩니다.

이미지, 비디오 또는 아바타를 생성하는 AI 기반 애플리케이션을 구축하고 있다면, Hypereal AI를 무료로 체험해 보세요 (35 크레딧 제공, 신용카드 불요). REST API는 Codex CLI로 구축 중인 모든 프로젝트에 쉽게 통합됩니다.