Windows에서 Codex CLI 설치하기: PowerShell과 WSL2 선택 기준

요약: 현재 Codex는 네이티브 Windows와 WSL2 환경을 안내합니다. 기존 개발 도구가 어느 환경에 설치되어 있는지 확인한 뒤 같은 환경에서 설치하고 실행하세요.

1. 오래된 Windows 안내를 그대로 따라 하면 안 되는 이유

OpenAI의 현재 Windows 문서는 CLI와 IDE 확장 등을 네이티브 Windows에서 사용하는 흐름과 Windows 샌드박스를 설명합니다. 따라서 모든 사용자에게 WSL이 필수라고 단정하면 현재 지원 상태와 맞지 않습니다. 설치 글을 읽을 때는 작성일뿐 아니라 공식 문서가 지금 어떤 환경을 안내하는지 확인하세요.

선택 기준은 자신의 프로젝트입니다. PowerShell에서 정상 실행되는 프로젝트라면 네이티브 환경부터 검토할 수 있습니다. 개발 도구와 저장소가 이미 Linux 환경에 있거나 Linux 도구가 필요하다면 WSL2가 자연스러울 수 있습니다. 아래 절차는 현재 작업 환경을 확인하고 첫 프로젝트를 여는 흐름으로 구성했습니다.

2. 공식 Windows 설치 명령부터 실행하기

OpenAI 공식 CLI 문서는 Windows용 독립 설치 명령을 안내합니다. 네이티브 Windows에서 시작한다면 PowerShell을 열고 다음 명령을 공식 안내와 비교한 뒤 실행할 수 있습니다. 이 방식부터 살펴보고, 이미 Node.js를 사용하는 독자는 아래 npm 대안을 선택하세요.

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

이 명령은 공식 주소의 설치 스크립트를 내려받아 실행합니다. 설치 출력에서 완료 안내와 오류를 구분해 읽고, 새 터미널에서 아래 명령으로 Codex가 인식되는지 확인하세요. 회사나 학교의 관리 정책이 적용되는 환경이라면 설치 방식이 허용되는지 확인해야 합니다.

codex --version

Node.js와 npm이 이미 설치된 환경의 대안: 공식 CLI 문서는 npm 설치도 안내합니다. 이 방식을 선택한다면 현재 터미널에서 도구를 확인한 뒤 설치하세요. 두 설치 방법을 연달아 실행하기보다 하나를 선택하고 결과를 기록하는 편이 설치 상태를 파악하기 쉽습니다.

node --version
npm --version
npm install -g @openai/codex
codex --version

버전 확인은 도구가 현재 터미널에서 인식되는지 점검하는 과정입니다. 설치가 끝난 뒤에는 작업할 프로젝트 폴더에서 codex를 실행합니다. 첫 실행의 로그인은 공식 CLI 문서가 안내하는 사용 가능한 방법을 따르세요. 설치 성공과 계정의 이용 가능 여부는 서로 다른 확인이며, 이 글은 특정 요금제나 이용 한도를 보장하지 않습니다.

3. PowerShell에서 먼저 확인할 것

터미널을 열고 현재 폴더를 확인한 뒤 프로젝트로 이동하세요. 아래 경로는 예시입니다. 저장소가 없는 사용자 문서 폴더 전체를 작업 대상으로 잡기보다 실제 코드가 있는 폴더를 선택하는 편이 작업 범위를 이해하기 쉽습니다.

Get-Location
Set-Location -LiteralPath 'C:\code\my-project'
Get-Command codex
codex

codex를 찾지 못한다면 설치 오류와 PATH 인식 오류를 구분해야 합니다. 새 터미널에서도 같은지 확인하고, 어떤 방식으로 어느 환경에 설치했는지 기록하세요. 회사 컴퓨터의 정책으로 설치나 샌드박스 설정이 막혔다면 오류 메시지를 먼저 읽습니다. 문제를 해결하려고 보안 설정을 일괄 해제하는 방법부터 적용하지 마세요.

