Codex CLI troubleshooting: installation, authentication, configuration and connection

Log the complete error, triggering command, Codex version, operating system, working directory and time of occurrence. Don't just cut off the last line, and don't try to recall the original state after reinstalling.

The recommended order is binary and PATH, configuration resolution, authentication, provider and model, network, permissions, and extensions. Only change one variable at a time and save the results before and after the change.

command not found usually means that the installation directory is not in PATH, or the terminal is still using the old environment. Version inconsistencies are common when npm, Homebrew, and script installations coexist.

Find all codex hits before upgrading or uninstalling the old copy using the original installation channel. Don't blindly use sudo to overwrite system directories.

Duplicate TOML keys, incorrect table levels, unknown fields and the wrong CODEX_HOME can all invalidate configuration. Back up the original file, then run strict configuration validation and doctor.

If you suspect that the user configuration affects the current command, you can use --ignore-user-config for comparison; it will not load the user config.toml, but CODEX_HOME will still be used for authentication. A successful comparison does not mean that the original file should be deleted, it only means that the problem is at the user configuration level.

For 401 or 403, check credentials and server permissions first. An unknown-model error usually means the request reached the service but the model name was rejected. A 404 may indicate a base URL path error; timeouts and DNS or TLS errors belong to the network layer.

CodeNodex users should run keys or setup to validate the API key and platform before checking Codex doctor. Never troubleshoot by disabling TLS verification, printing the Authorization header or pasting a real key into a ticket.

If a command can read but not write, check the sandbox mode and working directory; use --add-dir when it needs an adjacent directory. Unavailable network tools do not necessarily indicate a provider error; a sandbox, proxy or organization policy may be responsible.

For MCP issues, verify the configuration list and individual server before inspecting local processes or remote URLs. Temporarily removing the failing server can show whether it affects startup, but remote credentials still require separate revocation.

doctor --json provides a machine-readable, redacted report, but you must still inspect it before upload. Include a minimal reproduction, expected and actual behavior, version, relevant non-secret configuration fields and whether the issue persists when user configuration is ignored.

Submit Codex issues to the official repository and CodeNodex API key, gateway or model-mapping issues to CodeNodex support. Confirm ownership first so third-party credentials never enter a public issue.