GPT5 Codex CLI 사용방법(설치방법) - OpenAI Codex CLI 시작하기

안녕하세요! 갓대희입니다.

 

오늘은 Claude Code, Gemini CLI 등의 출시 이후 갑자기 뜨거운 감자처럼 떠오르는 Codex CLI에 대해 알아보려고 한다.  

 

최근 OpenAI가 2025년 8월 GPT-5 발표에 이어 9월에 코딩 특화 모델인 GPT-5-Codex를 출시한 뒤로 계속 논쟁이 끊이지 않는 것 같다. 일단 좋다 안좋다를 떠나서 키워드가 떠오르고 화제가 되고 있다는 점에서 무조건 일단 사용해 보자. 

 

OpenAI Codex CLI란?

공식문서 : https://openai.com/index/introducing-upgrades-to-codex

공식 github : https://github.com/openai/codex

 

OpenAI Codex CLI는 터미널에서 실행되는 경량 코딩 에이전트 이다.

2025년 9월 GPT-5-Codex로 대폭 업그레이드되어 기존 Codex CLI와는 차원이 다른 성능을 갖췄다고 하며, Codex Cloud를 통해 장시간 독립적으로 작업을 위임할 수도 있다.

이후 2025년 하반기 GPT-5.1-Codex, 12월 GPT-5.2를 거쳐 2026년 2월 현재 GPT-5.3-Codex가 최신 모델이다. (GPT-5.3-Codex는 이전 버전 대비 25% 빠른 속도로 실행된다.)

2026년 2월 업데이트
CLI 버전이 0.101.0까지 업데이트되었으며, 최신 모델 GPT-5.3-Codex가 출시되었다.
• GPT-5.3-Codex: 가장 강력한 코딩 모델. 코드 생성, 디버깅, 리팩토링 전반에서 대폭 개선
• GPT-5.3-Codex-Spark: 리서치 프리뷰. 초고속 실시간 코딩 속도 (Pro 전용)
• Codex App: macOS 데스크톱 앱 출시 (터미널 없이 사용 가능)
• Codex Cloud: chatgpt.com/codex 웹 인터페이스 및 codex cloud CLI 명령어
• 주요 신규 기능: Resume (세션 재개), Web Search (내장 검색), Steer Mode (커뮤니티 명칭, v0.98.0~), Memory 관리

 

Codex CLI는 단순한 코드 자동완성을 넘어서 프로젝트 전체를 읽고, 수정하고, 실행하는 진정한 개발자를 위한 AI Agent이다.  

작동 방식

1. 프로젝트 디렉토리에서 codex 명령어 실행
2. 자연어로 작업 요청 (예: "이 버그를 고쳐줘")
3. 코드베이스 전체를 읽고 이해
4. 필요한 파일들을 수정하고 테스트 실행
5. 결과를 검증하고 추가 개선 제안

 

다른 AI CLI 도구들과의 차이점

도구	작업 범위	독립성	특화 분야
OpenAI Codex CLI	프로젝트 전체	장시간 독립 작업	에이전틱 코딩
GitHub Copilot CLI	개별 명령어	즉시 응답	명령어 제안
Claude Code	프로젝트 수준	대화형 작업	컨텍스트 이해

 

가격 정책과 접근 방법

OpenAI Codex CLI의 가격 체계는 ChatGPT 구독과 연동되어 있어 생각보다 접근하기 쉽다.

( https://developers.openai.com/codex/pricing 참고 )

 

2025년 9월 작성일 기준 으로 여러 방법으로 사용할 수 있다.

가격 정책

ChatGPT Plus 구독자: 포함 ($20/월)
├─ 5시간당 45~225 로컬 메시지 / 10~60 클라우드 태스크
├─ GPT-5.3-Codex 접근 가능
└─ 주간 코드 리뷰 10~25회

ChatGPT Pro 구독자: 포함 ($200/월)
├─ Plus 대비 약 6배 높은 사용량 한도
├─ GPT-5.3-Codex-Spark 접근 (Pro 전용, 리서치 프리뷰)
└─ 우선 처리 및 고급 기능

ChatGPT Business: 포함 ($30/user/월)
├─ 팀 단위 관리 및 SSO
├─ 더 큰 VM으로 빠른 클라우드 태스크
└─ 비즈니스 데이터 학습 미사용 기본 적용

ChatGPT Enterprise/Edu: 영업팀 문의
├─ SCIM, RBAC 등 엔터프라이즈 보안
├─ 감사 로그 및 컴플라이언스
└─ 유연한 사용량 한도

API 직접 사용: 사용량 기반 과금
└─ 정확한 토큰 단가는 공식 pricing 페이지 참고
   https://developers.openai.com/codex/pricing

 

ex) 9월 19일자 기록

개발 팁
당분간은 관대한 무료 사용량을 제공하고 있어 부담 없이 시작할 수 있다.
ChatGPT Plus만 있어도 충분히 실험해볼 수 있으니, Pro 구독 전에 먼저 Plus로 체험해보는 것을 추천한다.

 

설치 및 시작해보기 

OpenAI가 "Zero-setup installation"을 강조한 만큼 설치가 매우 간단해졌다. npm 한 줄로 설치가 가능하다.

복잡한 설정 없이 바로 사용할 수 있도록 진입 장벽을 낮추는 추세인 것 같다.

 

난 간단하게 표현하려고 했는데, 해당 공식 문서를 통해서도 확인 하실분들은 확인하면 좋을 것 같다. 

https://developers.openai.com/codex/cli

설치 전 체크리스트
• ChatGPT Plus, Pro, Business, Enterprise 구독 중 하나 보유
• OS : macOS, Linux (공식 지원) / Windows (실험적, WSL 권장)
• Node.js 22+ (npm으로 설치 시 필요. Homebrew나 바이너리 직접 다운로드 시 불필요) ※ 공식 문서에 최소 버전이 명시되어 있지 않으나, 최신 LTS 사용 권장
• Git (선택, 버전 관리 기능 활용 시 필요)
• 안정적인 인터넷 연결
• 터미널 사용 기본 지식

