OpenAI Codex 설치 가이드 - Windows

OpenAI Codex는 코드를 읽고, 수정하고, 실행할 수 있는 AI 코딩 에이전트다. VS Code 확장으로 IDE에서 바로 사용하거나, CLI로 터미널에서 대화하듯 코딩할 수 있다. Windows에서는 WSL(Windows Subsystem for Linux)을 통해 사용하는 것이 가장 안정적이다.

사전 준비

필수 요구사항
• Windows 10/11
• ChatGPT Plus, Pro, Business, Edu, 또는 Enterprise 구독
• VS Code

Codex는 ChatGPT 유료 플랜에 포함되어 있다. 별도 API 키 없이 ChatGPT 계정으로 로그인하면 바로 사용할 수 있다.

VS Code 설치
1. code.visualstudio.com 접속
2. Download for Windows 클릭
3. 다운로드된 설치 파일 실행
4. 설치 옵션에서 Add to PATH 체크 (중요)
5. 설치 완료 후 VS Code 실행

PowerShell 여는 법
1. 키보드에서 Windows 키를 누른다
2. powershell 입력
3. Windows PowerShell이 나타나면 관리자 권한으로 실행 클릭

또는 시작 버튼 우클릭 → Windows 터미널(관리자)를 선택해도 된다.

방법 1: VS Code 확장 설치

가장 간단한 방법이다. VS Code 마켓플레이스에서 확장을 설치하면 된다.

설치 순서
1. VS Code를 연다
2. 왼쪽 사이드바에서 확장(Extensions) 아이콘 클릭 (또는 Ctrl+Shift+X)
3. 검색창에 OpenAI Codex 입력
4. Codex 확장을 찾아 설치 클릭
5. VS Code 재시작
6. 왼쪽 사이드바에 Codex 아이콘이 나타남
7. 클릭 후 ChatGPT 계정으로 로그인

참고: Windows 네이티브 환경에서 확장은 실험적(experimental) 상태다. 최상의 경험을 위해 WSL 환경에서 VS Code를 열어 사용하는 것을 권장한다.

방법 2: CLI 설치 (WSL 권장)

CLI는 터미널에서 Codex를 실행하는 방식이다. Windows에서는 WSL을 통해 설치하는 것이 안정적이다.

2-1. WSL 설치

PowerShell을 관리자 권한으로 열고 다음 명령어를 실행한다.

wsl --install

설치가 완료되면 컴퓨터를 재부팅한다. 재부팅 후 Ubuntu 터미널이 자동으로 열리며, 사용자 이름과 비밀번호를 설정하라는 메시지가 나온다.

터미널이 자동으로 열리지 않으면 Windows 검색에서 Ubuntu를 검색해서 실행하면 된다.

2-2. Node.js 설치 (nvm 사용)

WSL 터미널에서 다음 명령어를 순서대로 실행한다.

# nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
# 터미널 재시작 후
nvm install 22

터미널을 닫았다가 다시 열거나, source ~/.bashrc를 실행해야 nvm이 활성화된다.

2-3. Codex CLI 설치 및 실행

Node.js 설치가 완료되면 Codex를 설치한다.

# Codex CLI 설치
npm i -g @openai/codex
# Codex 실행
codex

처음 실행하면 로그인 화면이 나온다. ChatGPT 계정 또는 API 키로 인증하자.

WSL에서 VS Code 연결하기

WSL 환경에서 VS Code를 열면 Codex가 더 안정적으로 동작한다.

설정 방법
1. VS Code에서 WSL 확장 설치
2. WSL 터미널에서 프로젝트 폴더로 이동
3. code . 명령어 실행
4. VS Code가 WSL 모드로 열림 (하단 상태바에 WSL: Ubuntu 표시)

팁: 프로젝트는 /mnt/c/ 대신 ~/code/ 같은 Linux 경로에 두는 것이 성능상 유리하다.

문제 해결

확장이 응답하지 않는 경우
C++ 개발 도구가 필요할 수 있다. PowerShell에서 다음을 실행한다.

winget install --id Microsoft.VisualStudio.2022.BuildTools -e

설치 후 VS Code를 완전히 재시작한다.

대용량 저장소에서 느린 경우
• /mnt/c/ 경로 대신 WSL 내부 경로 사용
• WSL 업데이트: wsl --update && wsl --shutdown

codex 명령어를 찾을 수 없는 경우

which codex

명령어로 설치 여부를 확인하고, 없으면 npm으로 다시 설치한다.

업데이트

Codex는 자주 업데이트된다. 최신 버전으로 유지하려면 WSL 터미널에서 다음을 실행한다.

npm i -g @openai/codex@latest

VS Code 확장은 자동으로 업데이트되지만, 확장 페이지에서 수동으로 확인할 수도 있다.

다음 단계

설치가 완료되면 Codex에게 간단한 작업부터 시켜보자. '이 폴더에 있는 파일 목록 보여줘', '이 코드 설명해줘' 같은 요청으로 시작하면 된다. Codex는 파일을 읽고, 수정하고, 터미널 명령어도 실행할 수 있다.