2장: OpenAI Codex CLI - 터미널 AI 코딩 에이전트¶

Codex CLI가 뭔가요?¶

OpenAI Codex CLI는 터미널에서 바로 쓰는 AI 코딩 에이전트입니다.

OpenAI가 만든 오픈소스 프로젝트로, 터미널에 명령을 입력하면 AI가 코드를 읽고, 수정하고, 명령어를 실행해 줍니다. 마치 터미널 안에 코딩 친구가 앉아 있다고 생각하면 됩니다.

예전: 에디터에서 코딩 → 브라우저 켜서 ChatGPT → 코드 복사 → 다시 에디터에 붙여넣기
Codex: 터미널에서 "이 버그 고쳐줘" → AI가 바로 파일 수정 → 바로 실행까지

특징 한눈에 보기¶

특징	설명
오픈소스	누구나 코드를 보고 기여할 수 있음
터미널 기반	IDE나 브라우저 없이 터미널에서 바로 사용
파일 읽기/쓰기	프로젝트 파일을 직접 읽고 수정
명령어 실행	테스트 실행, 빌드 등 터미널 명령어도 대신 실행
샌드박스 보안	위험한 명령어는 안전한 환경에서만 실행

설치¶

사전 요구사항¶

Node.js 22 이상이 필요합니다. 설치되어 있는지 확인해 보세요.

node --version
# v22.x.x 이상이 나오면 OK!

Node.js가 없거나 버전이 낮다면 nodejs.org에서 설치하세요.

Windows¶

# 방법 1: npm (권장)
npm install -g @openai/codex

# 방법 2: WSL2 환경에서 사용 (권장)
# WSL2에서 Linux와 동일하게 설치
npm install -g @openai/codex

팁: Windows에서는 WSL2(Windows Subsystem for Linux 2) 환경에서 사용하는 걸 추천합니다. 샌드박스 보안 기능이 더 잘 동작합니다.

macOS¶

# 방법 1: npm (권장)
npm install -g @openai/codex

# 방법 2: Homebrew
brew install --cask codex

Linux¶

# npm으로 설치
npm install -g @openai/codex

참고: Full Auto 모드의 샌드박스 보안을 위해 Docker가 설치되어 있으면 더 안전합니다.

설치 확인¶

codex --version
# 버전 정보가 나오면 성공!

API 키 설정¶

Codex CLI를 쓰려면 OpenAI API 키가 필요합니다.

API 키 발급받기¶

platform.openai.com에 접속
회원가입 또는 로그인
API Keys 메뉴에서 "Create new secret key" 클릭
생성된 키 복사 (다시 볼 수 없으니 잘 보관!)

환경 변수로 설정¶

# 임시로 설정 (터미널을 닫으면 사라짐)
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"

# 영구 설정 - bash 사용자
echo 'export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

# 영구 설정 - zsh 사용자 (macOS 기본)
echo 'export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

ChatGPT 계정으로 로그인 (대안)¶

API 키 대신 ChatGPT 계정으로도 로그인할 수 있습니다.

codex --login
# 브라우저가 열리면 로그인하고 인증

참고: ChatGPT 계정 로그인은 사용량 제한이 있을 수 있습니다. 본격적으로 쓰려면 API 키를 설정하는 걸 추천합니다.

기본 사용법¶

원샷 모드 (One-shot)¶

명령어와 함께 질문을 바로 전달합니다. 결과만 빨리 보고 싶을 때 좋습니다.

# 간단한 질문
codex "Python으로 피보나치 수열 구하는 함수 만들어줘"

# 파일 수정 요청
codex "main.py의 버그를 찾아서 고쳐줘"

# 프로젝트 분석
codex "이 프로젝트 구조를 설명해줘"

대화형 모드 (Interactive)¶

터미널에서 대화하듯이 계속 질문하고 수정할 수 있습니다.

# 대화형 모드 시작
codex

# 프롬프트가 나오면 자유롭게 질문
> hello.py 파일을 만들어서 Hello World를 출력하는 코드를 작성해줘
> 이제 Korean도 추가해줘
> 테스트 코드도 만들어줘

대화형 모드에서 유용한 조작:

키	동작
`Enter`	메시지 전송
`Esc` `Esc`	입력 중인 내용을 에디터로 열어서 수정
`Ctrl+C`	현재 작업 취소
`Ctrl+C` (빈 줄)	종료

파일 읽기 / 쓰기 / 명령어 실행¶

Codex CLI는 세 가지 핵심 동작을 수행합니다.

파일 읽기   → AI가 프로젝트 코드를 읽고 이해
파일 쓰기   → AI가 직접 파일을 생성하거나 수정
명령어 실행 → 테스트, 빸드, lint 등 터미널 명령어 실행

# 파일 읽기 예시
codex "utils.py에 어떤 함수들이 있어?"

# 파일 쓰기 예시
codex "README.md 파일을 프로젝트에 맞게 만들어줘"

