OpenAI Codex CLI 에러 해결: 설치·로그인·한도 완전정복

터미널에서 codex를 처음 띄우던 날을 아직 기억합니다. 설치 한 줄, 로그인 한 번이면 끝일 줄 알았는데 npm ERR! code EACCES부터 시작해서 "Sign in with ChatGPT"가 무한 로딩, 겨우 로그인하니 이번엔 멀쩡한 Pro 구독인데 "usage limit reached"가 뜨더군요. 같은 길을 걷는 분이 많아서, 제가 삽질하며 정리한 Codex CLI의 4대 막힘 지점과 검증된 해결법을 풀어봅니다. 결론부터 말하면 대부분 CLI 버그가 아니라 내 로컬 설정(npm prefix, 프록시, 인증 캐시) 문제이고, 일부는 OpenAI 백엔드 동기화 지연입니다.

Codex CLI 플래그와 경로(--device-auth, ~/.codex/auth.json 등)는 버전에 따라 이름/위치가 자주 바뀝니다. 막히면 항상 codex --help와 codex login --help로 현행 옵션을 먼저 확인하세요. 이 글의 명령도 일부는 버전에 따라 다를 수 있습니다.

OpenAI Codex CLI가 뭔지부터 짧게

OpenAI Codex CLI는 터미널에서 도는 코딩 에이전트입니다. npm 패키지명은 @openai/codex이고 Node.js 18 이상이 필요합니다. 여기서 첫 번째 함정이 나옵니다. npm i -g codex가 아니라 npm install -g @openai/codex 입니다. 패키지명을 잘못 입력해 엉뚱한 패키지를 깔고 "왜 안 되지" 하는 경우가 생각보다 많습니다.

자, 이제 네 가지 막힘 지점을 순서대로 보겠습니다.

1. 설치 단계 EACCES 권한 에러 / codex: command not found

가장 흔한 첫 관문입니다. 실제로 이런 메시지를 만납니다.

npm ERR! code EACCES
npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@openai'

설치는 됐는데 실행하면 이런 경우도 있고요.

codex: command not found

Windows에서는 이렇게 나오기도 합니다.

operation rejected by your operating system.

원인

핵심 범인은 과거에 한 번이라도 sudo npm install -g를 실행한 이력입니다. sudo로 깔면 전역 node_modules 디렉터리가 root 소유로 바뀌고, 그 뒤 sudo 없이 설치하면 권한이 거부됩니다. command not found는 npm 전역 bin 경로가 PATH에 없거나, 앞서 말한 패키지명 오타 때문입니다.

단계별 해결

1. Node 버전 확인. node -v가 18 이상인지 봅니다. 낮으면 먼저 업그레이드하세요.
2. sudo를 쓰지 마세요. 가장 깔끔한 해법은 nvm입니다. nvm으로 Node를 설치하면 전역 패키지가 사용자 홈에 저장되어 권한 문제 자체가 사라집니다. 제가 가장 추천하는 방법입니다.
3. nvm을 안 쓴다면 사용자 소유 prefix를 직접 지정합니다.

npm config set prefix ~/.npm-global
# 그리고 ~/.zshrc 또는 ~/.bashrc에 추가
export PATH=~/.npm-global/bin:$PATH

4. 정확한 패키지명으로 설치.

npm install -g @openai/codex

5. 이미 root 소유로 망가졌다면 소유권을 복구합니다.

sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

6. 확인.

codex --version

여기서 안 잡히면 새 터미널을 여세요. PATH 변경이 현재 셸에 반영 안 된 경우가 대부분입니다.

증상	진짜 원인	한 줄 해법
EACCES permission denied	sudo로 깐 root 소유 디렉터리	nvm 사용 또는 prefix 변경
codex: command not found	PATH에 npm bin 없음	PATH 추가 후 새 터미널
설치는 되는데 엉뚱함	패키지명 오타	@openai/codex 정확히
Node 관련 에러	Node 18 미만	Node 업그레이드

2. ChatGPT 로그인(OAuth) 실패

설치를 넘겨도 로그인에서 또 막힙니다. 대표 메시지들입니다.

