12. 자주 막히는 문제

Codex 앱을 쓰다 보면 에러가 나거나, 화면이 이상하거나, 뭔가 안 될 때가 있습니다. 이 페이지는 초보자도 스스로 문제를 찾고 해결할 수 있도록 단계별로 안내하는 트러블슈팅 가이드입니다.

한 줄 요약 이 페이지에서 배우는 것

문제가 생겼을 때 당황하지 않고 원인을 찾는 5단계 체크리스트
가장 많이 발생하는 4가지 문제 유형과 각각의 상세 해결법
자주 나오는 에러 메시지를 보고 바로 대처하는 법
스스로 해결이 안 될 때 도움을 요청하는 방법
초보자가 자주 궁금해하는 FAQ 모음

문제가 생겼을 때 당황하지 마세요

Codex 앱에서 에러가 나거나 뭔가 이상하게 보이면 처음에는 당황할 수 있습니다. 하지만 걱정하지 마세요. 대부분의 문제는 아주 간단한 원인에서 비롯됩니다.

예를 들면, Git이 정리가 안 된 상태에서 작업을 시작했거나, 설정 폴더 위치가 살짝 잘못되었거나, 필요한 파일이 설치되지 않았을 뿐입니다. 코드를 잘 모르더라도 이 페이지의 순서대로 따라가면 대부분 해결할 수 있습니다.

이 페이지를 나만의 트러블슈팅 체크리스트로 활용하세요. 문제가 생길 때마다 여기로 돌아와서 하나씩 확인하면 됩니다.

체크리스트: 문제 해결 5단계

Codex 앱에서 문제가 발생하면 아래 순서대로 하나씩 확인하세요. 순서가 중요합니다 -- 위에서부터 차례로 진행하면 대부분의 이슈 원인을 찾을 수 있습니다.

Step 1: Git 상태 확인하기

터미널(명령 프롬프트)을 열고 프로젝트 폴더에서 아래 명령어를 입력합니다:

git status

결과 읽는 법:

"nothing to commit, working tree clean" -- 깨끗한 상태입니다. Git은 문제가 아닙니다.
"Changes not staged for commit" -- 수정되었지만 아직 저장(commit)하지 않은 파일이 있습니다. 이 파일들이 Review Pane에 나타날 수 있습니다.
"Untracked files" -- Git이 아직 관리하지 않는 새 파일이 있습니다.

Step 2: .codex 폴더 위치 확인하기

.codex 폴더는 Codex 앱의 설정 파일이 들어있는 숨김 폴더입니다. 이 폴더가 올바른 위치에 있어야 앱이 설정을 읽을 수 있습니다.

확인 방법 (터미널):

ls -la | grep .codex

올바른 위치: 프로젝트의 가장 최상위 폴더(루트)에 있어야 합니다.

예: my-project/.codex/ (O) / my-project/src/.codex/ (X)

Step 3: 프로젝트 루트 확인하기

"프로젝트 루트"란? 프로젝트의 가장 최상위 폴더를 말합니다. 쉽게 말해, package.json이나 .git 폴더가 있는 곳입니다.

왜 중요한가요?

Codex 앱은 프로젝트 루트를 기준으로 파일을 찾습니다.
모노레포(하나의 저장소에 여러 프로젝트가 있는 구조)를 쓴다면, Codex에서 열고 있는 폴더가 의도한 프로젝트의 루트인지 확인하세요.
상위 폴더나 하위 폴더를 잘못 열면 설정이 인식되지 않을 수 있습니다.

Step 4: Worktree 초기화 확인하기

Worktree는 Git에 저장(commit)된 파일만 가져옵니다. 따라서 로컬에서만 존재하는 파일은 Worktree에 없습니다.

확인할 것:

Setup Script가 설정되어 있는지 확인 (Settings > Local Environment)
Setup Script가 실행되었는지 확인 -- 에러 없이 완료되었나요?
node_modules, venv 등 설치 폴더가 생성되었는지 확인

Step 5: 앱 재시작 또는 업데이트 확인하기

위 4단계를 모두 확인했는데도 문제가 계속된다면, 가장 기본적인 해결법을 시도하세요:

앱 재시작: Codex 앱을 완전히 종료하고 다시 실행합니다.
업데이트 확인: 앱 스토어나 공식 사이트에서 최신 버전인지 확인합니다.
캐시 초기화: 가끔 오래된 캐시가 문제를 일으킬 수 있습니다. 주의: 앱 삭제·재설치는 사라진 스레드를 "복구"하지 못합니다 — 스레드는 영구 삭제되는 동작이 아니라 Archive 처리되며, Settings → Archived Threads에서 복원합니다.

주요 문제 유형 -- 상세 해결 가이드

가장 많이 보고되는 4가지 문제를 하나씩 자세히 설명합니다. 각 문제마다 원인, 해결법, 예방법을 정리했습니다.

문제 1: Review Pane에 이상한 파일이 보여요

왜 이런 일이 생기나요?

Review Pane은 Git의 상태(diff)를 기준으로 파일을 보여줍니다. Git에서 "변경됨"으로 인식되는 모든 파일이 표시되는데, 이 중에는 Codex가 수정하지 않은 파일도 포함될 수 있습니다. 예를 들어, 여러분이 직접 수정하다 저장하지 않은 파일이나, 다른 도구가 자동으로 변경한 파일도 함께 보입니다.

해결법 (단계별):

터미널에서 git status를 실행하여 어떤 파일이 변경되었는지 확인합니다.
Codex와 관련 없는 변경사항이 있다면, 임시로 저장해 둡니다: git stash (나중에 git stash pop으로 복원할 수 있습니다)
또는 특정 파일의 변경을 되돌리려면: git checkout -- 파일이름

예방법: Codex로 작업을 시작하기 전에 항상 git status로 깨끗한 상태인지 확인하는 습관을 들이세요.

문제 2: 스레드가 사라졌어요

왜 이런 일이 생기나요?

스레드가 "삭제"된 것이 아니라, 보관(archived)되었을 가능성이 높습니다. 참고로 Codex 앱은 스레드를 영구 삭제하는 동작을 노출하지 않습니다 — 사용자에게 제공되는 액션은 Archive와 Unarchive(복원)뿐입니다. Codex는 오래되거나 완료된 스레드를 자동으로 아카이브할 수 있고, 사이드바 필터 설정 때문에 일부 스레드만 표시되고 나머지는 숨겨질 수도 있습니다.

해결법:

보관된 스레드 찾기: Settings(설정)으로 이동하여 "Archived Threads" 항목을 찾습니다. 여기서 보관된 스레드 목록을 볼 수 있고, 필요한 스레드를 복원(unarchive)할 수 있습니다.
필터 설정 확인: 사이드바 상단에서 스레드 정렬/필터 옵션을 찾습니다. 필터가 특정 조건으로 설정되어 있으면 일부 스레드가 숨겨집니다. "Chronological"(시간순)으로 변경하면 모든 스레드가 표시됩니다.
검색 기능 활용: 스레드 이름이나 키워드를 기억한다면 검색 기능으로 직접 찾을 수 있습니다.

문제 3: Worktree에서 코드가 안 돌아요

가장 흔한 원인: 설치물(dependencies)이 없습니다

Worktree는 Git에 저장(commit)된 파일만 복사해옵니다. 하지만 node_modules(JavaScript 라이브러리), venv(Python 가상환경), .env(환경변수 파일) 같은 것들은 Git에 저장하지 않는 것이 일반적입니다. 그래서 Worktree에는 이런 파일들이 없어 코드가 실행되지 않습니다.

해결법 1: Setup Script 확인 및 생성