// 설치 및 초기 설정 스크립트

# 1. 설치
npm install -g @openai/codex

# 2. 첫 실행 (자동으로 인증 프롬프트)
codex

# 3. 재인증이 필요한 경우 ( 사실 /logout, 이후 /logint 하면 된다.)
rm ~/.codex/auth.json
codex

 

macOS 설치 

방법 1: npm 설치

# Node.js 버전 확인 (최신 LTS 권장)
node --version
npm --version

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

# 권한 문제 시 (필요한 경우만)
sudo npm install -g @openai/codex

# 인증
codex

# 업그레이드 (정기적으로 실행 권장)
npm i -g @openai/codex@latest

 

ex) 내 PC 환경에서는 약 25초 정도 만에 설치 완료

 

방법 2: Homebrew

# Homebrew가 없다면 먼저 설치
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Codex CLI 설치 (공식 quickstart 기준)
brew install --cask codex

# 인증 및 초기 설정
codex

# 설치 확인
codex --version

2025년 12월 업데이트: 직접 바이너리 다운로드도 가능합니다.
GitHub Releases에서 플랫폼별 바이너리 다운로드:
• macOS (Apple Silicon): codex-aarch64-apple-darwin.tar.gz
• macOS (Intel): codex-x86_64-apple-darwin.tar.gz
• Linux (x86_64): codex-x86_64-unknown-linux-musl.tar.gz
• Linux (arm64): codex-aarch64-unknown-linux-musl.tar.gz

방법 3: Codex App (macOS 데스크톱) 📢 2026년 신규 기능

터미널 없이 macOS 데스크톱 앱으로 Codex를 사용할 수 있다.
• openai.com/codex에서 다운로드
• macOS 전용 (Apple Silicon 및 Intel Mac 모두 지원. Windows, Linux는 미지원)
• ChatGPT 계정으로 로그인하면 바로 사용 가능
• CLI와 동일한 기능을 GUI로 제공

방법 4: Codex Cloud (웹)  2026년 신규

설치 없이 웹 브라우저에서 바로 사용할 수 있다.
• chatgpt.com/codex 접속
• CLI에서는 codex cloud 명령어로 클라우드 작업 관리 가능
• 긴 작업을 클라우드에 위임하고 결과만 받아올 수 있음

 

Windows 설치 (WSL 환경 권장 / 2025년 9월 기준)

Windows 주의사항
Windows 네이티브 환경은 아직 실험적 단계이다.
안정적인 사용을 위해 WSL(Windows Subsystem for Linux) 환경을 권장한다.

📢 2025년 11월 업데이트: Windows Agent 모드 도입
Windows Agent 모드가 도입되어 네이티브 Windows에서의 사용이 크게 개선되었다.
• 파일 읽기/쓰기, 명령어 실행이 승인 없이 가능 (작업 폴더 내에서)
• 새로운 실험적 Windows 샌드박스로 파일시스템 및 네트워크 접근 제한
• WSL 없이도 사용 가능하지만, 공식 문서에서는 여전히 실험적(experimental) 단계로 분류하며 WSL 사용을 권장

WSL 환경 설정

# PowerShell을 관리자 권한으로 실행 후
# WSL 설치 (Windows 10 2004+ 또는 Windows 11)
wsl --install

# Ubuntu 배포판 설치 (기본값)
wsl --install -d Ubuntu

# WSL 재시작 후 Ubuntu 터미널에서
sudo apt update && sudo apt upgrade -y

# Node.js 22+ 설치
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Codex CLI 설치
npm install -g @openai/codex
codex

Windows 네이티브 설치 (실험적 상태)

# Node.js 공식 사이트에서 Windows Installer 다운로드
# https://nodejs.org/en/download/

# PowerShell 또는 Command Prompt에서
npm install -g @openai/codex

# Windows Defender 예외 추가 (필요시)
# C:\Users\[사용자명]\AppData\Roaming\npm\node_modules\@openai\codex

# 인증
codex

# 문제 발생 시 관리자 권한으로 실행

 

ex) 실험적인 상태라고 하여 시도하였는데 powershell에서 최초 실패 / 관리자 권한으로 성공 하였다.

 - 설치는 정말 간단한다.

  - 나머지는 상기 내용과 동일하게 인증 진행 한다.

  - 상기 과정을 powershell을 관리자권한 으로 다시 시도 / 최종 성공 하였다.

 

Linux 설치 (Ubuntu/Debian/CentOS)

Ubuntu/Debian 계열

# 시스템 업데이트
sudo apt update && sudo apt upgrade -y

# Node.js 22+ 설치 (NodeSource 저장소 사용)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# npm 전역 패키지 권한 설정 (권장)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Codex CLI 설치
npm install -g @openai/codex

# 인증
codex

CentOS/RHEL/Fedora 계열

# Node.js 설치 (dnf 사용)
sudo dnf install nodejs npm -y

# 또는 NodeSource 저장소 사용 (최신 버전)
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo dnf install nodejs -y

# 전역 설치 디렉토리 설정
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Codex CLI 설치
npm install -g @openai/codex

# 방화벽 설정 (필요시)
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --reload

 

Codex 사용 방법 4가지 - 2026년 기준

2026년 현재 Codex는 CLI뿐만 아니라 다양한 방법으로 사용할 수 있다.

방법	설명	적합한 상황
CLI	터미널 기반 에이전트	프로젝트 전체 작업, 시스템 조작, CI/CD
App (신규)	macOS 데스크톱 앱	터미널에 익숙하지 않은 사용자, GUI 선호
IDE Extension	VS Code, Cursor, Windsurf, VS Code Insiders	에디터에서 바로 코딩 도움
Cloud (신규)	chatgpt.com/codex 웹 인터페이스	설치 없이 사용, 장시간 작업 위임

 

IDE 통합 (VS Code 확장) 

다양한 IDE 에서 확장 프로그램으로 사용가능하도록 되어있다.

