Preserve the evidence first
Record the surface, host, version, working directory, request time, and original error. Redact keys and sensitive identifiers. Change one setting at a time and repeat the same small task so that a successful result has an explainable cause.
codex --version
codex login status
printf '%s\n' "${CODEX_HOME:-$HOME/.codex}"Locate the failing layer
| Symptom | First checks | Avoid this assumption |
|---|---|---|
| TOML startup error | Quoting, duplicate keys, tables, supported version | It proves nothing about the key |
| 401 / 403 | Credentials, process environment, server permissions | The key must simply be expired |
| 404 | Actual path, Base URL, Responses support | Adding another /v1 will fix it |
| Unknown model | Exact ID and provider authorization | Display names are API IDs |
| Stale model | Overrides and existing processes | Saving forces a running session to reload |
| Denied command | Sandbox, approvals, managed requirements | The model API must be broken |
For 401, examine authentication and routing together
Distinguish cached official authentication from a custom provider’s env_key. Check login status and storage for the former, and process-visible variables for the latter. A third-party key sent to an official endpoint is a routing error as well as an authentication failure. A 403 can involve account or model access; inspect the actual response.
For 404, find the actual request path
Use provider logs or redacted diagnostics to identify the endpoint. Confirm the Base URL prefix and Responses support. Current wire_api supports responses only; a working Chat Completions endpoint is not sufficient. If the provider sees no request, investigate DNS, proxies, and connection failures before blaming the model.
Compare the Client and CLI systematically
- Confirm the execution host and CODEX_HOME on both sides.
- Check CLI flags, selected profiles, and trusted project overrides.
- Verify that the graphical process can access required variables; a terminal export is not proof.
- Fully restart and create a new session, then verify the new request in upstream logs.
Share a minimal redacted reproduction
Surface and version:
Operating system; local or remote:
Working directory and CODEX_HOME (redacted):
Expected model and provider:
Actual error and time:
Configuration layers checked:
Smallest reproduction steps:
Results before and after the change:Do not include a real key, full auth.json, or an entire chat transcript. Preserve field structure while redacting secrets. Validate a small task before returning to a long conversation. Be specific about what remains unknown: “authentication works; the route is not yet confirmed” is actionable.
Continue with credentials, provider routing, configuration precedence, or the interactive error doctor.
Sources and version notes
Based on the official documentation below. Replace example URLs, models, and paths for your environment. Older versions and managed environments may differ.
Sources checked：