Windows에서 WSL로 Codex 사용하는 방법 (2026)

WSL 환경의 Windows에서 Codex를 사용하는 방법 (2026)

OpenAI Codex CLI는 코드베이스를 읽고, 코드를 작성하며, 명령어를 실행하고, 파일을 관리할 수 있는 터미널 기반 AI 코딩 어시스턴트입니다. 모든 작업이 커맨드 라인에서 이루어집니다. 단, 이 도구는 macOS와 Linux용으로 설계되었습니다. Windows 사용자라면 WSL (Windows Subsystem for Linux)을 통해 실행해야 합니다.

이 가이드는 WSL 설치부터 Windows 머신에서 Codex를 실행하기까지의 전체 설정 과정을 안내합니다.

OpenAI Codex CLI란 무엇인가요?

Codex CLI는 AI 지원 소프트웨어 개발을 위한 OpenAI의 오픈 소스 커맨드 라인 도구입니다. 다음과 같은 기능을 수행하는 터미널 네이티브 코딩 에이전트라고 생각하면 됩니다.

• 전체 프로젝트 구조를 읽고 이해
• 여러 파일에 걸쳐 코드 작성, 편집 및 리팩토링
• 셸 명령어 실행 및 출력 결과 해석
• 로그와 스택 트레이스를 읽어 오류 디버깅
• 모든 프로그래밍 언어 지원

이 도구는 로컬에서 실행되지만, 언어 모델 백엔드로 OpenAI API(또는 호환되는 엔드포인트)를 사용합니다.

필수 요구 사항

요구 사항	상세 내용
Windows 10 (빌드 19041+) 또는 Windows 11	WSL2 사용을 위해 최신 Windows 버전 필요
관리자 권한	WSL 설치 시 필요
OpenAI API key	platform.openai.com에서 발급 가능
8GB 이상의 RAM	WSL2는 Windows와 함께 실제 Linux 커널을 실행함
안정적인 인터넷 연결	OpenAI API 호출을 위해 필요

1단계: WSL2 설치

WSL2가 아직 설치되어 있지 않다면, PowerShell을 관리자 권한으로 열고 다음 명령어를 실행하세요.

wsl --install

이 명령어는 Ubuntu를 기본 배포판으로 하여 WSL2를 설치합니다. 설치가 완료되면 컴퓨터를 다시 시작하세요.

재부팅 후 Ubuntu 터미널이 자동으로 열립니다. Linux 사용자 이름과 비밀번호를 설정하세요.

WSL2 실행 확인

# PowerShell에서 실행
wsl --list --verbose

다음과 같이 출력되어야 합니다.

  NAME      STATE           VERSION
* Ubuntu    Running         2

VERSION 열에 1이 표시된다면 WSL2로 업그레이드하세요.

wsl --set-version Ubuntu 2

2단계: Linux 환경 설정

WSL 터미널(시작 메뉴에서 "Ubuntu" 검색)을 열고 패키지를 업데이트합니다.

sudo apt update && sudo apt upgrade -y

Node.js 설치

Codex CLI는 Node.js 18 버전 이상이 필요합니다. nvm (Node Version Manager)을 통해 설치하세요.

# nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# 셸 설정 로드
source ~/.bashrc

# Node.js LTS 버전 설치
nvm install --lts

# 설치 확인
node --version  # v22.x 또는 그 이상의 버전이 표시되어야 함
npm --version

Git 설치 (없는 경우)

sudo apt install -y git

3단계: Codex CLI 설치

npm을 사용하여 Codex를 전역(global)으로 설치합니다.

npm install -g @openai/codex

설치를 확인합니다.

codex --version

4단계: API 키 구성

Codex가 작동하려면 OpenAI API 키가 필요합니다. 이를 환경 변수로 설정하세요.

# 영구 적용을 위해 셸 설정 파일에 추가
echo 'export OPENAI_API_KEY="sk-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

또는 프로젝트 디렉토리에 .env 파일을 생성할 수도 있습니다.

echo 'OPENAI_API_KEY=sk-your-api-key-here' > .env

다른 LLM 제공자 사용하기

Codex는 모든 OpenAI 호환 API를 지원합니다. 다른 제공자를 사용하려면 base URL을 설정하세요.

# 예: 로컬 Ollama 인스턴스 사용
export OPENAI_API_KEY="ollama"
export OPENAI_BASE_URL="http://localhost:11434/v1"

# 예: xAI Grok 사용
export OPENAI_API_KEY="your-xai-key"
export OPENAI_BASE_URL="https://api.x.ai/v1"

5단계: Windows 파일 액세스

WSL은 /mnt/c/ 경로를 통해 Windows 파일 시스템에 액세스할 수 있습니다. Windows 프로젝트는 다음 위치에서 사용할 수 있습니다.

# Windows 프로젝트 디렉토리로 이동
cd /mnt/c/Users/YourUsername/Projects/my-app

# 파일 목록 확인
ls -la

더 나은 성능을 위해 저장소를 WSL 파일 시스템 내로 직접 클론하는 것이 좋습니다.

# WSL 네이티브 디렉토리 (I/O 속도가 훨씬 빠름)
cd ~
mkdir projects
cd projects
git clone https://github.com/your-repo/my-app.git

중요: /mnt/c/에서의 파일 작업은 네이티브 WSL 파일 시스템(~/)보다 훨씬 느립니다. 최상의 Codex 성능을 위해 WSL 홈 디렉토리에서 작업하세요.

