OpenAI Codex CLI 설치 방법 완벽 가이드 — 초보자도 따라하는 AI 코딩 에이전트 설치법 (2026)

🤖 Codex CLI란?

Codex CLI는 OpenAI가 만든 터미널(명령어 창)에서 실행되는 AI 코딩 에이전트입니다. 자연어로 "로그인 페이지 만들어줘"라고 말하면 코드를 직접 작성하고, 파일을 생성하고, 버그도 잡아주는 똑똑한 코딩 비서입니다.

💡 Codex가 할 수 있는 일:

• ✍️ 코드 작성 — 원하는 기능을 설명하면 코드를 생성
• 🔍 코드 분석 — 복잡한 코드를 읽고 설명
• 🐛 디버깅 — 오류를 찾아서 고쳐줌
• 🔄 리팩토링 — 코드 구조 개선, 테스트 자동화
• 📝 코드 리뷰 — 잠재적 버그, 로직 오류 발견

---

📋 설치 전 준비사항

운영체제	macOS 12 이상 / Ubuntu 20.04+ / Debian 10+ / Windows 11 (WSL2)
RAM	최소 4GB (8GB 권장)
Git (권장)	2.23 이상 (PR 도우미 기능에 필요)
ChatGPT 계정	Plus, Pro, Team, Edu, Enterprise 중 하나

⚠️ Windows 사용자 주의: Codex CLI는 Windows에서 직접 실행되지 않습니다. 반드시 WSL2(Windows Subsystem for Linux)를 통해 설치해야 합니다. WSL2 설치 방법은 아래에서 안내합니다.

---

🪟 [Windows 사용자] WSL2 설치부터 하기

Windows 사용자는 먼저 WSL2를 설치해야 합니다. 이미 WSL2가 있다면 이 단계를 건너뛰세요.

Step 1. PowerShell을 관리자 권한으로 열기

1. 시작 메뉴에서 "PowerShell" 검색
2. "관리자 권한으로 실행" 클릭

Step 2. WSL2 설치 명령어 실행

wsl --install

설치가 완료되면 컴퓨터를 재부팅합니다.

Step 3. Ubuntu 초기 설정

재부팅 후 Ubuntu가 자동으로 열리며, 사용자 이름과 비밀번호를 설정합니다.

Enter new UNIX username: (원하는 이름 입력)
New password: (비밀번호 입력 — 화면에 안 보여도 정상!)

이후 모든 Codex 설치 과정은 WSL2 Ubuntu 터미널에서 진행합니다.

---

📦 설치 방법 ① npm으로 설치 (추천! 가장 쉬움)

Node.js가 설치되어 있다면 가장 간단한 방법입니다.

Step 1. Node.js 설치 확인

node --version

버전이 표시되면 OK! 표시되지 않으면 Node.js부터 설치합니다:

📌 Node.js 설치 (아직 없는 경우)

macOS / Linux / WSL2:

# nvm(Node Version Manager)으로 설치 — 가장 안전한 방법
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# 터미널 재시작 후
nvm install --lts
nvm use --lts

또는 nodejs.org에서 LTS 버전 다운로드 후 설치

Step 2. Codex CLI 설치

npm install -g @openai/codex

이 한 줄이면 설치 끝입니다! 🎉

Step 3. 설치 확인

codex --version

버전 번호가 나오면 설치 성공입니다.

---

📦 설치 방법 ② Homebrew로 설치 (macOS 추천)

macOS에서 Homebrew를 사용 중이라면:

Step 1. Homebrew 설치 확인

brew --version

Homebrew가 없다면 먼저 설치:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 2. Codex 설치

brew install --cask codex

---

📦 설치 방법 ③ GitHub에서 직접 다운로드

npm이나 Homebrew 없이 바이너리 파일을 직접 다운로드하는 방법입니다.

Step 1. GitHub Releases 페이지 방문

👉 https://github.com/openai/codex/releases/latest

Step 2. 운영체제에 맞는 파일 다운로드

운영체제	파일명
🍎 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

Step 3. 압축 풀고 설치

# 다운로드한 파일 압축 풀기 (예: Linux x86_64)
tar -xzf codex-x86_64-unknown-linux-musl.tar.gz

# 이름 바꾸기
mv codex-x86_64-unknown-linux-musl codex

# 실행 권한 부여
chmod +x codex

# PATH가 잡힌 디렉토리로 이동
sudo mv codex /usr/local/bin/

---

🔐 로그인 설정 (설치 후 필수!)

