Codex CLI 오류 해결: 실행 안될 때 확인해야 할 설정

Codex CLI가 실행되지 않을 때 바로 삭제하고 다시 설치하면 원인을 놓치기 쉽습니다. 먼저 명령이 PATH에서 발견되는지, 버전 출력이 되는지, 로그인과 네트워크가 정상인지, 현재 프로젝트와 샌드박스 권한이 맞는지를 순서대로 확인해야 합니다. 이 글은 “명령을 찾을 수 없음”, 로그인 반복, 연결 오류, 빈 화면·멈춤, 파일 접근 거부를 증상별로 해결하는 진단 가이드입니다.

가장 먼저 실행할 5가지 진단

codex --version
git --version
git status
codex --help

1. 버전: Codex 실행 파일 자체가 시작되는지 확인합니다.
2. Git: 프로젝트의 Git과 현재 브랜치가 정상인지 봅니다.
3. 위치: 의도한 저장소 루트에서 실행 중인지 확인합니다.
4. 오류 원문: 첫 오류 메시지와 발생 시각을 그대로 기록합니다.
5. 환경 분리: PowerShell, WSL2, macOS·Linux 중 실제 설치한 셸에서 실행합니다.

공식 문제 해결 문서는 멈춘 것처럼 보일 때 승인 대기 여부와 git status 같은 기본 명령을 먼저 확인하고, 더 좁은 요청으로 새 세션을 시작하도록 안내합니다.

증상별로 먼저 볼 설정

증상	우선 확인	다음 단계
codex 명령을 찾을 수 없음	설치 위치·PATH·셸 재시작	실행 파일 경로 확인 후 재설치
버전은 나오지만 로그인 반복	계정·시각·브라우저·인증 저장소	프록시와 워크스페이스 정책 확인
연결 실패·스트림 끊김	인터넷·프록시·TLS 인증서	기업 CA와 허용 도메인 확인
화면이 멈춤	승인 대기·실행 중 명령	좁은 새 요청과 디버그 로그
파일을 읽거나 쓰지 못함	워크스페이스·권한 프로필	대상 경로와 샌드박스 규칙 확인
WSL에서만 실패	WSL2·배포판 내부 설치·bwrap	Windows 설치본과 분리해 점검

codex 명령을 찾을 수 없을 때

명령을 찾을 수 없다는 오류는 Codex 서버나 계정 문제가 아니라 현재 셸이 실행 파일을 찾지 못하는 상태입니다. 설치 직후 열려 있던 터미널은 이전 PATH를 유지할 수 있으므로 먼저 완전히 닫고 새로 여세요.

Windows PowerShell에서는 다음 명령으로 실제 경로를 확인합니다.

Get-Command codex -ErrorAction SilentlyContinue
$env:Path -split ';'

Windows 독립 실행형 설치의 공식 기본 위치는 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin입니다. macOS·Linux에서는 사용하는 셸의 command -v codex로 경로를 확인할 수 있습니다.

command -v codex
which codex

PATH에 임의의 넓은 디렉터리를 추가하지 말고 실제 codex 실행 파일이 있는 bin 폴더만 추가합니다.

여러 Codex 버전이 충돌할 때

독립 실행형 설치, npm 전역 설치와 앱에 포함된 버전이 함께 있으면 셸마다 다른 실행 파일을 사용할 수 있습니다. 먼저 경로와 버전을 함께 기록하세요.

codex --version

PowerShell에서는 Get-Command codex -All, macOS·Linux에서는 type -a codex로 중복 경로를 찾을 수 있습니다. 사용하지 않는 설치본을 무작정 삭제하기보다 어떤 설치 방식이 프로젝트와 자동화에서 사용되는지 확인한 뒤 하나로 정리하세요.

설치를 다시 확인하는 방법

Windows 설치가 의심되면 Codex Windows 설치 가이드의 네이티브 PowerShell과 WSL2 구분을 먼저 확인하세요. 공식 PowerShell 설치 스크립트는 다음 주소를 사용합니다.

irm https://chatgpt.com/codex/install.ps1 | iex

macOS·Linux용 공식 독립 실행형 설치 스크립트는 다음과 같습니다.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

원격 설치 스크립트는 실행 전에 주소와 조직 정책을 확인하세요. 설치 오류 원문을 보관한 뒤 재실행하고, 보안 정책을 우회하거나 관리자 권한을 상시 부여하지 않습니다.

로그인이 반복되거나 Unauthorized가 나올 때

