codex doctor로 설치·인증·런타임 문제를 한 번에 점검하는 방법 | DAKER 커뮤니티

Codex가 갑자기 동작하지 않을 때는 원인을 하나씩 짚어 보게 됩니다. 설치가 꼬였는지, 로그인이 풀렸는지, Git이나 터미널 환경에 문제가 없는지 확인하다 보면 생각보다 시간이 오래 걸립니다. 이럴 때 codex doctor는 여러 점검 항목을 한 번에 모아 보여 주는 출발점이 됩니다.

특히 해커톤이나 바이브코딩처럼 바로 작업을 시작해야 하는 상황에서는, 같은 형식의 진단 리포트 하나만 있어도 문제를 훨씬 빠르게 좁힐 수 있습니다. 지원 티켓을 만들거나 동료와 상태를 공유할 때도 도움이 됩니다.

터미널에서 codex doctor를 실행하면 읽기 전용 진단 리포트가 나오고, 문제가 있으면 Fail과 함께 종료 코드가 남습니다.

긴 세션을 정리할 때는 Codex /compact 사용법을, 모델과 권한을 확인할 때는 Codex /status 사용법을 함께 보면 좋습니다. 코덱스 관련 글은 DAKER 코덱스 디렉터리에서 모아 볼 수 있습니다.

왜 codex doctor가 필요한가요?

어제까지 잘 되던 Codex가 오늘 갑자기 멈추는 경우가 있습니다. 인증이 만료되었을 수도 있고, 설정 파일 경로를 잘못 보고 있을 수도 있습니다. Git 설정이나 터미널 호환성처럼 전혀 다른 층위의 문제가 원인일 때도 있습니다. 원인이 제각각이다 보니 스크린샷을 여러 장 주고받으며 상태를 맞추는 일이 흔합니다.

작성 기준일(2026-09-13 KST) 기준 Codex CLI 공식 설명에 따르면, codex doctor는 로컬 설치, 설정, 인증, 런타임, Git, 터미널, 앱 서버, 스레드 인벤토리까지 점검하는 읽기 전용 명령입니다. 인벤토리는 현재 어떤 구성 요소가 있는지 정리한 목록을 뜻합니다. 이 명령은 자동으로 수리하지 않으며, Fail이 있으면 종료 코드가 0이 아닙니다.

무엇을 확인해 주는지

codex doctor는 설치와 설정이 기대한 위치에 있는지, 로그인 상태와 토큰이 정상인지, 실행에 필요한 런타임이 살아 있는지 확인합니다. 여기에 Git과 터미널 환경, 앱 서버 상태, 스레드 목록까지 함께 리포트에 담습니다. 스레드는 작업 흐름 단위를 뜻합니다.

이 명령은 상태를 읽어서 보여 주는 도구이며, 설정이나 파일을 직접 바꾸지는 않습니다.

기본 사용 흐름

터미널을 열고 Codex를 쓰는 프로젝트 폴더나 홈 환경에서 codex doctor를 실행하면 됩니다. 처음에는 codex doctor --summary로 Pass/Fail만 빠르게 확인하는 방식이 가장 간단합니다.

Fail이 보이면 codex doctor --all로 점검 범위를 넓혀 보는 것이 좋습니다. 지원팀이나 동료와 공유해야 할 때는 codex doctor --json 결과를 파일로 저장해 두면 편합니다. JSON은 데이터를 구조적으로 담는 형식이며, 여기서는 민감 정보가 가려진 상태로 출력됩니다.

로그에 붙여 넣을 때는 --no-color를 쓰면 깔끔하고, 문자가 깨져 보이면 --ascii를 함께 쓰면 됩니다. 종료 코드가 0이 아니면 Fail이 있다는 뜻이므로, 리포트에서 해당 항목부터 확인한 뒤 수정하고 다시 실행해 보면 됩니다.

실무에서 바로 쓰는 점검 순서

대회나 해커톤 시작 직전, 또는 갑자기 동작하지 않을 때는 먼저 codex doctor --summary를 실행해 전체 상태를 짧게 확인하면 됩니다. Fail이 인증이나 설정 쪽에 있으면 로그인과 설정 파일부터 보고, Git이나 터미널 Fail이면 로컬 도구 환경을 먼저 맞추는 편이 좋습니다.

팀 채널이나 지원 티켓에는 --json 출력과 함께 언제부터 문제가 생겼는지, 어떤 명령에서 막혔는지 같은 증상을 같이 적어 두면 도움이 됩니다. 수정한 뒤에는 doctor를 한 번 더 실행해 Fail이 사라졌는지 확인하면 됩니다. doctor는 직접 수리하지 않기 때문에 실제 수정은 사용자가 해야 합니다.

세션이 길어지면 /compact로 컨텍스트를 정리하고, 모델과 권한은 /status로 확인하면 좋습니다.

자주 묻는 질문

codex doctor가 설정을 직접 고쳐 주나요?

아닙니다. 읽기 전용 진단 명령입니다. 리포트의 Fail을 보고 사용자가 설치, 인증, 환경을 직접 고쳐야 합니다.

종료 코드가 0이 아니면 무조건 고장인가요?

Fail이 하나라도 있으면 비정상 종료 코드가 나옵니다. 다만 어떤 항목이 문제인지는 리포트 본문을 확인해야 정확히 알 수 있습니다.

--json 결과를 티켓에 붙여도 되나요?

공식 설명상 JSON 출력은 민감 정보가 가려진 형태입니다. 그래도 공유하기 전에 한 번 직접 확인하는 편이 안전합니다.

/status와는 무엇이 다른가요?

/status는 세션 안에서 모델, 권한, 컨텍스트를 확인하는 데 가깝습니다. 컨텍스트는 현재 대화와 작업에 쓰이는 정보 범위를 뜻합니다. 반면 codex doctor는 로컬 설치, 인증, 런타임, Git, 터미널 같은 환경을 점검합니다. 둘을 함께 쓰면 세션 문제와 머신 환경 문제를 나눠서 볼 수 있습니다.

참고 자료

Codex /compact 사용법
Codex /status 사용법
DAKER 코덱스 디렉터리

여러분은 Codex가 갑자기 멈췄을 때 가장 먼저 어떤 항목부터 확인하는 편인가요?