Codex CLI를 설치하려는데 어떤 글은 Node.js를, 어떤 글은 WSL을 먼저 요구한다면 출발점부터 헷갈릴 수 있습니다. 현재는 두 가지 모두 모든 환경의 필수 조건이 아닙니다. 운영체제용 독립 실행형 설치 방식(standalone installer)을 쓸 수 있고, 이미 npm이나 Homebrew를 관리하고 있다면 해당 패키지 관리자를 선택할 수도 있습니다.
이 글은 2026년 8월 15일에 확인한 Codex CLI 공식 문서를 기준으로 설치 명령과 최초 실행 절차를 정리했습니다. 여기서 완료 기준은 단순히 설치 명령이 오류 없이 끝나는 것이 아닙니다. 새 터미널이 codex 실행 파일을 찾고, 프로젝트 디렉터리에서 CLI가 시작되며, 자신의 계정에 제공되는 인증 흐름에 진입할 수 있어야 합니다.
내 환경에 맞는 설치 경로부터 고르기
선택은 간단합니다. 추가 런타임을 설치하고 싶지 않다면 운영체제용 standalone 명령부터 검토하세요. 이미 Node.js와 npm을 일관되게 관리하는 개발 환경이라면 npm이 편할 수 있습니다. macOS 등에서 Homebrew로 개발 도구를 관리하고 있다면 Homebrew도 자연스러운 선택입니다.
- macOS/Linux · standalone
- 전제:
curl, 셸 - 원격 스크립트 실행 허용
- 전제:
- Windows · standalone
- 전제: PowerShell
- 스크립트 실행·다운로드 허용
- npm 관리 환경 · npm
- 전제: Node.js와 npm 준비
- Homebrew 관리 환경 · Homebrew
- 전제: Homebrew 준비
공식 문서는 위 standalone 경로와 함께 npm, Homebrew 설치도 안내합니다. 따라서 npm은 npm 방식을 선택했을 때의 전제이지 Codex CLI 전체의 공통 필수 조건이 아닙니다. Windows에서도 공식 PowerShell용 standalone 명령이 있으므로, 일반 설치 자체를 위해 WSL이 무조건 필요하다고 볼 수 없습니다.
조직에서 지급한 기기라면 실행 전에 보안 정책을 확인하세요. curl ... | sh나 irm ... | iex 형식은 인터넷에서 받은 스크립트를 곧바로 실행합니다. 명령의 출처와 내용을 먼저 검토해야 하는 환경이라면 조직의 절차를 따르거나 공식 문서에 나온 다른 설치 방식을 고르세요.
macOS와 Linux에서 설치하기
standalone 방식을 선택했다면 터미널에서 다음 공식 명령을 실행합니다.
bashcurl -fsSL https://chatgpt.com/codex/install.sh | sh
이 명령은 설치 스크립트를 내려받아 셸로 실행합니다. 명령을 복사할 때는 도메인이 chatgpt.com인지 확인하세요. 회사 프록시, 인증서 검사, 셸 제한 또는 파일 쓰기 권한 때문에 중단될 수 있으므로, 오류가 발생하면 메시지를 지우지 말고 어느 단계에서 멈췄는지 먼저 확인합니다.
이미 npm을 사용하는 개발 환경이라면 다음 대안을 선택할 수 있습니다.
bashnpm install -g @openai/codex
npm 전역 설치에서 권한 오류가 발생했다면 무조건 관리자 권한으로 재시도하기보다 현재 Node.js 설치 방식과 npm 전역 경로를 먼저 점검하세요. 이 문제는 Codex 계정 인증 실패와는 다른 종류의 문제입니다.
Homebrew로 CLI 도구를 관리한다면 다음 명령도 공식 선택지입니다.
bashbrew install --cask codex
세 방법을 모두 실행할 필요는 없습니다. 하나를 골라 설치한 뒤 다음 확인 단계로 넘어가세요. 여러 방식으로 중복 설치하면 나중에 셸이 어느 codex 실행 파일을 가리키는지 혼란스러울 수 있습니다.
Windows PowerShell에서 설치하기
Windows에서는 PowerShell을 열고 공식 standalone 명령을 실행합니다.
powershellpowershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
이 명령은 해당 프로세스에 실행 정책을 지정하고, 공식 URL의 PowerShell 스크립트를 받아 실행합니다. 회사 정책이 스크립트 실행을 차단한다면 정책을 임의로 바꾸지 말고 관리자에게 허용 절차를 확인하세요. PowerShell 명령을 찾지 못하거나 다운로드가 차단된 상황도 Codex 로그인 문제와는 구분해야 합니다.
Node.js와 npm을 이미 관리하고 있고 그 방식이 조직 정책에 맞는다면 Windows에서도 npm 설치를 선택할 수 있습니다.
powershellnpm install -g @openai/codex
하지만 npm을 쓰기 위해 Node.js를 새로 추가하는 것이 부담스럽다면 standalone 경로부터 검토하면 됩니다. WSL은 Linux 환경이 필요한 별도 작업 흐름에서 유용할 수 있지만, 이 페이지의 일반적인 Windows 설치 완료 조건은 아닙니다.
설치가 끝났는지 세 단계로 확인하기
설치 명령이 끝났다는 메시지만으로 판단하지 말고, 실행 파일 탐색과 실제 시작을 나눠 확인하세요.
1. 새 터미널을 열어 실행 파일을 찾기
설치 도중 PATH가 변경됐다면 이미 열려 있던 터미널에는 반영되지 않을 수 있습니다. 터미널을 닫고 새로 연 뒤 macOS·Linux에서는 다음 명령을 실행합니다.
bashcommand -v codex
Windows PowerShell에서는 다음과 같이 확인할 수 있습니다.
powershellGet-Command codex
경로가 표시되면 현재 셸이 codex 실행 파일을 찾았다는 뜻입니다. 아무 결과가 없거나 “명령을 찾을 수 없음” 오류가 나오면 로그인으로 넘어가기 전에 설치 위치와 PATH부터 확인해야 합니다. npm과 standalone을 중복 설치했다면 표시된 경로가 자신이 의도한 설치본인지도 살펴보세요.
2. 작업할 프로젝트 디렉터리로 이동하기
Codex CLI는 작업할 프로젝트 디렉터리에서 실행하는 것이 기본 흐름입니다. 바로 홈 디렉터리에서 시작하기보다 먼저 대상 저장소나 프로젝트 폴더로 이동하세요.
bashcd /path/to/your-project codex
Windows PowerShell에서도 프로젝트 경로로 이동한 뒤 같은 codex 명령을 실행하면 됩니다.
powershellSet-Location C:\path\to\your-project codex
공식 빠른 시작도 프로젝트 디렉터리에서 codex를 실행하는 흐름을 안내합니다. 여기까지 도달해 프로그램이 시작되면 설치와 PATH 확인은 대체로 끝났다고 볼 수 있지만, 아직 계정 인증과 실제 서비스 이용 가능 여부는 남아 있습니다.
3. 제공되는 로그인 흐름에 진입하기
최초 실행에서는 ChatGPT 로그인 또는 현재 계정에 제공되는 다른 인증 방식을 선택하게 됩니다. 유효한 세션이 없다면 codex login으로 ChatGPT 브라우저 인증 흐름을 시작할 수 있습니다. 인증 방식의 범위는 Codex 인증 공식 문서에서 확인할 수 있습니다.
bashcodex login
공식 인증 문서 기준으로 Codex CLI는 ChatGPT 구독을 통한 접근과 API 키의 사용량 기반 접근을 지원합니다. 다만 실제로 보이는 선택지는 계정, 워크스페이스 정책, 역할과 기능 가용성에 따라 달라질 수 있습니다. 이 글은 두 방식의 요금이나 플랜을 비교하지 않습니다.
어디서 실패했는지 구분하면 해결이 빨라진다
설치와 인증을 한 덩어리로 생각하면 원인을 잘못 찾기 쉽습니다. 아래처럼 관찰한 지점부터 나누세요.
| 보이는 현상 | 먼저 확인할 범위 | 아직 단정할 수 없는 것 |
|---|---|---|
| 설치 명령 자체가 실행되지 않음 | 셸, 다운로드, 실행 정책, 권한, 조직 보안 정책 | Codex 계정 상태 |
codex 명령을 찾지 못함 | 설치 위치, PATH, 새 터미널 적용 여부, 중복 설치 | 로그인 성공 여부 |
codex는 시작되지만 인증이 진행되지 않음 | 브라우저 열기, 네트워크, 계정과 워크스페이스 정책 | 설치 파일이 잘못됐다는 결론 |
| 로그인 후 필요한 기능을 사용할 수 없음 | 계정 권한, 구독 또는 API 접근, 지역·모델·워크스페이스 가용성 | CLI 설치 자체의 실패 |
특정 오류 메시지가 반복된다면 메시지 전문, 운영체제, 사용한 설치 방식, codex가 가리키는 경로를 함께 기록하세요. 다만 프록시 주소, API 키, 로그인 토큰과 같은 비밀값은 공유하거나 로그에 남기면 안 됩니다.
설치 후 바로 할 일
이제 작업할 프로젝트 폴더에서 codex를 실행하고, 화면에 제시되는 인증 절차를 진행하세요. CLI가 열리고 인증 흐름에 진입하면 이 글이 다루는 설치·첫 실행 단계는 확인한 셈입니다. 다만 인증 완료나 실제 작업 성공까지 자동으로 보장되는 것은 아닙니다. 로그인 뒤 필요한 기능이 보이지 않는다면 설치를 반복하기보다 계정·워크스페이스·네트워크·지역 가용성을 별도로 확인하세요.
설치 명령과 인증 방식은 바뀔 수 있습니다. 실행하기 전에는 현재 운영체제에서 허용되는 설치 경로와 계정에 제공되는 인증 선택지가 여전히 유효한지 다시 확인하세요. 최신 공식 명령은 Codex CLI 공식 문서에서 확인할 수 있습니다. 이후 전체 명령어 사용법, config.toml 설정, 토큰 비용과 사용량, CLI와 데스크톱 앱 비교가 필요하다면 각각 별도의 과제로 살펴보는 것이 좋습니다.