VS Code, VS Code Insiders, Cursor, Windsurf에서 직접 Codex를 사용할 수 있어 터미널과 에디터를 오가지 않고도 seamless한 코딩 경험을 제공한다.

https://openai.com/index/introducing-upgrades-to-codex/

 

상기 URL에서 본인의 IDE환경이 있어서 클릭하면 바로 설치가 가능하다.

ex) Cursor에 설치해 보도록 하자. Cursor 클릭시 빈 브라우저 새창이 열리면서 다음과 같이 컨펌 창이 열린다. Cursor 열기 클릭. 

 

 - 바로 Install을 클릭하여 설치해보자.

 

 - 좌상한 패널을 클릭해보면 Codex Extension이 설치 되어있는것을 볼 수 있다. 클릭해 보자.

 

 - Try GPT-5-Codex now 클릭

 

 - 이후 인증단계가 나올 것 같은데 난 CLI를 통해 이미 인증해버렸다. ( 하기에 인증 방식을 써놓기도 했고, 인증방식이 챗 GPT 로그인만 되면 되다 보니 쭉쭉 넘어갈 수 있을 것 같다. )

 

 - 흔히 보던 cursor의 AI Chat 인터페이스와 유사하게 나타나는것을 볼 수 있다. 

 

 - 조금 특이한 부분은 기존 Codex를 사용 해보신분들은 아시겠지만, Run in the cloud  환경에서 동작할수 있는 옵션도 보인다. 그래서 N시간동안 동작할수 있다라고 한게 아닐까? 

CLI vs IDE 확장 비교

• CLI: 터미널 기반, 프로젝트 전체 작업, 복잡한 시스템 조작
• IDE 확장: 에디터 통합, 코드 편집 중심, 즉석 도움말과 미리보기
• 클라우드 연동: 복잡한 작업은 클라우드에 위임, 결과를 IDE로 가져오기
• 상호 보완: CLI로 환경 설정, IDE에서 코드 작성, 클라우드로 검증

 

인증 및 초기 설정

2025년 9월 업그레이드와 함께 인증 방식이 훨씬 간편해졌다.

더 이상 복잡한 API 키 설정이 필요 없고, ChatGPT 계정으로 바로 연동할 수 있다.

간편 인증 (ChatGPT 계정)

# 설치 후 첫 실행 시 자동으로 인증 프롬프트 나타남
codex

# "Sign in with ChatGPT" 선택
# 브라우저가 자동으로 열리며 ChatGPT 로그인 페이지로 이동
# ChatGPT 계정으로 로그인
# API 조직 선택 (회사 계정의 경우)
# 자동으로 인증 정보가 ~/.codex/auth.json에 저장됨

# 인증 상태 확인
codex --version

# 인증 파일 삭제 (재인증 필요시)
rm ~/.codex/auth.json

 

ex) 인증 

1) codex 입력 > "1. Sign in with ChatGPT" 에서 엔터

 

2) 다음과 같이 화면이 뜨며 openAI 인증을 요구하는 브라우저가 열리게 된다. 로그인 하여 인증 하자.

 

3) 계속

 

4) 모든 스텝을 진행 후 돌아오면 정상적으로 인증 되어 있다. "Enter"키를 입력하여 이후 단계 진행

 

5) 현재 내 프로젝트의 위치를 알려주며, 샌드박스 모드를 선택하는 단계이다. Codex는 두 가지 독립적인 보안 설정이 있다:

[Sandbox Policy] (--sandbox 플래그) - 파일시스템/네트워크 접근 범위 제어
 - read-only: 읽기만 가능
 - workspace-write: 워크스페이스 내 파일 편집/명령어 실행 가능 (네트워크 차단)
 - danger-full-access: 모든 제한 해제 (네트워크 포함)

[Approval Policy] (--ask-for-approval 플래그) - 승인 시점 제어
 - on-request: 워크스페이스 외부 편집이나 네트워크 접근 시 승인 요청
 - untrusted: 안전한 읽기만 자동 실행, 상태 변경 시 승인 필요
 - never: 모든 승인 프롬프트 비활성화

--full-auto 플래그는 workspace-write + on-request의 편의 조합이다. 난 1번 으로 진행 하려고 한다.

( 클로드의 claude --dangerously-skip-permissions 와 유사한 것은 danger-full-access 모드이다. ) 

 

6) 향상된 신규 GPT-5-Codex model 을 당연히 선택 하면 된다. 

 - 2025년 11월 GPT 5.1 업데이트가되어 이젠 5.1버전을 사용하면 된다.

 - 2025년 12월 GPT-5.2 출시.
2026년 2월 현재 GPT-5.3-Codex가 최신 권장 모델이다.

2026년 2월 기준 모델 현황:
• gpt-5.3-codex: 공식 문서에서 권장하는 최신 모델. 코드 생성, 디버깅, 리팩토링 전반에서 가장 강력
• gpt-5.3-codex-spark: 리서치 프리뷰. 초고속 실시간 코딩 속도 (Pro 전용)
• gpt-5.2-codex: CLI 기본(default) 모델. 안정적인 성능
• gpt-5.1-codex-max: 이전 모델 (여전히 사용 가능)
• gpt-5.1-codex-mini: 경량 모델 (여전히 사용 가능)
codex -m gpt-5.3-codex 또는 codex -m gpt-5.3-codex-spark로 모델 지정 가능

 

7) 이제 사용할 준비가 되었다. 

8) 2025년 11월 5.1이후엔 다양한 모델이 지원되니 본인의 필요에 따라 변경해보자. 

 - gpt-5.1-codex-mini

 

 - gpt-5.1-codex

 

기본 명령어

설치와 인증이 완료되면 바로 사용할 수 있다. 대화형 모드와 직접 명령어 모드 두 가지 방식을 지원한다.

대화형 모드

기본 사용 예시

# 프로젝트 디렉토리로 이동
cd my-project

# Codex 에이전트 시작
codex

# 환영 메시지가 나타나면 자연어로 요청
You: 이 프로젝트의 테스트 커버리지를 확인해줘

