OpenAI Codex CLI 완벽 설치 가이드 - npm 설치부터 API 키 설정, 샌드박스 보안 모드까지
OpenAI Codex CLI 완벽 설치 가이드
OpenAI Codex CLI는 터미널에서 자연어로 코드를 생성하고, 파일을 수정하며, 프로젝트를 자동화할 수 있는 오픈소스 AI 코딩 에이전트입니다. 이 가이드에서는 설치부터 첫 코드 생성까지 전 과정을 단계별로 안내합니다.
사전 요구사항
- Node.js 22 이상 — Codex CLI는 Node.js 22+를 요구합니다
- 운영체제 — macOS 12+, Ubuntu 20.04+, 또는 Windows (WSL2 권장)
- OpenAI API 키 — platform.openai.com에서 발급
- Git — 프로젝트 컨텍스트 분석에 필요
Step 1: Node.js 버전 확인 및 설치
먼저 현재 설치된 Node.js 버전을 확인합니다.
node —version
v22.0.0 이상이어야 합니다
Node.js 22 미만이라면 nvm을 사용해 업그레이드합니다.
# nvm으로 Node.js 22 설치
nvm install 22
nvm use 22
node —version
Step 2: Codex CLI 설치
npm을 통해 전역으로 Codex CLI를 설치합니다.
# 전역 설치 (권장)
npm install -g @openai/codex
설치 확인
codex —version
프로젝트 단위로 설치하려면 다음과 같이 합니다.
# 프로젝트 로컬 설치
npm install @openai/codex
npx codex —version
Step 3: OpenAI API 키 설정
Codex CLI를 사용하려면 OpenAI API 키가 필요합니다. 환경변수로 설정하는 방법이 가장 일반적입니다.
방법 A: 환경변수 직접 설정
# Linux/macOS — 셸 프로필에 추가
echo ‘export OPENAI_API_KEY=“YOUR_API_KEY”’ >> ~/.bashrc
source ~/.bashrc
Windows PowerShell
$env:OPENAI_API_KEY = “YOUR_API_KEY”
또는 Windows 시스템 환경변수로 영구 설정
[System.Environment]::SetEnvironmentVariable(‘OPENAI_API_KEY’, ‘YOUR_API_KEY’, ‘User’)
방법 B: .env 파일 사용
# 프로젝트 루트에 .env 파일 생성
echo "OPENAI_API_KEY=YOUR_API_KEY" > .env
# .gitignore에 반드시 추가
echo ".env" >> .gitignoreAPI 키가 올바르게 설정되었는지 확인합니다.
# 키 설정 확인
codex “say hello”
Step 4: 샌드박스 보안 모드 구성
Codex CLI는 세 가지 보안 모드를 제공하여 AI 에이전트의 시스템 접근 권한을 제어합니다.
| 모드 | 파일 읽기 | 파일 쓰기 | 명령 실행 | 사용 시나리오 |
|---|---|---|---|---|
| **suggest** | O | X (승인 필요) | X (승인 필요) | 코드 리뷰, 학습용 |
| **auto-edit** | O | O | X (승인 필요) | 일반 개발 작업 |
| **full-auto** | O | O | O (샌드박스 내) | 자동화 워크플로우 |
# suggest 모드 (기본값) — 모든 변경을 사용자가 승인
codex “버그를 찾아서 수정해줘”
auto-edit 모드 — 파일 수정은 자동, 명령 실행은 승인 필요
codex —approval-mode auto-edit “README.md를 한국어로 번역해줘”
full-auto 모드 — 네트워크 비활성화된 샌드박스 내에서 자동 실행
codex —approval-mode full-auto “테스트 코드를 작성하고 실행해줘”
**중요:** full-auto 모드에서는 네트워크 접근이 기본적으로 차단되며, 프로젝트 디렉토리 외부의 파일 쓰기가 제한됩니다. macOS에서는 Apple Seatbelt, Linux에서는 Docker 기반 샌드박스가 작동합니다.
Step 5: 첫 코드 생성 실행
이제 실제로 Codex CLI를 사용해 코드를 생성해봅니다.
자연어로 코드 생성하기
# 간단한 Python 함수 생성
codex “Python으로 피보나치 수열 함수를 만들어줘”
기존 프로젝트 컨텍스트를 활용한 작업
cd my-project
codex “이 프로젝트의 API 엔드포인트에 입력 검증을 추가해줘”
특정 파일을 대상으로 작업
codex “utils.js 파일의 함수들에 JSDoc 주석을 추가해줘”
인터랙티브 모드 활용
# 인터랙티브 세션 시작 (인수 없이 실행)
codex
# 프롬프트가 나타나면 자연어로 지시
> Express.js로 CRUD API 서버를 만들어줘
> 여기에 JWT 인증 미들웨어를 추가해줘
> 테스트 코드도 작성해줘구성 파일로 기본 설정 저장
홈 디렉토리에 ~/.codex/config.yaml 파일을 생성하여 기본 설정을 저장할 수 있습니다.
# ~/.codex/config.yaml
model: o4-mini
approvalMode: auto-edit
notify: true
프로젝트별 지시사항은 프로젝트 루트에 AGENTS.md 파일을 생성하여 설정합니다.
# AGENTS.md 예시
이 프로젝트는 TypeScript를 사용합니다.
코드 스타일은 Prettier 기본 설정을 따릅니다.
테스트는 Jest를 사용합니다.
API 응답은 항상 camelCase를 사용합니다.
Pro Tips — 파워 유저를 위한 팁
- 모델 선택:
codex —model o3으로 더 강력한 모델을 사용할 수 있습니다. 복잡한 리팩토링에는o3, 빠른 작업에는 기본o4-mini가 적합합니다. - 파이프라인 연동:
cat error.log | codex “이 에러 로그를 분석하고 해결책을 제시해줘”처럼 파이프를 통해 컨텍스트를 전달할 수 있습니다. - 조용한 모드:
codex —quiet “테스트 실행”으로 CI/CD 파이프라인에서 비대화형으로 실행 가능합니다. - AGENTS.md 계층화: 루트와 하위 디렉토리에 각각 AGENTS.md를 두면 디렉토리별로 다른 지시를 적용할 수 있습니다.
- 다중 프로바이더:
OPENAI_BASE_URL환경변수를 설정하면 OpenAI 호환 API 프록시나 Azure OpenAI 등도 사용할 수 있습니다.
Troubleshooting — 자주 발생하는 오류
오류: “Node.js version 22 or later is required”
# 해결: Node.js 업그레이드
nvm install 22
nvm alias default 22오류: “OPENAI_API_KEY is not set”
# 환경변수 확인
echo $OPENAI_API_KEY
# 설정되어 있지 않다면 다시 설정
export OPENAI_API_KEY="YOUR_API_KEY"오류: “Permission denied” (npm 전역 설치 실패)
# 방법 1: sudo 사용 (Linux/macOS)
sudo npm install -g @openai/codex
# 방법 2: npm 전역 디렉토리 변경 (권장)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH오류: 샌드박스 관련 경고 (Linux)
# Docker가 설치되어 있지 않으면 full-auto 샌드박스가 제한됨
# Docker 설치 후 재시도
sudo apt-get update && sudo apt-get install docker.io
sudo usermod -aG docker $USER오류: API 요금 한도 초과
OpenAI 대시보드에서 사용량을 확인하고, 필요시 결제 정보를 업데이트하거나 요금 한도를 조정합니다. o4-mini 모델은 o3보다 비용이 크게 낮으므로 일반 작업에는 기본 모델 사용을 권장합니다.
자주 묻는 질문 (FAQ)
Q1: Codex CLI는 무료로 사용할 수 있나요?
Codex CLI 도구 자체는 오픈소스(Apache 2.0)로 무료이지만, OpenAI API 호출 비용이 발생합니다. 기본 모델인 o4-mini는 상대적으로 저렴하며, 사용량에 따라 과금됩니다. OpenAI 대시보드에서 사용량 한도를 설정하여 비용을 관리할 수 있습니다.
Q2: full-auto 모드는 안전한가요?
full-auto 모드는 네트워크 접근이 차단된 샌드박스 환경에서 실행되므로 외부 시스템에 영향을 주지 않습니다. macOS에서는 Seatbelt, Linux에서는 Docker 컨테이너 격리를 사용합니다. 다만 처음에는 suggest 모드로 시작하여 동작을 확인한 후 단계적으로 권한을 높이는 것을 권장합니다.
Q3: 기존 프로젝트에서 Codex CLI를 사용하려면 어떻게 해야 하나요?
프로젝트 디렉토리로 이동한 후 codex 명령을 실행하면 됩니다. Codex는 자동으로 프로젝트의 파일 구조, 코드 스타일, 의존성을 분석합니다. 더 정확한 결과를 위해 프로젝트 루트에 AGENTS.md 파일을 작성하여 코딩 컨벤션, 사용 프레임워크, 특별한 규칙 등을 명시하면 AI가 프로젝트 맥락에 맞는 코드를 생성합니다.