코덱스(Codex) 설치 방법: 데스크톱 앱·CLI, Windows·macOS 명령과 자주 나는 오류

코덱스(Codex)는 쓰는 방식에 따라 두 가지로 설치합니다. 화면에서 쓰려면 ChatGPT 데스크톱 앱을 공식 다운로드 페이지에서 받아 설치하고 앱 안에서 Codex를 고르면 되고, 터미널에서 쓰려면 Codex CLI를 설치 명령 한 줄로 설치합니다. macOS·Linux는 curl -fsSL https://chatgpt.com/codex/install.sh | sh, Windows는 새 PowerShell 창에서 powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"를 실행하세요. 요금 문서 기준으로 데스크톱 앱의 Codex는 Free 플랜부터, CLI는 Plus 이상이나 API 키로 씁니다.

9월 가톨릭대학교 AI 부트캠프에서 코딩 경험이 없는 대학생 60여 명에게 데스크톱 앱만 쓰게 했는데, 가장 많이 막힌 곳이 코딩이 아니라 설치였고 Windows PC에서 더 자주 막혔습니다. 저는 평소 Codex CLI를 코드 리뷰와 교차 검증에 씁니다. 이 글은 설치와 로그인, 설치 직후 막히는 오류만 다룹니다. 설치 명령과 요구 사항은 2026년 10월 30일에 공식 문서와 GitHub 저장소로 다시 확인했어요.

무엇을 설치할지 먼저 고르세요

처음이라면 데스크톱 앱 하나로 충분합니다. 앱과 CLI는 같은 설정 폴더를 쓰기 때문에 나중에 CLI를 더 설치해도 설정을 두 번 하지 않아요. 네 가지 진입점의 차이는 코덱스(Codex) 사용법에 정리했습니다.

데스크톱 앱 설치: 운영체제별 요약

