지금 바로 "codex: command not found" 오류가 발생하나요? 30초 진단법

다음 세 가지 명령어를 순서대로 실행하세요. 예상치 못한 결과가 반환되는 첫 번째 명령어가 해결책을 가리킵니다.

node --version          # v22.x 이상이 나와야 함
which codex             # 실제 경로가 나와야 함, 예: /Users/you/.npm-global/bin/codex
npm prefix -g           # /bin 폴더에 codex가 포함되어 있어야 하는 prefix가 나와야 함

가장 흔한 원인은 해결 방법 1입니다. 즉, PATH에 npm global bin 디렉토리가 누락된 경우입니다. 나머지 6가지 해결 방법은 기타 다양한 사례들을 다룹니다. 각 해결 방법은 macOS 14, Ubuntu 24.04, 그리고 Windows 11 + WSL2 환경에서 Codex CLI 0.137.0 (2026-06-04 릴리스)을 기준으로 검증되었습니다.

설치 자체에 관한 내용 — npm, Homebrew, 바이너리 릴리스(binary release) 중 선택하거나, Codex를 OpenAI 호환 제공업체(provider)로 지정하는 방법 — 은 How to Install Codex CLI: The Complete Official Setup Guide를 참조하세요. 이 글은 설치가 오류 없이 완료되었으나, 그 이후 단계인 command not found 단계에서 막힌 상황을 가정합니다.

오류가 발생하는 이유: Codex CLI의 설치 경로 표면적 (Install Path Surface Area)

Codex CLI는 npm 패키지로 래핑(wrapped)된 Rust 바이너리로 제공됩니다. 이 래퍼(wrapper)는 설치 시점에 세 가지 작업을 수행합니다:

1. 플랫폼에 적합한 바이너리를 node_modules/@openai/codex/에 다운로드합니다.
2. 바이너리를 실행하는 <npm-prefix>/bin/codex 위치에 얇은 심(shim)을 생성합니다.
3. engines.node >= 22.0.0 조건을 검증하며, 그렇지 않으면 설치를 거부합니다.

이 세 가지 단계 중 어느 하나가 성공하더라도, 셸(shell)에서 codex를 여전히 찾지 못할 수 있습니다:

• Step 2는 성공했지만 PATH가 잘못된 경우 → 디스크에 shim(심)이 존재함에도 불구하고 command not found 발생
• NVM 방식의 버전 관리자는 Node 버전별로 <npm-prefix> 범위를 가짐 → codex shim은 설치를 실행한 해당 Node 버전 아래에만 존재함
• Codex Desktop의 통합 셸(integrated shell)은 비대화형(non-interactive)임 → ~/.zshrc를 소싱(source)하지 않으므로 NVM이 로드되지 않고, 이로 인해 prefix가 잘못되어 PATH가 틀려짐 (issue #13566, #14016)
• sudo npm install -g는 root 소유의 파일을 작성함 → 이후 sudo를 사용하지 않는 설치는 EACCES 오류로 실패하며, 불완전한 상태로 인해 Codex의 이전 Node.js 시대 shim이 오래된 경로를 가리키는 채로 남게 됨

아래의 해결 방법들은 이 미로의 각 경로를 다룹니다.

해결 방법 1: PATH에 npm Global bin 디렉토리가 누락된 경우

가장 흔한 단일 원인입니다. 다음 두 명령어로 진단하십시오:

npm prefix -g
echo $PATH | tr ':' '\n' | grep "$(npm prefix -g)/bin" || echo "NOT ON PATH"

만약 두 번째 명령어가 NOT ON PATH를 출력한다면, 그것이 바로 버그의 원인입니다. shim은 <prefix>/bin/codex에 존재하지만, 사용자의 셸이 그곳을 탐색하지 않는 것입니다.

zsh를 위한 해결 방법 (Catalina 이후 macOS 기본값)

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
which codex      # 이제 실제 경로를 출력해야 함
...

bash를 위한 해결 방법 (대부분의 Linux 배포판)

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
which codex

fish를 위한 해결 방법

fish_add_path (npm prefix -g)/bin
which codex

npm bin -g가 더 이상 작동하지 않는 이유

만약 2023년 Stack Overflow 답변을 복사했다면, 아마도 export PATH=$PATH:$(npm bin -g)를 실행하라고 되어 있을 것입니다. 해당 명령은 npm 9에서 제거되었으며 현재는 아무런 유용한 동작을 하지 않습니다. npm prefix -g는 상위 디렉토리를 반환하므로, 직접 /bin을 추가하십시오.

해결 후 예상 결과

$ which codex
/Users/you/.npm-global/bin/codex
$ codex --version
...

which codex는 경로를 찾아내지만 codex 실행 시 여전히 command not found가 발생한다면, 오래된 셸 세션(stale shell session)을 사용 중인 것입니다. 새 터미널을 여십시오. PATH 변경 사항은 기존에 열려 있는 셸에는 전파되지 않습니다.

해결 방법 2: NVM이 잘못된 Node 버전 아래에 Codex를 설치한 경우

NVM은 설치된 Node 버전별로 npm 전역 접두사 (global prefix)의 범위를 제한합니다. Node 22 환경에서 @openai/codex를 설치한 후, 관련 없는 다른 프로젝트를 위해 Node 20으로 전환하면 codex 명령어가 사라집니다.

범위 지정 (scoping) 문제를 확인하십시오:

nvm current                      # 현재 어떤 Node 버전을 사용 중인가?
ls "$(npm prefix -g)/bin/codex"  # 현재 Node 아래에 존재하는가?
nvm use 22 && which codex        # 여기서는 작동하는가?
...

마지막 두 줄을 통해 범위 지정 문제를 확인했다면, 이를 영구적으로 수정하십시오:

# 기본 Node 버전을 고정
nvm alias default 22

...

만약 반드시 Node 버전을 계속 전환해야 한다면, 모든 새 셸이 Node 22에서 시작할 수 있도록 ~/.zshrc 상단에 nvm use default를 추가하십시오:

# ~/.zshrc 상단, nvm.sh를 소싱한 직후에 추가
nvm use default --silent

더 미묘한 함정: nvm install-latest-npm

Codex를 설치한 후 nvm install-latest-npm을 실행하면 심 (shim)이 깨질 수 있습니다. 새로운 npm이 전역 접두사를 다시 작성하면서 기존의 심들을 고아(orphan) 상태로 만들기 때문입니다. npm을 업데이트할 때마다 Codex를 다시 설치하십시오.

해결 방법 3: EACCES 및 PATH 드리프트 방지를 위해 사용자 소유의 npm 접두사 설정하기

macOS 및 Linux에서 가장 깔끔한 설정은 npm이 사용자 소유의 디렉토리를 가리키도록 하는 것입니다. 이렇게 하면 sudo 사용을 없앨 수 있고, PATH 권한 관련 불만을 제거하며, (NVM을 사용하지 않을 때) Node 버전이 바뀌어도 변하지 않는 하나의 안정적인 접두사를 가질 수 있습니다.

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
...

이것이 sudo npm install -g보다 나은 이유

sudo는 루트 (root) 소유권과 함께 /usr/local/lib/node_modules에 파일을 작성합니다. 이로 인해 두 가지 실패 모드가 발생합니다:

1. sudo 없이 실행하는 향후 npm install -g 명령이 EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@openai' 오류를 내며 실패합니다.
2. Codex를 업데이트할 때 사용자 소유 파일과 섞인 부분적인 루트 소유 파일이 생성되며, 결국 codex가 절반만 작성된 바이너리를 가리키게 됩니다.

사용자 접두사 (user-prefix) 방식은 이 두 가지 문제를 모두 건너뜁니다. 공식 npm 문서에서는 2019년부터 이 패턴을 권장해 왔습니다.

sudo로 설치된 패키지 마이그레이션

만약 레거시 글로벌 패키지를 sudo를 사용하여 설치했다면, 전환하기 전에 정리해야 합니다:

sudo npm uninstall -g @openai/codex          # root 소유 버전 제거
npm config set prefix ~/.npm-global          # 경로 재설정
npm install -g @openai/codex                 # sudo 없이 다시 설치

해결 방법 4: Volta 또는 asdf가 codex 심(Shim)을 가로챔

Volta와 asdf는 codex 명령어를 가로채서 자체 심 계층(shim layer)을 통해 라우팅하는 대체 버전 관리자입니다. 이 심 계층이 동기화되지 않은 경우 — 예를 들어, Volta가 현재 프로젝트에 대한 Node 버전을 고정하지 않은 경우 — 바이너리가 node_modules에 존재함에도 불구하고 codex는 command not found를 반환합니다.

Volta

volta which node                 # Volta가 여기서 선택하는 Node 버전은 무엇인가?
volta install node@22            # Node 22 전역 고정
volta install @openai/codex      # Volta가 심을 관리하도록 함
...

Volta가 활성화된 상태에서 글로벌 도구를 추가하는 표준 방식은 npm install -g가 아니라 volta install <패키지>입니다. 만약 npm install -g와 volta install을 혼용했다면 일관되지 않은 동작을 볼 것이므로, 기기당 하나의 경로를 선택해야 합니다.

asdf

asdf는 새로운 글로벌 npm 패키지를 설치한 후 asdf reshim nodejs가 필요합니다. 이 리심(reshim) 과정을 건너뛰면 설치에 성공했음에도 불구하고 codex가 PATH에서 누락됩니다:

asdf install nodejs 22.12.0
asdf global nodejs 22.12.0
npm install -g @openai/codex
...

해결 방법 5: macOS EACCES — sudo 없이 npm 권한 수정

설치 오류에 다음 문자열 중 하나가 포함된 경우:

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@openai'
npm ERR! errno EACCES
operation rejected by your operating system

...당신은 sudo 함정에 빠진 것입니다. 올바른 해결책은 다시 sudo를 사용하는 것이 아닙니다. 올바른 해결책은 해결 방법 3의 사용자 접두사(user-prefix) 방식으로 전환하거나, — 만약 /usr/local에 글로벌 경로를 유지해야 한다면 — 해당 경로의 소유권을 가져오는 것입니다.

sudo chown -R $(whoami) $(npm prefix -g)/lib/node_modules
sudo chown -R $(whoami) $(npm prefix -g)/bin
sudo chown -R $(whoami) $(npm prefix -g)/share

이 일회성 chown 명령을 통해, 이후에는 sudo 없이도 현재 사용자가 npm install -g를 성공적으로 수행할 수 있습니다. 설치를 다시 실행하세요:

npm install -g @openai/codex
which codex

macOS Gatekeeper이 바이너리를 차단하는 경우

macOS 14 이상에서의 별도 실패 모드입니다. Gatekeeper이 서명되지 않은 Codex 바이너리를 첫 실행 시 차단하며, 이 경우 command not found 대신 "확인되지 않은 개발자가 배포했기 때문에 열 수 없습니다"라는 일반적인 대화 상자가 나타납니다. 시스템 설정(System Settings) → 개인정보 보호 및 보안(Privacy & Security) → "확인 없이 열기(Open Anyway)"에서 허용하면, codex --version이 성공합니다.

해결 방법 6: Node.js 버전이 너무 오래된 경우

Codex CLI 0.137.0은 Node 22 LTS 이상을 요구합니다. 이전 버전은 설치 시점에 명확한 에러와 함께 실패하지만, 만약 --force 옵션으로 엔진 체크(engines check)를 우회하면 런타임(runtime)에 대신 codex: command not found가 발생하여 진단이 더 어려워집니다.

$ node --version
v18.19.0
$ npm install -g @openai/codex
...

Node.js를 올바르게 업그레이드하기

올바른 경로는 Node가 설치된 방식에 따라 다릅니다:

• macOS (Homebrew): brew upgrade node 실행 후 brew link --overwrite node@22 실행
• macOS (공식 설치 프로그램): nodejs.org에서 Node 22 LTS를 다운로드하여 .pkg 파일을 실행한 뒤, 터미널을 재시작하세요.
• Linux (NodeSource): curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash - && sudo apt install -y nodejs 실행
• NVM (모든 OS): nvm install 22 && nvm alias default 22 && nvm use default 실행
• Windows: nodejs.org에서 공식 .msi 파일을 다운로드하여 재설치하세요.

업그레이드 후, 새로운 Node 버전에서 Codex CLI를 다시 설치하세요. 심(shim)은 버전별로 관리되므로 이전 버전은 작동하지 않습니다:

npm install -g @openai/codex
codex --version

해결 방법 7: Codex Desktop 비대화형 셸 버그 (Issues #13566, #14016)

이 문제는 Codex CLI가 터미널(Terminal)에서는 정상적으로 작동하지만, Codex Desktop 앱이나 VS Code Codex 확장 프로그램 내부에서는 실패하는 사용자들에게 매우 까다로운 문제입니다. 통합 셸(integrated shell)에서 발생하는 정확한 에러는 다음과 같습니다:

zsh: command not found: node
zsh: command not found: codex

…일반적인 터미널 창에서는 동일한 명령어가 정상적으로 작동함에도 불구하고 말입니다.

근본 원인 (Root cause)

Codex Desktop은 로그인되지 않은 비대화형 셸(non-login, non-interactive shell)을 통해 명령어를 실행합니다. 이러한 셸은 ~/.zshrc 또는 ~/.bashrc를 소싱(source)하지 않습니다. NVM, fnm, Volta는 모두 해당 파일들에 포함된 초기화 코드에 의존하므로, PATH(경로)가 전혀 구성되지 않습니다.

2026-06-04 기준으로 두 이슈 모두 오픈 상태입니다:

• openai/codex#13566: WSL에서의 NVM → "zsh: command not found: node"
• openai/codex#14016: Windows에서의 fnm → "npm isn't available in this shell path"

해결 방법 A: NVM 부트스트랩(bootstrap)을 ~/.zshenv로 이동

비대화형 셸은 .zshrc를 건너뛰더라도 ~/.zshenv는 읽어들입니다. 최소한의 NVM 로더(loader)를 그곳으로 이동시키세요:

# ~/.zshenv (파일이 없으면 생성)
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
...

Codex Desktop을 재시작하면, 통합 셸에서 node와 codex를 인식할 수 있습니다.

해결 방법 B: NVM 대신 공식 설치 프로그램을 통해 Node 설치

가장 간단한 해결책은 Codex Desktop이 실행되는 환경에서 버전 관리자(version managers)를 완전히 우회하는 것입니다. nodejs.org에서 Node 22 LTS를 설치하면 /usr/local/bin (macOS/Linux) 또는 C:\Program Files\nodejs (Windows)에 기록됩니다. 이 경로들은 로그인 여부와 상관없이 모든 셸의 시스템 PATH에 포함됩니다. 공식 Node를 사용하여 Codex를 재설치하면, Codex Desktop이 즉시 이를 찾아냅니다.

이는 현재 OpenAI 문서에서 #13566 이슈를 겪는 사용자들에게 권장하는 해결 방법입니다.

해결 방법 C: WSL 네이티브 셸 (WSL native shell)

Windows + WSL 환경인 경우, Codex Desktop의 터미널 기본 설정을 Windows Codex 셸 대신 wsl.exe -d Ubuntu를 직접 실행하도록 설정하세요. WSL의 bash는 NVM을 로드하는 자체 ~/.bashrc로부터 PATH를 상속받습니다.

우리가 관찰한 일반적인 실패 패턴 (최근 Codex 이슈)

지난 60일 동안 openai/codex에서 반복적으로 보고된 command not found 유형의 보고서 스냅샷입니다:

만약 귀하의 증상이 위 이슈 중 하나와 일치한다면, 위에 링크된 해결 방법으로 바로 이동하십시오.

해결 방법이 작동하지 않을 때: 즉시 실행 가능한 대안들

7가지 해결 방법을 모두 시도했음에도 불구하고 codex 문제가 여전히 해결되지 않는다면, 오늘 바로 작업을 계속할 수 있게 해주는 세 가지 탈출구(escape hatches)가 있습니다.

GitHub 바이너리 릴리스에서 Codex 실행 (Node 불필요)

Codex 저장소는 github.com/openai/codex/releases에서 플랫폼별 바이너리를 배포합니다. 다운로드하여 압축을 풀고, 이미 PATH에 등록되어 있는 디렉토리에 넣으십시오: