AI 해결 노트 · 2026-09-17 · 실측 2026-09-17

Codex CLI codex doctor 진단 결과 읽는 법 — ✓·⚠·✗와 --summary·--json 윈도우 실측

한 줄로

codex doctor는 설치·설정·로그인·네트워크 상태를 한 번에 점검하는 명령입니다. 저희 PC(0.153.4)에서는 마지막 줄 23 ok · 1 idle · 2 notes · 0 warn · 0 fail ok와 종료 코드 0이 나왔습니다. 로그인 정보가 없는 빈 CODEX_HOME으로 돌리자 ✗ auth와 ⚠ websocket이 뜨고 종료 코드가 1로 바뀌었습니다.

이런 분께

Codex CLI가 이상하게 동작하는데 어디부터 볼지 모르는 분. codex doctor 출력이 길어서 어떤 줄이 문제인지 가려내기 어려운 분. 진단 결과를 스크립트로 받아 보고 싶은 분.

실측 환경

옵션부터 보기

codex doctor --help의 설명은 "Diagnose local Codex installation, config, auth, and runtime health"입니다. 출력 모양을 바꾸는 옵션은 이렇습니다.

      --json
          Emit a redacted machine-readable report
      --summary
          Only show grouped check rows and the final count summary
      --all
          Expand long lists in detailed human output
      --no-color
          Disable ANSI color in human output
      --ascii
          Use ASCII status labels and separators in human output

그 밖에 -c key=value, --enable, --disable로 설정값과 기능 플래그를 그 실행에만 바꿔 진단할 수 있다고 적혀 있습니다(이번에는 쓰지 않음).

1단계 — --summary로 전체 모양 보기

codex doctor --summary --no-color

Codex Doctor v0.153.4 · windows-x86_64

Notes
   ↑ updates      0.154.0 available (current 0.153.4)
   ↑ desktop      build 26.911.7940.0 available
─────────────────────────────────────────────────────────────

Environment
  ✓ system       ko-KR
  ✓ disk         sufficient free disk space (23.0 GiB)
  ...
Configuration
  ✓ config       loaded
  ✓ auth         auth is configured
  ✓ mcp          1 server (1 stdio) · 0 disabled
  ✓ sandbox      restricted fs + restricted network · approval OnRequest
  ...
Connectivity
  ✓ network      no proxy env vars
  ✓ websocket    connected (HTTP 101 Switching Protocols) · 15s timeout
  ✓ reachability active provider endpoints are reachable over HTTP

Background Server
  ○ app-server   not running (ephemeral mode)

─────────────────────────────────────────────────────────────
23 ok · 1 idle · 2 notes · 0 warn · 0 fail ok

(...은 글에서 줄인 부분입니다. 원래 출력에는 runtime·install·search·git·terminal·title·state·threads, Desktop App, Updates 줄이 더 있습니다.)

구획은 Notes, Environment, Configuration, Desktop App, Updates, Connectivity, Background Server 순서로 나왔습니다. 맨 위 Notes에는 새 버전 알림이 모입니다. 이번에는 CLI 0.154.0과 데스크톱 앱 새 빌드가 있다는 알림 두 줄이었고, 마지막 줄의 2 notes가 이것입니다.

줄마다 무엇을 뜻하나

기호 뒤의 영어 문구가 판정 내용입니다. 저희 출력에 나온 줄을 문구 그대로 옮기면 이렇습니다(자세한 값은 --summary 없이 돌린 출력 기준).

○는 마지막 줄의 1 idle에 해당합니다. 백그라운드 서버가 떠 있지 않다는 표시였고, 경고나 실패로 세지 않았습니다. reachability의 HTTP 405도 reachable로 판정됐습니다.

auth 줄의 자세한 값은 저장 방식(File), 인증 파일 경로(C:\Users\User\.codex\auth.json), 로그인 방식(chatgpt), API 키·ChatGPT 토큰·agent identity 저장 여부(stored ChatGPT tokens true 등)였습니다. 저희 출력에서는 이메일이나 계정 ID가 나오지 않았습니다.

2단계 — 문제가 있을 때의 모양

정상 PC에서는 경고가 하나도 없었습니다. 그래서 빈 임시 폴더를 CODEX_HOME으로 지정해 로그인 정보가 없는 상태를 만들었습니다. 사용자 ~/.codex는 쓰지 않았습니다.

CODEX_HOME="C:\Users\User\AppData\Local\Temp\longtail_B2\emptyhome" codex doctor --summary --no-color

WARNING: proceeding, even though we could not create PATH aliases: Refusing to create helper binaries under temporary dir "C:\\Users\\User\\AppData\\Local\\Temp\\" ...
Codex Doctor v0.153.4 · windows-x86_64

