Codex CLI 설치 안 됨: command not found·로그인·WSL 점검
설치를 마쳤는데 codex: command not found가 뜬다면 로그인 문제는 아닙니다. 터미널이 실행 파일을 못 찾는 상태입니다. 반대로 codex 화면은 열리고 브라우저 인증에서 멈춘다면 설치는 끝난 것입니다. 두 경우를 섞지 않고 지금 보이는 증상부터 확인해 보세요.
설치됐는지 한 줄로 확인
새 터미널을 열고 버전을 확인합니다.
codex --version
버전이 나오면 현재 터미널의 PATH에서 실행 가능한 Codex를 찾은 것입니다. 로그인에서 막혔다면 아래 로그인 항목으로 넘어가세요. command not found가 나오면 설치한 환경과 지금 터미널이 같은지 확인합니다. PowerShell에 설치해 놓고 WSL에서 codex를 찾거나, 그 반대인 경우가 흔합니다.
설치 명령을 실행한 터미널부터 확인
macOS·Linux·WSL에서는 공식 설치 스크립트를 해당 셸 안에서 실행합니다.
curl -fsSL https://chatgpt.com/codex/install.sh | sh
Windows에서 바로 쓸 때는 WSL 창이 아닌 PowerShell에서 Windows용 스크립트를 실행합니다.
irm https://chatgpt.com/codex/install.ps1 | iex
Node.js와 npm이 이미 준비돼 있다면 npm 패키지로 설치할 수도 있습니다.
npm install --global @openai/codex
어느 방법이든 설치가 끝나면 터미널을 모두 닫고 새로 연 뒤 codex --version을 실행하세요. 설치 방식은 하나만 고르는 편이 낫습니다. 여러 방식으로 설치하면 예전 실행 파일이 PATH 앞쪽에 남아 어느 버전이 열리는지 헷갈릴 수 있습니다.
독립 설치 스크립트가 실행 파일을 두는 기본 위치는 macOS·Linux에서 ~/.local/bin, Windows에서 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin입니다.
파일은 있는데 명령만 인식되지 않는다면 설치 위치와 PATH를 비교합니다.
macOS·Linux·WSL:
ls -l ~/.local/bin/codex
printf '%s\n' "$PATH" | tr ':' '\n'
~/.local/bin이 없다면 현재 셸에서 export PATH="$HOME/.local/bin:$PATH"를 실행해 다시 확인하세요. 해결되면 같은 줄을 ~/.zshrc 또는 ~/.bashrc에 추가합니다.
Windows PowerShell:
Test-Path "$env:LOCALAPPDATA\Programs\OpenAI\Codex\bin\codex.exe"
$env:Path -split ';'
파일은 있는데 경로가 없다면 Windows의 사용자 Path에 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin을 추가한 뒤 PowerShell을 다시 엽니다.
Windows와 WSL은 설치 환경을 맞춰야 합니다
PowerShell과 WSL은 서로 다른 실행 환경입니다. WSL은 기본 설정에서 Windows 경로를 $PATH에 덧붙여 codex.exe 같은 Windows 프로그램을 실행할 수 있지만, Linux용 codex 명령이 설치된 것은 아닙니다. WSL에서 작업할 때는 공식 절차대로 WSL 셸 안에 Linux용 Codex를 설치하세요.
WSL에서 작업할 계획이라면 관리자 PowerShell이나 Windows Terminal에서 WSL2를 준비합니다.
wsl --install
Windows가 재부팅을 요구하면 먼저 재부팅하고, 처음 여는 Linux 배포판에서 사용자 초기 설정을 마친 뒤 wsl을 실행하세요.
wsl
그다음 열린 Linux 셸 안에서 Linux용 설치 명령을 실행합니다.
curl -fsSL https://chatgpt.com/codex/install.sh | sh
설치가 끝나면 WSL 셸을 새로 열고 codex --version을 확인하세요. 현재 Codex 문서는 WSL2를 기준으로 합니다. WSL1은 Codex 0.115부터 지원되지 않습니다. 프로젝트도 /mnt/c/...보다 ~/code/...처럼 WSL 홈 아래에 두는 편이 파일 처리와 권한 문제를 줄이기 좋습니다.
PowerShell에서 계속 작업한다면 Windows용 설치만 유지하세요. WSL을 쓴다면 설치와 실행, 프로젝트 경로를 모두 WSL 쪽에 맞추는 것이 덜 헷갈립니다.
브라우저 로그인을 마쳐도 터미널이 멈춰 있을 때
명령이 열리는데 로그인이 끝나지 않는다면 먼저 기본 로그인 흐름을 다시 시작합니다.
codex login
브라우저에서 ChatGPT 로그인을 마치면 자격 증명이 Codex로 돌아옵니다. 현재 어떤 방식으로 로그인됐는지는 다음 명령으로 확인할 수 있습니다.
codex login status
원격 서버나 화면 없는 환경, 또는 회사망에서 로컬 콜백이 막힌 경우에는 브라우저가 인증을 마쳐도 터미널로 돌아오지 않을 수 있습니다. 이때는 베타 기능인 기기 코드 로그인을 사용할 수 있습니다. 개인 계정은 ChatGPT 보안 설정에서 기기 코드 로그인을 먼저 켜야 하며, 관리형 워크스페이스에서는 관리자가 해당 권한을 허용해야 합니다.
codex login --device-auth
인증 캐시 문제를 의심하거나 계정을 바꿀 때는 로그아웃한 뒤 다시 로그인할 수 있습니다. codex logout은 저장된 인증 정보를 지우므로, 다시 로그인할 준비가 됐을 때 실행하세요.
codex logout
codex login
회사에서 관리하는 ChatGPT 워크스페이스는 허용된 로그인 방식이나 워크스페이스가 정해져 있을 수 있습니다. 개인 계정으로 계속 튕긴다면 재설치보다 관리자 정책을 먼저 확인해야 합니다.
설치와 로그인은 정상인데 실행이 이상할 때
버전도 나오고 로그인 상태도 정상인데 Codex가 시작되지 않거나 설정 오류가 이어지면 진단 요약을 봅니다.
codex doctor --summary
이 명령은 로컬 설치, 설정, 인증, 실행 환경의 점검 결과를 묶어서 보여줍니다. 오류를 문의할 때는 운영체제, 사용한 셸, codex --version 결과, 설치 방식과 함께 진단에서 실패한 항목을 전달하세요. 토큰이나 ~/.codex/auth.json 내용은 붙여 넣으면 안 됩니다.