AI 해결 노트 · 2026-09-17 · 실측 2026-09-17

WSL(Ubuntu)에 Codex CLI 설치하기 — 윈도우 codex가 먼저 잡히는 함정까지, 로그인 전 단계 실측

한 줄로

윈도우에 Codex CLI를 깔아 둔 저희 PC에서는 WSL Ubuntu에서도 윈도우 쪽 codex가 잡혔고, codex --version이 Missing optional dependency @openai/codex-linux-x64 오류로 끝났습니다. WSL 안에 따로 설치해 그 경로를 PATH 앞에 두자 정상으로 나왔습니다.

이런 분께

• 윈도우에서 npm install -g @openai/codex로 codex를 쓰고 있는데 WSL에서도 쓰고 싶은 분
• WSL에서 codex를 쳤더니 codex.js가 /mnt/c/... 경로에서 오류를 내는 분

실측 환경

WSL 안의 명령은 윈도우에서 wsl.exe -d Ubuntu -- bash -lc '...' 형태로 실행했습니다. 아래 코드블록에는 wsl로 줄여 적었습니다.

1. 먼저 배포판과 node를 확인합니다

wsl -l -v
wsl -d Ubuntu -- bash -lc 'cat /etc/os-release; uname -r'
wsl -d Ubuntu -- bash -lc 'command -v node; node --version; command -v npm; npm --version'

이 PC의 Ubuntu에는 node v22.22.1과 npm 9.2.0이 /usr/bin에 이미 있었습니다. 그래서 node 준비 단계는 건너뛰었습니다. node가 없는 배포판이라면 이 단계에서 node부터 준비해야 하는데, 그 과정은 이번에 돌려 보지 않았습니다(아래 「확인하지 않은 것」).

2. 설치 전에 codex가 어디서 잡히는지 봅니다

여기가 이 글의 핵심입니다.

wsl -d Ubuntu -- bash -lc 'which -a codex'

/mnt/c/Users/User/AppData/Roaming/npm/codex

이 PC의 WSL PATH를 찍어 보니 /mnt/c로 시작하는 항목이 27개였고, 그중 /mnt/c/Users/User/AppData/Roaming/npm(윈도우 npm 전역 폴더)도 들어 있었습니다. 그래서 WSL 안에 codex를 설치하지 않았는데도 which가 윈도우 쪽 파일을 찾아 줍니다.

이 파일은 npm이 만든 sh 스크립트라 WSL에서도 실행은 됩니다. 하지만 이 설치본을 WSL에서 실행하자 리눅스용 선택적 의존성을 찾지 못했다는 오류로 끝났습니다.

Error: Missing optional dependency @openai/codex-linux-x64. Reinstall Codex: npm install -g @openai/codex@latest
    at findCodexExecutable (file:///mnt/c/Users/User/AppData/Roaming/npm/node_modules/@openai/codex/bin/codex.js:107:9)

종료 코드는 1이었습니다. 오류 문구는 npm install -g로 재설치하라고 권합니다. 이번에는 윈도우 쪽 재설치를 시험하지 않았고, 대신 WSL 안에 리눅스용으로 따로 설치해서 해결했습니다.

3. WSL 안에 설치합니다

이번 실측은 PC를 건드리지 않으려고 홈 아래 임시 폴더에 설치했습니다.

wsl -d Ubuntu -- bash -lc 'mkdir -p ~/longtail_tmp/prefix && cd ~/longtail_tmp && npm install --prefix ~/longtail_tmp/prefix @openai/codex@latest'

added 2 packages in 7s

설치된 패키지는 codex와 codex-linux-x64 두 개였습니다. WSL 임시 설치 경로에는 codex-linux-x64 패키지가 함께 설치됐습니다.

prefix@ /home/<user>/longtail_tmp/prefix
└── @openai/codex@0.154.0

실제로 계속 쓸 목적이라면 npm install -g @openai/codex로 전역 설치하는 것이 일반적입니다. 이 PC의 WSL npm 전역 폴더는 npm config get prefix 결과 /home/<user>/.npm-global로 사용자 홈 아래였습니다. 다만 이번에는 전역 설치를 돌리지 않았습니다.

4. PATH 순서를 맞추고 버전을 봅니다

wsl -d Ubuntu -- bash -lc 'PATH="$HOME/longtail_tmp/prefix/node_modules/.bin:$PATH"; which -a codex; codex --version < /dev/null'

/home/<user>/longtail_tmp/prefix/node_modules/.bin/codex
/mnt/c/Users/User/AppData/Roaming/npm/codex
codex-cli 0.154.0

which -a 결과에 두 개가 나옵니다. 위에 있는 WSL 설치본이 실행됐고, 버전도 WSL에 깐 0.154.0으로 나왔습니다. 전역 설치로 바꿔도 결국 어느 폴더가 PATH 앞에 오느냐의 문제라서, 설치 뒤에는 which -a codex로 순서부터 보는 것이 안전합니다(전역 설치 경우는 돌려 보지 않았습니다).

5. 로그인 전 상태까지만

wsl -d Ubuntu -- bash -lc '~/longtail_tmp/prefix/node_modules/.bin/codex login status < /dev/null'

Not logged in

종료 코드는 1이었습니다. WSL에 새로 깐 codex는 Not logged in으로 나왔습니다. 로그인 상태를 보는 방법은 Codex CLI 로그인 상태 확인에 따로 적었습니다. 로그인(codex login)은 이 글에서 실행하지 않았습니다.

결과

실패한 것

• 설치 전 codex --version은 위처럼 실패했습니다. 이 글이 다루는 증상 자체입니다.
• 처음에 export PATH=$HOME/...:$PATH를 따옴표 없이 넘겼다가 export: ... not a valid identifier 오류가 줄줄이 났습니다. 윈도우 PATH에 Program Files 같은 공백 경로가 섞여 있어서입니다. PATH="$HOME/...:$PATH"처럼 큰따옴표로 감싸서 다시 돌렸습니다.
• WSL 설치본의 codex --version을 실행한 뒤 확인해 보니 WSL 홈에 ~/.codex/tmp/arg0/ 폴더가 있었습니다. ~/.codex의 생성 시각은 첫 실행 시간대인 17:24:57로 기록돼 있었습니다. 임시 설치 폴더 ~/longtail_tmp는 지웠고, ~/.codex는 지우지 않고 남겨 두었습니다.

확인하지 않은 것

• node가 없는 배포판에서 node를 준비하는 과정(apt, nvm 등)은 돌려 보지 않았습니다. 이 PC에는 node가 이미 있었습니다.
• npm install -g로 WSL 전역 설치하는 경우는 돌려 보지 않았습니다.
• codex login과 로그인 뒤 실제 질문 실행은 하지 않았습니다. 브라우저 로그인이 WSL에서 어떻게 열리는지도 확인하지 않았습니다.
• /etc/wsl.conf에서 윈도우 PATH 이어 붙이기를 끄는 설정은 시험하지 않았습니다. 이 PC의 wsl.conf에는 [user]와 [boot] 항목만 있었습니다.
• Ubuntu 26.04 외 다른 배포판, WSL1은 확인하지 않았습니다.

함께 보기

• Codex CLI 윈도우 설치
• Codex CLI 로그인 상태 확인
• Codex CLI 버전 확인·업데이트