AI how-to notes · 2026-09-17 · last run 2026-09-17 · 한국어 원문

Reading codex doctor output — ✓, ⚠, ✗ and --summary / --json measured on Windows (Codex CLI)

One line summary

codex doctor checks your install, configuration, login and network in one pass. On our PC (0.153.4) the last line read 23 ok · 1 idle · 2 notes · 0 warn · 0 fail ok and the exit code was 0. Running it against an empty CODEX_HOME with no credentials produced ✗ auth and ⚠ websocket, and flipped the exit code to 1.

Who this is for

Anyone whose Codex CLI is misbehaving with no obvious place to start. Anyone struggling to pick the problem line out of the long codex doctor output. Anyone who wants the diagnosis in a form a script can read.

Test environment

Start with the options

codex doctor --help describes it as "Diagnose local Codex installation, config, auth, and runtime health". The options that change the output shape:

      --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

It also documents -c key=value, --enable and --disable for changing settings and feature flags for that run only (we did not use them).

Step 1 — get the shape with --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

(The ... marks what we trimmed for this note. The real output also has runtime, install, search, git, terminal, title, state and threads rows, plus Desktop App and Updates.)

The sections came in this order: Notes, Environment, Configuration, Desktop App, Updates, Connectivity, Background Server. Notes at the top collects new-version announcements. Here that was two lines — a new CLI 0.154.0 and a new desktop app build — which is what 2 notes on the last line refers to.

What each row means

The English phrase after the symbol is the verdict. Here are the rows from our output, quoted as printed (detail values come from the run without --summary).

○ is what the 1 idle on the last line counts. It marks the background server as not up, and it isn't counted as a warning or a failure. reachability was judged reachable on an HTTP 405 too.

The detail values on the auth row were the storage mode (File), the credentials file path (C:\Users\User\.codex\auth.json), the login method (chatgpt), and whether an API key, ChatGPT tokens and an agent identity are stored (stored ChatGPT tokens true and so on). No email address or account ID appeared in our output.

Step 2 — what it looks like when something is wrong

Our healthy PC produced no warnings at all, so we manufactured a no-credentials state by pointing CODEX_HOME at an empty temp folder. The user's ~/.codex was left out of it.

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

Three things changed.

1. The failure (✗) and warning (⚠) rows stayed in their original sections and also climbed into the Notes section under the update announcements. 4 notes is the two update announcements plus these two rows. Whatever follows - on each row is the suggested fix.
2. The last word changed from ok to failed, and the exit code was 1. The healthy run was 0.
3. The detail values behind the websocket warning included http 401 Unauthorized and Missing bearer or basic authentication in header. The message told us to check the network side (proxy, VPN, firewall), but in this case the cause was the missing credentials. When an auth failure is sitting next to it, that seems like the right place to look first.

The first line, WARNING: ... Refusing to create helper binaries under temporary dir, appeared because we put CODEX_HOME under a temp folder. It prints separately from the diagnostic rows, and the emptyhome folder was still empty after the run.

Step 3 — taking it as --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
    }
  }
}

(We kept one of the 24 checks and only part of details.)

Exactly as --help says with "redacted", the list of enabled feature flags came out as "<redacted>", and the tail of the connection address was <redacted> too. Local paths like C:\Users\... were still in there, though, so give the user folder name a second look before sending this to anyone.

The empty-CODEX_HOME run had overallStatus as "fail", and the problem entries came out like this.

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."

The entry that shows up as ○ app-server in the human output is app_server.status in JSON, with "status": "ok" and "summary": "background server is not running". For a scripted verdict, read overallStatus and the exit code.

Worth knowing — --ascii

The console code page was 949, and in this round ✓ and ↑ were not garbled. If your window mangles the symbols, try --ascii. The same rows turn into this.

   [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

Results

What failed

We could not produce a warning or failure in a real working environment. The empty CODEX_HOME was missing not only credentials but config.toml as well (in JSON: "missing", model <default>, 0 MCP servers, no rollout/state DB inventory to compare). We did not reproduce low disk space, a syntax error in the config file, or a proxy problem.

What we did not test

• The long lists expanded by --all, and diagnostics run with -c, --enable or --disable.
• What actually changes if you take the update announcement (0.154.0 available) and update. We avoided it so as not to alter the installation.
• API key login, and the output on WSL, macOS or Linux.
• How the config and mcp rows look with a broken config file or a broken MCP server.
• The official documentation on codex doctor (this round we looked only at the help text and the real output).

Related notes

• Checking Codex CLI login status
• Checking and updating the Codex CLI version
• Installing Codex CLI on Windows
• Adding an MCP server to Codex CLI config.toml