Codex Windows 설치 방법: 앱과 CLI 설정까지 한 번에

Windows에서 Codex를 시작하는 방법은 크게 두 가지입니다. 화면에서 프로젝트와 변경 사항을 관리하려면 ChatGPT 데스크톱 앱의 Codex를, 터미널 중심으로 작업하려면 Codex CLI를 설치하면 됩니다. 현재 Windows에서는 PowerShell 기반 네이티브 실행과 WSL2 실행을 모두 선택할 수 있으므로 프로젝트의 도구 체인과 경로에 맞춰 한쪽을 정하는 것이 중요합니다.

Codex 앱과 CLI 중 무엇을 설치할까

구분	Codex가 포함된 데스크톱 앱	Codex CLI
사용 방식	프로젝트·채팅·diff를 화면에서 관리	PowerShell 또는 WSL 터미널에서 명령
추천 대상	처음 쓰는 사용자, 시각적 검토 중심	터미널·스크립트·Git 중심 개발자
프로젝트 작업	폴더 열기, 작업 트리, Git 검토	현재 디렉터리를 기준으로 실행
Windows 실행	네이티브 PowerShell 또는 WSL 선택	네이티브 PowerShell 또는 WSL2
설치 경로	Microsoft Store	공식 PowerShell 설치 스크립트

둘 중 하나만 사용해야 하는 것은 아닙니다. 같은 프로젝트를 앱에서 검토하고 CLI에서 빠르게 작업할 수도 있지만, 한 작업 중 네이티브 Windows와 WSL 경로를 섞으면 의존성과 권한 문제가 생길 수 있으므로 실행 환경은 일관되게 유지하세요.

설치 전 준비 사항

• 업데이트가 적용된 Windows 환경
• ChatGPT 계정 또는 Codex에 사용할 OpenAI API 키
• Git이 설치되고 복제된 개발 프로젝트
• 프로젝트에서 사용하는 Node.js, Python, Java 등의 런타임
• WSL2를 선택할 경우 설치된 Linux 배포판과 해당 배포판 안의 Git·런타임
• 회사 PC라면 Microsoft Store, PowerShell 스크립트와 로그인에 대한 조직 정책 확인

API 키를 사용할 경우 채팅이나 저장소 파일에 직접 붙여 넣지 말고 인증 화면 또는 환경 변수와 비밀 관리 수단을 사용하세요. 일부 기능은 로그인 방식이나 계정 제공 범위에 따라 다를 수 있습니다.

Windows에 Codex 데스크톱 앱 설치하기

1. Microsoft Store에서 ChatGPT 데스크톱 앱을 찾아 설치합니다.
2. 앱을 열고 ChatGPT 계정으로 로그인합니다. 지원되는 환경에서는 API 키 로그인도 선택할 수 있습니다.
3. 제품 선택 영역에서 Codex를 선택합니다.
4. 작업할 Git 저장소 폴더를 엽니다.
5. 처음 표시되는 폴더 접근과 명령 실행 권한 범위를 검토합니다.
6. 간단한 읽기 전용 요청으로 프로젝트 인식 여부를 확인합니다.

이 프로젝트의 기술 스택과 빌드 명령을 확인해줘.
파일은 수정하지 말고 근거가 되는 설정 파일 경로를 알려줘.

공식 변경 로그에 따르면 Windows용 Codex는 현재 ChatGPT 데스크톱 앱에 포함됩니다. 이전 독립 Codex 앱을 사용하던 환경은 업데이트 후 프로젝트와 설정이 이어질 수 있지만, 실제 화면은 설치된 버전과 조직 정책에 따라 달라질 수 있습니다.

PowerShell에서 Codex CLI 설치하기

OpenAI 공식 문서가 제공하는 Windows용 독립 실행형 설치 스크립트는 다음과 같습니다. 출처를 확인한 공식 주소만 사용하고 회사 보안 정책상 원격 스크립트 실행이 허용되는지 먼저 확인하세요.

irm https://chatgpt.com/codex/install.ps1 | iex

설치가 끝난 뒤 새 PowerShell 창을 열고 다음 명령으로 실행 파일이 인식되는지 확인합니다.

codex --version
codex

Windows의 기본 사용자 설치 경로는 공식 환경 변수 문서 기준으로 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin입니다. 설치 직후 codex를 찾지 못한다면 PowerShell을 완전히 다시 열고 PATH와 실제 설치 폴더를 확인하세요.

ChatGPT 계정으로 CLI 로그인하기

처음 codex를 실행하면 제공되는 로그인 흐름을 따라 ChatGPT 계정으로 인증할 수 있습니다. 브라우저가 열리면 주소와 요청 주체가 올바른지 확인하고 로그인을 완료합니다.