Codex: 프로젝트를 분석하고 있습니다...
package.json에서 jest 설정을 발견했습니다.
테스트를 실행하고 커버리지 리포트를 생성하겠습니다.

[실행 중: npm run test -- --coverage]

현재 테스트 커버리지: 87.3%
추천 사항: utils/ 디렉토리의 테스트가 부족합니다.

 

ex) 해당 프로젝트에 대해 분석 요청

 

ex) 결과

 

직접 명령어 모드

// 직접 명령어로 빠른 작업

# 코드베이스 전체 분석
codex "이 프로젝트의 아키텍처를 분석해줘"

# 특정 작업 실행
codex exec "CI 실패를 고쳐줘"

# 이미지와 함께 요청 (멀티모달)
codex "이 에러 스크린샷을 보고 고쳐줘" --image error-screenshot.png

# 비대화형 실행 (exec 명령어)
codex exec "모든 테스트를 실행하고 실패하는 것을 고쳐줘"

# 모델 변경
codex --model gpt-5.3-codex

# 도움말
codex --help

 

내장 명령어

아직 GeminiCL나 Claude Code에 비해 많은 내장명령어가 있지 않지만, 원래 제미나이도 그랬고 차츰 기능이 추가되지 않을까 싶다.

📢 2026년 2월 현재, Codex CLI는 매우 풍부한 내장 명령어 세트를 갖추고 있다. 초기에 비해 크게 성장했다.

# 대화형 모드 내에서 사용하는 특수 명령어
/model        choose what model and reasoning effort to use
/permissions  set what Codex can do without asking first
/review       ask Codex to review your working tree
/new          start a new conversation inside the same CLI session
/init         generate an AGENTS.md scaffold in the current directory
/compact      summarize the visible conversation to free tokens
/diff         show git diff (including untracked files)
/mention      attach a file to the conversation
/status       display session configuration and token usage
/mcp          list configured MCP tools
/plan         switch to plan mode and optionally send a prompt (📢 2026년 신규)
/apps         browse apps (connectors) and insert them into your prompt (📢 2026년 신규)
/personality  choose a communication style for responses (📢 2026년 신규)
/ps           show experimental background terminals (📢 2026년 신규)
/resume       resume a saved conversation from your session list (📢 2026년 신규)
/fork         fork current conversation into a new thread (📢 2026년 신규)
/statusline   configure TUI status-line fields interactively (📢 2026년 신규)
/debug-config print config layer and requirements diagnostics (📢 2026년 신규)
/logout       log out of Codex
/quit         exit Codex
/exit         exit Codex
/feedback     send logs to maintainers

📢 2026년 신규 CLI 명령어 & 플래그

# 세션 관리
codex resume              # 이전 세션 목록에서 선택하여 재개
codex resume --last       # 마지막 세션 바로 재개
codex fork                # 현재 세션에서 새 스레드 분기

# 비대화형 실행
codex exec "작업 지시"    # 비대화형으로 즉시 실행

# 클라우드 작업
codex cloud               # 클라우드 작업 관리 (chatgpt.com/codex 연동)

# 기능 관리
codex features list       # 사용 가능한 feature flag 목록
codex features enable <name>   # 특정 기능 활성화
codex features disable <name>  # 특정 기능 비활성화

# 셸 자동완성
codex completion bash     # bash 자동완성 스크립트 생성
codex completion zsh      # zsh 자동완성 스크립트 생성
codex completion fish     # fish 자동완성 스크립트 생성

# 패치 적용
codex apply <file>        # diff/patch 파일 적용

# 주요 신규 플래그
codex --full-auto         # Full Access 모드로 바로 시작
codex --profile <name>    # 특정 설정 프로필로 실행
codex --sandbox           # 샌드박스 환경에서 실행
codex --search            # 웹 검색 활성화
codex --add-dir <path>    # 추가 디렉토리를 컨텍스트에 포함

 

ex) /model - 모델 및 추론 수준 선택

 - 2025년 9월 당시의 기록 

 

ex) /review : 현재 기준으로 변경사항 리뷰 하고 리뷰 이슈를 찾아 준다. ( 하기 예시의 리뷰 코멘트만 번역해서 올려 두어야 겠다. )

[P0] def 앞에 있는 문법 오류 수정 – test_aws_integration.py:578-584
이 파일은 지금 상태로는 임포트조차 되지 않습니다.
_test_opensearch_connection의 마지막 부분에서, 딕셔너리 리터럴이 닫히고 난 뒤 불필요한 문자(}d)가 남아 있는데,
그 다음 함수 헤더가 바로 다음 줄에 ef _test_model_access_permissions(...)로 시작합니다.
Python이 이 코드를 해석할 때, def 앞에 줄 바꿈이 아니라 다른 문자가 있어서 SyntaxError가 발생합니다.
똑같은 복사/붙여넣기 실수가 파일의 다른 부분에도 반복됩니다.
모든 def가 반드시 새로운 줄에서 시작하도록 정리해주세요.

 

ex) /permissions (이전: /approvals) - Codex 자동 실행 권한 설정

 Codex의 보안 설정은 Sandbox Policy와 Approval Policy 두 축으로 나뉜다.

 [Sandbox Policy] - 파일시스템/네트워크 접근 범위
 - read-only: 파일 읽기만 가능. 편집/명령어/네트워크 차단
 - workspace-write: 워크스페이스 내 파일 편집, 명령어 실행 가능. 네트워크 차단
 - danger-full-access: 모든 제한 해제 (네트워크 포함, 주의 필요!)

 [Approval Policy] - 승인 시점
 - on-request: 외부 편집/네트워크 접근 시 승인 요청
 - untrusted: 안전한 읽기만 자동, 상태 변경 시 승인 필요
 - never: 승인 프롬프트 완전 비활성화

 