An error occurred during authentication (invalid_state)
Token exchange failed: error sending request for url (https://auth.openai.com/oauth/token)
get_chatgpt_account_error
Sign-in could not be completed

원인

codex login은 localhost 콜백으로 OAuth 토큰을 CLI에 되돌려주는 방식입니다. 그런데 VPN, 프록시, 방화벽이 127.0.0.1 콜백을 가로채거나 차단하면 토큰 교환이 실패합니다. invalid_state는 손상된 로컬 인증 캐시가 원인인 경우가 많고요. 그리고 SSH로 접속한 헤드리스 서버에는 브라우저가 없으니 일반 로그인이 안 됩니다. 이때는 device code 인증이 필요한데, 회사 워크스페이스 관리자가 Device Code auth를 꺼두면 로그인 자체가 막힙니다.

단계별 해결

1. VPN/프록시 일시 해제. 그리고 localhost가 프록시를 우회하도록 설정합니다.

export no_proxy="localhost,127.0.0.1,::1"

2. 인증 캐시 삭제 후 재시도. invalid_state에 특히 잘 듣습니다.

rm ~/.codex/auth.json   # 경로는 버전에 따라 ~/.codex/ 하위 다른 파일일 수 있음
codex login

3. 로컬 데스크톱이면 브라우저 'Sign in with ChatGPT'를 다시 수행하고, 콜백 URL(예: localhost:1455)이 브라우저에서 정상적으로 열리는지 확인합니다. 안 열리면 그게 차단의 증거입니다.
4. SSH/헤드리스 서버라면 device code 로그인(베타)을 씁니다.

codex login --device-auth

이게 막히면, 로컬에서 정상 로그인한 뒤 생성된 auth.json을 서버 ~/.codex/로 복사하는 방법도 있습니다.

5. 회사(Business/Edu/Team) 워크스페이스에서 막히면 사용자 조치로 안 풀립니다. 관리자에게 Device Code authentication 허용을 요청해야 하는 권한 정책 문제입니다.
6. 그래도 안 되면 API 키 인증으로 우회합니다. ChatGPT 구독 인증을 건너뛰는 경로입니다.

# API 키를 명령 인자로 직접 노출하지 말고 stdin으로 전달하세요(셸 히스토리·로그 노출 방지)
printenv OPENAI_API_KEY | codex login --with-api-key

3. 구독이 멀쩡한데도 뜨는 usage limit reached / 429

가장 답답한 케이스입니다. Pro 결제도 잘 됐고 대시보드는 잔여 100%인데 CLI가 이럽니다.

You've hit your usage limit
usage limit reached
429 Too Many Requests
Rate limit reached for organization on tokens per min (TPM): Limit 250000, Used 250000, Requested 18667

원인

한도가 여러 종류로 겹쳐서 헷갈리는 겁니다.

• ChatGPT Plus/Pro: 5시간 롤링 윈도우 + 주간 한도가 별도로 있습니다. 긴 단일 프롬프트 하나가 주간 한도의 수%를 한 방에 태웁니다.
• API 키 사용 시: 조직 단위 TPM(분당 토큰) 한도. 위 메시지의 250000은 한 사용자 조직 설정값일 뿐, 계정마다 다릅니다.
• 백엔드 동기화 버그: Pro/Business인데 대시보드는 100%로 보이지만 CLI가 한도 도달로 잘못 보고하는, 다수 보고된 OpenAI 측 이슈입니다. 게다가 한도가 web(chatgpt.com/codex/settings/usage)에만 노출되고 CLI에서는 잘 안 보여서 혼란이 더 큽니다.

단계별 해결

1. 실제 잔여 한도를 web에서 확인. chatgpt.com/codex/settings/usage에서 5시간/주간 윈도우 리셋 시각을 봅니다.
2. 429(TPM) 에러면 요청 빈도와 동시성을 줄이고 exponential backoff로 재시도합니다. 큰 작업은 잘게 쪼개 토큰 소비를 낮추세요. 이건 한도 정책상 당연한 동작이라 기다리는 게 맞습니다.
3. Plus/Pro 한도 소진이면 윈도우 리셋까지 대기하거나, 상위 플랜 또는 API 종량제(크레딧 충전)로 전환합니다.
4. **구독 멀쩡한데 잘못 보고(알려진 버그)**라면 로그아웃 후 재로그인, 또는 버전 교체를 시도합니다.

codex logout
codex login
# 또는
npm install -g @openai/codex@latest

5. API 키 경로라면 OpenAI 플랫폼 대시보드에서 조직 spending limit / rate limit 상향을 신청합니다.
6. 현재 인증 주체(ChatGPT vs API key)와 한도 정보를 CLI에서 확인하려면 /status를 써보세요. 다만 노출 범위는 버전마다 다릅니다.

솔직히 말하면, 재로그인·버전 변경으로도 안 풀리는 "구독 멀쩡한데 한도 보고" 케이스는 사용자가 손쓸 수 없는 OpenAI 백엔드 문제일 수 있습니다. 즉시 해결을 보장할 수 없으니, 이럴 땐 깔끔하게 인정하고 openai/codex GitHub 이슈를 추적하는 게 현실적입니다.

4. 모델 404 Model not found / sandbox 권한 거부

마지막 관문입니다. 모델 선택기에는 보이는데 실제 호출하면 이럽니다.

unexpected status 404 Not Found: Model not found gpt-5.x
gpt-5-codex returns 404 on v1/chat/completions
400 unsupported-model (ChatGPT Plus)

샌드박스 권한 거부도 같이 묶어 보겠습니다.

sandbox-exec: sandbox_apply: Operation not permitted
bwrap: Failed to make / slave: Permission denied

원인

모델 404는 CLL의 로컬 모델 목록(엔트리먼트 메타데이터)과 실제 서비스 백엔드가 어긋나서 납니다. 선택기에는 신규 모델(gpt-5.5 등)이 보여도 내 계정/플랜에 권한이 없거나 백엔드 롤아웃이 안 된 상태인 거죠. 특히 gpt-5-codex는 v1/responses 엔드포인트 전용이라 chat/completions로 호출하면 404가 납니다.

(참고: 위 모델명들은 검색 결과에 등장한 명칭을 그대로 인용한 것으로, 시점에 따라 가용 모델 목록은 달라집니다. 정확한 사용 가능 모델은 계정의 모델 선택기/대시보드 기준으로 확인하세요.)

샌드박스 에러는 macOS는 Seatbelt, Linux/WSL은 bubblewrap + seccomp(Landlock 폴백)를 쓰는데, 컨테이너나 제한된 권한 환경에서 마운트 전파/명령 실행이 거부되는 경우입니다.

단계별 해결

1. 404 모델 에러: 모델을 계정이 실제 보유한 안정 모델로 바꿉니다.

codex --model <작동확인된-모델>

신규 모델은 롤아웃/엔트리먼트 반영까지 기다려야 합니다.

2. gpt-5-codex 사용 시 responses API 경로를 쓰는 최신 CLI인지 확인하세요. cline 같은 서드파티 통합이면 chat/completions가 아니라 responses 엔드포인트로 설정해야 합니다.
3. ChatGPT 인증에서 unsupported-model이 나면 API 키 인증으로 전환하거나, 모델을 플랜 지원 범위로 바꿉니다.
4. **Linux sandbox에서 bwrap: Permission denied**가 나면 레거시 Landlock으로 폴백합니다.

codex --enable use_legacy_landlock   # 플래그명은 codex --help로 재확인

bubblewrap이 아예 없으면 패키지 매니저로 먼저 설치하세요.

5. 쓰기/네트워크가 막혀 실패하면 필요한 디렉터리만 허용합니다.

codex --add-dir ./my-project

신뢰할 수 있는 환경에서만 전체 접근을 허용할 수 있습니다(보안 주의).

codex --sandbox danger-full-access   # 말 그대로 위험. 신뢰 환경 한정

6. macOS에서 network_access=true가 무시되는 알려진 이슈가 있습니다. 네트워크가 필요한 명령은 승인 모드를 조정하거나 sandbox 모드를 완화해 실행하세요.

실전 팁 5가지

1. nvm은 선택이 아니라 기본값. 권한 에러 절반은 nvm만 써도 사라집니다. sudo로 전역 설치하는 습관을 버리세요.
2. 막히면 codex --help부터. 이 글 포함 어떤 블로그도 버전 변화를 따라잡지 못합니다. 플래그명/경로는 항상 현행 help가 정답입니다.
3. 한도는 web에서 확인하는 습관. CLL에 안 보여서 답답할 뿐, usage 페이지에 실제 숫자가 있습니다.
4. 버전 교체는 양방향으로. @latest로 올려도 안 되면 직전 안정 버전으로 내려보세요. CLI 자체 버그면 다운그레이드가 답인 경우가 있습니다.
5. 샌드박스는 최소 권한 원칙. danger-full-access를 습관적으로 쓰지 마세요. --add-dir로 필요한 곳만 여는 게 정석입니다.

Do's / Don'ts

Do (권장)	Don't (피하기)
nvm으로 Node 설치	sudo npm install -g 남발
npm install -g @openai/codex	npm i -g codex (오타)
로그인 전 VPN/프록시 점검	프록시 켠 채로 무한 재시도
한도는 web usage 페이지 확인	CLI 표시만 믿고 결제 추가
--add-dir로 최소 권한	무조건 danger-full-access
안 풀리면 GitHub 이슈 추적	"내 잘못"이라며 무한 삽질

마무리

OpenAI Codex CLI의 막힘은 결국 네 갈래입니다. (1) 설치 권한은 sudo를 버리고 nvm으로, (2) 로그인 실패는 프록시 우회 + 인증 캐시 삭제 + 헤드리스는 device code로, (3) usage limit은 web에서 실제 한도 확인하고 잘못 보고면 재로그인/버전 교체로, (4) 모델 404·샌드박스는 보유 모델로 변경하고 권한은 최소로 엽니다.

정직하게 덧붙이면, "구독 멀쩡한데 한도", "신규 모델 404"는 사용자 조치로 안 풀리는 OpenAI 백엔드 버그일 수 있습니다. 이럴 땐 시간 낭비하지 말고 공식 OpenAI 개발자 문서와 GitHub 이슈를 확인하는 게 빠릅니다.

다음 행동으로, AI 코딩 도구 에러 대응에 관심 있다면 Claude API 529 Overloaded 에러 핸들링 글과 /blog의 다른 AI 도구 활용 팁도 함께 보세요. 비슷한 류의 rate limit·인증·재시도 패턴이 도구를 넘나들며 반복되니, 한 번 체화해두면 두고두고 써먹습니다.

여러분의 터미널이 빨간 에러 없이 잘 돌기를 바랍니다.