Codex config.toml: proveedor, Base URL y API Key

Codex CLI y Codex App comparten config.toml y auth.json para las tareas locales. Esta configuración usa una BetterToken API Key mediante OpenAI Responses.

Localiza los archivos y crea copias de seguridad

Si has definido un CODEX_HOME personalizado, edita allí config.toml y auth.json. En caso contrario, usa ~/.codex en macOS / Linux o %USERPROFILE%\.codex en Windows. CLI y App deben usar el mismo directorio. WSL tiene su propio directorio de usuario.

Cierra Codex por completo antes de editar. Guarda copias de ambos archivos en un lugar privado. Crea los archivos que falten. Sustituye los ajustes existentes sin duplicar claves ni tablas; conserva los demás ajustes.

Esta configuración cambia el inicio de sesión con ChatGPT por la autenticación con API Key. No conserva el acceso a la cuenta oficial. Protege auth.json y sus copias; no los compartas ni los incluyas en el repositorio.

Configuración mínima funcional

Edita config.toml

Esta guía usa config.toml de usuario. Coloca las claves raíz antes de todas las tablas TOML, no en [projects."<path>"]; esa tabla guarda el trust_level del proyecto. El ID del provider debe coincidir con su tabla. Para autenticación por archivo, elimina env_key y experimental_bearer_token del provider seleccionado.

model_provider = "bettertoken"
model = "gpt-6-astra"
cli_auth_credentials_store = "file"

[model_providers.bettertoken]
name = "BetterToken"
base_url = "https://bettertoken.ai/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

El ejemplo usa GPT-6 Astra (gpt-6-astra). Para otro modelo, copia su ID completo de la model plaza y sustituye model. GPT, Kimi y GLM usan la misma estructura de autenticación por archivos; la configuración automática está disponible para GPT.

Edita auth.json

auth.json está en el mismo directorio que config.toml. Si no existe auth.json, créalo en ese directorio. Usa el siguiente JSON como contenido del archivo, reemplaza YOUR_API_KEY por tu BetterToken API Key y guarda el archivo.

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "YOUR_API_KEY"
}

Parámetros de configuración

Parámetro	Función y ubicación	Valores predeterminados y ejemplos
model_provider	Raíz del archivo de usuario; selecciona el ID definido abajo.	Predeterminado: openai; aquí bettertoken.
model	Raíz; Model ID completo de la plaza de modelos.	Ejemplo: gpt-6-astra; cámbialo según necesites.
cli_auth_credentials_store	Raíz; almacén de credenciales de inicio de sesión.	Aquí file: lee auth.json del mismo directorio.
name	Tabla del provider; solo el nombre visible.	BetterToken no es un Model ID.
base_url	Tabla del provider; Base URL de la API del modelo.	Usa https://bettertoken.ai/v1; Codex añade /responses.
wire_api	Tabla del provider; protocolo de solicitud.	Actualmente solo admite responses, también predeterminado.
requires_openai_auth	Tabla del provider; autenticación OpenAI y su almacén.	Predeterminado: false; aquí true. No es un interruptor para conservar archivos de sesión.
supports_websockets	Tabla del provider; compatibilidad con Responses WebSocket.	Predeterminado: false; aquí se mantiene HTTP/SSE.
auth_mode	En auth.json; modo de autenticación.	Aquí apikey: sustituye la autenticación oficial de ChatGPT.
OPENAI_API_KEY	En auth.json; clave para autenticar la API.	Sustituye YOUR_API_KEY por BetterToken API Key.

La autenticación por archivo cambia al modo API Key. Para conservar tu cuenta oficial usa conservar el inicio de sesión; no mezcles los modos. Se distinguen por el objetivo de autenticación, no por CLI, App o Extension.

Ajustes opcionales

Si tu organización administra las credenciales con un programa auxiliar, consulta la autenticación de proveedores mediante comandos. Es una alternativa a la autenticación por archivo de este ejemplo: una tabla auth del proveedor no puede combinarse con env_key, experimental_bearer_token o requires_openai_auth. Usa el programa auxiliar y la configuración que proporcione tu administrador.

Estos tres ajustes son opcionales, no requisitos de conexión. Añádelos a la tabla existente [model_providers.bettertoken] si los necesitas; no crees otra tabla idéntica.

request_max_retries = 4
stream_max_retries = 8
stream_idle_timeout_ms = 300000

Parámetro	Función y ubicación	Valores predeterminados y ejemplos
request_max_retries	Tabla del provider; máximo de reintentos HTTP.	Predeterminado: 4; ajusta según la conexión.
stream_max_retries	Tabla del provider; reconexiones tras una interrupción del flujo.	Predeterminado: 5; 8 es un valor personalizado opcional.
stream_idle_timeout_ms	Tabla del provider; tiempo de inactividad del flujo en milisegundos.	Predeterminado: 300000; no limita la duración total de la tarea.

Capas de configuración y claves antiguas

No coloques modelos o razonamiento en [projects."<path>"]. Un modelo específico del proyecto puede usar claves raíz en .codex/config.toml de un proyecto de confianza; provider y autenticación permanecen en la configuración de usuario. Los perfiles actuales usan NAME.config.toml dentro de CODEX_HOME, elegido con codex --profile NAME, no tablas antiguas [profiles.NAME] ni el selector raíz profile.

Reinicia y verifica

Guarda ambos archivos. Inicia una nueva sesión de Codex CLI directamente desde el terminal:

codex

Cierra Codex App por completo, incluidos los procesos en segundo plano. Ábrelo de nuevo y crea una tarea local nueva. Envía una indicación breve en cada cliente que uses. Una respuesta normal verifica la conexión de ese cliente.

Solución de problemas

Ante 401, 403 o una solicitud de inicio de sesión, revisa el directorio activo, la Key de auth.json, auth_mode = apikey, cli_auth_credentials_store = file y requires_openai_auth = true. Ante errores del proveedor o modelo, comprueba el ID del proveedor, https://bettertoken.ai/v1, wire_api = responses y la disponibilidad del modelo. Si los cambios no se aplican, revisa las opciones que sobrescriben la configuración y confirma que CLI y App usan el mismo CODEX_HOME.

Documentación relacionada

• Guía completa de configuración de Codex
• Configurar una Base URL personalizada en la extensión Codex para VS Code
• Explicación de model_provider, base_url y wire_api
• Sandbox y modo de aprobación de Codex CLI
• ¿Qué es AGENTS.md?

Referencias

• Configuración básica de Codex
• Referencia de configuración de Codex