4. WSL을 선택한다면 WSL2와 경로를 확인하기

공식 WSL 안내는 WSL2를 설명하며, Codex 0.115부터 WSL1을 지원하지 않는다고 명시합니다. WSL 환경을 쓸 때는 Windows 터미널에서 설치한 도구와 Linux 환경의 도구를 같은 것으로 생각하지 않는 것이 중요합니다. 프로젝트를 실행할 셸 안에서 도구를 확인하세요.

이미 WSL을 사용한다면 Windows의 PowerShell 또는 Windows 터미널에서 아래 명령으로 배포판 목록을 먼저 읽습니다. 사용할 배포판의 VERSION 열이 2인지 확인하세요. 1이면 그 배포판에서 Codex 설치를 계속하지 말고 WSL2 준비 절차를 마친 뒤 다시 확인합니다. 이 명령은 배포판 정보를 조회하는 단계입니다.

wsl --list --verbose

공식 문서는 WSL에서 저장소를 Linux 홈 디렉터리에 두는 흐름을 권장합니다. Windows 파일 경로와 /home 아래 경로는 표시와 접근 방식이 다릅니다. 아래는 Linux 셸에서 현재 위치와 설치 상태를 살펴보는 예시이며, PowerShell용 명령과 섞어 실행하지 않습니다.

pwd
command -v codex
codex --version

VS Code를 쓰는 경우에도 터미널이 Windows에서 실행되는지 WSL에서 실행되는지 확인하세요. 한쪽에서는 명령이 되고 다른 쪽에서는 안 되는 문제라면 설치를 여러 번 반복하기 전에 실행 환경 차이를 먼저 점검할 수 있습니다.

5. 설치 후 첫 요청과 실패 확인

이 프로젝트의 실행 방법과 테스트 명령을 찾아 설명해 주세요.
현재 작업 경로와 사용 중인 셸도 확인해 주세요.
아직 파일을 수정하거나 새 패키지를 설치하지 마세요.
실행할 수 없는 확인은 그 이유를 표시해 주세요.

• 명령을 찾지 못함: 설치 방식, 현재 셸, PATH 인식을 확인합니다.
• 프로젝트가 보이지 않음: 현재 경로와 Windows·WSL 파일 위치를 확인합니다.
• 로그인이 안 됨: 설치 문제가 아니라 인증 단계의 오류인지 구분합니다.
• 명령 실행이 차단됨: 샌드박스와 조직 정책의 제한을 확인합니다.

6. PowerShell과 WSL2를 고르는 실용적인 기준

두 환경의 선택은 성능 순위를 정하는 일이 아닙니다. 지금 프로젝트가 사용하는 런타임, 실행 스크립트, 파일 경로에 맞추는 일입니다. Windows에서 개발 서버와 테스트가 이미 잘 실행된다면 새로 Linux 환경을 만드는 대신 그 환경에서 시작할 수 있습니다. 반대로 쉘 스크립트와 Linux 도구가 중심인 프로젝트라면 WSL2 안에서 실행하는 쪽이 기존 안내를 따라가기 쉽습니다.

환경을 정했으면 경로와 도구를 한곳에 기록하세요. “Windows·PowerShell·C:\Projects\demo” 또는 “WSL2·Linux 셸·~/code/demo”처럼 짧은 조합이면 충분합니다. 문제가 생겼을 때 “Codex 설치가 안 된다”보다 이 조합과 실패한 명령을 전달하면 어디에서 실행됐는지 바로 알 수 있습니다. 같은 이름의 프로젝트 복사본이 양쪽에 있다면 현재 수정하는 복사본도 표시하세요.

7. 설치 성공, PATH, 인증을 분리해 점검하기

