Codex 에러 메시지별 대처법 — 자주 만나는 오류 10가지 정리
Codex에서 자주 발생하는 에러 10가지와 해결법을 정리합니다. API 오류, 인코딩 깨짐, 타임아웃, 권한 문제, 샌드박스 에러까지.
Codex를 쓰다 보면 에러 메시지와 친해질 수밖에 없습니다. API 호출이 실패하거나, 한글이 깨지거나, 샌드박스가 파일을 못 찾거나. Codex 에러는 종류가 다양하지만, 같은 에러가 반복적으로 나타나는 패턴이 있습니다. 이 글에서는 자주 만나는 Codex 에러 10가지를 분류하고, 각각의 원인과 해결법을 정리합니다.
에러 분류 — 5가지 카테고리
Codex 에러를 크게 다섯 가지로 나눌 수 있습니다.
| 카테고리 | 대표 에러 | 빈도 |
|---|---|---|
| API 에러 | Rate Limit, Token Exceeded, Invalid Key | 높음 |
| 인코딩 에러 | UTF-8 Encoding Failure | 중간 |
| 샌드박스 에러 | File Not Found, Sandbox Escape | 중간 |
| 네트워크 에러 | Timeout, Connection Refused | 낮음 |
| 환경 에러 | Permission Denied, Execution Policy | 낮음 |
API 에러 — 가장 흔한 Codex 에러
1. Rate Limit Exceeded
에러 메시지: 429 Too Many Requests — Rate limit exceeded
원인: 짧은 시간에 너무 많은 요청을 보낸 경우입니다. OpenAI API는 분당/일당 요청 제한이 있습니다.
해결: 요청 간격을 늘립니다. Plus 플랜에서는 제한이 상대적으로 넉넉하지만, 자동화 스크립트에서 반복 호출하면 쉽게 도달합니다. 잠시 기다린 후 재시도하면 대부분 해결됩니다.
2. Token Limit Exceeded
에러 메시지: 400 Bad Request — Maximum context length exceeded
원인: 입력과 출력을 합친 토큰 수가 모델의 컨텍스트 윈도우를 초과했습니다. 큰 파일을 통째로 넘기거나, 대화 히스토리가 길어지면 발생합니다.
해결: 파일을 분할하여 전달하거나, 필요한 부분만 선택적으로 넘깁니다. --max-tokens 옵션으로 출력 길이를 제한하는 것도 방법입니다.
3. API Key Invalid
에러 메시지: 401 Unauthorized — Invalid API key
원인: API 키가 만료되었거나, 잘못 입력되었거나, 환경 변수에 공백이 포함된 경우입니다.
해결: Codex CLI 설치 트러블슈팅에서 다뤘듯이, echo $OPENAI_API_KEY로 실제 저장된 값을 확인합니다. 키를 재발급받아야 하는 경우도 있습니다.
인코딩 에러 — 한국 개발자 필수
4. UTF-8 Encoding Failure
에러 메시지: UnicodeDecodeError: 'utf-8' codec can't decode byte 0xb0
원인: Codex 샌드박스가 EUC-KR이나 CP949로 인코딩된 파일을 UTF-8로 읽으려 할 때 발생합니다. 한국 레거시 프로젝트에서 특히 빈번합니다.
해결: 파일을 UTF-8로 변환한 후 커밋합니다. 이전 글에서 다뤘듯이, iconv -f euc-kr -t utf-8 input.txt > output.txt로 변환할 수 있습니다.
5. Korean Filename Broken
에러 메시지: FileNotFoundError + 깨진 한글 파일명
원인: 클라우드 샌드박스의 로케일이 en_US.UTF-8로 고정되어 있어 한글 파일명의 유니코드 정규화(NFC vs NFD)가 불일치하는 문제입니다.
해결: 파일명을 영문으로 변경하는 것이 가장 확실합니다. 한글 파일명을 유지해야 한다면 AGENTS.md에 인코딩 관련 지침을 명시합니다.
샌드박스 에러
6. File Not Found in Sandbox
에러 메시지: FileNotFoundError: [Errno 2] No such file or directory
원인: 리포지토리를 업로드할 때 .gitignore에 포함된 파일이나 대용량 바이너리가 제외되었기 때문입니다. 샌드박스는 Git이 추적하는 파일만 봅니다.
해결: 필요한 파일이 Git에 포함되어 있는지 확인합니다. 환경 파일(.env)은 Codex 설정에서 별도로 전달해야 합니다.
7. Sandbox Escape Blocked
에러 메시지: PermissionError: Operation not permitted — sandbox policy violation
원인: Codex의 보안 정책이 샌드박스 외부로의 접근을 차단한 것입니다. 네트워크 요청이나 특정 시스템 콜이 해당됩니다.
해결: Codex의 승인 모드(approval mode)에서 suggest → auto-edit → full-auto로 단계적으로 권한을 올릴 수 있습니다. 하지만 보안상 full-auto는 신뢰할 수 있는 코드에서만 사용합니다.
네트워크 에러
8. Network Timeout
에러 메시지: TimeoutError: Request timed out after 300s
원인: 네트워크 연결이 불안정하거나, 요청 자체가 너무 복잡하여 처리 시간이 초과된 경우입니다.
해결: 작업을 더 작은 단위로 나누어 요청합니다. VPN을 사용 중이라면 잠시 끄고 시도합니다. OpenAI 서비스 상태는 OpenAI Status에서 확인합니다.
환경 에러
9. Permission Denied
에러 메시지: EACCES: permission denied, access '/usr/local/lib/node_modules'
원인: npm 글로벌 디렉토리의 권한 문제입니다. Codex CLI 설치 시뿐 아니라, 업데이트 시에도 동일하게 발생합니다.
해결: 설치 트러블슈팅 글의 npm 권한 섹션을 참고합니다. nvm을 사용하면 근본적으로 해결됩니다.
10. PowerShell Execution Policy
에러 메시지: scripts is disabled on this system (한국어 Windows: 이 시스템에서 스크립트를 실행할 수 없습니다)
원인: Windows PowerShell의 기본 실행 정책이 Restricted로 설정되어 있습니다.
해결: Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned를 실행합니다. 또는 Git Bash나 WSL을 사용합니다.
Codex 에러 빠른 참조 표
마지막으로 전체 에러를 한눈에 볼 수 있도록 정리합니다.
| 번호 | 에러 | 카테고리 | 핵심 해결법 |
|---|---|---|---|
| 1 | Rate Limit Exceeded | API | 잠시 대기 후 재시도 |
| 2 | Token Limit Exceeded | API | 입력 분할, 출력 제한 |
| 3 | API Key Invalid | API | 키 재확인, 공백 제거 |
| 4 | UTF-8 Encoding Failure | 인코딩 | iconv로 변환 |
| 5 | Korean Filename Broken | 인코딩 | 영문 파일명 사용 |
| 6 | File Not Found | 샌드박스 | Git 추적 파일 확인 |
| 7 | Sandbox Escape Blocked | 샌드박스 | 승인 모드 조정 |
| 8 | Network Timeout | 네트워크 | 작업 분할, VPN 확인 |
| 9 | Permission Denied | 환경 | nvm 사용 |
| 10 | Execution Policy | 환경 | RemoteSigned 설정 |
Codex 에러는 처음 만나면 당황스럽지만, 패턴이 정해져 있습니다. 이 가이드를 북마크해 두고 에러가 날 때마다 참조하면 대부분 몇 분 안에 해결할 수 있습니다. 특히 한국 개발자라면 인코딩 관련 에러(4번, 5번)를 미리 숙지해 두는 것이 시간을 크게 절약합니다.