Codex CLI 진단 시작 방법: codex doctor로 설치 상태 처음 점검하는 법

TL;DR

핵심 3줄 요약

이 글에서 다룰 내용

codex doctor는 무엇이고 언제 쓰면 좋은가

시작 전에 진입 위치와 출력 경계를 확인합니다

codex doctor 는 운영체제 셸에서 실행하는 CLI 하위 명령입니다. Codex 대화형 화면 안에 넣는 /doctor 같은 slash command가 아닙니다.

공식 문서는 codex doctor 를 Stable로 표시하지만 이 명령의 공통 최소 버전, 플랜, 계정, 지역, 언어, 가격 조건을 따로 명시하지 않습니다. 따라서 현재 컴퓨터에서 codex doctor --help 가 열리는지 먼저 확인합니다.

--json 은 공식 문서상 redacted machine-readable support report를 출력합니다. redacted라는 설명만 믿고 바로 외부에 보내지 말고 경로·계정 상태·조직 정보처럼 공유하지 않을 내용을 사람이 다시 확인합니다.

codex doctor를 처음 실행하는 순서

1. 현재 Codex CLI와 doctor 도움말을 확인합니다

터미널에서 다음 명령을 실행합니다.

codex --version
codex doctor --help

두 번째 명령이 열리면 현재 설치본이 doctor 와 어떤 옵션을 제공하는지 읽습니다. 알 수 없는 하위 명령이라는 오류가 나오면 이 글의 옵션을 추정 적용하지 않고 공식 설치 경로와 현재 버전을 별도로 확인합니다.

2. 요약 보고서부터 실행합니다

처음에는 긴 세부 목록보다 그룹별 결과를 먼저 봅니다.

codex doctor --summary --no-color

공식 문서에서 --summary 는 그룹별 check row와 마지막 count summary만 보여줍니다. --no-color 는 사람이 읽는 출력의 ANSI 색상을 끕니다. 색상이 없는 출력은 터미널 기록에서 상태를 다시 읽기 쉽습니다.

3. 마지막 개수 요약과 비정상 항목을 기록합니다

출력 마지막의 개수 요약을 확인합니다. 경고나 실패로 표시된 그룹 이름과 설명은 그대로 기록합니다. 정상·대기·참고 상태를 모두 실패로 해석하지 않습니다.

이번 첫 점검에서는 원인을 확정하지 않습니다. 보고서가 실제로 표시한 항목, 현재 명령, 재현 시각만 적습니다.

4. 필요한 그룹만 상세 출력으로 다시 봅니다

요약에서 확인할 항목이 생기면 기본 상세 보고서를 실행합니다.

codex doctor --no-color

긴 목록까지 펼쳐야 할 때만 도움말에서 --all 을 확인한 뒤 사용합니다. 처음부터 모든 세부를 복사하기보다 문제와 가까운 그룹의 설명을 읽습니다.

5. 공유용 구조화 보고서는 화면에서 먼저 검토합니다

지원 요청이나 실행 전후 비교에 구조화된 값이 필요하면 다음 명령을 사용할 수 있습니다.

codex doctor --json

공식 문서는 이 출력을 redacted machine-readable support report라고 설명합니다. 그래도 화면에 나온 내용은 사람이 읽어야 합니다. 공개 범위에 맞지 않는 값이 없는지 확인한 다음 공유 여부를 결정합니다.

6. 후속 조치와 승인자를 분리해 기록합니다

각 항목을 관찰된 상태 | 근거 줄 | 다음 확인 | 담당자 | 승인 필요 여부 로 정리합니다. 업데이트, config.toml 수정, 로그인 재설정, 프록시·인증서 변경, 지원 제출은 첫 실행의 완료 기준에서 뺍니다.

완료 기준은 진단 보고서를 얻고 확인할 항목을 분류한 상태입니다. 실제 변경은 원인과 되돌리기 방법을 검토한 뒤 별도로 승인합니다.

결과를 읽고 다음 행동을 정하는 법

요약은 우선순위를 정하는 데 씁니다

마지막 count summary에서 경고·실패가 있는지 먼저 확인합니다. 그런 다음 해당 그룹의 상세 설명으로 이동합니다. 개수만 보고 인증, 네트워크, 설정 가운데 하나를 임의로 원인으로 정하지 않습니다.

참고나 대기 상태도 현재 실행 방식에서는 정상일 수 있습니다. 예를 들어 백그라운드 구성 요소가 실행되지 않았다는 관찰이 곧 설치 실패를 뜻하는지는 보고서 설명과 실제 사용 방식을 함께 봐야 합니다.

수정 뒤에는 같은 조건으로 다시 실행합니다

별도 승인을 거쳐 변경했다면 같은 작업 폴더와 셸에서 같은 doctor 명령을 다시 실행합니다. 수정 전후의 해당 그룹과 마지막 개수 요약을 나란히 비교합니다.

새 오류가 생겼다면 변경을 성공으로 기록하지 않습니다. 되돌리기 조건을 적용하고 원래 진단 결과와 함께 남깁니다.

그대로 복사해 쓸 진단 검토 프롬프트

목표: codex doctor 결과를 근거로 현재 Codex CLI 설치에서 추가 확인이 필요한 영역만 분류한다.
허용 입력: codex --version 출력, codex doctor --help 출력, codex doctor --summary --no-color 결과, 사람이 검토한 codex doctor --json 결과.
제외 입력: API 키, access token, 비밀번호, 원문 auth 파일, 고객 데이터, 저장소 소스, 공개 승인이 없는 사용자 경로·조직 정보.
출력 형식: 관찰된 상태 | 근거 줄 | 다음 확인 | 담당자 | 승인 필요 여부의 5개 열로 작성한다.
완료 기준: 보고서에 실제로 나온 확인 항목을 분류한다. 업데이트·설정 변경·인증 삭제·네트워크 변경은 실행하지 않은 상태다.
추정 금지: 출력에 없는 원인, 플랜·계정 제공 조건, 최소 버전, 자동 수리 결과, 정상 작동 보증을 만들어 내지 않는다.
승인 지점: config.toml 수정, 로그인 재설정, 업데이트, 프록시·인증서 변경, 외부 지원 제출은 담당자가 근거와 되돌리기 방법을 확인한 뒤 승인한다.

실전 활용 팁

주의할 점

자주 묻는 질문

출처

마무리

Codex CLI가 이상할 때는 바로 설정을 지우거나 재설치하기보다 codex doctor --help 와 요약 보고서로 현재 상태를 먼저 기록합니다. 확인할 그룹과 근거 줄을 분리하면 후속 조치의 범위도 좁아집니다.

첫 실행은 진단과 분류에서 멈춥니다. 업데이트, 설정 수정, 인증 재설정, 네트워크 변경은 원인과 되돌리기 방법을 검토한 뒤 별도로 승인합니다.