Last updated August 7, 2026

Codex Router doctor — Diagnose & Fix Install Issues

The doctor command is the single most useful tool in Codex Router. It checks every layer of the integration — config, credentials, catalog, service and routing health — and reports each one as OK, WARN or FAIL, with a targeted fix under every failed layer.

Run the doctor

./bin/model-router codex doctor

On Windows:

./codex-router.ps1 codex doctor

The doctor never prints credential values. Diagnostics report credential presence and source only.

What the doctor checks

The integration is healthy when all of these layers report OK:

Core config — the marked managed block in your Codex config.toml, including the loopback base URL and the catalog path.
Config privacy — the config and its backups are protected for the current user.
Catalog — the merged model_catalog_json is present and matches the installed Codex build.
Caller capability — the generated /_codex-router/.../v1 path is valid local authentication.
Internal key — the random loopback service key exists with protected permissions.
Service — the per-user background service (launchd, systemd or Task Scheduler) is running with the expected identity.
Router health — every local listener on ports 4100–4103 reports its expected service identity.
Selected credentials — the providers you selected have a stored key or valid OAuth session. Unselected credentials may report WARN and are fine.

Repair with doctor —fix

To rebuild only repository-managed files, config and service state:

./bin/model-router codex doctor --fix

--fix rebuilds the Node and Python dependencies unconditionally — unlike a normal install or update, which skips whichever dependency step already matches its fingerprint. This makes it the right tool when an environment looks corrupted rather than merely out of date.

For a recognized older Kimi router:

./bin/model-router codex doctor --fix --migrate-known

Repair refuses unknown router owners. If the doctor ever reports a state ownership failure, you are running from a clone that did not perform the install — repair through the checkout that owns the installed state. See state ownership below.

State ownership

When the recorded state owner still exists, doctor --fix runs the repair from that checkout and keeps the installed checkout unchanged. It deliberately transfers ownership to the current checkout only when the recorded owner is gone, or when you set:

MODEL_ROUTER_ALLOW_FOREIGN_STATE=1 ./bin/model-router codex doctor --fix

To inspect the recorded owner:

STATE_DIR="${MODEL_ROUTER_STATE_DIR:-${CODEX_ROUTER_STATE_DIR:-${HOME}/.codex/codex-router}}"
cat "$STATE_DIR/install-manifest.json" | sed -n '1,80p'

After the doctor passes

Run the doctor after any update or rollback, then fully quit Codex, reopen it, and create a new task so the picker reloads the merged catalog. If a layer still fails after --fix, create a support bundle:

./bin/support-bundle

The bundle is a mode-600 JSON with versions, doctor checks, service state, provider presence, config ownership and file metadata — no credential values, prompts, responses or log contents. Share its path when you open an issue, and use --include-logs only when log context is genuinely necessary.