Codex CLI 설치가 안 될 때 — 초기 설정부터 에러 해결까지 트러블슈팅 모음
Codex CLI 설치 중 발생하는 에러를 정리합니다. Node.js 버전, npm 권한, API 키 설정, 버전 불일치, PowerShell 호환 문제까지 단계별 해결법.
Codex CLI 설치가 한 번에 되면 좋겠지만, 현실은 다릅니다. Node.js 버전이 안 맞거나, npm 권한 문제가 나오거나, API 키가 인식되지 않는 일이 빈번합니다. 이 글은 Codex CLI 설치 과정에서 자주 만나는 에러를 한곳에 모아 정리합니다. 위에서부터 순서대로 확인하면 대부분의 문제를 해결할 수 있습니다.
설치 전 필수 요건 확인
Codex CLI 설치를 시작하기 전에 세 가지를 먼저 확인합니다.
Node.js 22 이상: Codex CLI는 Node.js 22 이상을 요구합니다. 18이나 20 버전에서는 설치는 되지만 실행 시 에러가 발생합니다.
[code lang="bash"] node -v
v22.x.x 이상이어야 합니다
[/code]
npm 최신 버전: Node.js 22에 기본 포함된 npm으로 충분하지만, 오래된 npm이 글로벌에 남아 있으면 충돌합니다.
OpenAI API 키: OpenAI Platform에서 발급받은 API 키가 필요합니다.
Node.js 버전 불일치 에러
가장 흔한 Codex CLI 설치 실패 원인입니다.
증상: npm install -g @openai/codex 실행 후 engine 관련 경고 또는 실행 시 SyntaxError: Unexpected token 에러가 뜹니다.
원인: 시스템에 Node.js 18이나 20이 설치되어 있는 경우입니다. Codex CLI는 최신 ECMAScript 기능을 사용하므로 22 미만에서는 호환되지 않습니다.
해결:
[code lang="bash"]
nvm 사용자
nvm install 22 nvm use 22
Homebrew 사용자 (macOS)
brew install node@22 [/code]
여러 Node 버전이 공존할 때
nvm을 쓰는 개발자는 터미널을 열 때마다 기본 버전이 바뀔 수 있습니다. Codex CLI를 설치한 Node 버전과 실행하는 버전이 다르면 MODULE_NOT_FOUND 에러가 발생합니다.
[code lang="bash"] nvm alias default 22
모든 터미널 세션에서 Node 22를 기본으로 사용
[/code]
활성 Node 경로 확인하기
nvm use 22를 했는데도 에러가 나면 which node를 실행합니다. 경로가 /usr/local/bin/node처럼 시스템 경로를 가리키고 있다면 nvm 버전이 적용되지 않은 것입니다. 셸 프로필에 nvm use default를 추가하면 터미널을 열 때마다 올바른 버전을 사용합니다.
npm 권한 에러 — EACCES
증상: npm install -g @openai/codex 실행 시 EACCES: permission denied 에러가 뜹니다.
원인: npm 글로벌 디렉토리의 소유권이 root로 설정되어 있는 경우입니다. sudo npm install로 한 번이라도 설치한 적 있으면 이 상태가 됩니다.
해결 (방법 1 — npm 디렉토리 변경):
[code lang="bash"]
mkdir /.npm-global
npm config set prefix '/.npm-global'
.bashrc 또는 .zshrc에 추가
export PATH=~/.npm-global/bin:$PATH [/code]
해결 (방법 2 — nvm 사용): nvm으로 Node를 설치하면 글로벌 패키지가 사용자 디렉토리에 저장되므로 권한 문제가 없습니다.
sudo npm install -g는 권장하지 않습니다. 추후 업데이트와 삭제에서 계속 권한 문제가 따라옵니다.
API 키 설정 — 환경 변수 vs .env
Codex CLI 설치 후 첫 실행에서 가장 많이 막히는 부분입니다.
환경 변수 방식 (권장):
[code lang="bash"]
.bashrc 또는 .zshrc에 추가
export OPENAI_API_KEY="sk-..." [/code]
.env 파일 방식: 프로젝트 루트에 .env 파일을 만들고 OPENAI_API_KEY=sk-...를 넣습니다. Codex CLI가 자동으로 읽습니다.
| 방식 | 장점 | 단점 |
|---|---|---|
| 환경 변수 | 모든 디렉토리에서 작동 | 터미널 재시작 필요 |
| .env 파일 | 프로젝트별 분리 가능 | git에 올리지 않도록 주의 |
주의: API 키를 설정했는데도 Authentication error가 뜬다면, 키 앞뒤의 공백이나 따옴표를 확인합니다. 쉘에서 echo $OPENAI_API_KEY로 실제 저장된 값을 확인할 수 있습니다.
Codex CLI 버전 불일치
증상: codex 명령어가 실행은 되지만 특정 기능(예: GPT-5.5 모델 선택)이 없거나 에러가 나는 경우입니다.
원인: Codex CLI는 빠르게 업데이트됩니다. 0.114 버전에서 설치 후 방치하면 0.123 이상에서 추가된 기능을 쓸 수 없습니다.
해결:
[code lang="bash"] npm update -g @openai/codex codex --version
최신 버전 확인
[/code]
GPT-5.5 모델을 사용하려면 반드시 최신 버전으로 업데이트해야 합니다. 구버전에서는 모델 목록에 표시되지 않습니다.
PowerShell 호환 문제 (Windows)
Windows에서 Codex CLI 설치 후 실행이 안 되는 경우가 많습니다.
증상: PowerShell에서 codex 명령어를 입력하면 "이 시스템에서 스크립트를 실행할 수 없습니다" 에러가 뜹니다.
원인: PowerShell의 실행 정책(Execution Policy)이 Restricted로 설정되어 있어 npm으로 설치된 스크립트를 차단합니다.
해결:
[code lang="powershell"] Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned [/code]
또는 Git Bash나 WSL을 사용하면 이 문제를 피할 수 있습니다. Codex CLI는 Unix 계열 셸에서 더 안정적으로 동작합니다.
한글 인코딩 설정
Codex CLI 설치가 완료되었다면 한글 환경 설정도 확인합니다. Codex 한글 깨짐 글에서 다뤘듯이, 클라우드 샌드박스의 로케일 문제로 한글 파일명이 깨질 수 있습니다.
로컬 환경에서는 터미널 로케일을 확인합니다:
[code lang="bash"] locale
LANG=ko_KR.UTF-8 또는 en_US.UTF-8이면 정상
[/code]
Codex CLI 설치 체크리스트
마지막으로 전체 과정을 체크리스트로 정리합니다.
- Node.js 22 이상 설치 확인 (
node -v) - npm 글로벌 권한 정상 확인 (
npm list -g --depth=0) npm install -g @openai/codex실행OPENAI_API_KEY환경 변수 설정codex --version으로 설치 확인- Windows라면 PowerShell 실행 정책 변경
- 한글 프로젝트라면 로케일 설정 확인
Codex와 Claude Code 중 어떤 도구가 나은지 궁금하다면 Codex vs Claude Code 한글 환경 비교도 참고하세요.
Codex CLI 설치는 한 번 제대로 세팅하면 이후에는 업데이트만 신경 쓰면 됩니다. 위 체크리스트를 순서대로 따라가면 대부분의 설치 에러를 해결할 수 있습니다. 그래도 문제가 지속된다면 OpenAI 커뮤니티에서 동일 증상을 검색해 보는 것을 권장합니다.