Codex doctor로 설치·인증·런타임 문제를 한 번에 진단해 지원 시간을 줄입니다 | DAKER 커뮤니티
설치가 됐는지, 로그인이 살아 있는지, Git·터미널·런타임이 정상인지 — 하나씩 확인하다 보면 오전이 갑니다. codex doctor는 로컬 Codex 환경의 설치·설정·인증·런타임·Git·터미널·앱 서버·스레드 목록을 한 번에 모아 진단 리포트로 보여 줍니다. 고치지는 않고, Fail이 있으면 비정상 종료 코드로 알려 지원 티켓과 삽질 시간을 줄입니다.
한 줄 요약
터미널에서 codex doctor를 실행하면 읽기 전용 진단 리포트가 나오고, 문제가 있으면 Fail과 함께 종료 코드가 남습니다.
긴 세션 정리는 Codex /compact 사용법을, 모델·권한 확인은 Codex /status 사용법을 함께 보면 좋습니다. 코덱스 글 모음은 DAKER 코덱스 디렉터리에 있습니다.
문제 상황: 왜 doctor가 필요할까요?
해커톤·바이브코딩 전에 「어제까지 되던 Codex」가 갑자기 멈출 때가 있습니다. 인증 만료, 설정 파일 경로 혼동, Git 미설정, 터미널 호환 문제처럼 원인은 제각각입니다. 지원 채널에 스크린샷을 여러 장 올리기 전에, 같은 진단 리포트 한 장으로 상태를 맞추면 질문과 답변이 짧아집니다.
작성 기준일(2026-09-13 KST) 기준 Codex CLI 공식 설명에 따르면, codex doctor는 로컬 설치·설정·인증·런타임·Git·터미널·앱 서버·스레드 인벤토리를 점검하는 읽기 전용 명령입니다. 자동 수리는 하지 않으며, Fail이 있으면 종료 코드가 0이 아닙니다.
핵심 개념: doctor가 보는 범위
- 설치·설정 — CLI가 기대하는 경로와 설정이 갖춰졌는지 봅니다.
- 인증 — 로그인·토큰 상태가 정상인지 확인합니다.
- 런타임 — 실행에 필요한 환경이 살아 있는지 점검합니다.
- Git·터미널 — 저장소·셸 쪽 전제 조건을 함께 봅니다.
- 앱 서버·스레드 — 앱 서버와 스레드 목록 상태를 리포트에 포함합니다.
- 읽기 전용 — 리포트만 생성하고, 설정을 고치거나 파일을 수정하지 않습니다.
| 플래그 | 하는 일 | 언제 쓰나요 |
|---|---|---|
--summary | 요약한 진단 결과를 보여 줍니다. | 빠르게 Pass/Fail만 볼 때 |
--json | 민감 정보가 가려진 JSON으로 출력합니다. | 로그·자동화·티켓 첨부에 넣을 때 |
--all | 가능한 점검을 넓게 돌립니다. | 원인을 좁히기 전 전체 스캔 |
--ascii | ASCII 중심으로 출력합니다. | 특수문자·이모지가 깨지는 터미널 |
--no-color | 색 없이 출력합니다. | 로그 파일·파이프 저장 |
단계별 사용법
- 터미널을 열고 Codex를 쓰는 프로젝트 또는 홈 환경에서
codex doctor를 실행합니다. - 첫 확인은
codex doctor --summary로 Pass/Fail만 빠르게 봅니다. - Fail이 있으면
codex doctor --all로 범위를 넓혀 같은 항목이 반복되는지 확인합니다. - 지원·동료에게 공유할 때는
codex doctor --json결과를 파일로 저장합니다. JSON은 민감 정보가 가려진 형태입니다. - 로그에 붙일 때는
--no-color, 깨진 문자가 보이면--ascii를 함께 씁니다. - 종료 코드가 0이 아니면 Fail이 있다는 뜻입니다. 리포트의 Fail 항목부터 고치고, 다시 doctor를 돌려 확인합니다.
실무에서 바로 쓰는 루틴
- 대회·해커톤 시작 직전, 또는 「갑자기 안 된다」는 순간 먼저
codex doctor --summary를 돌립니다. - Fail이 인증·설정 쪽이면 로그인·설정 파일부터 손보고, Git·터미널 Fail이면 로컬 도구 환경을 먼저 맞춥니다.
- 팀 채널·지원 티켓에는
--json출력과 증상(언제부터, 어떤 명령에서)을 같이 적습니다. - 고친 뒤에는 doctor를 한 번 더 실행해 Fail이 사라졌는지 확인합니다. doctor 자체는 수리하지 않으므로, 수정은 사용자가 합니다.
- 세션이 길어지면 /compact로 컨텍스트를 정리하고, 모델·권한은 /status로 확인합니다.
자주 묻는 질문
codex doctor는 설정을 고쳐 주나요?
아닙니다. 읽기 전용 진단입니다. 리포트의 Fail을 보고 사용자가 설치·인증·환경을 직접 고칩니다.
종료 코드가 0이 아니면 무조건 고장인가요?
Fail이 하나라도 있으면 비정상 종료 코드가 납니다. 어떤 항목이 Fail인지는 리포트 본문을 확인해야 합니다.
--json을 티켓에 붙여도 되나요?
공식 설명상 JSON 출력은 민감 정보가 가려진 형태입니다. 그래도 공유 전에 한 번 눈으로 확인하는 편이 안전합니다.
/status와 무엇이 다른가요?
/status는 세션 안의 모델·권한·컨텍스트를 보는 쪽에 가깝고, codex doctor는 로컬 설치·인증·런타임·Git·터미널 등 환경 진단을 모읍니다. 둘 다 쓰면 「세션」과 「머신」을 나눠 점검할 수 있습니다.
오늘 따라 할 순서
codex doctor --summary로 Pass/Fail을 확인합니다.- Fail이 있으면
codex doctor --all과 필요 시--json으로 기록을 남깁니다. - Fail 항목만 고친 뒤 doctor를 다시 실행합니다.
- 정상화되면 본 작업을 시작하고, 긴 세션은 /compact·/status로 관리합니다.
관련 글: /compact 사용법, /status 사용법, DAKER 코덱스 디렉터리