• 운영체제의 날짜·시간과 시간대가 자동 동기화되는지 확인합니다.
• 브라우저에서 의도한 ChatGPT 계정과 조직 워크스페이스를 선택했는지 봅니다.
• API 키를 사용한다면 키의 프로젝트, 권한, 만료·회수 여부를 확인합니다.
• 회사 프록시나 보안 프로그램이 로그인 리디렉션을 막는지 확인합니다.
• 여러 셸에서 서로 다른 CODEX_HOME을 사용하고 있지 않은지 봅니다.

자격 증명을 채팅, 셸 기록이나 이슈 본문에 붙여 넣지 마세요. 인증 파일을 직접 수정하는 방식보다 공식 로그인·로그아웃 흐름을 사용하는 편이 안전합니다.

CODEX_HOME 설정 때문에 실행되지 않을 때

CODEX_HOME은 Codex 구성, 인증, 로그, 세션과 스킬의 루트 경로입니다. 값을 직접 지정했다면 공식 문서 기준으로 해당 디렉터리가 미리 존재해야 합니다. 잘못된 경로나 쓰기 불가능한 폴더를 가리키면 초기화와 로그인 문제가 생길 수 있습니다.

PowerShell:

$env:CODEX_HOME
Test-Path $env:CODEX_HOME

macOS·Linux·WSL:

printf '%s\n' "$CODEX_HOME"
test -d "$CODEX_HOME" && echo exists

값이 비어 있으면 기본 위치인 ~/.codex를 사용합니다. 기존 상태 폴더를 삭제하면 세션과 로그를 잃을 수 있으므로 먼저 경로와 백업 필요성을 확인하세요.

연결 실패와 스트림 끊김 해결

HttpConnectionFailed, ResponseStreamDisconnected와 반복 재시도는 인터넷 연결, 프록시, 방화벽, TLS 검사 또는 서비스 측 오류와 관련될 수 있습니다.

1. 일반 브라우저에서 공식 로그인 페이지에 접속 가능한지 확인합니다.
2. VPN을 켜거나 끄기 전에 회사 네트워크 정책을 확인합니다.
3. 다른 네트워크에서 재현되는지 시험해 로컬 네트워크 문제를 분리합니다.
4. 기업 TLS 검사 환경에서는 관리자가 제공한 CA 번들 설정을 확인합니다.
5. 오류 발생 시각과 HTTP 상태 코드가 표시되면 함께 기록합니다.
6. 잠시 후 좁은 요청으로 다시 실행하되 무한 재시도하지 않습니다.

기업 프록시와 인증서 설정

공식 환경 변수 문서에는 기업 TLS 가로채기나 사설 루트 인증서를 위한 CODEX_CA_CERTIFICATE가 정의되어 있습니다. 값은 관리자가 제공한 PEM CA 번들의 경로여야 하며 인증서 내용을 채팅에 공유하지 않습니다.

# PowerShell 예시: 현재 세션에만 적용
$env:CODEX_CA_CERTIFICATE = "C:\path\to\company-ca.pem"

임의로 인증서 검증을 끄는 것은 중간자 공격 위험을 키웁니다. 올바른 CA 파일과 프록시 허용 정책을 조직 관리자에게 확인하세요.

Codex가 멈춘 것처럼 보일 때

1. 화면 아래나 다른 에이전트 스레드에 승인 요청이 있는지 확인합니다.
2. 오래 실행 중인 빌드·테스트·패키지 설치가 있는지 봅니다.
3. 새 터미널에서 git status와 간단한 파일 조회가 작동하는지 확인합니다.
4. 현재 작업을 안전하게 중단할 수 있는지 판단한 뒤 더 좁은 새 세션을 시작합니다.
5. 같은 증상이 반복되면 디버그 로그를 수집합니다.

출력만 없다고 프로세스를 여러 개 겹쳐 실행하면 잠금과 자원 문제가 늘 수 있습니다. 승인 대기인지 실제 정지인지 먼저 구분하세요.

현재 디렉터리와 Git 저장소 확인

Codex가 엉뚱한 파일을 보거나 프로젝트 지침을 읽지 못한다면 실행 위치가 잘못됐을 수 있습니다.

git rev-parse --show-toplevel
git status --short
git branch --show-current

모노레포에서는 열어야 할 프로젝트 루트와 .codex, AGENTS.md 위치가 일치하는지 확인합니다. 저장소 규칙의 탐색 방식은 Codex AGENTS.md 작성법에서 자세히 설명합니다.

프로젝트 신뢰와 로컬 설정 충돌

Codex는 프로젝트가 신뢰된 경우에만 프로젝트 범위의 일부 구성을 로드합니다. 사용자 전역 config.toml과 프로젝트의 .codex/config.toml이 서로 다른 모델, 권한 또는 도구 설정을 가질 수도 있습니다.