1. PowerShell 또는 WSL 터미널에서 codex를 실행합니다.
2. 표시되는 로그인 방식을 선택합니다.
3. 브라우저 인증을 완료합니다.
4. 터미널로 돌아와 현재 프로젝트와 계정을 확인합니다.
5. 공용 PC라면 작업 후 로그아웃하고 저장된 인증 정보를 점검합니다.

API 키로 로그인할 때 주의할 점

API 키 인증도 가능하지만 일부 ChatGPT 기반 기능을 사용하지 못할 수 있고 API 사용량 과금 체계를 따를 수 있습니다. 키를 명령 기록, .env 커밋이나 화면 캡처에 노출하지 마세요.

• 개인 키를 저장소의 설정 파일에 기록하지 않습니다.
• 회사 프로젝트에는 조직에서 발급하고 회전 가능한 자격 증명을 사용합니다.
• CI와 비대화형 자동화의 키는 작업 범위에만 주입합니다.
• 로그와 오류 보고서를 공유하기 전에 토큰과 경로를 가립니다.

네이티브 Windows와 WSL2 선택 기준

상황	권장 환경	이유
PowerShell·.NET·Windows 도구 중심	네이티브 Windows	경로와 도구를 그대로 사용
bash·Linux 패키지·컨테이너 중심	WSL2	Linux 개발 환경과 명령 호환
저장소가 C:\에 있음	네이티브 Windows	Windows 파일 시스템 접근이 단순
저장소가 WSL 홈에 있음	WSL2	Linux 권한과 성능 특성 유지
팀 CI가 Linux만 사용	WSL2 고려	로컬·CI 명령 차이를 줄임

WSL1은 최신 Codex의 Linux 샌드박스 경로에 맞지 않으므로 WSL을 사용할 계획이라면 WSL2인지 확인하세요. 저장소를 Windows와 WSL 양쪽에서 번갈아 편집하면 줄바꿈, 파일 권한과 의존성 폴더가 꼬일 수 있습니다.

WSL2 설치와 상태 확인

관리자 PowerShell에서 WSL 설치가 필요한 경우 Windows의 표준 설치 절차를 사용하고 재부팅 후 버전을 확인합니다. 조직 관리 PC에서는 관리자 정책을 먼저 따르세요.

wsl --install
wsl --status
wsl --list --verbose

배포판의 VERSION 열이 2인지 확인합니다. Codex를 WSL 안에서 사용할 때는 Linux 배포판 터미널 안에서 CLI와 프로젝트 의존성을 설치하고, 저장소도 가능하면 WSL 파일 시스템에 두는 편이 일관적입니다.

WSL2에서 샌드박스 준비하기

OpenAI의 샌드박스 문서는 Linux와 WSL2에서 배포판 패키지의 bubblewrap 설치를 권장합니다. Ubuntu 또는 Debian 기반 배포판에서는 다음과 같이 준비할 수 있습니다.

sudo apt update
sudo apt install bubblewrap

설치할 수 없는 환경에서는 Codex가 포함한 보조 경로를 사용할 수 있지만 사용자 네임스페이스 지원 여부에 따라 경고가 나타날 수 있습니다. 경고를 무시하고 샌드박스를 해제하기보다 원인과 조직 정책을 확인하세요.

앱에서 WSL 프로젝트 사용하기

Windows용 데스크톱 앱은 Codex 에이전트와 통합 터미널을 WSL에서 실행하도록 전환할 수 있습니다. 프로젝트가 Linux 도구 체인을 사용한다면 앱 설정에서 WSL 실행 환경을 선택하고 대상 배포판의 프로젝트 폴더를 여세요.

1. WSL2 배포판이 정상 실행되는지 확인합니다.
2. 배포판 안에 Git과 프로젝트 런타임을 설치합니다.
3. 저장소를 WSL 파일 시스템에 복제합니다.
4. 앱 설정에서 Codex의 WSL 실행을 선택합니다.
5. 통합 터미널에서 pwd, Git과 런타임 버전을 확인합니다.
6. 프로젝트의 실제 lint·test·build 명령을 실행합니다.

VS Code 확장을 WSL2에서 실행하기

Windows에서 Codex IDE 확장을 사용한다면 VS Code 설정으로 에이전트를 WSL2 안에서 실행할 수 있습니다.

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

이 설정을 사용하면 Windows 호스트에서도 Linux 샌드박스의 명령 실행, 승인과 파일 시스템 규칙이 적용됩니다. VS Code가 실제로 WSL 폴더를 연 상태인지도 확인하세요.

첫 프로젝트를 안전하게 열기

CLI에서는 작업할 저장소로 이동한 뒤 실행합니다. 처음부터 광범위한 수정 요청을 하기보다 프로젝트 구조와 적용되는 지침을 먼저 확인하세요.

