A Codex CLI 401 means authentication was rejected by the server handling the request. The quickest useful check is the combination of destination host, selected provider, and credential source. An empty environment variable is one possibility; it is not the explanation for every 401. Follow the branch that matches your setup.
First identify which connection failed
| Failure point | Likely scope | First check |
|---|---|---|
| ChatGPT sign-in or token refresh | Stored account session | Active login and intended workspace |
| Request to the OpenAI API | Platform credentials and project | Key validity and project access |
| Request to a custom gateway | That provider's configuration | Host, provider ID, and named environment variable |
| Only an MCP or external tool fails | That tool's separate login | The tool name and its authentication |
Save the status, error text, timestamp, and request ID when present. Remove authorization headers, keys, and tokens before sharing details. Do not paste auth.json into a support ticket: it may contain credentials. An error from one integration does not establish that the model connection is broken.
1. Check the CLI and login method
codex --version
codex login status
# POSIX shell: report presence only, without printing the secret
if [ -n "${KUNAVO_API_KEY:-}" ]; then
printf 'KUNAVO_API_KEY is set\n'
else
printf 'KUNAVO_API_KEY is missing or empty\n'
fiRun the checks in the same terminal that launches Codex. Replace the variable name in the presence check if your provider uses a different env_key. “Set” only confirms a value exists; it cannot prove the value is current or accepted by the destination.
For a personal ChatGPT login that has stopped refreshing, use codex logout followed by codex login, then complete the browser flow for the intended account. This changes stored login state; it is not a required step for every custom-provider error. In managed automation, follow the administrator's authentication method instead. See the official authentication guide.
2. Match an API key to its issuer and destination
An OpenAI Platform key belongs on the OpenAI API route. A Kunavo key belongs on Kunavo's route. A successful ChatGPT browser login does not validate a gateway key, and a gateway balance is not an OpenAI Platform balance. Check the actual host in the error before replacing anything.
In the issuer's dashboard, confirm that the key still exists and is active. Check the associated project and any access restrictions. The OpenAI API error reference includes invalid credentials, organization membership, and IP allowlist failures under authentication errors. Use the accompanying message to choose the correction; repeatedly creating keys does not repair an account or network policy.
3. Check the provider configuration that Codex uses
# Compare these non-secret fields with your intended provider.
model = "gpt-5-6-sol"
model_provider = "kunavo"
[model_providers.kunavo]
name = "Kunavo"
base_url = "https://api.kunavo.com/v1"
env_key = "KUNAVO_API_KEY"
wire_api = "responses"The selected model_provider must match the provider block. The env_key field names the variable; it does not contain the secret. Verify the active configuration and any profile or command-line override, then restart Codex after correcting it. Avoid copying an unrelated provider block over your working configuration.
OpenAI's configuration reference documents the Responses protocol. A base URL ending in /v1 is different from a full /v1/responses request URL. A wrong path usually needs endpoint diagnosis even after authentication succeeds. Also check requires_openai_auth: when enabled, OpenAI authentication takes precedence over env_key, as described in the authentication guide.
4. Change one thing and retry one small task
- Preserve the error details and identify the selected route.
- Correct the login, credential, or provider field that the evidence points to.
- Restart the affected CLI or editor process so it receives the new setting.
- Run a small request before restarting a long coding task.
- If the failure persists, send the provider a redacted error and request ID, not the credential.
A later 429, balance warning, or missing-model error is a new diagnostic branch. Keep the authentication fix and address that next issue rather than undoing every setting. The Codex limits guide separates those cases. For a Kunavo setup, use the complete Codex integration and manage keys in your dashboard.
FAQ
What does a Codex CLI 401 mean?
The server receiving the request rejected authentication. The cause can be a stale account session, an invalid or revoked key, a credential sent to the wrong provider, or account restrictions. Identify the destination and active authentication route before changing credentials.
Can codex login status verify a custom provider key?
It reports the CLI login state, but it does not prove that an environment-backed custom provider accepts its key. For that route, check the selected provider, its env_key variable in the launching process, and the provider's account controls.
Why does the key work in one terminal but fail in my IDE?
The processes may have different environment variables, profiles, or configuration. An editor started before a variable was set may not inherit it. Compare the selected provider and launch environment, then restart the affected process after fixing the relevant setting.
Should I delete my Codex configuration to fix authentication?
Start with the specific login or provider setting that is wrong. Deleting the entire configuration can remove unrelated settings without addressing a rejected credential. Preserve your configuration and make one targeted correction at a time.
Official documentation and local CLI help checked September 17, 2026. No credential needs to be shared to follow these checks.