설치 이후 오류는 서로 다른 단계에서 생깁니다. 버전이 출력되지 않는다면 명령 인식부터 보고, 버전은 출력되지만 로그인에서 멈춘다면 인증을 봅니다. Codex가 켜지지만 프로젝트를 못 읽는다면 작업 경로와 접근 범위를 살펴봅니다. 아래는 PowerShell에서 위치와 현재 인식되는 명령을 읽는 점검 예시입니다.

Get-Location
Get-Command codex -All
Get-Command node -ErrorAction SilentlyContinue
Get-Command npm -ErrorAction SilentlyContinue
codex --version

Get-Command 결과의 경로를 보면 어떤 설치가 호출되는지 파악할 수 있습니다. 여러 결과가 나온다면 예전에 다른 방식으로 설치한 실행 파일이 남아 있을 수 있으므로, 무작정 둘 다 다시 설치하기보다 사용하려는 설치 방식을 정리합니다. 현재 터미널에서만 못 찾으면 새 PowerShell 창을 열어 다시 확인하세요. 새 창에서도 안 되면 설치 출력의 완료 여부와 PATH 안내를 읽어 다음 조치를 정합니다.

npm 방식에서 node와 npm을 찾지 못하면 Codex 패키지 설치 이전의 런타임 준비 문제입니다. 독립 설치 방식을 쓸 계획이라면 npm을 추가로 설치할 필요가 없습니다. 로그인 단계에서는 공식 CLI의 첫 실행 안내를 따르고, 조직 계정이라면 해당 작업 공간의 이용 권한도 확인합니다. 오류 화면에는 로그인 관련 비밀 정보가 들어갈 수 있으므로 공유할 때는 실패 단계와 메시지만 전달하세요.

Windows PowerShell에서 Codex를 시작하려고 합니다.
선택한 설치 방식: [독립 설치 / npm]
현재 작업 경로: [경로]
실행한 명령: [명령]
관찰한 결과: [버전 출력 / 명령 없음 / 인증 오류]
오류 메시지: [비밀값을 제외한 원문]
같은 설치를 반복하기 전에 실패한 단계부터 구분해 주세요.

8. WSL2를 선택한 독자의 설치 순서

WSL을 처음 준비하는 경우와 이미 사용하는 경우를 구분하세요. 공식 WSL 안내에는 Windows에서 WSL을 설치하고 셸을 연 다음, 그 Linux 셸 안에서 Codex를 설치하는 순서가 나옵니다. WSL 설치가 필요한 경우의 Windows 명령은 다음과 같습니다. WSL 초기 설치는 관리자 권한이 필요한 단계이며, 완료 후 배포판의 초기 설정 안내를 따라야 합니다.

wsl --install

설치 안내에서 재시작을 요구하면 재시작하고 배포판의 초기 설정을 마칩니다. 이어 Windows 셸에서 wsl --list --verbose를 실행해 사용할 기본 배포판의 VERSION이 2인지 확인한 뒤 Linux 셸을 엽니다. 이미 설치된 배포판을 사용하는 독자는 초기 설치 단계부터 반복하지 않습니다.

wsl

아래 명령은 PowerShell이 아니라 열린 WSL Linux 셸에서 실행합니다. 기존에 WSL을 사용한다면 초기 설치를 반복할 필요 없이 자신의 배포판과 프로젝트를 여세요. Windows에서 Codex를 설치했더라도 WSL의 PATH와 실행 환경은 별도이므로 그 안에서 명령이 인식되는지 확인해야 합니다.

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version
mkdir -p ~/code
cd ~/code
pwd

프로젝트를 ~/code 아래에 준비했다면 그 프로젝트 폴더에서 codex를 실행합니다. 저장소를 가져오는 방법은 프로젝트의 안내를 따르고, 실제 주소가 아닌 예시 주소를 그대로 복제하지 마세요. 이미 /mnt/c 아래에서 작업하던 프로젝트를 옮기려면 저장되지 않은 변경과 로컬 설정을 먼저 보관하고 새 위치의 실행 상태를 확인합니다. 위치만 바꿨다고 의존성이나 환경 설정이 자동으로 준비되지는 않습니다.