Settings > Local Environment에서 Setup Script를 설정하세요. Worktree가 만들어질 때 자동으로 필요한 설치를 해줍니다. 예시:

npm install

해결법 2: 수동으로 설치하기

프로젝트 유형에 따라 터미널에서 직접 실행합니다:

JavaScript/Node.js: npm install
Python: pip install -r requirements.txt
Ruby: bundle install
Go: go mod download

문제 4: .codex가 인식이 안 돼요

원인 1: 폴더 위치 문제

.codex 폴더가 프로젝트 루트가 아닌 하위 폴더에 있으면 앱이 인식하지 못합니다. 반드시 .git 폴더와 같은 레벨(프로젝트 최상위)에 위치해야 합니다.

원인 2: 숨김 파일 보기 설정

.codex는 점(.)으로 시작하는 숨김 폴더입니다. 파일 탐색기에서 보이지 않을 수 있습니다.

macOS: Finder에서 Cmd + Shift + .을 누르면 숨김 파일이 보입니다.
Windows: 파일 탐색기 > 보기 > "숨긴 항목" 체크
터미널: ls -la 명령어로 확인

원인 3: 모노레포에서의 올바른 위치

모노레포(하나의 Git 저장소 안에 여러 프로젝트)를 사용하는 경우, .codex 폴더는 Codex 앱에서 실제로 열고 있는 디렉터리에 있어야 합니다. Git 저장소의 최상위가 아니라, 앱에서 프로젝트로 열고 있는 폴더에 배치하세요.

자주 나오는 에러 메시지와 해결법

에러 메시지를 보면 무섭게 느껴질 수 있지만, 대부분은 정해진 해결법이 있습니다. 아래 표에서 본인이 겪은 에러 메시지를 찾아보세요.

에러 메시지	의미	해결 방법
`Git repository not found`	현재 폴더가 Git 저장소가 아닙니다. Git 초기화가 안 되어 있는 상태입니다.	터미널에서 프로젝트 폴더로 이동 후 `git init`을 실행합니다.
`Permission denied`	파일이나 폴더에 접근할 권한이 없습니다.	macOS/Linux: `chmod +x 파일이름`으로 실행 권한을 부여합니다. Windows: 관리자 권한으로 실행해 보세요.
`Command not found`	해당 명령어(도구)가 설치되어 있지 않거나, 시스템이 찾을 수 없습니다.	필요한 도구(Node.js, Python 등)를 설치하세요. 이미 설치했다면 PATH 환경변수에 경로가 등록되어 있는지 확인합니다.
`ENOENT: no such file or directory`	앱이 찾으려는 파일이나 폴더가 존재하지 않습니다.	해당 파일이 실제로 있는지 확인합니다. 파일 경로에 오타가 없는지, 대소문자가 맞는지 체크하세요.
`EADDRINUSE: port already in use`	사용하려는 포트 번호를 다른 프로그램이 이미 쓰고 있습니다.	해당 포트를 쓰는 프로그램을 종료하거나, 다른 포트 번호를 사용하세요. `lsof -i :포트번호`로 확인 가능합니다.
`Module not found`	코드에서 불러오려는 라이브러리가 설치되어 있지 않습니다.	`npm install` 또는 `pip install -r requirements.txt`로 의존성을 설치합니다.
`fatal: not a git repository`	현재 위치가 Git 저장소 안이 아닙니다.	`cd`로 프로젝트 폴더로 정확히 이동했는지 확인합니다. 필요하면 `git init`으로 초기화합니다.

문제 해결 흐름

문제가 발생했을 때 체크포인트를 순서대로 확인하고, 해결되지 않으면 도움을 요청하는 전체 흐름입니다.

Troubleshooting Flow

문제 발생

5단계 체크리스트 확인

Git 상태 > .codex 위치 > 프로젝트 루트 > Worktree 초기화 > 앱 재시작

해결됨

원인 파악 후 조치 완료

도움 요청