6단계: Codex 실행

프로젝트 디렉토리로 이동하여 Codex를 시작합니다.

cd ~/projects/my-app

# 대화형 모드로 Codex 시작
codex

# 또는 직접 작업 명령 전달
codex "Add error handling to all the API route handlers in this project"

Codex의 자율 모드 (Autonomy Modes)

Codex는 사용자 확인 없이 수행할 수 있는 작업 범위를 제어하는 세 가지 자율 단계를 제공합니다.

모드	플래그	가능한 작업
Suggest	--suggest	파일 읽기, 변경 사항 제안 (기본값)
Auto-edit	--auto-edit	파일 읽기, 코드 변경 사항 적용
Full auto	--full-auto	파일 읽기, 코드 편집, 명령어 실행

# Codex가 코드를 자동으로 수정하도록 허용
codex --auto-edit "Refactor this Express app to use TypeScript"

# 명령어 실행까지 허용 (주의해서 사용)
codex --full-auto "Set up ESLint and Prettier for this project, install dependencies, and fix all linting errors"

실무 예시

에러 메시지로 버그 수정하기:

codex "I'm getting 'TypeError: Cannot read property of undefined' on line 42 of src/utils/parser.ts. Fix it."

기존 코드에 대한 테스트 추가:

codex "Write unit tests for all functions in src/services/auth.ts using Jest"

컴포넌트 리팩토링:

codex "Convert the UserProfile class component in src/components/UserProfile.jsx to a functional component with hooks"

문제 해결 (Troubleshooting)

"codex: command not found" 오류

npm 전역 bin 디렉토리가 PATH에 포함되어 있는지 확인하세요.

# npm이 전역 패키지를 설치하는 위치 확인
npm config get prefix

# 필요한 경우 PATH에 추가
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

파일 액세스 속도 저하

/mnt/c/의 파일을 다룰 때 Codex가 느리다면 프로젝트를 WSL 파일 시스템으로 옮기세요.

cp -r /mnt/c/Users/YourUsername/Projects/my-app ~/projects/my-app
cd ~/projects/my-app

WSL 메모리 사용량

WSL2는 메모리를 많이 소모할 수 있습니다. Windows 홈 디렉토리에 .wslconfig 파일을 생성하여 제한을 설정하세요.

# C:\Users\YourUsername\.wslconfig
[wsl2]
memory=8GB
processors=4
swap=4GB

설정 변경 후 WSL을 다시 시작합니다.

# PowerShell에서 실행
wsl --shutdown

네트워크 문제 (API 호출 실패)

Codex가 OpenAI API에 연결하지 못하는 경우 WSL의 DNS 설정을 확인하세요.

# DNS 해석 작동 여부 확인
nslookup api.openai.com

# 실패하는 경우 DNS 수정
sudo rm /etc/resolv.conf
sudo bash -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'
sudo bash -c 'echo "[network]\ngenerateResolvConf = false" > /etc/wsl.conf'

GUI 애플리케이션 및 클립보드

Codex 출력을 Windows 클립보드에 복사하려면 다음과 같이 하세요.

# 출력을 Windows 클립보드로 전달
codex "explain this function" | clip.exe

# 또는 양방향 클립보드를 위해 xclip 설치
sudo apt install -y xclip

VS Code 연동

최상의 사용자 경험을 위해 WSL 확장이 설치된 VS Code를 사용하세요.

1. VS Code에서 "WSL" 확장을 설치합니다.
2. WSL 터미널에서 code . 명령으로 WSL 프로젝트를 엽니다.
3. VS Code의 통합 터미널은 자동으로 WSL을 사용하게 됩니다.
4. VS Code 터미널에서 직접 Codex를 실행합니다.

# WSL 프로젝트 디렉토리에서
code .

# 그 후 VS Code 터미널(현재 WSL 상태)에서
codex "Add a README with setup instructions for this project"

Codex vs. 다른 AI 코딩 도구

기능	Codex CLI	Claude Code	Cursor	GitHub Copilot
인터페이스	터미널	터미널	IDE	IDE
파일 편집	가능	가능	가능	제안만 가능
명령어 실행	가능	가능	제한적	불가능
WSL 지원	WSL 필요	WSL 필요	네이티브 지원	네이티브 지원
오픈 소스	예	아니오	아니오	아니오
모델 유연성	모든 OpenAI 호환 모델	Claude 전용	다중 모델	GPT 기반
오프라인 모드	아니오 (API 필요)	아니오	아니오	아니오
가격	API 비용만 발생	Claude 구독	$20+/월	$10+/월

마치며

WSL을 통해 Windows에서 Codex를 실행하면 macOS나 Linux 사용자와 동일한 경험을 누릴 수 있습니다. 설정에는 약 15분 정도 소요되며, WSL2 통합 수준이 높아서 차이점을 거의 느끼지 못할 것입니다. 최상의 성능을 위해 프로젝트 파일을 Windows 드라이브가 아닌 WSL 파일 시스템에 보관하는 것을 잊지 마세요.

코드와 함께 AI 생성 미디어가 포함된 프로젝트를 진행 중이라면, 이미지 생성, 비디오, 대화형 아바타 등을 모두 처리하는 통합 API인 Hypereal AI를 확인해 보세요.

Hypereal AI 무료 체험하기 -- 신용카드 없이 35 크레딧 제공.