VS Code에서 WSL 프로젝트를 열려면 WSL 셸에서 프로젝트로 이동한 뒤 code .을 사용하는 공식 흐름을 참고할 수 있습니다. 편집기와 터미널이 같은 환경을 보고 있는지 먼저 확인하세요. Linux 경로의 파일을 수정하면서 Windows 쪽 개발 서버 화면을 보고 있다면, 실제 변경이 반영되지 않은 것처럼 보일 수 있습니다.

9. Windows 샌드박스 설정과 첫 실행을 마무리하기

현재 공식 Windows 문서는 네이티브 샌드박스의 elevated와 unelevated 모드를 안내합니다. elevated가 권장되고 unelevated는 초기 설정이 제한되는 환경에서 검토할 대안입니다. 이것은 Codex CLI 설치 방식과 다른 설정입니다. 설치 파일이 존재하는데 실제 명령 실행이 막힌다면 이 단계의 오류를 별도로 보아야 합니다.

[windows]
sandbox = "elevated"

위 내용은 공식 config.toml 설정 형식의 예시입니다. 이미 설정 파일이 있다면 같은 [windows] 구역을 중복해서 추가하지 말고 기존 항목을 검토하세요. 조직에서 허용 모드를 관리하는 경우 개인 설정으로 바꾸어도 적용되지 않을 수 있습니다. elevated 초기 설정 실패 시 오류 메시지와 정책을 조사하고, 허용된 경우에만 unelevated 대안을 선택합니다. 매 작업을 관리자 터미널에서 수행하는 것과 초기 샌드박스 준비는 같은 의미가 아닙니다.

1. 선택한 셸에서 Codex 버전을 기록합니다.
2. 실제 프로젝트 폴더로 이동해 codex를 시작하고 로그인 단계까지 마칩니다.
3. 수정 없이 구조와 실행 명령을 읽는 작은 요청을 보냅니다.
4. 현재 경로·읽은 파일·검증 도구가 예상과 맞으면 작은 수정으로 진행합니다.
5. 실행이 막히면 설치·인증·샌드박스·프로젝트 준비 중 어느 단계인지 나누어 해결합니다.

업데이트할 때도 최초에 선택한 설치 방식을 기준으로 관리하세요. 공식 CLI는 독립 설치 스크립트를 다시 실행하는 업데이트와 npm install -g @openai/codex 방식의 업데이트를 함께 안내합니다. 업데이트 후에는 새 터미널에서 버전과 간단한 탐색 요청을 확인하면 현재 실행되는 도구가 바뀌었는지 파악하기 쉽습니다. 특정 버전의 설치 성공을 이 글에서 보장하는 것은 아니므로 실제 출력은 자신의 환경에서 확인해야 합니다.

10. 자주 묻는 질문

WSL2로 무조건 옮겨야 하나요? 현재 공식 문서는 네이티브 Windows도 안내합니다. 프로젝트의 도구와 기존 작업 환경에 맞춰 선택하세요.

관리자 권한으로 계속 실행해야 하나요? 설치나 초기 설정에서 필요한 권한과 매 작업의 권한은 구분하세요. 구체적인 요구는 선택한 설치 방식과 공식 샌드박스 안내를 확인해야 합니다.

업데이트 후 명령이 달라지면 어떻게 하나요? 현재 버전을 기록하고 공식 CLI 문서의 설치 안내를 다시 확인하세요. 오래된 블로그의 명령을 최신 환경에 맞는 것으로 가정하지 않는 것이 좋습니다.

공식 출처 및 확인일: OpenAI 공식 문서: Codex CLI · OpenAI 공식 문서: Windows sandbox · OpenAI 공식 문서: WSL. 2026년 10월 3일 확인. 명령과 기능은 현재 환경 및 권한을 확인한 뒤 사용하세요.