ex) /mention - 파일 컨텍스트 추가

 - 특정 파일을 대화 컨텍스트에 추가하여 Codex가 해당 파일을 참조할 수 있게 합니다.
 - @기호와 동일한 기능이지만, 명령어 형태로 파일 선택 인터페이스를 제공합니다.
 - 사용법: /mention 입력 후 Enter → 파일 선택 UI에서 원하는 파일 선택
 - 활용: 코드 분석이나 리팩토링 요청 전에 관련 파일들을 미리 지정할 때 유용합니다.

 

ex) /init 

 - 클로드, gemini 처럼 해당 프로젝트를 이해하고 codex의 이해를 돕는 AGENTS.md파일을 생성 한다.

 - 나의 경우 특히 클로드라면 CLAUDE.md / gemini라면 GEMINI.md 파일을 최대한 잘 활용하는게 중요하다고 생각 하는 편 이다.

AGENTS.md 활용 예시

# AGENTS.md 예시 파일
## 프로젝트 개요
- React + TypeScript + Node.js 풀스택 앱
- PostgreSQL 데이터베이스 사용
- Jest + Cypress 테스트 환경

## 코딩 규칙
- ESLint + Prettier 사용
- 함수형 컴포넌트 + Hooks 선호
- API 에러는 try-catch로 처리

## 테스트 실행 방법
```bash
npm run test        # 유닛 테스트
npm run test:e2e    # E2E 테스트
npm run test:watch  # 개발 중 테스트
```

## PR 메시지 형식
- feat: 새로운 기능
- fix: 버그 수정
- refactor: 리팩토링

 

ex) /new - 새 대화 시작

 - 현재 대화를 종료하지 않고 새로운 대화를 시작한다.
 - 다른 주제나 작업으로 전환할 때 컨텍스트를 깔끔하게 정리하고 싶을 때 사용한다.

 

ex) /compact - 대화 요약

 - 긴 대화를 요약하여 토큰 사용량을 줄인다.
 - 컨텍스트 한계에 도달하기 전에 사용하면 대화를 계속 이어갈 수 있다.

 

ex) /plan - 플래닝 모드 진입 (📢 2026년 신규)

 - 플래닝 모드로 전환하여 작업 계획을 수립한다.
 - 복잡한 작업을 단계별로 분해하여 실행 전에 검토할 수 있다.

 

ex) /diff - Git 변경사항 확인

 - git diff를 표시하며, 추적되지 않는(untracked) 파일도 포함한다.
 - 커밋 전에 Codex가 수정한 모든 변경사항을 한눈에 확인할 수 있다.

 

ex) /status - 세션 상태 확인

 - 현재 세션의 설정 정보와 토큰 사용량을 표시한다.

 

ex) /mcp - MCP 도구 목록

 - 현재 설정된 MCP(Model Context Protocol) 도구들의 목록을 표시한다.
 - 연결된 외부 도구나 API가 제대로 구성되어 있는지 확인할 때 사용한다.
 - MCP 서버 설정 후 연결 상태를 점검하는 데 필수적이다.

 

ex) /feedback - 피드백 전송

 - 현재 세션의 로그를 OpenAI 개발팀에 전송한다.
 - 버그를 발견하거나 개선 사항을 제안할 때 사용한다.

 

ex) /logout, /quit, /exit - 세션 종료

 - /logout: Codex에서 로그아웃 (인증 정보 초기화)
 - /quit, /exit: Codex를 종료 (동일한 기능)

 

2025년 11-12월 신규 기능

최근 업데이트에서 추가된 주요 기능들:

• Extra High (xhigh) Reasoning: 지연 시간에 민감하지 않은 작업에서 모델이 더 오래 생각하여 더 나은 답변을 제공. /model 명령어에서 reasoning effort를 xhigh로 설정 가능
• Native Compaction Support: 긴 코딩 세션에서 자동으로 컨텍스트를 요약하여 성능 개선. GPT-5.1-Codex-Max는 수백만 토큰에 걸친 작업을 coherent하게 처리
• Tool Token Limits 확대: 도구 출력 토큰 한도가 10,000으로 확대됨. config.toml에서 tool_output_token_limit으로 설정 가능
• Ghost Snapshot v2: 개선된 세션 캡처 및 ghost commits 지원 (0.73.0)
• Skills Manager: skills 로딩 재구현으로 확장성 개선 (0.73.0)
• OpenTelemetry 추적: Codex용 분산 추적 지원 추가 (0.73.0)

2026년 1-2월 신규 기능 (v0.74 ~ v0.101)

약 2개월간 대규모 업데이트가 이루어졌다:

• Resume Conversations: codex resume --last로 이전 세션을 이어서 작업 가능. 세션 목록에서 선택하여 재개할 수도 있음
• Web Search: 내장 웹 검색 기능. --search 플래그로 활성화 가능
• Steer Mode: 새로운 입력 방식이 v0.98.0부터 기본값으로 변경. Enter 즉시 전송, Tab으로 대기열 입력 (커뮤니티에서 ‘Steer Mode’로 불림. 공식 문서에 별도 명칭 미기재)
• Concurrent Execution: 실행 중인 작업이 있을 때도 추가 명령어를 동시에 실행 가능
• Memory Management: 세션 간 맥락 유지 강화. config.toml의 history 설정으로 메모리 관리 가능
• Config Profiles: --profile <name>으로 프로필 기반 설정 전환. 프로젝트별 다른 설정 사용 가능
• GIF/WebP 이미지 지원: 멀티모달 입력이 GIF, WebP 포맷까지 확장됨 (공식 문서에는 PNG/JPEG만 명시. 소스코드에 GIF/WebP 디코딩 라이브러리 포함되어 있어 동작할 수 있으나 공식 보장 아님)
• Shell Completions: codex completion bash/zsh/fish로 셸 자동완성 설치 가능
• Feature Flags: codex features list/enable/disable로 실험적 기능 관리
• requirements.toml: 관리자가 보안 정책을 강제할 수 있는 설정 파일 지원

 

AGENTS.md를 통한 커스텀 지시

프로젝트별 지시사항은 AGENTS.md 파일에 작성하여 Codex가 프로젝트의 규칙과 컨벤션을 이해하도록 할 수 있다. /init 명령어로 기본 템플릿을 생성할 수 있다.