# 명령어 실행 예시
codex "테스트를 실행하고 실패한 테스트만 보여줘"

이전 세션 이어하기¶

# 이전 대화 세션 목록 보기
codex --history

# 가장 최근 세션 이어서 하기
codex --resume

# 특정 세션 이어서 하기
codex --resume <session-id>

권한 모드 (Approval Mode)¶

Codex CLI는 AI가 어디까지 허락할 건지 세 가지 모드를 제공합니다. 안전이 중요하니 꼭 이해하고 사용하세요.

Suggest 모드 (읽기 전용)¶

codex --approval-mode suggest

AI가 파일을 읽기만 하고 제안만 합니다
파일 수정이나 명령어 실행은 직접 해야 합니다
가장 안전한 모드

Auto Edit 모드 (파일 수정 허용)¶

codex --approval-mode auto-edit

AI가 파일을 직접 수정할 수 있습니다
터미널 명령어 실행은 여전히 사용자 승인이 필요합니다
코딩할 때 가장 많이 쓰는 모드

Full Auto 모드 (전체 허용)¶

codex --approval-mode full-auto

AI가 파일 수정 및 터미널 명령어까지 실행합니다
샌드박스(격리된 안전한 환경)에서 실행되어 시스템이 보호됩니다
반복적인 작업이나 CI/자동화에 유용

주의: Full Auto 모드에서는 네트워크 접근이 차단됩니다. npm install 같은 명령은 실행할 수 없습니다.

모드별 비교¶

모드	파일 읽기	파일 수정	명령어 실행	샌드박스	추천 상황
Suggest	가능	직접	직접	없음	처음 쓸 때, 코드 리뷰
Auto Edit	가능	AI가	승인 필요	없음	일반적인 코딩
Full Auto	가능	AI가	AI가	활성화	자동화, 반복 작업

샌드박스 보안¶

Full Auto 모드에서는 보안을 위해 샌드박스가 활성화됩니다:

운영체제	샌드박스 방식
macOS	Seatbelt (Apple 내장 보안)
Linux	Docker 컨테이너
Windows	WSL2 내부에서 Docker

샌드박스가 하는 일: - 파일 시스템 접근을 프로젝트 폴더로 제한 - 네트워크 접근 차단 - 시스템 명령어 실행 제한

# 샌드박스 옵션 직접 지정
codex --sandbox seatbelt    # macOS
codex --sandbox docker      # Linux/Docker
codex --sandbox none        # 샌드박스 끄기 (위험!)

주요 옵션¶

모델 선택 (--model / -m)¶

# 기본 모델 (o4-mini - 빠르고 경제적)
codex -m o4-mini "코드 리뷰해줘"

# 더 강력한 모델
codex -m o3 "이 알고리즘 최적화해줘"

# GPT-4.1 모델
codex -m gpt-4.1 "복잡한 리팩토링해줘"

모델	특징	추천 상황
o4-mini	빠르고 경제적 (기본값)	일반적인 코딩, 질문
o3	강력한 추론能力	복잡한 알고리즘, 버그 분석
gpt-4.1	긴 컨텍스트 처리	대규모 프로젝트 분석

권한 모드 (--approval-mode / -a)¶

# 짧은 옵션으로도 가능
codex -a suggest "이 코드 설명해줘"
codex -a auto-edit "버그 고쳐줘"
codex -a full-auto "테스트 모두 실행해줘"

이미지 입력 (--image / -i)¶

# 이미지 파일에서 코드 읽기
codex -i screenshot.png "이 화면의 코드를 작성해줘"

# 클립보드 이미지 붙여넣기
# 대화형 모드에서 이미지를 클립보드에 복사한 후 붙여넣기

스크린샷, 에러 화면, 디자인 시안 등을 AI가 보고 코드를 작성할 수 있습니다.

조용한 모드 (--quiet / -q)¶

# AI의 생각 과정을 숨기고 결과만 출력
codex -q "hello.py 만들어줘"

전체 컨텍스트 (--full-context / -f)¶

# 프로젝트 전체 파일을 한 번에 읽기
codex -f "이 프로젝트 전체 구조를 설명해줘"

참고: 큰 프로젝트에서는 시간이 오래 걸릴 수 있습니다. 작은 프로젝트에서만 사용하세요.

작업 디렉토리 지정¶

# 특정 폴더에서 실행
codex --cd /path/to/project "버그 찾아줘"

# 추가 디렉토리 포함
codex --add-dir ../shared-lib "이 라이브러리도 참고해서 작성해줘"

CI/자동화용 실행¶

# 대화 없이 한 번 실행하고 종료
codex exec "테스트를 실행하고 결과를 요약해줘"

# 스크립트에서 사용
codex exec -a full-auto "lint 에러를 모두 수정해줘"

AGENTS.md로 AI에게 지시사항 남기기¶

프로젝트 루트에 AGENTS.md 파일을 만들면, AI가 매번 새로 세션을 시작할 때 자동으로 읽습니다.

# AGENTS.md