• 깨끗한 테스트 저장소에서도 같은 오류가 나는지 확인합니다.
• 사용자 설정과 프로젝트 설정을 비교하되 비밀값은 출력하지 않습니다.
• 최근 추가한 설정 항목 하나씩 되돌려 원인을 분리합니다.
• 오래된 옵션을 최신 구성 참조와 대조합니다.
• 조직 관리 설정은 로컬에서 우회하지 말고 관리자에게 확인합니다.

파일 접근 거부와 SandboxError 해결

샌드박스 오류는 Codex가 허용된 작업 공간 밖의 파일이나 명령에 접근했거나 플랫폼 샌드박스 준비가 실패했음을 뜻할 수 있습니다. 가장 먼저 현재 워크스페이스와 요청 대상 경로가 일치하는지 확인하세요.

원인	안전한 해결
프로젝트 밖 파일 필요	필요한 정확한 경로만 별도 승인
.env 읽기 거부	비밀값을 읽히지 말고 필요한 변수만 안전하게 주입
패키지 설치 네트워크 차단	승인된 레지스트리와 명령만 허용
Windows 샌드박스 초기화 실패	elevated 설정 절차 또는 조직 정책 확인
WSL 샌드박스 경고	WSL2와 bubblewrap·사용자 네임스페이스 확인

:danger-full-access 같은 광범위한 프로필은 원인 파악을 위한 기본 해결책이 아닙니다. 필요한 범위에서 가장 제한적인 권한을 유지하세요.

Windows 네이티브에서만 실패할 때

• Get-Command codex -All로 실행 중인 설치본을 확인합니다.
• 설치 bin 폴더가 사용자 PATH에 있는지 봅니다.
• 보안 제품이 실행 파일이나 샌드박스 초기화를 차단했는지 확인합니다.
• 네이티브 Windows와 WSL 설치본·상태 폴더를 혼동하지 않습니다.
• [windows] 샌드박스 설정과 관리자 정책을 확인합니다.

설치부터 다시 점검해야 한다면 Windows용 Codex 앱·CLI 설정 가이드를 참고하세요.

WSL2에서만 실행되지 않을 때

wsl --status
wsl --list --verbose

Windows PowerShell에서 배포판이 VERSION 2인지 확인합니다. WSL 터미널 안에서는 다음 항목을 별도로 확인하세요.

command -v codex
codex --version
command -v bwrap
git status

Windows에 설치된 Codex CLI가 WSL 안에 자동 설치되는 것은 아닙니다. 프로젝트와 런타임이 WSL에 있다면 CLI도 해당 배포판에서 사용하고, WSL1은 최신 Linux 샌드박스 경로와 호환되지 않으므로 WSL2를 사용합니다.

요청 한도와 서버 오류 구분하기

UsageLimitExceeded는 로컬 설치 오류가 아니며 계정의 사용 가능 범위와 관련됩니다. InternalServerError나 5xx 응답도 설정 파일을 삭제한다고 해결되지 않을 수 있습니다.

• 오류 유형과 HTTP 상태 코드가 있는지 확인합니다.
• 같은 요청을 무한 반복하지 않습니다.
• 계정의 사용량과 워크스페이스를 확인합니다.
• 잠시 뒤 최소 요청으로 재현 여부를 확인합니다.
• 지속되면 세션 ID, 버전과 민감정보를 제거한 로그로 신고합니다.

디버그 로그 수집 방법

공식 문서에 따르면 RUST_LOG로 로그 상세 수준을 조절하고 log_dir를 지정해 대화형 CLI의 일반 텍스트 로그를 남길 수 있습니다.

macOS·Linux·WSL:

RUST_LOG=debug codex -c log_dir=./.codex-log
tail -F ./.codex-log/codex-tui.log

PowerShell:

$env:RUST_LOG = "debug"
codex -c log_dir=./.codex-log
Get-Content .\.codex-log\codex-tui.log -Wait

문제를 재현한 뒤 로그를 보관하고 디버그 환경 변수는 필요하지 않으면 해제합니다. trace는 정보량과 민감정보 노출 위험이 커질 수 있으므로 먼저 debug로 시작하세요.

로그를 공유하기 전에 지울 정보

• API 키, 액세스 토큰과 인증 헤더
• 사용자 홈 경로와 개인 이름
• 비공개 저장소 주소와 원격 URL
• 고객 데이터, 소스코드와 내부 프롬프트
• 환경 변수 값과 인증서 내용
• 조직 이름, 사설 호스트와 IP 주소

오류 줄만 무작정 잘라내기보다 Codex 버전, 운영체제, 셸, 발생 시각, 재현 단계와 비밀정보를 제거한 관련 로그 범위를 함께 제공하면 원인 분석에 도움이 됩니다.

