OpenAI Codex CLI는 OpenAI가 2025년 중반에 출시한 터미널 AI 프로그래밍 어시스턴트입니다. 강력한 코드 생성 능력을 명령줄 환경으로 직접 가져왔습니다. Anthropic Claude Code와 경쟁하는 핵심 제품인 Codex CLI는 오픈소스 무료, 샌드박스 보안 모델, MCP 프로토콜 통합, 유연한 Profile 구성 체계 덕분에 2026년 개발자 도구 상자에서 필수 아이템으로 빠르게 자리 잡았습니다.
Codex CLI란 무엇인가?
단순히 “터미널 속 ChatGPT”가 아니다
Codex CLI를 처음 접하는 많은 개발자는 이를 단순히 “터미널에서 실행되는 ChatGPT”로 이해하곤 합니다. 하지만 이런 인식은 설계의 깊이를 심각하게 과소평가한 것입니다. Codex CLI는 완전한 **상호작용형 코드 에이전트(Code Agent)**입니다. 자연어 명령을 이해할 뿐만 아니라 다음과 같은 기능을 제공합니다.
- 프로젝트 컨텍스트 읽기: 현재 디렉토리의 파일 구조, 의존 관계, 코드 스타일을 자동으로 분석합니다
- 다단계 작업 실행: 요구사항 분석부터 코드 구현, 테스트 검증까지 완전한 워크플로우를 형성합니다
- 안전한 샌드박스 격리: 3단계 샌드박스 모드와 4단계 승인 전략으로 AI 작업이 시스템을 손상시키지 않도록 보장합니다
- 세션 지속성: 세션 복구, 분기 실험, 이력 추적을 지원하여 작업 진행 상황을 잃지 않도록 합니다
핵심 아키텍처 설계
Codex CLI는 Rust로 개발되었으며 모듈식 아키텍처를 채택했습니다.
codex-cli/
├── core/ # 코어 엔진: 모델 호출, 컨텍스트 관리
├── sandbox/ # 샌드박스 레이어: 파일 시스템 격리, 명령 실행 제한
├── mcp/ # MCP 프로토콜 통합: 외부 도구 연결
├── config/ # 구성 시스템: Profile 관리, 별칭 해석
└── ui/ # 상호작용 인터페이스: TUI, 슬래시 명령어 파싱이러한 설계로 Codex CLI는 경량을 유지하면서도 기업 수준의 보안성과 확장성을 갖추었습니다. 기존 IDE 플러그인과 비교했을 때 장점은 다음과 같습니다.
- 에디터 종속성 없음: Vim, Emacs, VS Code 중 무엇을 선호하든 터미널에서 원활하게 사용할 수 있습니다
- 원격 친화적: SSH로 연결된 서버나 Docker 컨테이너에서도 동일하게 원활하게 실행됩니다
- 낮은 리소스 점유율: Rust로 작성된 바이너리 파일은 시작 속도가 빠르며 메모리 점유율이 Electron 애플리케이션보다 훨씬 낮습니다
설치 및 기본 구성
네 가지 설치 방법
1. npm 설치 (대부분의 사용자에게 권장)
npm install -g @openai/codex가장 일반적인 설치 방식입니다. macOS, Linux, Windows(WSL2)에서 모두 사용 가능합니다. 설치가 완료되면 codex --version을 실행하여 설치가 성공했는지 확인하세요.
2. Homebrew 설치 (macOS 사용자首选)
brew install --cask codexHomebrew 설치의 장점은 의존성과 PATH 구성을 자동으로 처리한다는 점입니다. 업그레이드 시에는 brew upgrade codex만 실행하면 됩니다.
3. 바이너리 파일 다운로드
GitHub Releases에서 해당 플랫폼의 사전 컴파일된 바이너리 파일을 다운로드하세요.
- macOS Apple Silicon:
codex-macos-arm64 - macOS Intel:
codex-macos-x86_64 - Linux x86_64:
codex-linux-x86_64 - Linux ARM64:
codex-linux-arm64 - Windows:
codex-windows-x86_64.exe
다운로드 후 실행 권한을 부여하고 PATH 디렉토리로 이동하세요.
chmod +x codex-linux-x86_64
sudo mv codex-linux-x86_64 /usr/local/bin/codex4. WSL2 설치 (Windows 사용자)
Windows 네이티브 지원은 아직 개선 중입니다. WSL2(Windows Subsystem for Linux)를 통해 설치하는 것이 좋습니다.
# WSL2 Ubuntu에서
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g @openai/codex인증 방식: ChatGPT 구독 vs API Key
Codex CLI는 두 가지 인증 방식을 지원합니다. 각각 적합한 사용 사례가 있습니다.
ChatGPT 구독 로그인 (개인 사용자에게 적합)
ChatGPT Plus, Pro, Team, Edu 또는 Enterprise 구독을 보유하고 있다면 브라우저를 통해 직접 로그인할 수 있습니다.
codex login기본 브라우저가 열리고 OAuth 승인을 완료하면 토큰이 자동으로 저장됩니다. 구독 사용자의 혜택:
- Plus 사용자: 월 $5 무료 API 한도 (30일 롤링)
- Pro 사용자: 월 $50 무료 API 한도 (30일 롤링)
한도를 초과하면 표준 API 가격으로 청구됩니다.
API Key 환경 변수 (팀/자동화에 적합)
팀 협업이나 CI/CD 통합에는 API Key를 사용하는 것이 좋습니다.
export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx"이 줄을 ~/.bashrc 또는 ~/.zshrc에 추가하여 영구적으로 적용하세요. API Key는 OpenAI Platform에서 생성하고 관리할 수 있습니다.
보안 팁: API Key를 코드 저장소에 하드코딩하지 마세요. .env 파일이나 키 관리 서비스를 사용하는 것이 좋습니다.
시스템 요구사항 및 사전 점검
설치 전에 시스템이 다음 요구사항을 충족하는지 확인하세요.
| 구성 요소 | 최소 버전 | 권장 버전 |
|---|---|---|
| Node.js | 18.x | 20.x LTS |
| npm | 9.x | 10.x |
| Git | 2.x | 2.40+ |
| 운영체제 | macOS 12+/Ubuntu 20.04+/WSL2 | 최신 안정판 |
다음 명령을 실행하여 사전 조건을 확인하세요.
node --version # v18.x 이상 출력 필요
npm --version # 9.x 이상 출력 필요
git --version # git version 2.x 출력 필요Node.js 버전이 너무 낮다면 Node.js 공식 사이트에서 최신 LTS 버전을 다운로드하여 설치하세요.
세 가지 작동 모드详解
Codex CLI는 세 가지 작동 모드를 제공합니다. 각각 다른 자동화 수준과 보안级别에 해당합니다.
suggest 모드 (가장 안전)
codex --mode suggestsuggest 모드에서 Codex는 코드 제안과 설명만 제공합니다. 어떤 파일도 자동으로 수정하지 않습니다. 제안된 코드를 수동으로 복사하여 프로젝트에 적용해야 합니다.
적합한 상황:
- 새 프레임워크를 배우면서 각 단계의 원리를 이해하고 싶을 때
- 민감한 코드 변경을 검토하기 전에 수동 확인이 필요할 때
- Codex를 처음 사용하여 출력 스타일에 익숙해지고 싶을 때
예시:
$ codex --mode suggest
> React Todo 컴포넌트 생성
[CODEx] 다음 파일 구조를 생성하는 것을 제안합니다:
- src/components/TodoList.jsx
- src/components/TodoItem.jsx
- src/hooks/useTodos.js
다음은 TodoList.jsx의 내용입니다:
[code block...]
이 파일들을 수동으로 생성하거나 auto-edit 모드로 전환하여 자동으로 작성하도록 할 수 있습니다.auto-edit 모드 (균형)
codex --mode auto-editauto-edit는 기본 모드입니다. Codex가 파일을 자동으로 편집하지만 부작용이 있을 수 있는 명령(예: rm, git push)을 실행할 때는 확인을 요청합니다.
적합한 상황:
- 일상적인 개발 워크플로우
- AI가 코드를 빠르게 반복하지만 핵심 작업의 승인권을 유지하고 싶을 때
- 중간 복잡도 프로젝트의 리팩토링
예시:
[CODEx] src/components/TodoList.jsx를 생성하겠습니다... ✓
[CODEx] src/components/TodoItem.jsx를 생성하겠습니다... ✓
[CODEx] npm install react-icons를 실행해야 합니다. 계속하시겠습니까? [Y/n]full-auto 모드 (가장 빠름)
codex --mode full-autofull-auto 모드에서 Codex는 파일 편집과 명령 실행을 포함한 모든 작업을 완전히 자동으로 수행합니다. 확인 없이 실행됩니다. 가장 효율적이지만 가장 위험한 모드입니다.
적합한 상황:
- 격리된 개발 환경(예: Docker 컨테이너)
- Codex의 판단을 충분히 신뢰하고 극致的 효율을 추구할 때
- 일괄 코드 생성 작업
경고: 프로덕션 환경에서 full-auto를 사용하기 전에 반드시 샌드박스 모드를 구성하여 권한 범위를 제한하세요.
샌드박스 보안 모델 심층解析 ⭐차별화 포인트
샌드박스(Sandbox)는 Codex CLI의 핵심 보안 메커니즘입니다. 파일 시스템과 명령 실행 권한을 격리하여 AI의 오작동이나 악의적인 행동으로 인한 시스템 손상을 방지합니다. 샌드박스 모델을 이해하는 것은 Codex를 프로덕션급으로 사용하는 데 핵심적입니다.
세 가지 샌드박스 모드 비교
Codex는 3단계 샌드박스 모드를 제공합니다. --sandbox 매개변수로 지정합니다.
| 모드 | 파일 시스템 권한 | 명령 실행 | 적합 상황 |
|---|---|---|---|
read-only | 읽기 전용, 모든 쓰기 금지 | 읽기 전용 명령 허용(ls, cat, grep) | 코드 검토, 문서 분석 |
workspace-write | 현재 프로젝트 디렉토리에서만 쓰기 허용 | 일반 명령 허용, 시스템级 작업 금지 | 일상 개발(권장) |
danger-full-access | 완전 읽기/쓰기 권한 | 모든 명령 허용 | 격리 환경, 실험적 작업 |
기본 모드: workspace-write. 보안성과 편의성 사이의 균형을 맞춥니다.
read-only 모드 실전
codex --sandbox read-only
> 이 프로젝트의 아키텍처 분석
[CODEx] src/ 디렉토리 구조를 읽고 있습니다...
[CODEx] 다음 모듈을 발견했습니다:
- auth/ (인증)
- api/ (REST API)
- components/ (UI 컴포넌트)
read-only 모드이므로 파일을 수정할 수 없습니다. 리팩토링이 필요하면 workspace-write 모드로 전환하세요.workspace-write 모드 (권장)
codex --sandbox workspace-write
> auth 모듈 리팩토링, JWT 갱신 토큰 추가
[CODEx] src/auth/token.js를 수정하겠습니다... ✓
[CODEx] src/auth/refresh.js를 생성하겠습니다... ✓
[CODEx] 변경 사항을 검증하기 위해 테스트를 실행합니다... ✓이 모드에서 Codex는 현재 작업 디렉토리와 하위 디렉토리의 파일만 수정할 수 있습니다. /etc, /usr 등의 시스템 디렉토리에는 접근할 수 없습니다.
danger-full-access 모드 (주의해서 사용)
codex --sandbox danger-full-access
> 모든 node_modules 디렉토리 정리
[CODEx] 경고: 이 작업은 여러 디렉토리를 삭제합니다. 계속하시겠습니까? [Y/n]다음 상황에서만 사용하세요:
- Docker 컨테이너 내 임시 환경
- 전용 샌드박스 가상 머신
- Codex의 판단을 완전히 신뢰하며 중요 데이터를 백업한 경우
승인 전략 4단계 세분화
샌드박스 모드 외에도 Codex는 세밀한 명령 승인 전략을 제공합니다. --ask-for-approval 매개변수로 제어합니다.
| 전략 | 동작 | 적합 상황 |
|---|---|---|
untrusted | 신뢰할 수 없는 명령만 승인 필요(기본값) | 일상 개발 |
on-failure | 명령 실패 시에만 승인 요청 | 디버깅 상황 |
on-request | Codex가主動 요청할 때만 승인 | AI를高度로 신뢰할 때 |
never | 승인 요청 안 함 | 샌드박스와 함께 사용 |
신뢰할 수 없는 명령의 정의:
- 네트워크 작업 관련(
curl,wget) - 패키지 관리 관련(
npm install,pip install) - 버전 관리 관련(
git push,git reset --hard) - 시스템 구성 관련(
sudo,chmod)
조합 사용 예시
# 가장 안전한 조합: 읽기 전용 샌드박스 + 엄격한 승인
codex --sandbox read-only --ask-for-approval untrusted
# 효율적인 조합: 작업 공간 쓰기 + 실패 시 승인
codex --sandbox workspace-write --ask-for-approval on-failure
# 완전 자동 조합: 위험 샌드박스 + 승인 안 함(격리 환경 전용)
codex --sandbox danger-full-access --ask-for-approval never—full-auto vs —yolo의 본질적 차이
많은 사용자가 --mode full-auto와 --yolo 매개변수를 혼동합니다.但它们的作用层面不同:
--mode full-auto: Codex가 코드 편집에 대해 사용자 확인이 필요한지 제어--yolo: 모든 명령 실행 승인 프롬프트 건너뛰기(--ask-for-approval never와 동일)
# 다음 두 명령은 효과가 동일합니다
codex --mode full-auto --yolo
codex --mode full-auto --ask-for-approval never명칭 유래: “Yolo”는 유행어 “You Only Live Once”에서 유래했습니다. 기술 커뮤니티에서는 종종 “결과를 고려하지 않고 실행”을 의미하는 데 사용됩니다. OpenAI는 이 유머러스한 명칭으로 사용자에게 이 모드에 위험이 있으니 주의해서 사용하라고 상기시킵니다.
프로덕션 환경의 보안 모범 사례
프로덕션 환경에서 Codex CLI를 사용할 때는 다음 보안 지침을 따르는 것이 좋습니다.
- 기본적으로
workspace-write샌드박스 사용: AI가 현재 프로젝트 파일만 수정하도록 제한 - Git 통합 활성화: AI가 수정할 때마다 자동 커밋하여 롤백 용이
- Transcripts 정기 검토: Codex는 모든 상호작용과 작업 로그를 기록합니다
- 민감한 작업은 수동 실행: 데이터베이스 마이그레이션, 프로덕션 배포 등 핵심 단계는 AI에 맡기지 마세요
- Profile로 환경 격리: 각 프로젝트에 다른 보안 전략 구성
# 프로덕션 프로젝트 구성 예시
codex --profile production --sandbox workspace-write --ask-for-approval untrusted
# 실험 프로젝트 구성 예시
codex --profile experimental --sandbox danger-full-access --yolo24개 슬래시 명령어 완전解析 ⭐차별화 포인트
Codex CLI는 24개의 슬래시 명령어(Slash Commands)를 제공합니다. 세션 제어, 모델 전환, 권한 관리, 파일 작업 등 여러 차원을 커버합니다. 이러한 명령어를 숙달하면 작업 효율을 크게 향상시킬 수 있습니다.
세션 제어(/new, /resume, /fork, /compact)
/new - 새 세션 시작
/new현재 컨텍스트를 지우고 완전히 새로운 대화를 시작합니다. 작업 전환이나 이력 간섭 제거에 적합합니다.
/resume - 이력 세션 복구
/resume상호작용형 세션 선택기를 열어 모든 이력 세션을 나열합니다. 날짜, 디렉토리별로 필터링할 수 있습니다. 자세한 내용은 뒤의 “세션 복구” 장을 참조하세요.
/fork - 분기 실험
/fork현재 세션의 사본을 생성합니다. 메인 세션에 영향을 주지 않고 새 브랜치에서 다양한 해결책을 시도할 수 있습니다. 다음과 같은 상황에 적합합니다.
- 여러 구현方案 비교
- 실험적 리팩토링. 실패 시 쉽게 폐기 가능
- 병렬로 다른 아키텍처 설계 탐색
> /fork
[CODEx] 세션 브랜치 fork-2026-06-07-14-30을 생성했습니다
> Redux로 Context API 대체 시도
[CODEx] 브랜치에서 상태 관리를 리팩토링하겠습니다.../compact - 컨텍스트 압축
/compact세션 이력이 너무 길어져 token 소모가 급증할 때 /compact를 사용하여 컨텍스트를 압축합니다. 핵심 정보를 유지하고 불필요한 대화를 제거합니다. 이는 후속 호출 비용을 효과적으로 낮출 수 있습니다.
모델 및 스타일(/model, /personality, /plan)
/model - 모델 전환
/model gpt-5실행 중에 사용할 모델을 전환합니다. 사용 가능한 모델은 다음과 같습니다.
gpt-5.3-codex(기본값, 코드 최적화 전용)gpt-5(범용 플래그십 모델)o4-mini(경량 추론 모델, 비용 낮음)
> /model o4-mini
[CODEx] o4-mini 모델로 전환했습니다. 이 모델은 간단한 작업에 적합합니다. 추론 능력은 약하지만 비용이 더 낮습니다./personality - AI 성격 조정
/personality conciseCodex의 답변 스타일을 조정합니다.
concise: 간결하고 직설적, 설명 적음verbose: 상세한 설명, 학습에 적합professional: 공식적인 어조, 문서 생성에 적합friendly: 친근하고轻松, 일상 대화에 적합
/plan - 실행 계획 생성
/planCodex에게 상세한 실행 계획을 먼저 출력하도록 한 다음 단계적으로 시행하도록 합니다. 복잡한 작업에 적합하며 잠재적 문제를 조기에 발견하는 데 도움이 됩니다.
> /plan
> 전체 인증 모듈 리팩토링, OAuth2 지원 추가
[CODEx] 실행 계획:
1. 기존 auth/ 디렉토리 구조 분석
2. OAuth2 흐름 설계(Authorization Code Grant)
3. oauth2/ 하위 모듈 생성
4. 로그인 인터페이스 수정, 전통 비밀번호와 OAuth2 호환
5. 테스트 케이스 업데이트
6. 마이그레이션 문서 생성
실행을 시작하시겠습니까? [Y/n]권한 및 상태(/permissions, /status, /debug-config)
/permissions - 현재 권한 보기
/permissions현재 샌드박스 모드와 승인 전략 구성을 표시합니다.
> /permissions
[CODEx] 현재 권한 구성:
- Sandbox: workspace-write
- Approval Policy: untrusted
- Yolo Mode: disabled/status - 세션 상태 보기
/status현재 세션의 상세 정보를 표시합니다. 포함 내용:
- 사용 중인 모델과 추론等级
- Token 사용량 통계
- 세션 지속 시간
- 실행된 작업 수
> /status
[CODEx] 세션 상태:
- Model: gpt-5.3-codex (reasoning: high)
- Tokens: 12,450 input / 3,200 output
- Duration: 45 minutes
- Operations: 23 file edits, 8 commands executed/debug-config - 구성 로드 체인 진단
/debug-config구성 문제排查의神器입니다. Codex가 구성 파일을 어떻게 로드하는지 표시합니다. 포함 내용:
- 전역 구성 경로(
~/.codex/config.toml) - 프로젝트 구성 경로(
.codex/config.toml) - 환경 변수覆盖
- Profile 활성화 상태
- 최종生效 구성 값
> /debug-config
[CODEx] 구성 로드 체인:
1. 전역 구성: /home/user/.codex/config.toml ✓
2. 프로젝트 구성: /path/to/project/.codex/config.toml ✓
3. 환경 변수: OPENAI_API_KEY set ✓
4. Active Profile: production
5. Final Config:
- model: gpt-5.3-codex
- sandbox_mode: workspace-write
- approval_policy: untrusted파일 및 도구(/mention, /diff, /review, /mcp)
/mention - 특정 파일 인용
/mention src/auth/token.jsCodex가 특정 파일을 강제로 주목하도록 합니다. 현재 컨텍스트에 없어도 됩니다. 대형 프로젝트에서 핵심 파일을定位하는 데 적합합니다.
/diff - 변경 사항差异 보기
/diff세션 시작 이후 모든 파일 변경 사항의差异对比를 표시합니다. AI의 수정이 예상대로인지 검토하는 데 편리합니다.
/review - 코드 리뷰
/reviewCodex에게 최근 코드 변경 사항을 리뷰하도록 합니다. 잠재적 문제, 성능 병목, 보안 위험을 지적합니다.
> /review
[CODEx] 코드 리뷰 보고서:
✓ 장점:
- async/await를 올바르게 사용하여 비동기 작업 처리
-完善的 오류 처리 추가
⚠ 개선 제안:
- token.js 45행: 입력 검증 누락. 인젝션 공격 가능성
- refresh.js 12행: HttpOnly 플래그 미설정. XSS 위험
🔴 심각한 문제:
- 하드코딩된 JWT 키. 환경 변수 사용 필요/mcp - MCP 서버 관리
/mcp list구성된 Model Context Protocol(MCP) 서버를 나열합니다. MCP를 통해 Codex는 GitHub, 데이터베이스, 모니터링 플랫폼 등 외부 도구에 연결할 수 있습니다. 자세한 내용은 뒤의 “MCP 프로토콜 통합” 장을 참조하세요.
기타 유용한 명령어
| 명령어 | 기능 |
|---|---|
/init | 프로젝트 구성 초기화, .codex/config.toml 생성 |
/feedback | OpenAI에 피드백 전송 |
/logout | 로그아웃, 인증 토큰清除 |
/quit | Codex CLI 종료 |
/statusline | 터미널 상태 표시줄 사용자 정의 |
/ps | 백그라운드에서 실행 중인 작업 보기 |
/apps | 통합된 애플리케이션 관리 |
세션 복구: 작업 진행 상황을 잃지 않음 ⭐차별화 포인트
세션 복구는 Codex CLI에서 심각하게 과소평가된 기능 중 하나입니다. 기존 터미널 도구에서는 터미널을 닫으면 모든 컨텍스트가 손실됩니다. 하지만 Codex는 Transcripts 메커니즘을 통해 세션의 지속성과 유연한 복구를 구현했습니다.
네 가지 복구 방식
1. 상호작용형 선택기(권장)
codex resume상호작용형 인터페이스를 열어 모든 이력 세션을 나열합니다. 다음을 지원합니다.
- 날짜순 정렬
- 디렉토리별 필터링
- 키워드 검색
- 세션 요약 미리보기
$ codex resume
복구할 세션 선택:
1. [2026-06-07 14:30] refactor auth module (12 ops)
2. [2026-06-07 10:15] create React todo app (8 ops)
3. [2026-06-06 16:45] debug API endpoint (5 ops)
> 1
[CODEx] 세션 복구됨: refactor auth module2. 마지막 세션 복구
codex resume --last상호작용형 선택 없이 가장 최근에 사용한 세션을 빠르게 복구합니다. 중단 후 작업을 계속하는 상황에 적합합니다.
3. 특정 세션 복구
codex resume <SESSION_ID>세션 ID를 통해 정확히 복구합니다. 세션 ID는 /status 명령어 출력에서 찾을 수 있거나 Transcripts 디렉토리에서 확인할 수 있습니다.
codex resume sess_abc123def4564. 모든 디렉토리에서 세션 복구
codex resume --all모든 디렉토리의 이력 세션을 나열합니다. 여러 프로젝트 간 전환 상황에 적합합니다.
복구 시 무엇이 보존되는가?
세션 복구 시 Codex는 다음 상태를 재구축합니다.
- 대화 이력: 이전 모든 질문과 답변 기록
- 파일 컨텍스트: 읽히고 수정된 파일 목록
- 모델 구성: 사용 중인 모델과 추론等级
- 샌드박스 권한: 현재 보안 구성
- 미완료 작업: 이전에 다단계 작업을 실행 중이었다면 중단점에서 계속
보존되지 않는 내용:
- 임시 변수或未保存的中间结果
- 외부 명령 실행 상태(예: 실행 중인 서버)
실용 상황案例
상황 1: 중단 후 작업 계속
# 오전에 인증 모듈 리팩토링 시작
$ codex
> auth 모듈 리팩토링, JWT 갱신 토큰 추가
[CODEx] 기존 코드 분석 중...
# 갑자기 회의 필요. Ctrl+C로 종료
# 오후에 돌아와서 직접 복구
$ codex resume --last
[CODEx] 세션 복구됨. 지난번에 auth/token.js를 분석했습니다. 이제 refresh.js를 생성하겠습니다...상황 2: 여러方案 비교
# 메인 세션: Context API 사용
$ codex
> 상태 관리 구현
[CODEx] Context API를 사용하겠습니다...
# 분기 실험: Redux 시도
> /fork
[CODEx] 브랜치 생성됨. 이제 Redux方案을 시도합니다...
# 비교 후 메인 세션 유지, 브랜치 폐기상황 3: 장기 프로젝트의 점진적 개발
# 첫날: 프로젝트 골격 구축
$ codex
> Next.js 프로젝트 구조 생성
[CODEx] 완료...
# 둘째날: 세션 복구, 개발 계속
$ codex resume --last
[CODEx] 돌아오신 것을 환영합니다. 어제 프로젝트 구조를 생성했습니다. 오늘 페이지 컴포넌트 구현을 계속하겠습니다...프로덕션급 구성方案 ⭐차별화 포인트
Codex CLI의 구성 시스템은 매우 유연합니다. 전역 구성, 프로젝트 구성, Profile 다중场景 구성을 지원합니다. 적절한 구성은 작업 효율성과 보안성을 크게 향상시킬 수 있습니다.
별칭 구성: 한 명령으로 시작 매개변수 해결
자주 사용하는 시작 매개변수 조합은 shell 별칭을 통해 명령을 단순화할 수 있습니다.
# ~/.bashrc 또는 ~/.zshrc
alias codex-safe='codex --sandbox read-only --ask-for-approval untrusted'
alias codex-dev='codex --sandbox workspace-write --mode auto-edit'
alias codex-yolo='codex --sandbox danger-full-access --yolo'사용법:
codex-safe # 안전 검토 모드
codex-dev # 일상 개발 모드
codex-yolo # 실험 모드(주의!)Profile 다중场景 구성(더 우아한方案)
별칭은 간단하지만 유연성이 부족합니다. Codex의 Profile 시스템을 사용하면 구성 파일에 여러场景을 정의하고 --profile 매개변수로 한 번에 전환할 수 있습니다.
구성 파일 구조
전역 구성 파일은 ~/.codex/config.toml에 위치합니다. 프로젝트 구성 파일은 .codex/config.toml에 위치합니다.
# ~/.codex/config.toml
# 기본 구성
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
web_search = "live"
sandbox_mode = "workspace-write"
approval_policy = "untrusted"
# Profile: 코드 검토(읽기 전용, 엄격한 승인)
[profiles.review]
sandbox_mode = "read-only"
approval_policy = "untrusted"
model_reasoning_effort = "medium"
# Profile: 빠른 프로토타입(경량 모델, 저비용)
[profiles.quick]
model = "o4-mini"
model_reasoning_effort = "low"
web_search = "disabled"
sandbox_mode = "workspace-write"
# Profile: 프로덕션 환경(안전 우선)
[profiles.production]
sandbox_mode = "workspace-write"
approval_policy = "on-failure"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
# Profile: 실험 환경(완전 자동, 고위험)
[profiles.experimental]
sandbox_mode = "danger-full-access"
approval_policy = "never"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"Profile 사용
# 코드 검토场景
codex --profile review
# 빠른 프로토타입场景
codex --profile quick
# 프로덕션 프로젝트
codex --profile production
# 실험 프로젝트
codex --profile experimental프로젝트級 구성覆盖
프로젝트 루트 디렉토리에 .codex/config.toml을 생성하여 전역 구성을覆盖할 수 있습니다.
# my-project/.codex/config.toml
# 이 프로젝트는 읽기 전용 샌드박스强制 사용
sandbox_mode = "read-only"
# 이 프로젝트는 네트워크 검색禁用
web_search = "disabled"Codex의 구성 로드 우선순위: 프로젝트 구성 > Profile 구성 > 전역 구성 > 기본값.
debug-config로 구성 로드 체인 진단
구성이 예상대로生效되지 않을 때 /debug-config 명령어로 진단하세요.
> /debug-config
[CODEx] 구성 로드 체인:
1. 전역 구성: /home/user/.codex/config.toml ✓
- model: gpt-5.3-codex
- sandbox_mode: workspace-write
2. 프로젝트 구성: /path/to/project/.codex/config.toml ✓
- sandbox_mode: read-only (전역 구성覆盖)
3. Active Profile: review
- approval_policy: untrusted
4. 환경 변수:
- OPENAI_API_KEY: set ✓
- CODEX_MODEL: not set
5. Final Config:
- model: gpt-5.3-codex (전역 구성에서)
- sandbox_mode: read-only (프로젝트 구성에서, 우선순위 더 높음)
- approval_policy: untrusted (Profile에서)이 출력을 통해 각 구성 값의 출처를 명확히 볼 수 있어 문제를 빠르게定位할 수 있습니다.
모델 전환 및 추론等级
기본 모델 gpt-5.3-codex
Codex CLI는 기본적으로 gpt-5.3-codex 모델을 사용합니다. 이는 OpenAI가 코드 생성을 위해 특별히 최적화한 변형 버전입니다. 다음과 같은 특징이 있습니다.
- 코드 이해 능력 강함: 여러 프로그래밍 언어와 프레임워크에 대한 깊은 이해
- 큰 컨텍스트 창: 긴 파일과 복잡한 프로젝트 구조 분석 지원
- 높은 추론 효율: 코드 작업에 최적화된 추론 경로
런타임 중 모델 전환
/model 명령어 또는 구성 파일을 통해 모델을 전환합니다.
# 범용 플래그십 모델로 전환
/model gpt-5
# 경량 모델로 전환
/model o4-mini각 모델의 적합 상황:
| 모델 | 적합 상황 | 비용 |
|---|---|---|
gpt-5.3-codex | 복잡한 코드 생성, 리팩토링, 디버깅 | 높음 |
gpt-5 | 범용 작업, 문서 생성, 아키텍처 설계 | 높음 |
o4-mini | 간단한 작업, 빠른 프로토타입, 저비용场景 | 낮음 |
추론等级 선택 전략(high/medium/low)
추론等级(Reasoning Effort)는 모델이 답변 생성 전에 생각하는 깊이를 제어합니다.
| 等级 | 동작 | 적합 상황 | Token 소모 |
|---|---|---|---|
high | 심층 분석, 다단계 추론 | 복잡한 알고리즘, 아키텍처 설계, 난해한 bug | 높음 |
medium | 속도와 품질 균형 | 일상 개발,常规 리팩토링 | 중간 |
low | 빠른 응답, 얕은 추론 | 간단한 작업, 문법 수정, 템플릿 생성 | 낮음 |
구성 파일에서 설정:
model_reasoning_effort = "high" # 또는 "medium", "low"런타임 중 전환:
> /reasoning high
[CODEx] high 추론等级로 전환했습니다. 이후 답변은 더 심층적인 분석을 수행합니다.비용 최적화: 한 달에 token 절반 절약하는 방법
모델과 추론等级을 합리적으로 사용하면 비용을 크게 절감할 수 있습니다.
-
간단한 작업에는 o4-mini + low 추론 사용:
codex --profile quick # o4-mini + low 사용 -
복잡한 작업에만 gpt-5.3-codex + high 추론 사용:
codex --profile production # gpt-5.3-codex + high 사용 -
정기적으로 /compact로 컨텍스트 압축: 불필요한 대화 이력 제거
-
ChatGPT 구독 한도 활용: Plus/Pro 사용자의 무료 한도优先 사용
-
불필요한 네트워크 검색回避:
web_search = "disabled"설정으로 추가 호출 감소
절감 효과 추정:
- 간단한 작업의 50%를
gpt-5.3-codex + high에서o4-mini + low로 전환하면 token 비용을 약 60-70% 절감할 수 있습니다 - 구독 한도와 결합하면 개인 사용자의 월평균 비용을 $10-20 이내로 통제할 수 있습니다
MCP 프로토콜 통합: 외부 도구 연결
Model Context Protocol(MCP)은 Anthropic이 제안한 개방형 프로토콜입니다. AI 어시스턴트가 외부 도구와 데이터 소스에 연결할 수 있도록 합니다. Codex CLI는 MCP 통합을 통해 GitHub, 데이터베이스, 모니터링 플랫폼 등 외부 리소스에 접근할 수 있어 능력 범위를 크게 확장합니다.
MCP란 무엇인가?
MCP의 핵심 아이디어는 다음과 같습니다. AI 어시스턴트는 자체 지식에 국한되지 않고 외부 시스템의 최신 데이터에 실시간으로 접근할 수 있어야 합니다. MCP 서버를 통해 Codex는 다음과 같은 작업을 수행할 수 있습니다.
- GitHub 저장소의 Issues와 Pull Requests 읽기
- PostgreSQL 데이터베이스의 기록查询
- Sentry의 오류 로그获取
- Slack 채널의 메시지 접근
GitHub/Sentry/데이터베이스 MCP 서버 구성
~/.codex/config.toml에서 MCP 서버를 구성합니다.
[mcp_servers]
# GitHub MCP 서버
github = { command = "npx", args = ["-y", "@modelcontextprotocol/server-github"] }
# PostgreSQL MCP 서버
postgres = { command = "npx", args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"] }
# Sentry MCP 서버
sentry = { command = "npx", args = ["-y", "@modelcontextprotocol/server-sentry"] }
# 파일 시스템 MCP 서버(샌드박스 능력 확장)
filesystem = { command = "npx", args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"] }실전: MCP로 Codex 능력 확장
상황 1: GitHub Issue 분석
codex --mcp github
> repo:openai/codex의 최근 bug report 분석
[CODEx] GitHub MCP를 통해查询...
[CODEx] 최근 bug report 5개를 찾았습니다:
1. #123: Session restore fails on Windows
2. #124: Sandbox permission leak in workspace-write mode
3. ...
#123 문제를 상세히 분석하겠습니다...상황 2: 데이터베이스查询
codex --mcp postgres
> users 테이블에서 최근 가입한 사용자查询
[CODEx] PostgreSQL MCP를 통해查询 실행...
[CODEx] 결과:
- user_id: 1001, email: alice@example.com, created_at: 2026-06-07
- user_id: 1002, email: bob@example.com, created_at: 2026-06-06상황 3: Sentry 오류排查
codex --mcp sentry
> 최근 24시간 critical errors 분석
[CODEx] Sentry MCP를 통해查询...
[CODEx] critical error 3개를 발견했습니다:
1. TypeError: Cannot read property 'token' of undefined (auth/token.js:45)
2. ...
수정方案 제안: token 속성에 접근하기 전 null 값检查 추가...MCP 서버 보기 및 관리
# 구성된 MCP 서버 나열
/mcp list
# 특정 서버 활성화/비활성화
/mcp enable github
/mcp disable postgres
# 서버 상태 보기
/mcp statusCodex CLI vs Claude Code 전면 비교
Codex CLI와 Claude Code는 모두 터미널 AI 프로그래밍 어시스턴트의 대표 제품입니다. 각각 장단점이 있습니다. 다음은 전면 비교입니다.
기능 비교 테이블
| 차원 | Claude Code | Codex CLI |
|---|---|---|
| 사용자 정의 구성 | 상태 표시줄, 프롬프트, 출력 스타일 지원 | Profile 다중场景 구성, 추론等级 세밀 제어 |
| 시각적 컨텍스트 | 이미지 입력 지원 | Ctrl+V로 이미지 붙여넣기 지원 |
| 세션 관리 | 세션 복구, 백그라운드 작업 | /resume, /fork, Transcripts 기록 |
| 보안성 | 내장 보안审查 | 샌드박스 3단계 모드 + 승인 4단계 세분화 |
| 특수 모드 | Vim 모드 | —yolo 완전 자동(위험 모드) |
| MCP 통합 | 네이티브 지원 | 구성 파일을 통한 통합 |
| 오픈소스 상태 | 클로즈드 소스 | 오픈소스(Apache 2.0) |
| 모델 선택 | Claude 모델만 | gpt-5.3-codex, gpt-5, o4-mini |
| 커뮤니티 생태계 | Anthropic 공식 지원 | GitHub 39K+ Stars, 활발한 커뮤니티 |
가격 비교
| 항목 | Claude Code | Codex CLI |
|---|---|---|
| 도구 자체 | 무료 | 무료(오픈소스) |
| 구독 비용 | Claude Pro $20/월 | 고정 월요금 없음 |
| API 비용 | Pro 구독에 포함 | API 사용량에 따라課金 |
| 무료 한도 | Pro 구독 무제한 사용 | Plus: $5/월, Pro: $50/월 |
| 초과 후課金 | 없음(Pro 무제한) | OpenAI API 가격 기준 |
비용 추정:
- 경도 사용자(매일 1-2시간): Codex CLI 월평균 $5-15(구독 한도 활용), Claude Pro $20
- 중도 사용자(매일 3-5시간): Codex CLI 월평균 $20-50, Claude Pro $20
- 重度 사용자(매일 6시간 이상): Codex CLI 월평균 $50-150+, Claude Pro $20
###如何选择?
Codex CLI를 선택하세요, 만약:
- 오픈소스 도구와 투명한 구성 시스템을 선호한다면
- 모델 선택과 추론等级을 세밀하게 제어해야 한다면
- 프로젝트에 다양한 모델 전환이 필요하다면(예: 간단한 작업에는 경량 모델 사용)
- 샌드박스 보안과 세션 복구 기능을 중요시한다면
- 예산이 제한되어 있고 구독 한도로 비용을 절감하고자 한다면
Claude Code를 선택하세요, 만약:
- 이미 Claude Pro 구독 사용자라면
- 성숙하고 안정적인 제품 경험을 선호한다면
- 자주 모델을 전환할 필요가 없다면
- Anthropic의 공식 지원과 생태계 통합을 중요시한다면
혼합 사용 전략: 많은 개발자가 두 도구를 동시에 설치하고场景에 따라 선택합니다.
- 일상 개발에는 Claude Code 사용(안정적,省心)
- 복잡한 리팩토링에는 Codex CLI 사용(다중 모델, 세밀 제어)
- 비용에 민감할 때는 Codex CLI 사용(구독 한도 활용)
자주 묻는 질문 FAQ
설치 후 실행 시 “command not found” 오류
원인: npm 전역 설치 디렉토리가 PATH에 없습니다.
해결:
# codex 설치 위치 찾기
which codex
# 찾지 못하면 npm 전역 디렉토리 확인
npm config get prefix
# 해당 디렉토리의 bin 하위 디렉토리를 PATH에 추가
echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.bashrc
source ~/.bashrcNode.js 버전이 너무 낮음
원인: Codex CLI는 Node.js 18.x 이상이 필요합니다.
해결:
# 현재 버전 확인
node --version
# 18.x 미만이면 LTS 버전으로 업그레이드
# macOS
brew install node@20
# Ubuntu
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# nvm 사용(권장)
nvm install 20
nvm use 20API Key가 유효하지 않음
원인: API Key 형식 오류, 만료 또는 권한 부족.
해결:
- API Key 형식 확인:
sk-proj-또는sk-로 시작해야 함 - OpenAI Platform에서 Key 상태 확인
- 계정에 충분한 잔액或구독 한도가 있는지 확인
- 환경 변수 다시 내보내기:
export OPENAI_API_KEY="sk-proj-올바른密钥"
중국 내에서 Codex CLI를 사용하는 방법
네트워크 문제: Codex CLI는 OpenAI API에 접근해야 합니다. 중국에서 직접 연결하면 불안정할 수 있습니다.
해결方案:
- 프록시 사용: HTTP_PROXY 환경 변수 구성
export HTTP_PROXY=http://your-proxy:port export HTTPS_PROXY=http://your-proxy:port - 중계 서비스 사용: 일부 클라우드 서비스 제공업체가 API 중계를 제공합니다
- 로컬 모델 배포: Ollama 등 로컬 모델 도구와 결합(Codex 구성 수정 필요)
계정 문제: OpenAI 계정 등록에는 해외 전화번호나 이메일이 필요할 수 있습니다.
결제 문제: ChatGPT 구독에는 국제 신용카드或선불카드가 필요합니다.
Git 경고 처리 방법
현상: Codex 실행 시 Git 관련 경고 발생.
원인: Git이 설치되지 않았거나 사용자 정보가 구성되지 않았습니다.
해결:
# Git 설치
# macOS
brew install git
# Ubuntu
sudo apt install git
# 사용자 정보 구성
git config --global user.name "Your Name"
git config --global user.email "your@email.com"
# 프로젝트 디렉토리에서 저장소 초기화
git init요약 및 빠른 시작 3단계
OpenAI Codex CLI는 터미널 AI 프로그래밍 어시스턴트의 최신 발전 방향을 대표합니다. 코드 생성 도구를 넘어 보안 샌드박스, 세션 관리, MCP 통합, 프로덕션급 구성을 융합한 완전한 개발 플랫폼입니다.
핵심 가치回顾
- 안전 우선: 3단계 샌드박스 모드 + 4단계 승인 전략으로 AI 작업 제어 가능 보장
- 유연한 구성: Profile 시스템으로 다중场景 한 번에 전환
- 세션 지속성: /resume과 /fork로 작업 진행 상황 손실 방지
- 생태계 확장: MCP 프로토콜로 GitHub, 데이터베이스 등 외부 도구 연결
- 비용 최적화: 다중 모델 선택 + 추론等级 제어로 필요에 따라 사용
빠른 시작 3단계
1단계: 설치 및 인증
npm install -g @openai/codex
codex login # 또는 API Key 사용2단계: 안전 모드 선택
# 초보자 권장: 안전 검토 모드
codex --sandbox read-only
# 일상 개발: 작업 공간 쓰기 모드
codex --sandbox workspace-write3단계: 첫 번째 작업 시작
codex
> GET /health 엔드포인트를 포함하는 간단한 Express.js API 생성
[CODEx] 다음 파일을 생성하겠습니다:
- package.json
- server.js
- routes/health.js
실행 시작... ✓다음 단계 학습 리소스
- 공식 문서: developers.openai.com/codex
- GitHub 저장소: github.com/openai/codex
- IDE 통합 가이드: developers.openai.com/codex/ide
- API 가격 상세: openai.com/api/pricing
- 커뮤니티 토론: GitHub Issues와 Reddit r/OpenAI
숙련된 개발자이든 AI 프로그래밍 초보자이든 Codex CLI는 워크플로우에 상당한 향상을 가져올 수 있습니다. 오늘부터 AI를 터미널 속 페어 프로그래밍 파트너로 만들어보세요!
관련 읽기:
