ChatGPT Codex 설치·사용법: 앱·CLI 선택과 첫 프로젝트

ChatGPT Codex를 처음 쓴다면 ChatGPT 데스크톱 앱에서 Codex를 골라 프로젝트 하나를 열거나, 터미널을 자주 쓰면 CLI를 설치한다. 첫 작업은 저장소 구조를 읽게 하고 이해 → 계획 → 수정 → 테스트 순서로 진행한다. Codex는 저장소를 읽고 파일을 고치며 명령을 실행하는 OpenAI의 코딩 에이전트다. ChatGPT Plus 이상은 요금제 사용량으로, 무료·Go는 데스크톱 앱에서 제한적으로 쓸 수 있다.

앱·CLI·IDE·클라우드 중 어디서 쓸까

방식	맞는 경우	특징
데스크톱 앱	여러 작업을 동시에 관리	프로젝트·대화·변경 내용을 한 화면에서 본다
CLI	터미널 중심 개발	현재 폴더에서 바로 작업
IDE 확장	VS Code 등 쓰던 편집기 유지	코드를 보며 수정을 이어 간다
클라우드	오래 걸리는 작업 맡기기	격리된 환경에서 백그라운드 실행 후 검토

데스크톱 앱은 macOS·Windows·Linux를 지원한다. 앱을 열면 ChatGPT와 Codex 중 하나를 고르고, 코드를 다루는 일은 Codex에서 시작한다. (데스크톱 앱)

Windows에서는 기본으로 Windows 네이티브 환경과 PowerShell을 쓰고, 설정에서 WSL2로 바꿀 수 있다. 둘은 파일 경로와 샌드박스가 달라 저장소 위치를 함께 확인한다. (Windows 앱)

Windows에 CLI 설치

CLI 설치 문서의 Windows 공식 명령이다.

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Node.js를 이미 쓴다면 npm install -g @openai/codex도 된다. 설치 경로가 겹치지 않게 한 방식만 쓴다. 설치 후 codex --version으로 확인한다.

터미널에서 codex --version이 실행되는지 먼저 확인한다. 명령을 찾지 못하면 CLI 설치 안내를 따라 설치한 뒤 새 터미널에서 다시 확인한다.

프로젝트 폴더에서 codex를 실행하고 Sign in with ChatGPT를 고르면 요금제 사용량을 쓴다. API 키로 로그인하면 API 요금이 따로 나간다.

모델 고르기

9월 22일부터 GPT-6 Sol과 Luna가 Codex에 순서대로 들어왔다. 복잡한 코딩·에이전트 작업은 Sol, 좁고 반복적인 작업은 Luna가 맞다. ChatGPT 계정으로 로그인한 Codex에서 GPT-5.4와 GPT-5.4 mini는 2026년 8월 31일에 종료됐고, 공식 안내는 GPT-5.4를 GPT-6 Sol로, GPT-5.4 mini를 GPT-6 Luna로 바꾸라고 한다. API 키로 쓰는 Codex와 OpenAI API는 해당하지 않는다. GPT-5.5도 10월 14일 ChatGPT·Codex에서 종료되며(OpenAI API는 제외), Plus 이상은 GPT-6 Sol, 무료·Go는 데스크톱 앱의 GPT-6 Luna가 대체 모델이다. (Codex 모델) GPT-6 Astra를 쓰려면 Codex CLI 0.153.0 이상이 필요하고, Astra는 사용량을 더 빨리 쓴다. 모델 목록에 없으면 앱·CLI를 업데이트하고 요금제·워크스페이스 권한을 확인한다. (Work·Codex 도움말) 모델별 차이는 GPT-6 Sol·Luna 정리에 있다.

첫 작업

이 저장소 구조를 먼저 읽고, 실행 방법과 핵심 폴더만 설명해줘. 아직 파일은 수정하지 마.

구조를 확인한 뒤에는 대상·유지할 것·확인 방법을 함께 적어 작은 작업을 맡긴다. 예를 들어 다음처럼 범위와 확인 방법을 지정할 수 있다.

회원가입 폼의 이메일 검증 버그를 찾아 수정해줘. 기존 UI는 바꾸지 말고, 관련 테스트를 실행한 뒤 변경 파일과 결과를 요약해줘.

처음 맡기기 좋은 일은 저장소 구조 설명, 특정 함수 흐름 추적, 재현되는 버그 하나 수정, 기존 코드에 테스트 추가, 작은 문서 수정처럼 결과를 확인하기 쉬운 것이다.

“완료”라는 답만 믿지 말고 실제 상태를 본다. git status와 git diff로 바뀐 파일을 보고, 관련 테스트·빌드를 직접 돌린다. CLI의 /review로 현재 변경을 따로 검토받을 수도 있다. 깨끗한 Git 상태에서 시작해야 무엇이 바뀌었는지 가려내기 쉽다. (승인과 보안)

Local·Worktree·Cloud 차이

새 Codex 대화를 만들 때 실행 위치를 고른다. (실행 환경)

위치	어디서	특징
Local	내 PC	지금 프로젝트 폴더를 직접 고친다
Worktree	내 PC	Git worktree(별도 작업 사본)에서 고쳐 원본과 분리한다
Cloud	클라우드	연결한 저장소를 별도 환경에서 작업한다

Cloud에 맡기기 전에는 커밋하지 않은 파일, .gitignore에 있는 파일, 설치 도구와 환경 변수가 클라우드에도 있는지 본다. 결과를 가져온 뒤에는 내 저장소에서 diff와 테스트를 다시 확인한다. CLI의 codex cloud로 클라우드 작업을 제출하고 결과를 가져올 수 있다.

여러 에이전트를 동시에 돌릴 수도 있다. 백엔드 오류 분석과 프런트엔드 수정, 테스트 작성과 문서 작성처럼 서로 다른 파일을 맡기면 효율적이다. 같은 파일을 동시에 크게 고치게 하면 충돌이 난다.

안 될 때

증상	원인	조치
codex 명령을 찾을 수 없음	앱만 설치했거나 PATH가 아직 반영 안 됨	CLI를 설치하고 새 터미널을 연다
모델 목록에 Sol·Astra가 없음	앱·CLI 버전이 낮거나 요금제 권한 없음	업데이트 후 요금제·워크스페이스 확인
명령이 멈추고 승인을 기다림	현재 승인 정책·샌드박스·네트워크 설정에 따라 승인이 필요할 수 있다	표시된 명령과 요청 사유, /permissions의 설정을 확인
You've hit your usage limit	사용량 한도 도달	계정의 사용량 화면과 표시된 재설정 시각을 확인

한도에 도달하면 계정의 사용량 화면을 확인한다. 모델을 바꾸는 것만으로 한도가 풀린다고 가정하지 않는다.

자주 묻는 질문

무료로 쓸 수 있나? 무료·Go 요금제도 데스크톱 앱에서 GPT-6 Luna로 Codex를 쓸 수 있다. 웹·모바일과 Sol 모델은 Plus 이상이다. 요금제별 차이는 ChatGPT 요금제 비교에 있다.

Claude Code와 무엇이 다른가? 둘 다 저장소를 읽고 고치는 코딩 에이전트다. ChatGPT 구독이 있으면 Codex, Claude 구독이 있으면 Claude Code부터 써 보는 것이 비용상 자연스럽다.