/feedback 또는 커뮤니티

모노레포에서 .codex 위치 주의 모노레포에서 .codex를 둔 디렉터리를 실제로 프로젝트 루트로 열었는지 확인하세요. 상위 디렉터리에서 열면 앱이 설정을 인식하지 못할 수 있습니다.

사이드바 스레드 필터 확인 사이드바에서 스레드가 일부만 보이면 필터가 Chronological로 설정되어 있는지 점검하세요. 다른 필터 모드에서는 일부 스레드가 숨겨질 수 있습니다.

도움 요청하기

위의 방법들을 모두 시도했는데도 문제가 해결되지 않나요? 혼자 고민하지 마세요. 아래 채널을 통해 도움을 받을 수 있습니다.

OpenAI 공식 문서

가장 정확하고 최신 정보를 제공합니다. 영어이지만 브라우저 번역 기능을 활용하면 읽기 편합니다.

developers.openai.com/codex

커뮤니티 포럼

다른 사용자들이 같은 문제를 겪고 해결한 경험을 공유합니다. 검색해보면 이미 답이 있는 경우가 많습니다.

community.openai.com

/feedback 명령어

Codex 앱 안에서 /feedback 명령어를 입력하면 OpenAI 팀에 직접 피드백을 보낼 수 있습니다. 명령 실행 시 세션 ID가 함께 생성되므로(공식 troubleshooting 안내), 보고 메일/이슈에 그 세션 ID를 같이 첨부하면 지원팀이 해당 세션 로그를 빠르게 추적할 수 있습니다.

자주 묻는 질문 (FAQ)

초보자들이 가장 많이 궁금해하는 질문과 답변을 모았습니다.

Q: Codex가 아무 반응이 없어요. 메시지를 보냈는데 답이 안 와요.

A: 먼저 인터넷 연결을 확인하세요. Codex는 클라우드 기반으로 동작하므로 네트워크가 끊기면 응답하지 않습니다. 인터넷이 정상이라면, 앱을 완전히 종료했다가 다시 실행해 보세요. 그래도 안 되면 OpenAI 서비스 상태 페이지(status.openai.com)에서 서버 장애 여부를 확인합니다.

Q: 작업이 너무 오래 걸려요. 진행 중인지 멈춘 건지 모르겠어요.

A: 복잡한 작업은 시간이 걸릴 수 있습니다. 화면에 "진행 중" 표시가 있는지 확인하세요. 만약 5분 이상 아무 변화가 없다면, 해당 스레드를 닫고 새 스레드에서 작업을 더 작은 단위로 나누어 요청해 보세요. "이 파일 전체를 리팩토링해줘"보다 "이 함수 하나만 수정해줘"처럼 구체적으로 요청하면 훨씬 빠릅니다.

Q: Codex가 틀린 코드를 만들었어요. 어떻게 해야 하나요?

A: AI가 만든 코드는 항상 검토해야 합니다. Review Pane에서 변경사항을 꼼꼼히 확인하고, 문제가 있으면 "Reject"(거부)를 선택하세요. 그리고 Codex에게 무엇이 잘못되었는지 구체적으로 알려주면(예: "이 함수의 반환값 타입이 잘못됐어") 더 정확한 결과를 얻을 수 있습니다. AI는 완벽하지 않으므로, 최종 확인은 반드시 사람이 해야 합니다.

Q: 앱이 계속 크래시(강제 종료)해요.

A: 아래 순서로 시도해 보세요: (1) 앱을 최신 버전으로 업데이트합니다. (2) 컴퓨터를 재시작합니다. (3) 앱을 삭제하고 다시 설치합니다. (4) 특정 프로젝트에서만 크래시하는지 확인합니다 -- 다른 프로젝트에서는 정상이라면 해당 프로젝트의 설정 파일에 문제가 있을 수 있습니다. (5) 여전히 크래시하면 /feedback으로 에러 상황을 상세히 보고해 주세요.