cd C:\work\my-project
codex

이 저장소의 AGENTS.md, 패키지 관리자, 빌드·테스트 명령을 확인해줘.
아직 파일을 수정하거나 새 의존성을 설치하지 마.

저장소별 규칙은 Codex AGENTS.md 작성법처럼 프로젝트 파일에 남겨두면 앱과 CLI에서 같은 기준을 공유하기 쉽습니다.

Windows 샌드박스 설정 이해하기

네이티브 Windows에서 Codex는 Windows 샌드박스를 사용합니다. 공식 기본 구성 문서는 가능하면 elevated 방식을 권장하고, 관리자 설정이 불가능한 경우 unelevated를 폴백으로 안내합니다.

[windows]
sandbox = "elevated"   # 권장
# sandbox = "unelevated" # 관리자 설정을 사용할 수 없을 때

elevated라는 이름은 Codex에 컴퓨터 전체 관리자 권한을 계속 부여한다는 뜻이 아니라, 더 강한 Windows 네이티브 샌드박스 경계를 설정하기 위한 방식입니다. 실제 권한 요청의 대상 경로와 명령을 매번 확인하세요.

처음 설정할 권한 원칙

• 프로젝트 폴더만 쓰기 가능한 워크스페이스로 선택합니다.
• 홈 전체, 다른 드라이브와 네트워크 공유를 불필요하게 열지 않습니다.
• 패키지 설치와 인터넷 접근은 필요한 도메인과 작업에만 허용합니다.
• 배포, 삭제, 데이터베이스 변경 명령은 자동 승인하지 않습니다.
• .env, 인증서와 개인 키를 읽거나 출력하지 못하도록 관리합니다.
• 권한 오류가 나도 즉시 전체 접근 모드로 전환하지 않습니다.

앱에서 프로젝트 설정과 액션 만들기

데스크톱 앱의 로컬 환경 설정에서는 새 작업 트리를 준비하는 설정 스크립트와 빌드·테스트 같은 공통 액션을 정의할 수 있습니다. 플랫폼별 명령이 다르면 Windows와 Linux 스크립트를 따로 작성하세요.

# Windows PowerShell 예시
pnpm install
pnpm build

설정 스크립트에는 개발 환경 준비만 넣고 운영 배포나 데이터 변경은 넣지 않는 것이 좋습니다. 반복 개발 작업을 더 체계화하려면 Codex Skills 사용법도 참고하세요.

설치가 정상인지 확인하는 체크리스트

1. codex --version이 오류 없이 버전을 표시합니다.
2. 올바른 ChatGPT 계정 또는 API 자격 증명으로 로그인됐습니다.
3. 현재 디렉터리가 의도한 Git 저장소입니다.
4. Codex가 프로젝트 파일을 읽고 실제 빌드 명령을 찾습니다.
5. 작은 테스트 파일에서 허용된 범위의 읽기·쓰기가 작동합니다.
6. 범위 밖 접근에는 승인 또는 거부가 적용됩니다.
7. 프로젝트의 lint·test·build가 기존 개발 환경과 동일하게 실행됩니다.

codex 명령을 찾을 수 없을 때

증상	확인할 원인	해결
codex를 인식하지 못함	PowerShell이 이전 PATH 사용	터미널을 완전히 닫고 다시 실행
설치 파일은 있으나 실행 안 됨	설치 폴더가 PATH에 없음	기본 bin 경로와 사용자 PATH 확인
스크립트 실행 차단	조직 또는 실행 정책	정책을 우회하지 말고 관리자 승인·배포 방식 사용
WSL에서 명령 없음	Windows에만 CLI 설치	사용할 WSL 배포판 안에 별도로 설치
다른 버전이 실행됨	PATH에 여러 설치본 존재	Get-Command codex로 실제 경로 확인

로그인이 반복되거나 실패할 때

• 시스템 날짜와 시간이 자동 동기화되는지 확인합니다.
• 브라우저에서 올바른 계정과 워크스페이스를 선택했는지 봅니다.
• 회사 프록시·방화벽이 인증 주소를 차단하는지 관리자에게 확인합니다.
• 앱과 CLI를 최신 버전으로 업데이트하고 완전히 다시 시작합니다.
• API 키를 사용한다면 만료·회수 여부와 프로젝트 권한을 확인합니다.
• 인증 정보를 삭제하기 전 조직에서 정한 복구·로그아웃 절차를 따릅니다.

Windows 경로와 줄바꿈 오류 줄이기

네이티브 Windows와 WSL2를 함께 쓰면 C:\work\app과 /home/user/app처럼 경로 체계가 다릅니다. 한 저장소의 의존성 폴더를 양쪽 런타임이 공유하지 않도록 하고 Git 줄바꿈 정책도 팀과 맞추세요.