Codex CLI를 사용하려면 OpenAI 계정으로 로그인해야 합니다. 두 가지 방법이 있습니다.

방법 A. ChatGPT 계정으로 로그인 (추천 ⭐)

ChatGPT Plus, Pro, Team, Edu, Enterprise 구독자라면 추가 비용 없이 사용할 수 있습니다.

codex

1. codex 명령어를 실행하면 "Sign in with ChatGPT" 옵션이 나타납니다
2. 선택하면 브라우저가 자동으로 열립니다
3. ChatGPT 계정으로 로그인하면 끝!
4. 로그인 토큰이 ~/.codex/auth.json에 저장되어 다음부터 자동 로그인됩니다

⚠️ 보안 주의: ~/.codex/auth.json 파일은 비밀번호처럼 취급하세요! 절대 다른 사람에게 공유하거나, Git에 커밋하지 마세요.

방법 B. API 키로 로그인

API 키를 사용하면 사용량에 따라 비용이 청구됩니다.

1. OpenAI 대시보드에서 API 키 발급
2. 환경 변수에 등록:

# ~/.bashrc 또는 ~/.zshrc에 추가
export OPENAI_API_KEY="sk-여기에-API-키-입력"

# 적용
source ~/.bashrc

---

🚀 첫 실행! Codex 사용해보기

기본 실행

# 대화형 모드로 실행
codex

# 바로 질문하기
codex "이 프로젝트의 구조를 설명해줘"

# 코드 작성 요청
codex "React로 로그인 페이지 컴포넌트 만들어줘"

프로젝트 폴더에서 실행하기

# 내 프로젝트 폴더로 이동
cd ~/my-project

# Codex 실행 — 프로젝트 구조를 자동으로 파악합니다
codex "README.md를 한국어로 작성해줘"

🎯 실전 활용 예시:

• codex "이 파일의 버그를 찾아서 고쳐줘"
• codex "Jest 테스트 코드를 작성해줘"
• codex "이 코드를 TypeScript로 변환해줘"
• codex "API 엔드포인트를 추가해줘"
• codex "코드 리뷰 해줘"

---

🖥️ IDE에서도 사용 가능!

터미널이 익숙하지 않다면, 코드 에디터 안에서 바로 사용할 수도 있습니다.

• ✅ VS Code
• ✅ Cursor
• ✅ Windsurf

👉 IDE 확장 설치 가이드

데스크톱 앱으로도 사용 가능합니다:

# 데스크톱 앱 실행
codex app

---

🔧 원격/헤드리스 환경에서 로그인하기

서버처럼 브라우저가 없는 환경에서는 Device Code 인증을 사용합니다:

codex login --device-auth

1. 터미널에 표시된 URL과 코드를 확인
2. 다른 기기의 브라우저에서 해당 URL 접속
3. 일회용 코드 입력하면 로그인 완료

---

❓ 자주 묻는 질문 (FAQ)

Q. 무료로 사용할 수 있나요?

A. ChatGPT Plus($20/월), Pro, Team, Edu, Enterprise 구독에 Codex가 포함되어 있습니다. API 키를 사용하면 사용량에 따라 별도 과금됩니다.

Q. Windows에서 직접 설치할 수 없나요?

A. 현재 Codex CLI는 Windows에서 직접 지원하지 않습니다. WSL2를 통해 Linux 환경에서 사용해야 합니다.

Q. npm install 시 권한 오류가 나요

A. sudo npm install -g @openai/codex로 실행하거나, nvm을 사용하면 권한 문제가 해결됩니다.

Q. Codex CLI와 Codex Web(chatgpt.com/codex)의 차이는?

A. CLI는 로컬 터미널에서 실행되어 내 컴퓨터의 파일을 직접 수정합니다. Web은 클라우드에서 실행되는 버전입니다.

Q. 인터넷 없이도 사용 가능한가요?

A. 아닙니다. Codex는 OpenAI 서버와 통신이 필요하므로 인터넷 연결이 필수입니다.

---

📝 마무리

Codex CLI는 AI가 직접 코드를 작성하고 수정하는 시대를 보여주는 도구입니다. 설치 자체는 npm install -g @openai/codex 한 줄이면 끝나지만, 그 안에서 할 수 있는 일은 무궁무진합니다.

특히 바이브코딩(Vibe Coding) 트렌드와 함께, 비개발자도 자연어로 소프트웨어를 만들 수 있는 시대가 열리고 있습니다. Codex CLI를 설치하고 직접 체험해 보세요!

🔗 Codex GitHub 바로가기  📚 공식 문서 보기