Codex 문제를 단계별로 분리하기
"Codex가 안 된다"는 증상에는 실행 파일을 못 찾는 문제, 로그인 문제, 승인 대기, 프로젝트 테스트 실패가 섞여 있습니다. 설정을 여러 개 바꾸기 전에 어느 단계까지 정상인지 기록하세요.
이 글은 공식 문서와 일반적인 개발 진단 절차를 결합한 비공식 해설입니다. 아래 표가 모든 장애의 해결을 보장하지는 않으며, 실제 계정·네트워크 장애를 재현한 결과도 아닙니다.
단계 하나씩 확인하세요
| 증상 | 먼저 확인할 것 | 바로 하지 않을 일 |
|---|---|---|
| 명령을 찾지 못함 | 설치 경로와 PATH, 새 터미널의 실행 파일 | 설치 방식을 계속 추가하기 |
| 예상과 다른 기능 | CLI 버전·도움말, 앱과 CLI의 차이 | 모든 환경이 같은 버전이라고 가정하기 |
| 로그인 실패 | 계정·워크스페이스·공식 인증 흐름 | 토큰 파일을 출력하거나 공유하기 |
| 작업이 멈춘 듯함 | 승인 대기·현재 폴더·오류 메시지 | 전체 접근을 무조건 허용하기 |
| 지침을 무시하는 듯함 | 시작 위치·override·새 세션 여부 | 지침이 OS 권한을 강제한다고 가정하기 |
| 테스트 실패 | 저장소의 실제 실행 명령과 의존성 | Codex 결함으로 단정하기 |
버전과 실행 경로
codex --version
codex --help
CLI와 앱에 포함된 Codex 버전은 다를 수 있습니다. 이 가이드의 검수에서 조회한 CLI는 0.167.0이지만, 다른 환경에 그 버전을 강제하지 않습니다. macOS/Linux에서는 command -v codex, PowerShell에서는 Get-Command codex로 어떤 실행 파일을 사용하는지 확인할 수 있습니다.
새 옵션이 보이지 않으면 현재 도움말과 해당 환경의 공식 문서를 대조하세요. 오래된 블로그의 옵션을 억지로 추가하기보다 설치 경로에 맞는 업데이트 절차를 확인합니다.
인증과 권한은 따로 보기
인증이 성공했어도 조직 권한이나 과금 조건 때문에 요청이 실패할 수 있습니다. 반대로 승인 대기는 로그인 실패가 아닙니다. 오류 문구를 읽고 인증 또는 권한 안내로 돌아갑니다.
샌드박스 초기화 오류가 생겼다면 OS별 공식 사전 조건을 확인합니다. OS 보안 기능을 전역 해제하거나 조직 정책을 우회하는 것을 기본 해결책으로 삼지 마세요. 관리형 환경에서는 담당자에게 실행 환경과 필요한 동작을 설명합니다.
다른 폴더에서는 실행되지 않는다면
Git worktree나 새 체크아웃은 원래 폴더와 경로가 다릅니다. 의존성·개발 도구·gitignore된 로컬 설정이 모두 준비되었다고 가정하지 않습니다. 공식 문제 해결 문서도 worktree의 환경 준비를 별도로 확인하도록 안내합니다.
필요한 환경 설정은 프로젝트 문서에서 확인하세요. 해결을 위해 운영 비밀값이나 개인 인증 파일을 연습 폴더에 복사하지 않습니다. 기존 변경을 초기화하는 명령도 원인을 확인하기 전에 실행하지 마세요.
지침이 반영되지 않는다면
AGENTS.md 발견 순서를 확인하고 현재 작업 디렉터리까지의 경로를 점검합니다. 예상하지 못한 AGENTS.override.md가 있는지, Codex 홈이 다른 위치인지 살펴보세요. 지침을 바꾼 뒤에는 새 세션에서 적용을 확인합니다.
지원 요청에 남길 최소 자료
문제가 발생한 시각, 운영체제, CLI 버전, 사용 환경, 실제 입력, 기대 결과와 관찰 결과를 기록합니다. 공개해도 되는 작은 합성 저장소와 최소 재현 절차가 있으면 원인을 좁히기 쉽습니다.
로그에는 코드·개인 경로·계정·토큰·입력 내용이 섞일 수 있습니다. 원본 세션이나 인증 파일을 그대로 업로드하지 마세요. 민감한 부분을 검토·제거한 자료만 공유하고, 공식 이슈에 같은 증상이 있는지 먼저 찾습니다. 로그 조회나 지원 요청 게시도 별도 외부 공유 행동입니다.
공식 한국어 도움말: ChatGPT 플랜과 Codex에서 계정별 이용 안내를 확인할 수 있습니다. 이 글은 해당 도움말의 공식 번역이 아니며, 계정 조건과 요금은 공식 안내를 우선합니다.