## 프로젝트 규칙
- Python 3.12 사용
- Black 포매터 사용
- 테스트는 pytest로 작성
- 커밋 메시지는 Conventional Commits 형식

## 코드 스타일
- 타입 힌트 필수
- docstring은 Google 스타일
- 한 줄 최대 88자

AI가 이 파일을 읽고, 코딩할 때 이 규칙을 따릅니다. 팀 프로젝트에서 특히 유용합니다.

실전 예제¶

예제 1: 코드 생성¶

codex "FastAPI로 간단한 REST API를 만들어줘. 할 일(Todo) CRUD 기능이 필요해."

AI가 main.py, models.py, requirements.txt 등 필요한 파일들을 자동으로 만들어 줍니다.

예제 2: 리팩토링¶

codex "app.py의 process_data 함수가 너무 길어. 함수를 여러 개로 나눠줘."

기존 코드를 읽고, 적절히 분리해서 수정해 줍니다.

예제 3: 테스트 작성¶

codex "utils.py의 모든 함수에 대한 pytest 테스트를 작성해줘. 엣지 케이스도 포함해."

소스 코드를 분석해서 테스트 파일을 만들어 줍니다.

예제 4: 디버깅¶

codex "테스트가 실패하는데 원인을 찾아서 고쳐줘"

테스트를 실행해 보고, 에러 메시지를 읽고, 원인을 파악해서 수정까지 해 줍니다.

Claude Code와 비교¶

Codex CLI와 비슷한 도구로 Anthropic의 Claude Code가 있습니다. 객관적으로 비교해 봅시다.

항목	OpenAI Codex CLI	Claude Code
개발사	OpenAI	Anthropic
기본 모델	o4-mini	Claude Sonnet
오픈소스	네 (MIT 라이선스)	아니요
설치	npm	npm
IDE 연동	없음 (터미널 전용)	VS Code 확장 있음
파일 수정	가능	가능
명령어 실행	가능 (샌드박스)	가능
권한 모드	3단계 (Suggest/Auto/Full)	4단계 (Suggest/Auto-edit/Full-auto/YOLO)
이미지 입력	가능 (-i 플래그)	가능
MCP 지원	가능	가능
가격	API 사용량 과금	API 사용량 과금
AGENTS.md	지원	CLAUDE.md로 지원
CI/자동화	codex exec 명령어	headless 모드

Codex CLI가 좋을 때¶

오픈소스 도구를 선호할 때
OpenAI 모델(o3, o4-mini)을 쓰고 싶을 때
가볍고 빠른 터미널 에이전트가 필요할 때
샌드박스 보안이 중요할 때

Claude Code가 좋을 때¶

VS Code와 통합해서 쓰고 싶을 때
Claude 모델의 강점(코드 이해, 글쓰기)을 활용하고 싶을 때
더 세밀한 권한 제어가 필요할 때

결론: 둘 다 훌륭한 도구입니다. 상황에 따라 번갈아 쓰는 것도 좋은 방법입니다.

명령어 치트시트¶

# 기본 실행
codex                           # 대화형 모드 시작
codex "질문 내용"                # 원샷 모드
codex exec "명령"                # CI/자동화용 (비대화형)
codex --resume                  # 이전 세션 이어하기

# 모델 선택
codex -m o4-mini "질문"         # 기본 모델
codex -m o3 "질문"              # 강력한 모델
codex -m gpt-4.1 "질문"         # GPT-4.1

# 권한 모드
codex -a suggest "질문"         # 읽기 전용 (가장 안전)
codex -a auto-edit "질문"       # 파일 수정 허용
codex -a full-auto "질문"       # 전체 자동 (샌드박스)

# 입력/출력 옵션
codex -i image.png "질문"       # 이미지 입력
codex -q "질문"                  # 조용한 모드
codex -f "질문"                  # 전체 컨텍스트 읽기

# 디렉토리
codex --cd /path/to/dir         # 작업 디렉토리 지정
codex --add-dir /path/to/lib    # 추가 디렉토리 포함

# 설정
codex --login                   # ChatGPT 계정으로 로그인
codex --history                 # 세션 기록 보기
codex --sandbox docker          # 샌드박스 방식 지정

실습 미션¶

codex를 설치하고 codex --version으로 설치를 확인하세요
OpenAI API 키를 발급받고 환경 변수에 설정하세요
codex -a suggest로 Suggest 모드를 실행하고, "현재 디렉토리의 파일들을 설명해줘"라고 물어보세요
codex -a auto-edit으로 Auto Edit 모드를 실행하고, 간단한 Python 프로젝트를 만들어 보세요
AGENTS.md 파일을 만들고 코딩 규칙을 적어보세요
codex exec -a full-auto "echo hello"로 CI 모드를 테스트해 보세요
-i 옵션으로 이미지를 입력받아 코드를 생성해 보세요

이전 장: 01-claude-code.md 다음 장: 03-ai-tools-comparison.md - AI 코딩 도구 비교 가이드