Q: 업데이트가 안 돼요. 새 버전이 나왔다는데 업데이트 버튼이 없어요.

A: 업데이트 방법은 설치 방식에 따라 다릅니다. Mac App Store에서 설치했다면 App Store에서 업데이트를 확인하세요. 직접 다운로드한 경우 공식 사이트에서 최신 버전을 받아 다시 설치합니다. 자동 업데이트가 되지 않을 때는 수동으로 새 버전을 다운로드하는 것이 가장 확실한 방법입니다.

Q: 무료 사용 한도가 있나요? 갑자기 작동이 안 돼요.

A: 로그인 방식에 따라 한도와 확인 위치가 다릅니다.

ChatGPT 구독 로그인 — 공식 Quickstart는 "Every ChatGPT plan includes Codex"라고 안내합니다. 다만 2026년 6월 기준 개발자 홈페이지는 Free/Go 한시 제공과 Plus·Pro·Business·Enterprise의 2x Codex rate limits를 따로 강조하므로, 체감 한도는 최신 공식 안내를 우선 확인하세요 (platform.openai.com 사용량 대시보드는 이 경우와 무관).

OpenAI API 키 로그인 — 종량제로 청구되며, 현재 사용량과 남은 크레딧은 platform.openai.com/usage에서 확인합니다. 결제 한도(billing limit)도 같은 대시보드에서 설정할 수 있어 예상치 못한 비용을 막을 수 있습니다.

핵심 포인트

문제가 생기면 5단계 체크리스트(Git 상태 > .codex 위치 > 프로젝트 루트 > Worktree 초기화 > 앱 재시작)를 순서대로 확인하세요.
Review Pane은 Git 상태 기준으로 파일을 보여줍니다. 작업 전 깨끗한 상태에서 시작하세요.
사라진 스레드는 Settings의 Archived Threads에서 찾을 수 있습니다.
Worktree에서 코드가 안 돌면 Setup Script나 수동 설치로 의존성을 확인하세요.
에러 메시지를 정확히 읽으면 해결법의 80%는 이미 메시지 안에 있습니다.
혼자 해결이 안 되면 /feedback 명령어로 OpenAI에 직접 보고하세요.

플랫폼별 샌드박스 백엔드

"쓰기 권한이 거부되었다", "네트워크 접근 차단" 같은 메시지를 만났다면 운영체제별 샌드박스 메커니즘을 확인해야 합니다(공식 sandbox 문서).

macOS — Seatbelt

Apple 내장 sandbox-exec(Seatbelt) 프로파일을 사용. 보호된 폴더(Downloads/Desktop/Documents/Music)는 시스템 권한 프롬프트가 별도로 뜹니다.

Linux — bubblewrap

Codex 0.115부터 Linux 샌드박스가 bubblewrap으로 통합되었습니다(WSL1이 더 이상 지원되지 않는 이유). bubblewrap이 없을 때는 번들된 helper로 대체되며, 이 경우 unprivileged user namespace 생성을 지원하는 커널이 필요합니다.

Windows — Native Sandbox

데스크톱 앱은 Windows 네이티브 샌드박스(PowerShell 기반)를 사용합니다. WSL2 안에서 실행하면 위 Linux(bubblewrap) 백엔드가 적용됩니다.

팁: 권한 문제는 대부분 샌드박스 모드(read-only / workspace-write / danger-full-access)와 OS 수준 권한이 겹쳐서 발생합니다. Settings의 승인 정책을 먼저 확인한 뒤, OS 권한 다이얼로그가 차단되어 있는지 점검하세요.

로그 위치 및 버전 확인

지원팀에 문의하거나 직접 원인을 추적할 때 가장 먼저 확인해야 하는 경로입니다(공식 Troubleshooting 문서 기준).

