미래이음연구소

🤖 Codex CLI란?

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

📋 설치 전 준비사항

⚠️ 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부터 설치합니다:

# 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

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. 운영체제에 맞는 파일 다운로드

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에 저장되어 다음부터 자동 로그인됩니다

방법 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를 한국어로 작성해줘"

🖥️ IDE에서도 사용 가능!

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

• ✅ VS Code
• ✅ Cursor
• ✅ Windsurf

👉 IDE 확장 설치 가이드

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

# 데스크톱 앱 실행
codex app

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

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

codex login --device-auth

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

❓ 자주 묻는 질문 (FAQ)

📝 마무리

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

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

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