Codex 앱은 7월 9일에 macOS·Windows용 ChatGPT 데스크톱 앱으로 합쳐졌습니다(What's new). 그래서 지금은 Codex만 따로 받는 데스크톱 설치 파일이 없고, ChatGPT 데스크톱 앱을 설치한 뒤 위쪽 메뉴에서 Codex를 고릅니다. 같은 공지는 이 앱을 Free를 포함한 모든 ChatGPT 플랜에서 전 세계에 제공한다고 적었어요.

설치한 뒤 앱을 열고 Continue to sign in을 누르면 브라우저가 열립니다. ChatGPT 계정으로 로그인하면 앱으로 돌아와요(인증 문서). 2026년 10월 30일 Mac에서 연 다운로드 페이지에는 Download for macOS 버튼과 함께 기존 Codex 앱 사용자는 ChatGPT로 업데이트한 뒤 Codex를 열면 된다는 안내가 있었습니다. 폴더 열기, 권한 모드, 첫 페이지 만들기까지는 코덱스 데스크톱 앱 설치와 사용법에 화면 순서대로 적었습니다.

Codex CLI 설치: macOS·Linux

Codex CLI 문서는 설치 방법 세 가지를 안내합니다. 하나만 고르면 됩니다.

# 공식 설치 스크립트 (권장)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Homebrew
brew install --cask codex

# npm
npm install -g @openai/codex

공식 설치 스크립트는 codex 실행 파일을 ~/.local/bin에 넣고, 이 폴더가 PATH에 없으면 셸 설정 파일에 추가합니다. Mac의 기본 셸(zsh)이라면 ~/.zprofile이에요. 설치가 끝나면 "새 터미널을 열고 codex를 실행하라"는 안내가 나옵니다. 지금 열린 창은 PATH가 바뀌기 전 상태라서 그렇습니다.

npm으로 설치하려면 Node.js가 먼저 있어야 합니다. npm 패키지 정보 기준으로 Node.js 16 이상이에요. 공식 설치 스크립트와 Homebrew는 Node.js가 필요 없습니다. Codex CLI 자체가 Node.js가 아닌 Rust로 만든 실행 파일이기 때문입니다.

Linux에서는 Codex가 명령을 격리해서 실행할 때 bubblewrap을 씁니다. 샌드박스 문서는 먼저 설치해 두라고 안내해요. Ubuntu·Debian은 sudo apt install bubblewrap, Fedora는 sudo dnf install bubblewrap입니다.

Codex CLI 설치: Windows

새 PowerShell 창을 열고 아래를 붙여 넣습니다.

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

공식 설치 스크립트는 실행 파일을 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin에 넣습니다. 설치한 그 창에서는 바로 codex를 쓸 수 있고, 다른 창에서는 새 PowerShell 창을 열어야 잡힌다고 안내가 나와요. npm(npm install -g @openai/codex)으로 설치해도 됩니다.

Windows에서 Codex는 WSL 없이 PowerShell에서 바로 돕니다. 작업 폴더 밖 쓰기와 허락 없는 네트워크 접속은 Windows 샌드박스로 막아요(Windows 앱 문서). Windows 샌드박스 문서의 지원 표는 이렇습니다.

WSL을 쓰고 싶다면 WSL2여야 합니다. Codex 0.115부터 WSL1은 지원하지 않습니다. WSL 안에서 CLI를 따로 돌리면 Linux 쪽 홈 폴더(~/.codex)를 써서 Windows 앱의 설정·로그인·대화 기록(%USERPROFILE%\.codex)과 자동으로 공유되지 않아요. 공유하려면 WSL에서 CODEX_HOME을 Windows 쪽 폴더로 지정합니다.

설치 확인과 첫 로그인

설치가 끝나면 새 터미널 창에서 버전부터 확인합니다.

codex --version

버전 번호가 나오면 설치는 된 겁니다. 그다음 작업할 프로젝트 폴더로 이동해 codex를 실행하고 Sign in with ChatGPT를 고릅니다. 브라우저에서 로그인하면 터미널로 돌아와요. 로그인만 따로 하려면 codex login, 지금 어떤 방식으로 로그인돼 있는지는 codex login status로 봅니다(인증 문서).

API 키로 로그인할 수도 있습니다. 키를 환경변수에 넣어 둔 상태라면 printenv OPENAI_API_KEY | codex login --with-api-key입니다. 다만 이 경우 ChatGPT 구독 한도가 아니라 API 요금이 따로 나가고 Codex Cloud 같은 클라우드 기능은 쓸 수 없어요. 처음에는 ChatGPT 계정으로 시작하는 편이 낫습니다. 키 값은 대화창이나 문서에 붙여 넣지 말고 환경변수로 두세요.

CLI와 IDE 확장은 저장된 로그인 정보를 함께 씁니다. 한쪽에서 로그아웃하면 다른 쪽도 다음에 시작할 때 다시 로그인해야 해요(인증 문서).

요금제별로 설치해서 쓸 수 있는 것

Codex 요금 문서의 2026년 10월 30일 기준 내용입니다.

Free나 Go라면 CLI를 설치해도 요금 문서상 쓸 수 있는 곳은 데스크톱 앱입니다. 결제 통화와 부가세는 결제 화면에서 확인하세요. 플랜별 한도와 크레딧은 코덱스 요금제 정리에 따로 모았습니다.

업데이트하는 법

데스크톱 앱에 들어 있는 Codex와 따로 설치한 CLI는 버전이 다를 수 있습니다. 그래서 어떤 기능이 CLI에는 있는데 앱에는 아직 없을 수 있어요(문제 해결 문서). CLI 버전은 codex --version으로 봅니다.

설치 직후 자주 나는 오류

아래는 제가 겪은 사례가 아니라 공식 문서와 공식 설치 스크립트가 안내하는 확인 항목입니다.

설치했는데 codex 명령을 찾지 못한다고 나옵니다

설치한 뒤 새 터미널(Windows는 새 PowerShell 창)을 열었는지부터 확인하세요. 공식 설치 스크립트는 PATH를 셸 설정 파일에 추가하지만 이미 열려 있던 창에는 반영되지 않습니다. 새 창에서도 안 되면 설치 방법을 하나로 정했는지 봅니다. 여러 방법으로 겹쳐 설치했다면 하나만 남기는 편이 헷갈리지 않아요.

npm.ps1 cannot be loaded because running scripts is disabled on this system.

Windows PowerShell에서 npm을 처음 쓸 때 실행 정책 때문에 나는 오류입니다. Windows 앱 문서는 흔한 해결책으로 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned를 소개하면서 바꾸기 전에 Microsoft 실행 정책 안내를 확인하라고 적었습니다. 학교·회사 PC라면 관리자에게 먼저 물어보세요. 공식 설치 스크립트로 설치하면 npm을 거치지 않습니다.

로그인 창이 열렸는데 터미널로 돌아오지 않습니다

원격 서버나 SSH 접속처럼 브라우저가 없는 환경이거나, 네트워크 설정이 로그인 정보를 CLI로 돌려주는 내 컴퓨터 안 주소(localhost) 연결을 막는 경우입니다. 인증 문서는 이때 기기 코드 로그인(베타)을 권합니다.

1. ChatGPT 보안 설정에서 기기 코드 로그인을 켭니다(회사 워크스페이스는 관리자가 켭니다).
2. 터미널에서 codex login --device-auth를 실행합니다.
3. 나온 링크를 브라우저에서 열고 로그인한 뒤 일회용 코드를 입력합니다.

그래도 안 되면 codex login이 남기는 codex-login.log 파일을 확인하거나 피드백에 첨부합니다.

회사 네트워크에서 인증서 오류가 납니다

회사가 보안 프록시나 자체 루트 인증서를 쓰는 경우입니다. 인증 문서는 로그인 전에 CODEX_CA_CERTIFICATE에 회사 인증서 파일(PEM) 경로를 지정하라고 안내합니다. 인증서 파일은 회사 IT 담당자에게 받으세요.

이메일로 로그인했더니 다단계 인증(MFA)을 설정하라고 합니다

계정의 로그인 방법 중에 이메일·비밀번호가 있으면 Codex를 쓰기 전에 MFA를 먼저 설정해야 합니다. 구글·마이크로소프트·애플 계정으로만 로그인한다면 ChatGPT 쪽 MFA는 필수가 아니고 해당 계정에서 설정할 수 있어요(인증 문서).

Windows에서 샌드박스 설정이 실패합니다

Windows 샌드박스 문서가 꼽는 흔한 원인은 관리자 승인 창(UAC)을 거절한 경우입니다. 학교·회사가 관리하는 노트북은 Windows 버전이 맞아도 이 단계가 막힐 수 있어요. 내 PC라면 승인하고, 관리 기기라면 담당자에게 앱 설치와 관리자 승인이 가능한지 물어보세요. 자세한 확인 순서는 데스크톱 앱 글의 Windows 항목에 있습니다.

Linux·WSL2에서 시작할 때 bwrap 경고가 뜹니다

bubblewrap이 없거나 격리 실행에 필요한 사용자 네임스페이스를 만들 수 없을 때 뜨는 경고입니다. 위 Linux 절의 bubblewrap 설치 명령을 먼저 실행하세요. Ubuntu에서는 설치한 뒤에도 AppArmor 설정이 필요할 수 있어서 샌드박스 문서의 해당 단계를 따릅니다.

자주 묻는 질문

코덱스 설치는 무료인가요?

설치 파일과 CLI는 무료로 받습니다. 쓰는 데 필요한 플랜은 따로예요. 요금 문서상 Free 플랜에도 데스크톱 앱의 Codex가 들어 있지만 GPT-6 Luna를 순차 공개하는 조건이 붙고, CLI·IDE 확장은 Plus부터 나옵니다.

Codex만 따로 설치할 수는 없나요?

데스크톱 앱은 ChatGPT 데스크톱 앱 하나로 합쳐져서 Codex만 든 설치 파일이 없습니다. 터미널용 Codex CLI는 따로 설치하는 도구라 데스크톱 앱 없이 CLI만 설치해도 됩니다.

Windows에서 WSL을 꼭 설치해야 하나요?

아닙니다. 지금은 데스크톱 앱과 CLI 모두 PowerShell에서 바로 돕니다. WSL을 쓰고 싶을 때만 WSL2로 설치하세요. WSL1은 Codex 0.115부터 지원하지 않습니다.

Node.js를 먼저 설치해야 하나요?

npm으로 설치할 때만 필요합니다. 공식 설치 스크립트나 Homebrew로 설치하면 Node.js 없이 설치됩니다.

클로드 코드(Claude Code)도 같이 설치하고 싶어요

설치 방법이 다르니 Claude Code 설치 가이드를 보세요. Windows에서 막혔다면 Claude Code Windows 설치 오류 해결에 오류별 해결책을 모았습니다. 둘 중 무엇으로 시작할지는 클로드 코드 vs 코덱스에 비교해 두었어요.

다음 단계

• 데스크톱 앱으로 첫 페이지 만들기: 코덱스(Codex) 데스크톱 앱 설치와 사용법
• 앱·CLI·IDE·클라우드 전체 사용법: 코덱스(Codex) 사용법
• 플랜과 한도: 코덱스 요금제 정리
• 노션·GitHub 연결: Codex MCP 연결 방법
• 주제 모아 보기: 코덱스

출처와 확인 (2026-10-30)

• Codex CLI (설치 스크립트·Homebrew·npm 설치와 업데이트 명령, Windows는 새 PowerShell 창, 첫 로그인)
• GitHub openai/codex README (설치 명령, 설치 스크립트의 내려받기 위치, GitHub Release 실행 파일)
• 공식 설치 스크립트 install.sh·install.ps1 (설치 폴더, PATH 추가 위치, 새 터미널 안내. 실행하지 않고 내용만 확인)
• npm @openai/codex (2026년 10월 30일 최신 0.166.0, Node.js 16 이상)
• Authentication (ChatGPT·API 키 로그인, codex login status, 로그인 공유, 기기 코드 로그인, CODEX_CA_CERTIFICATE, MFA, codex-login.log)
• Pricing (플랜별 가격과 쓸 수 있는 곳, API 키 조건)
• What's new (7월 9일 Codex 앱이 ChatGPT 데스크톱 앱으로 통합, 모든 플랜 전 세계 제공)
• Quickstart · Download ChatGPT (데스크톱 앱 받는 곳. 다운로드 페이지는 2026년 10월 30일 Mac 브라우저로 확인)
• Homebrew cask codex (실행 파일 설치, 별도 의존성 없음)
• ChatGPT desktop app for Windows (Microsoft Store 링크, winget, PowerShell 실행, WSL2, WSL1 미지원, CODEX_HOME, 실행 정책 오류)
• Windows sandbox (Windows 버전 지원 표, winget, 관리자 승인 거절)
• ChatGPT desktop app for Linux (지원 배포판과 아키텍처)
• Sandbox (Linux·WSL2의 bubblewrap, 시작 경고)
• Troubleshooting (앱과 CLI의 Codex 버전 차이)