• 스크립트에서 Windows 절대 경로를 하드코딩하지 않습니다.
• Node.js의 node_modules나 Python 가상환경을 Windows·WSL이 공유하지 않습니다.
• 셸 문법이 다르면 PowerShell과 bash 스크립트를 분리합니다.
• 대소문자 구분과 실행 권한이 중요한 파일을 Git에서 확인합니다.
• CI가 Linux라면 WSL2에서 최종 검증을 한 번 더 실행합니다.

설치 후 활용할 핵심 기능

• Codex 코드리뷰로 커밋 전 diff와 PR 위험을 확인합니다.
• Codex 병렬 에이전트로 독립적인 탐색·테스트 작업을 동시에 처리합니다.
• 작업 트리로 여러 변경을 현재 체크아웃과 분리합니다.
• 앱의 Git 도구로 변경을 검토하고 필요한 부분만 스테이징합니다.
• 공통 빌드와 테스트를 프로젝트 액션으로 구성합니다.

편집부 결론

Windows에서 Codex를 가장 쉽게 시작하려면 Microsoft Store의 ChatGPT 데스크톱 앱에서 Codex를 선택하세요. 터미널이 익숙하다면 공식 PowerShell 설치 스크립트로 CLI를 설치할 수 있습니다. Windows 도구 중심이면 네이티브 실행, Linux 도구 체인 중심이면 WSL2를 선택하고 저장소·의존성·셸을 한 환경에 맞춰 유지하는 것이 핵심입니다.

이 글은 2026년 9월 4일 OpenAI 공식 문서를 분석해 작성했으며 새 Windows PC에 직접 설치해 장기간 사용한 후기는 아닙니다. 앱 통합 방식, 계정별 제공 기능과 설치 경로는 업데이트될 수 있으므로 설치 직전 최신 공식 문서를 확인하세요.

공식 문서와 함께 읽을 글

OpenAI ChatGPT·Codex 빠른 시작 확인하기

Codex CLI 설치 경로와 환경 변수 확인하기

Windows·WSL2 샌드박스 공식 문서 보기

Codex와 Claude Code 선택 기준 비교하기

Codex CLI가 실행되지 않을 때 해결하기

설치 후 AGENTS.md 프로젝트 규칙 설정하기

Codex 코드리뷰로 첫 프로젝트 검토하기

자주 묻는 질문

Windows에서 Codex 앱을 설치할 수 있나요?

가능합니다. 현재 Codex는 Windows용 ChatGPT 데스크톱 앱에 포함되며 Microsoft Store에서 앱을 설치한 뒤 Codex를 선택할 수 있습니다.

Windows에 Codex CLI를 설치하는 공식 명령은 무엇인가요?

PowerShell에서 irm https://chatgpt.com/codex/install.ps1 | iex를 사용할 수 있습니다. 원격 스크립트 실행 전 공식 주소와 조직 정책을 확인하세요.

Codex CLI 설치 후 명령을 찾지 못하면 어떻게 하나요?

PowerShell을 완전히 다시 열고 Get-Command codex와 사용자 PATH를 확인하세요. 공식 문서의 기본 설치 위치는 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin입니다.

Windows에서 WSL이 반드시 필요한가요?

아닙니다. Codex는 네이티브 Windows PowerShell과 Windows 샌드박스로 실행할 수 있습니다. Linux 전용 도구가 많은 프로젝트라면 WSL2를 선택할 수 있습니다.

WSL1에서도 Codex를 사용할 수 있나요?

최신 Linux 샌드박스 구현은 WSL2를 전제로 하므로 WSL을 사용할 때는 wsl --list --verbose로 버전 2인지 확인하세요.

ChatGPT 계정과 API 키 중 무엇으로 로그인해야 하나요?

일반 사용자는 ChatGPT 계정 로그인이 간단합니다. API 키 로그인도 가능하지만 일부 기능과 과금 방식이 다를 수 있으므로 사용 목적을 확인하세요.

네이티브 Windows와 WSL에서 같은 프로젝트를 번갈아 써도 되나요?

가능하지만 의존성, 경로, 줄바꿈과 권한 충돌이 생길 수 있습니다. 프로젝트별로 주 실행 환경을 하나 정하고 생성된 의존성 폴더를 공유하지 않는 편이 안전합니다.

Windows 샌드박스를 꺼야 Codex가 작동하나요?

아닙니다. 기본 권한 모드에서 샌드박스가 적용됩니다. 오류가 나면 전체 권한을 열기 전에 경로, 명령과 네이티브 또는 WSL 설정을 먼저 확인하세요.