항목	경로 / 명령
macOS 앱 로그	`~/Library/Logs/com.openai.codex/YYYY/MM/DD`
활성 세션	`$CODEX_HOME/sessions`
아카이브된 세션	`$CODEX_HOME/archived_sessions`
CLI 버전	`codex --version`
앱 번들 안의 CLI 버전	`/Applications/Codex.app/Contents/Resources/codex --version`

앱과 번들 CLI의 버전이 다르면 한쪽이 자동 업데이트에서 누락된 것입니다. 동일하게 맞춰주면 대부분의 "동작이 다르다" 류 문제가 해소됩니다.

자주 잊는 복구 팁

"Last turn changes" 보기

Review Pane 상단의 "Last turn"으로 전환하면 직전 Codex 응답이 만든 변경만 표시됩니다. lock 파일 등 노이즈 제거에 유용합니다.

멈춘 통합 터미널 복구 (Terminal frozen)

공식 troubleshooting 안내: ① 터미널 패널을 닫고 → ② Cmd+J로 다시 열고 → ③ pwd·git status로 현재 디렉터리와 브랜치를 먼저 검증합니다. 문제를 보고하기 전에도 cwd와 branch부터 확인하라는 게 공식 권고입니다. Codex 세션 자체는 유지됩니다.

취소한 프롬프트 되살리기

실행을 취소(Cancel)한 직후 Composer에서 ↑ 키를 누르면 직전 프롬프트가 다시 채워집니다 — 공식 troubleshooting 문서에 명시된 복구 방법입니다 ("Press up arrow key in composer after canceling run"). 터미널 history와 같은 방식.

macOS 파일 시스템 권한

Apple Music, Downloads, Desktop 등 보호된 폴더 접근이 필요할 때 macOS 권한 프롬프트가 뜹니다. 시스템 설정 → 개인정보 보호 및 보안 → 파일과 폴더에서 Codex에 권한을 부여하세요.

폰트 렌더링이 깨질 때

Settings → Appearance의 Code font를 다른 모노스페이스 폰트(JetBrains Mono 등)로 바꾸면 즉시 해결되는 경우가 많습니다.

로그·세션 위치 (디버깅용)

앱 로그: ~/Library/Logs/com.openai.codex/YYYY/MM/DD (macOS). 세션: $CODEX_HOME/sessions (기본 ~/.codex/sessions). 아카이브된 세션: $CODEX_HOME/archived_sessions. 인증 토큰: ~/.codex/auth.json — 비밀번호처럼 취급하라는 공식 권고가 있습니다.

다음 단계

수고하셨습니다! 이 페이지까지 읽으셨다면 Codex 앱에서 발생하는 대부분의 문제를 스스로 해결할 수 있는 준비가 된 것입니다.

홈으로 돌아가기

전체 가이드 목차를 다시 보고, 아직 읽지 않은 페이지를 확인하세요.

메인 페이지로 이동

처음부터 시작하기

아직 Codex를 설치하지 않았다면, 설치 가이드부터 시작하세요.

1. 설치와 첫 메시지

장점 / 단점 / 한계점

✅ 장점

공식 문서 기반으로 검증된 해결 방법 제공
문제 유형별로 체계적으로 분류되어 빠른 탐색
재현 단계부터 해결까지 단계별 가이드 제공
FAQ 형태로 자주 묻는 질문에 즉시 답변

❌ 단점

모든 에러 상황을 다루지는 못함
환경별(OS, 버전) 차이로 동일한 해결법이 적용 안 될 수 있음
새로운 버전 업데이트로 해결법이 달라질 수 있음

⚠️ 한계점

네트워크 관련 문제는 사용자 환경에 따라 원인이 다양하여 일반화 어려움
기업 방화벽이나 VPN 환경의 문제는 IT 부서 협조 필요
로그 분석이 필요한 복잡한 문제는 공식 지원 채널 이용 권장

공식 출처

Troubleshooting Review pane, archived threads, worktree, .codex 위치 문제 해결