⚠️ 참고: 이전에 소개했던 /prompts:<name> 형태의 커스텀 프롬프트 기능은 2026년 2월 현재 공식 슬래시 명령어 목록에서 확인되지 않습니다. AGENTS.md를 활용하는 것이 공식적으로 권장되는 방법입니다.

 

활용 시나리오

시나리오 1: 레거시 프로젝트 현대화

사용자: 이 jQuery 기반 프론트엔드를 React로 마이그레이션해줘.
기존 기능을 모두 유지하면서 현대적인 패턴으로 바꿔줘.

Codex: jQuery 프로젝트를 분석하고 있습니다...

발견한 주요 컴포넌트:
- 사용자 목록 테이블 (ajax 기반)
- 모달 다이얼로그 시스템
- 폼 유효성 검증
- 실시간 검색 기능

React 19 + TypeScript로 마이그레이션하겠습니다.
Context API를 사용해서 상태 관리를 개선하겠습니다.
✅ 마이그레이션 완료!
- 12개 컴포넌트 생성
- 95% 기능 호환성 달성
- 번들 크기 40% 감소
- TypeScript 지원 추가
- 테스트 커버리지 92%

시나리오 2: 성능 최적화 프로젝트

사용자: 이 Node.js API 서버가 너무 느려. 프로파일링하고 최적화해줘.

Codex: API 서버 성능을 분석하겠습니다.

[분석 결과]
1. 주요 병목: N+1 쿼리 문제 (users → posts → comments)
2. 캐싱 부재: 자주 조회되는 데이터 캐싱 없음
3. 비효율적 미들웨어: 모든 요청에 불필요한 DB 연결

최적화 계획:
- Dataloader 패턴으로 N+1 쿼리 해결
- Redis 캐싱 레이어 추가
- 미들웨어 순서 재조정
- 데이터베이스 인덱스 최적화


성능 개선 결과:
- 평균 응답 시간: 850ms → 120ms (86% 개선)
- 동시 처리량: 50 RPS → 400 RPS
- 메모리 사용량: 25% 감소
- CPU 사용률: 45% 감소

시나리오 3: 버그 수정 요청

사용자: 로그인할 때 가끔 세션이 만료되는 버그가 있어. 고쳐줄 수 있어?

Codex: 네, 세션 만료 이슈를 살펴보겠습니다.
먼저 코드베이스를 분석하고 인증 관련 파일들을 확인하겠습니다.

[코드베이스 스캔 중...]

auth/session.js와 middleware/auth.js에서 토큰 검증 로직에
race condition이 발견되었습니다. 수정하겠습니다.

[3개 파일 수정 완료]

테스트를 실행해서 검증하겠습니다...

✅ 모든 테스트 통과! 세션 관리가 개선되었습니다.

시나리오 4: 신기능 개발

사용자: 사용자가 자신의 활동 통계를 볼 수 있는 대시보드 페이지를 만들어줘.
API도 만들고 프론트엔드 컴포넌트도 다 만들어줘.

Codex: 활동 통계 대시보드를 만들어드리겠습니다.

다음 작업을 수행하겠습니다:
1. 데이터베이스 쿼리 로직 개발
2. REST API 엔드포인트 생성
3. React 대시보드 컴포넌트 개발
4. 차트 라이브러리 통합
5. 테스트 코드 작성

[45분 후...]

✅ 대시보드 개발 완료!
- /api/users/stats 엔드포인트 생성
- DashboardStats.jsx 컴포넌트 개발
- Chart.js로 시각화 추가
- 93% 테스트 커버리지 달성

localhost:3000/dashboard에서 확인해보세요!

 

멀티모달 입력

Codex CLI는 이미지를 함께 전달하여 시각적 컨텍스트를 제공할 수 있다. 공식 문서 기준 PNG, JPEG 포맷이 지원된다. (소스코드에 GIF/WebP 디코딩 라이브러리가 포함되어 있으나, 공식적으로는 PNG/JPEG만 명시되어 있다.)

# 이미지와 함께 요청 (-i / --image 플래그)
codex "이 에러를 고쳐줘" -i error-screenshot.png
codex "이 UI를 개선해줘" --image design-mockup.webp

# 공식 지원 포맷: PNG, JPEG

스크린샷으로 버그 문의

사용자: [스크린샷 첨부] 이 에러가 왜 나오는지 모르겠어. 고쳐줘.

Codex: 스크린샷을 분석했습니다. TypeError: Cannot read property 'name' of undefined
에러가 UserProfile 컴포넌트에서 발생하고 있습니다.

user 객체가 로딩되기 전에 user.name에 접근하려고 해서 발생하는 문제입니다.
Optional chaining과 로딩 상태를 추가해서 수정하겠습니다.

[UserProfile.jsx 수정 완료]

이제 user 데이터가 로딩 중일 때 스켈레톤 UI가 표시됩니다!

 

CI/CD 파이프라인 통합

OpenAI가 공식 제공하는 GitLab 통합 가이드와 커뮤니티에서 개발한 다양한 CI/CD 통합 방법들이 있다.

코드 품질 자동화와 보안 검증에 특히 유용할 것 같다.

다만 나의 경우 GitHub을 사용하고 Github에서는 딸깍 하면 Gemini로 소스 리뷰를 받을 수 있기 떄문에 하기 내용은 현재 사용하지 않는다. 

( Gemini github pull request 자동 리뷰 글 참고 )

2025.07.22 - [AI/Gemini] - [gemini 활용기] - Github PR 리뷰 AI 자동화 (PullRequest 소스검토 Automation with Gemini Code Assist)

 

CI/CD 파이프라인 통합은 다음과 같이 진행했던 이력이 있으니 예시로 참고사항으로 작성해 두려고 한다. 

⚠️ 주의: 아래 CI/CD 통합 예시는 공식 문서에서 검증되지 않은 내용입니다. codex review --format, codex login --with-api-key, openai/codex-action@v1 등의 명령어/Action은 2026년 2월 현재 공식 문서에서 확인되지 않습니다. 참고용으로만 봐주시고, 실제 적용 전 반드시 공식 문서를 확인하세요.