Notes
   ↑ updates      0.154.0 available (current 0.153.4)
   ↑ desktop      build 26.911.7940.0 available
   ✗ auth         no Codex credentials were found - Run codex login or provide an API key through a supported auth env var.
   ⚠ websocket    Responses WebSocket failed; HTTPS fallback may still work - Check proxy, VPN, firewall, DNS, custom CA, and WebSocket policy support.
...
21 ok · 1 idle · 4 notes · 1 warn · 1 fail failed

바뀐 점은 세 가지였습니다.

1. 실패(✗)와 경고(⚠) 줄이 원래 구획에도 남고, 업데이트 알림 아래 Notes 구획에도 올라왔습니다. 4 notes는 업데이트 알림 2개에 이 두 줄을 더한 수입니다. 각 줄의 - 뒤가 고치는 방법 안내입니다.
2. 마지막 단어가 ok에서 failed로 바뀌었고, 종료 코드가 1이었습니다. 정상 실행은 0이었습니다.
3. websocket 경고의 자세한 값에는 http 401 Unauthorized와 Missing bearer or basic authentication in header가 들어 있었습니다. 문구는 네트워크 쪽(proxy, VPN, firewall)을 점검하라고 안내했지만, 이번 경우의 원인은 로그인 정보가 없는 것이었습니다. auth 실패가 함께 떠 있으면 그것부터 보는 편이 맞아 보입니다.

맨 첫 줄 WARNING: ... Refusing to create helper binaries under temporary dir는 CODEX_HOME을 임시 폴더 아래에 둔 탓에 나온 문구입니다. 진단 항목과는 따로 찍혔고, 실행 뒤 emptyhome 폴더는 비어 있었습니다.

3단계 — --json으로 받기

codex doctor --json

{
  "schemaVersion": 1,
  "generatedAt": "1789636091s since unix epoch",
  "overallStatus": "ok",
  "codexVersion": "0.153.4",
  "checks": {
    "auth.credentials": {
      "id": "auth.credentials",
      "category": "auth",
      "status": "ok",
      "summary": "auth is configured",
      "details": { "auth storage mode": "File", "stored API key": "false", "...": "..." },
      "remediation": null,
      "durationMs": 0
    }
  }
}

(checks는 24개 중 하나만, details는 일부만 남겼습니다.)

--help가 "redacted"라고 적은 대로 켜진 기능 플래그 목록은 "<redacted>"로 나왔고, 접속 주소 뒷부분도 <redacted>였습니다. 다만 C:\Users\... 같은 로컬 경로는 그대로 들어 있었으니 남에게 보낼 때는 사용자 폴더 이름을 한 번 더 확인하는 편이 좋겠습니다.

빈 CODEX_HOME 실행에서는 overallStatus가 "fail"이었고, 문제 항목은 이렇게 나왔습니다.

auth.credentials                 status "fail"     remediation "Run codex login or provide an API key through a supported auth env var."
network.websocket_reachability   status "warning"  remediation "Check proxy, VPN, firewall, DNS, custom CA, and WebSocket policy support."

사람용 출력에서 ○ app-server로 보이던 항목은 JSON에서는 app_server.status, "status": "ok", "summary": "background server is not running"이었습니다. 스크립트로 판정할 때는 overallStatus와 종료 코드를 보면 됩니다.

알아 둘 것 — --ascii

콘솔 코드 페이지가 949였는데 이번 로그에서는 ✓·↑가 깨지지 않았습니다. 기호가 깨지는 창이라면 --ascii를 붙여 볼 수 있습니다. 같은 항목이 이렇게 바뀌었습니다.

   [up] updates      0.154.0 available (current 0.153.4)
  [ok] system       ko-KR
  [--] app-server   not running (ephemeral mode)
23 ok | 1 idle | 2 notes | 0 warn | 0 fail ok

결과

실패한 것

실제 사용 환경에서 경고나 실패가 나는 경우는 만들지 못했습니다. 빈 CODEX_HOME은 로그인 정보뿐 아니라 config.toml도 없는 상태였습니다(JSON에 "missing", 모델 <default>, MCP 서버 0개, no rollout/state DB inventory to compare). 디스크 부족이나 설정 파일 문법 오류, 프록시 문제는 재현하지 않았습니다.

확인하지 않은 것

• --all로 펼친 긴 목록과 -c·--enable·--disable을 붙인 진단.
• 업데이트 알림(0.154.0 available)대로 실제 업데이트했을 때의 변화. 설치본을 바꾸지 않으려고 하지 않았습니다.
• API 키 로그인, WSL·맥·리눅스에서의 출력.
• 설정 파일 오류·MCP 서버 고장이 있을 때 config·mcp 줄의 모양.
• 공식 문서의 codex doctor 설명(이번에는 도움말과 실제 출력만 봤습니다).

함께 보기

• Codex CLI 로그인 상태 확인
• Codex CLI 버전 확인·업데이트
• Codex CLI 윈도우 설치
• codex config.toml에 MCP 서버 넣기