재설치 전에 확인할 체크리스트

1. 실제 실행 파일 경로와 버전을 기록했습니다.
2. 새 터미널에서도 같은 문제가 재현됩니다.
3. 다른 빈 Git 저장소에서도 동일한지 확인했습니다.
4. 로그인·네트워크·프록시 문제를 분리했습니다.
5. CODEX_HOME과 설정 경로를 확인했습니다.
6. 샌드박스를 해제하지 않고 권한 오류의 대상 경로를 찾았습니다.
7. 기존 세션과 설정을 보존할 필요가 있는지 확인했습니다.

재설치는 실행 파일 손상이나 설치 실패에는 도움이 되지만 계정, 프록시, 권한과 프로젝트 설정 문제는 그대로 남을 수 있습니다.

정상 복구 후 검증하기

codex --version
git status

의도한 저장소에서 Codex를 시작한 뒤 다음처럼 읽기 전용 요청으로 확인합니다.

현재 저장소 루트와 적용되는 프로젝트 지침을 확인해줘.
파일은 수정하지 말고 실행 가능한 lint와 test 명령만 정리해줘.

그다음 작은 변경과 검증을 수행하고, Codex 코드리뷰로 diff를 확인하세요. 여러 작업을 동시에 실행하다 멈췄다면 병렬 에이전트 관리법에서 스레드와 승인 대기를 점검할 수 있습니다.

편집부 결론

Codex CLI 오류는 설치 파일 자체보다 PATH, 중복 버전, 로그인, 네트워크, 현재 프로젝트와 샌드박스 범위에서 발생하는 경우가 많습니다. 버전과 실행 경로부터 확인하고 오류를 재현한 뒤 한 설정씩 바꾸세요. 디버그 로그는 마지막 근거로 활용하되 자격 증명과 비공개 코드가 포함되지 않았는지 반드시 검토해야 합니다.

이 글은 2026년 9월 4일 OpenAI 공식 문서를 분석해 작성했으며 모든 운영체제와 오류를 직접 재현한 사용 후기는 아닙니다. CLI 버전과 조직 정책에 따라 메시지와 설정이 달라질 수 있으므로 최신 공식 문서와 실제 오류 원문을 함께 확인하세요.

공식 문서와 함께 읽을 글

OpenAI Codex 문제 해결 공식 문서 확인하기

Codex 환경 변수와 디버그 로그 확인하기

Codex 샌드박스 작동 방식 확인하기

Windows에서 Codex CLI 다시 설정하기

프로젝트 설정과 AGENTS.md 확인하기

자주 묻는 질문

Codex CLI가 실행되지 않을 때 가장 먼저 무엇을 확인하나요?

codex --version을 실행하세요. 실패하면 설치와 PATH 문제부터 확인하고, 성공하면 로그인·네트워크·프로젝트 설정으로 범위를 좁힙니다.

codex를 찾을 수 없다는 오류는 어떻게 해결하나요?

새 터미널을 열고 실행 파일 경로와 PATH를 확인하세요. Windows에서는 Get-Command codex -All, macOS·Linux에서는 type -a codex가 유용합니다.

Codex가 아무 응답 없이 멈춘 이유는 무엇인가요?

승인 요청이나 오래 실행 중인 명령을 기다리고 있을 수 있습니다. 승인 화면을 확인하고 별도 터미널에서 git status가 작동하는지 봅니다.

로그인이 계속 반복되면 재설치해야 하나요?

재설치 전에 시스템 시간, 계정·워크스페이스, 프록시, 인증 저장 위치와 CODEX_HOME을 확인하세요.

SandboxError가 나오면 전체 권한을 허용해도 되나요?

기본 해결책으로 권장하지 않습니다. 현재 워크스페이스와 대상 경로를 확인하고 필요한 정확한 범위만 승인하세요.

WSL에서 Codex 명령이 보이지 않는 이유는 무엇인가요?

Windows와 WSL은 별도 실행 환경입니다. WSL 배포판 안의 설치 경로와 PATH를 확인하고 WSL2인지 점검하세요.

Codex CLI 디버그 로그는 어떻게 남기나요?

RUST_LOG=debug와 -c log_dir=./.codex-log를 사용해 로그를 활성화할 수 있습니다. 공유 전 토큰, 경로와 비공개 정보를 제거하세요.

Codex CLI를 삭제하고 다시 설치하면 모든 오류가 해결되나요?

아닙니다. 실행 파일 문제에는 도움이 되지만 계정, 프록시, 조직 정책, 샌드박스와 프로젝트 설정 문제는 남을 수 있습니다.