// GitLab CI/CD 통합 예시

# .gitlab-ci.yml
stages:
  - code-analysis
  - deploy

codex-review:
  stage: code-analysis
  image: node:22-slim
  script:
    - npm install --global @openai/codex
    - echo $OPENAI_TOKEN | codex login --with-api-key
    - codex review --format codeclimate-json > quality-report.json
  artifacts:
    reports:
      codequality: quality-report.json
  only:
    - merge_requests

# GitHub Actions 통합
- name: OpenAI Codex Analysis
  uses: openai/codex-action@v1
  with:
    api-key: ${{ secrets.OPENAI_API_KEY }}
    analysis-type: 'security,quality'

CI/CD 활용 팁
merge request나 pull request에서 자동으로 코드 품질 리포트를 생성하도록 설정하면 코드 리뷰 효율성이 크게 향상된다. 특히 GitLab의 CodeClimate JSON 형식으로 결과를 내보내면 merge request 화면에서 바로 문제점을 확인할 수 있다.

 

트러블슈팅 가이드

실제 사용하면서 겪을 수 있는 문제들과 해결 방법들 정리.

🚨 흔한 문제들과 해결 방법:

# 인증 문제
문제: "401 AK/SK errors" 또는 인증 실패
해결: .env 파일의 OPENAI_API_KEY 삭제 또는 이름 변경
      codex login으로 다시 인증

# 모델 호환성 오류
문제: "404 This model is only supported in v1/responses"
해결: /model 명령어로 GPT-5.1-Codex로 변경

# 터미널 시작 실패
문제: "Terminal errored - An unexpected error occurred"
해결: npm i -g @openai/codex@latest 로 최신 버전 업데이트
      WSL 환경에서 실행 (Windows 사용자)

# PR 생성 실패
문제: GitHub PR 생성이 계속 실패
해결: GitHub 토큰 권한 확인
      Repository settings에서 Actions 권한 확인

# 성능 개선
문제: 응답이 너무 느림
해결: 로컬 프로젝트 크기 최적화 (.gitignore 확인)
      /model 명령어로 더 빠른 모델 선택

 

커뮤니티 & 생태계

OpenAI Codex CLI는 활발한 오픈소스 커뮤니티와 공식 지원을 통해 지속적으로 발전하고 있다. 문제가 생기거나 새로운 아이디어가 있을 때 참여할 수 있는 곳들을 정리했다.

🔗 주요 리소스

• GitHub 저장소: github.com/openai/codex - 소스 코드, 이슈 트래킹, 기능 요청
• OpenAI Cookbook: 실무 자동화 예제와 베스트 프랙티스 모음
• 개발자 커뮤니티: OpenAI Developer Community에서 Q&A 및 토론
• 공식 문서: developers.openai.com/codex - 최신 기능 및 API 레퍼런스
• 튜토리얼: DataCamp, YouTube 등에서 제공하는 실습 가이드

 

로드맵 & 발전 과정

2025년 9월 GPT-5-Codex 출시를 시작으로, 11월 GPT-5.1-Codex, 12월 GPT-5.2, 그리고 2026년 2월 GPT-5.3-Codex까지 빠른 속도로 진화해 왔다. OpenAI의 향후 방향을 보면, 단순한 코딩 도구를 넘어 통합된 AI 개발 플랫폼으로 발전하려는 의도가 분명하다.

2025년 11-12월 구현 완료

• GPT-5.1-Codex-Max: 프로젝트 규모 리팩토링, 심층 디버깅, 수백만 토큰 coherent 처리
• GPT-5.2: 최신 프론티어 모델. 지식, 추론, 코딩 전반 개선
• Windows Agent 모드: 네이티브 Windows 정식 지원
• Extra High (xhigh) Reasoning: 더 긴 사고 시간으로 더 나은 답변
• Native Compaction: 수백만 토큰에 걸친 장기 세션 지원
• GitHub Copilot 통합: GPT-5.1-Codex-Max가 Copilot에서 사용 가능 (❓ 정확한 지원 플랜은 공식 문서 확인 필요)

2026년 1-2월 구현 완료

• GPT-5.3-Codex: 가장 강력한 코딩 모델. 코드 생성, 디버깅, 리팩토링 전반 대폭 개선
• GPT-5.3-Codex-Spark: 리서치 프리뷰. 초고속 실시간 코딩 (Pro 전용)
• Codex App: macOS 데스크톱 앱 출시. 터미널 없이 GUI로 사용 가능
• Codex Cloud: chatgpt.com/codex 웹 인터페이스 및 codex cloud CLI 명령어
• Resume/Fork: codex resume --last로 세션 재개, codex fork으로 스레드 분기
• Web Search: 내장 웹 검색 기능 (--search 플래그로 활성화)
• Steer Mode: Enter 즉시 전송, Tab 대기열 입력이 기본값으로 변경
• Memory 관리: 세션 간 맥락 유지 및 메모리 관리 강화
• Config Profiles: 프로필 기반 설정 전환 (--profile 플래그)
• Shell Completions: bash/zsh/fish 자동완성 지원
• CLI v0.101.0: 약 30회 이상의 릴리스를 거치며 안정성과 기능 대폭 강화

예정된 주요 업데이트

• API 확장: 개발자 API를 통한 커스텀 통합 지원 예정 (gpt-5.3-codex API "coming soon" 상태)
• 대화형 워크플로우: 실시간 페어링과 작업 위임의 통합된 경험 (Codex Cloud, Resume, Concurrent Execution으로 구현)
• IDE 확장: 더 많은 IDE와 개발 도구 연동 (VS Code, VS Code Insiders, Cursor, Windsurf 지원 완료)
• 성능 최적화: 동적 사고 시간 조절로 응답 속도 개선 (xhigh reasoning + GPT-5.3-Codex-Spark 초고속 응답)
• Codex App Windows: Windows 알파 테스트 진행 중
• 모바일 지원: 스마트폰에서도 Codex 작업 가능

