OpenAI Codex CLI 설치 및 초기 설정 완벽 가이드 (2025)
OpenAI Codex CLI란?
OpenAI Codex CLI는 터미널에서 자연어 명령을 통해 코드를 생성, 편집, 실행할 수 있는 오픈소스 커맨드라인 도구입니다. GPT-4o 모델을 기반으로 파일 시스템을 직접 읽고 수정할 수 있으며, 샌드박스 환경에서 안전하게 코드를 실행합니다. 복잡한 리팩토링부터 간단한 스크립트 작성까지, 개발 워크플로우를 획기적으로 단축시킬 수 있습니다.
1단계: 사전 요구사항 확인
Codex CLI를 설치하기 전에 다음 환경이 준비되어 있어야 합니다.
- Node.js 22 이상 — Codex CLI는 최신 Node.js 런타임을 요구합니다- Git — 프로젝트 디렉토리에서의 버전 관리 연동에 필요- OpenAI API 키 — Platform 계정에서 발급- 운영체제 — macOS 또는 Linux (Windows는 WSL2 환경 필요)Node.js 버전을 확인하세요:
node —version
v22.0.0 이상이어야 합니다
Node.js가 없거나 버전이 낮은 경우
nvm install 22
nvm use 22
2단계: OpenAI API 키 발급
- OpenAI Platform에 로그인합니다- 좌측 메뉴에서 API Keys를 클릭합니다- Create new secret key 버튼을 클릭합니다- 키 이름을 입력하고 (예:
codex-cli) 권한을 설정합니다- 생성된 키를 안전한 곳에 복사합니다 — 이 키는 다시 확인할 수 없습니다환경 변수로 API 키를 설정합니다:
# 현재 세션에 설정 export OPENAI_API_KEY=“YOUR_API_KEY”
영구적으로 설정 (bash)
echo ‘export OPENAI_API_KEY=“YOUR_API_KEY”’ >> ~/.bashrc
source ~/.bashrc
zsh 사용자
echo ‘export OPENAI_API_KEY=“YOUR_API_KEY”’ >> ~/.zshrc
source ~/.zshrc
3단계: Codex CLI 설치
npm을 통해 전역으로 설치합니다:
# 전역 설치
npm install -g @openai/codex
설치 확인
codex —version
설치가 완료되면 바로 터미널에서 사용할 수 있습니다:
# 첫 번째 명령 실행
codex “현재 디렉토리의 파일 목록을 보여줘”
4단계: 샌드박스 모드 구성
Codex CLI는 세 가지 자율성 모드를 제공합니다. 각 모드는 에이전트가 수행할 수 있는 작업의 범위를 결정합니다.
| 모드 | 플래그 | 파일 읽기 | 파일 쓰기 | 명령 실행 | 사용 시나리오 |
|---|---|---|---|---|---|
| Suggest | --suggest | O | X (제안만) | X | 코드 리뷰, 학습 |
| Auto Edit | --auto-edit | O | O | X | 리팩토링, 코드 수정 |
| Full Auto | --full-auto | O | O | O (샌드박스) | 자동화된 개발 작업 |
# Suggest 모드 — 가장 안전한 모드로 시작 권장
codex --suggest "이 함수의 성능을 개선할 방법을 알려줘"
Auto Edit 모드 — 파일 자동 수정 허용
codex —auto-edit “모든 var 선언을 const로 변경해줘”
Full Auto 모드 — 명령 실행까지 허용 (샌드박스 내에서)
codex —full-auto “테스트를 작성하고 실행해서 통과하는지 확인해줘”
Full Auto 모드에서는 네트워크 접근이 기본적으로 차단되며, 파일 쓰기는 현재 작업 디렉토리와 임시 폴더로 제한됩니다. macOS에서는 Apple Seatbelt(sandbox-exec), Linux에서는 Docker 기반 격리가 적용됩니다.
5단계: VS Code 통합 설정
VS Code의 통합 터미널에서 Codex CLI를 직접 사용할 수 있으며, 프로젝트 컨텍스트를 자동으로 활용합니다.
- VS Code에서 프로젝트 폴더를 엽니다- 통합 터미널을 열고 (
Ctrl+`) Codex 명령을 실행합니다- 프로젝트 루트에AGENTS.md파일을 생성하여 사용자 지침을 설정합니다# AGENTS.md 파일 예시
이 파일은 Codex가 프로젝트 컨텍스트를 이해하는 데 사용됩니다
이 프로젝트는 TypeScript + React 기반 웹 애플리케이션입니다.
테스트 프레임워크: Jest + React Testing Library
스타일링: Tailwind CSS
패키지 매니저: pnpm
코딩 컨벤션: ESLint + Prettier 설정을 따르세요.
설정 파일(~/.codex/config.yaml)을 통해 기본 동작을 커스터마이징할 수 있습니다:
# ~/.codex/config.yaml
model: o4-mini
approvalMode: auto-edit
notify: true
history:
maxSize: 1000
saveHistory: true
providers:
name: openai envKey: OPENAI_API_KEY
실전 워크플로우 예시
설치 후 실제 개발 작업에 Codex CLI를 활용하는 방법입니다:
# 버그 수정 워크플로우
codex "src/utils/parser.ts에서 null 체크가 누락된 부분을 찾아서 수정해줘"
테스트 생성
codex “src/components/Button.tsx에 대한 단위 테스트를 작성해줘”
코드 마이그레이션
codex “이 프로젝트의 모든 class 컴포넌트를 함수형 컴포넌트로 변환해줘”
Git 커밋 메시지 생성
codex “현재 스테이징된 변경사항을 분석해서 커밋 메시지를 작성해줘”
인터랙티브 모드 (대화형)
codex
> 프롬프트가 나타나면 자연어로 요청을 입력합니다
Pro Tips — 파워 유저를 위한 팁
- 모델 선택: 빠른 응답이 필요하면
codex —model o4-mini, 복잡한 작업에는codex —model o3을 사용하세요- AGENTS.md 활용: 하위 디렉토리별로AGENTS.md를 배치하면 해당 폴더에 특화된 지침을 줄 수 있습니다- Quiet 모드:codex —quiet “작업 내용”으로 CI/CD 파이프라인에 통합할 수 있습니다. 최종 출력만 stdout으로 반환됩니다- 컨텍스트 최적화: 큰 프로젝트에서는 관련 디렉토리에서 실행하세요. Codex는 현재 위치 기준으로 파일을 탐색합니다- 비용 관리:o4-mini모델은o3대비 약 10배 저렴하면서도 대부분의 코딩 작업에 충분한 성능을 제공합니다
Troubleshooting — 자주 발생하는 오류 해결
| 오류 메시지 | 원인 | 해결 방법 |
|---|---|---|
OPENAI_API_KEY is not set | 환경 변수 미설정 | export OPENAI_API_KEY="YOUR_API_KEY" 실행 후 셸 재시작 |
Node.js version too old | Node.js 22 미만 버전 | nvm install 22 && nvm use 22로 업그레이드 |
Permission denied | 전역 설치 권한 부족 | sudo npm install -g @openai/codex 또는 nvm 사용 |
Sandbox execution failed | Docker 미설치 (Linux) | Docker를 설치하거나 --suggest 모드 사용 |
Rate limit exceeded | API 호출 한도 초과 | OpenAI Platform에서 Usage Tier 확인 및 업그레이드 |
WSL2 환경에서 설치 시 Windows 네이티브 Node.js가 아닌 WSL 내부의 Node.js를 사용해야 합니다:
# WSL2 내부에서 확인
which node
# /home/user/.nvm/versions/node/v22.x.x/bin/node 형태여야 합니다
# /mnt/c/... 경로라면 Windows 버전이므로 WSL 내부에 별도 설치 필요
## 자주 묻는 질문 (FAQ)
Q1: Codex CLI는 무료로 사용할 수 있나요?
Codex CLI 도구 자체는 오픈소스로 무료입니다. 하지만 OpenAI API를 호출하므로 API 사용량에 따른 비용이 발생합니다. o4-mini 모델은 입력 100만 토큰당 약 $1.10, 출력 100만 토큰당 약 $4.40으로 비교적 저렴합니다. OpenAI Platform의 Usage 페이지에서 실시간 사용량을 모니터링할 수 있습니다.
Q2: Codex CLI에서 GPT-4o 외에 다른 모델도 사용할 수 있나요?
네, —model 플래그로 다양한 OpenAI 모델을 지정할 수 있습니다. 기본 모델은 o4-mini이며, 더 강력한 추론이 필요한 경우 o3를 사용할 수 있습니다. 또한 OPENAI_BASE_URL 환경 변수를 설정하면 OpenAI API 호환 엔드포인트를 가진 다른 LLM 프로바이더(예: Azure OpenAI, Ollama)도 연동할 수 있습니다.
Q3: 기존 프로젝트에 Codex CLI를 도입할 때 보안상 주의할 점은 무엇인가요?
먼저 —suggest 모드로 시작하여 Codex가 제안하는 변경사항을 직접 검토하는 것을 권장합니다. Full Auto 모드에서는 샌드박스가 적용되지만, 민감한 환경 변수나 시크릿 파일이 있는 디렉토리에서는 주의가 필요합니다. AGENTS.md에 접근 제한 지침을 명시하고, .gitignore에 포함된 파일은 Codex도 무시하도록 설정하세요. API 키는 반드시 환경 변수로 관리하며, 코드에 하드코딩하지 마세요.