Error 401 de Codex CLI: corrige la ruta de autenticación adecuada

Un 401 de Codex CLI significa que el servidor que gestiona la solicitud rechazó la autenticación. La comprobación útil más rápida combina el host de destino, el proveedor seleccionado y el origen de la credencial. Una variable de entorno vacía es una posibilidad, pero no explica todos los 401. Sigue la rama que corresponda a tu configuración.

Primero identifica qué conexión falló

Guarda el estado, el texto del error, la marca de tiempo y el ID de solicitud cuando estén disponibles. Elimina las cabeceras de autorización, las claves y los tokens antes de compartir los detalles. No pegues auth.json en un ticket de soporte: puede contener credenciales. Un error de una integración no demuestra que la conexión con el modelo esté rota.

1. Comprueba la CLI y el método de inicio de sesión

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

Ejecuta las comprobaciones en el mismo terminal que inicia Codex. Sustituye el nombre de la variable en la comprobación de presencia si tu proveedor usa una diferente env_key. «Establecida» solo confirma que existe un valor; no demuestra que el valor sea actual o que el destino lo acepte.

Para un inicio de sesión personal de ChatGPT que haya dejado de renovarse, usa codex logout seguido de codex login y completa el flujo del navegador para la cuenta prevista. Esto cambia el estado de inicio de sesión almacenado; no es un paso necesario para todos los errores de proveedores personalizados. En automatizaciones administradas, sigue el método de autenticación del administrador. Consulta la guía oficial de autenticación.

2. Relaciona una clave de API con su emisor y destino

Una clave de OpenAI Platform pertenece a la ruta de la API de OpenAI. Una clave de Kunavo pertenece a la ruta de Kunavo. Un inicio de sesión correcto en el navegador de ChatGPT no valida una clave de puerta de enlace, y el saldo de una puerta de enlace no es un saldo de OpenAI Platform. Comprueba el host real en el error antes de sustituir nada.

En el panel del emisor, confirma que la clave aún existe y está activa. Comprueba el proyecto asociado y cualquier restricción de acceso. La referencia de errores de la API de OpenAI incluye credenciales no válidas, pertenencia a organizaciones y fallos de listas de IP permitidas entre los errores de autenticación. Usa el mensaje adjunto para elegir la corrección; crear claves repetidamente no repara una cuenta ni una política de red.

3. Comprueba la configuración del proveedor que usa Codex

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

El model_provider seleccionado debe coincidir con el bloque del proveedor. El campo env_key indica el nombre de la variable; no contiene el secreto. Verifica la configuración activa y cualquier anulación de perfil o de línea de comandos, y reinicia Codex después de corregirla. Evita copiar un bloque de proveedor no relacionado sobre tu configuración funcional.

La referencia de configuración de OpenAI documenta el protocolo Responses. Una URL base que termina en /v1 es diferente de una URL de solicitud completa /v1/responses. Una ruta incorrecta suele requerir un diagnóstico del endpoint incluso después de que la autenticación funcione. Comprueba también requires_openai_auth: cuando está habilitado, la autenticación de OpenAI tiene prioridad sobre env_key, como se describe en la guía de autenticación.

4. Cambia una sola cosa y vuelve a intentar una tarea pequeña

1. Conserva los detalles del error e identifica la ruta seleccionada.
2. Corrige el inicio de sesión, la credencial o el campo del proveedor que indiquen las pruebas.
3. Reinicia el proceso de la CLI o del editor afectado para que reciba la nueva configuración.
4. Ejecuta una solicitud pequeña antes de reiniciar una tarea de programación larga.
5. Si el fallo persiste, envía al proveedor un error redactado y el ID de solicitud, no la credencial.

Un 429 posterior, una advertencia de saldo o un error de modelo inexistente constituyen una nueva rama de diagnóstico. Conserva la corrección de autenticación y aborda el siguiente problema en lugar de deshacer toda la configuración. La guía de límites de Codex separa esos casos. Para una configuración de Kunavo, usa la integración completa de Codex y administra las claves en tu panel.

Preguntas frecuentes

Documentación oficial y ayuda local de la CLI comprobadas el 17 de septiembre de 2026. No es necesario compartir ninguna credencial para realizar estas comprobaciones.