OpenAI의 비전
"개발자들이 IDE와 일상 도구에서 AI 에이전트와 협업하여 질문하고, 제안받고, 긴 작업을 위임할 수 있는 통합된 워크플로우"를 목표로 하고 있다. 이는 단순한 코드 생성을 넘어 진정한 AI 개발 파트너를 만들겠다는 의미다.

 

자주 묻는 질문 ❓

Q: 보안이나 개인정보는 안전한가요?

A: 코드 실행은 로컬에서 이루어지지만, AI 모델에 요청을 보내기 위해 프롬프트와 코드 컨텍스트는 OpenAI 서버로 전송됩니다. 민감한 정보가 있는 프로젝트에서는 주의해서 사용하세요. sandbox_mode 설정으로 접근 범위를 제한할 수 있습니다.

Q: 기존 Codex CLI와 무엇이 다른가요?

A: 현재 기본 모델은 GPT-5.3-Codex로, Codex Cloud를 통한 장시간 독립 작업이 가능해졌습니다. Zero-setup 설치와 ChatGPT 계정 간편 인증을 지원합니다. (⚠️ 구체적인 작업 시간이나 성능 향상 수치는 공식 문서에서 확인되지 않은 내용이므로 참고용으로만 봐주세요.)

Q: Windows에서 안정적으로 사용할 수 있나요?

A: Windows 네이티브는 아직 실험적 단계입니다. WSL(Windows Subsystem for Linux) 환경을 사용하면 macOS/Linux와 동일한 안정성을 얻을 수 있습니다.

2025년 11월 업데이트: Windows Agent 모드가 도입되어 네이티브 Windows 지원이 크게 개선되었습니다. 파일 읽기/쓰기, 명령어 실행이 작업 폴더 내에서 가능합니다. 다만 공식 문서에서는 여전히 실험적(experimental) 단계로 분류하고 있으며, 안정적인 사용을 위해 WSL도 권장합니다.

2026년 2월 업데이트: Windows 샌드박스가 개선되었으며, Codex App Windows 알파 버전도 테스트 진행 중입니다.

Q: 팀에서 함께 사용하려면 어떻게 해야 하나요?

A: ChatGPT Business 이상 구독에서 팀 워크스페이스를 통해 공유 가능합니다. 관리자 콘솔에서 멤버 관리와 사용량 모니터링을 할 수 있습니다.

Q: 개인정보나 회사 코드가 유출될 위험은 없나요?

A: 코드 실행 자체는 로컬에서 이루어지지만, 프롬프트와 코드 컨텍스트는 AI 모델 처리를 위해 OpenAI 서버로 전송됩니다. 중요한 비즈니스 로직이나 민감한 정보가 있는 프로젝트에서는 read-only 모드 사용 등 주의가 필요합니다.

Q: API 비용이 많이 나올까 걱정됩니다.

A: ChatGPT Plus/Pro 구독자는 관대한 무료 사용량이 제공됩니다. GPT-5.3-Codex-Spark(Pro 전용)는 빠른 응답 속도로 비용 효율성도 개선되었습니다. 정확한 비용은 사용 패턴에 따라 다르므로 공식 pricing 페이지를 참고하세요.

Q: 어떤 프로젝트에 가장 유용한가요?

A: 레거시 코드 개선, 대규모 리팩토링, 반복 작업 자동화에 특히 강합니다. 새 프로젝트보다는 기존 프로젝트의 개선 작업에 더 유용합니다.

Q: Codex App과 CLI 중 어떤 걸 써야 하나요? (📢 2026년 신규)

A: CLI는 터미널에 익숙한 개발자에게, App은 GUI를 선호하는 사용자에게 적합합니다. 기능은 동일하므로 작업 스타일에 맞게 선택하면 됩니다. CI/CD 통합이나 스크립트 자동화가 필요하다면 CLI가 유리합니다.

Q: 이전 세션을 이어서 작업할 수 있나요? (📢 2026년 신규)

A: 네, codex resume 명령어로 이전 세션 목록에서 선택하여 재개할 수 있습니다. codex resume --last를 사용하면 마지막 세션을 바로 이어서 작업할 수 있습니다.

 

참고 자료

• OpenAI Codex GitHub 저장소 - 소스 코드 및 이슈 트래킹
• GPT-5-Codex 업그레이드 공지 - 최신 기능 소개

• OpenAI Codex CLI 개발자 문서 - 공식 설치 가이드 및 API 레퍼런스
• OpenAI Codex CLI 시작하기 - 도움말 센터 기본 가이드
• GPT-5 소개 - GPT-5 모델 전체 개요
• Codex Changelog - 최신 변경사항 확인 (v0.101.0까지, 📢 2026년 2월 업데이트)
• Codex Models - 지원 모델 목록 및 설정 방법 (📢 2025년 12월 추가)
• GPT-5.1-Codex-Max 소개 - 에이전틱 코딩 모델 (📢 2025년 12월 추가)
• Codex Cloud - 클라우드 기반 Codex 사용 가이드 (📢 2026년 2월 추가)
• Codex Config Reference - 설정 파일 레퍼런스 (📢 2026년 2월 추가)
• Codex CLI Features - CLI 기능 상세 문서 (📢 2026년 2월 추가)

OpenAI Codex CLI는 2025년 9월 첫 출시 이후 빠른 속도로 성장하여, 2026년 2월 현재 CLI v0.101.0, GPT-5.3-Codex까지 도달했다. CLI뿐 아니라 App, Cloud, IDE Extension 등 다양한 접근 방법을 제공하며 통합 AI 개발 플랫폼으로 자리잡아 가고 있다.

복잡한 레거시 프로젝트나 대규모 리팩토링쪽에서 강하다는 말이 좀 들리는데, ChatGPT Plus 구독만 있으면 바로 시작할 수 있으니, 아직 경험해보지 않았다면 꼭 한 번 시도해보면 좋을 것 같다.