Codex CLI/App: proveedor propio, API Key y Base URL

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.

Ajustes principales

Campo	Valor
API Key	auth.json → OPENAI_API_KEY
Base URL	https://bettertoken.ai/v1
Model	gpt-6-astra

Requisitos previos

• Instala Node.js si usas npm o el script de configuración automática de BetterToken
• Crea una BetterToken API Key
• Copia un Model ID del model plaza o del cuadro de diálogo Setup de la Key

Regístrate y obtén una BetterToken API Key→

¿Ya tienes una cuenta? Inicia sesión, recarga el saldo y crea una clave en la consola.

Instalación

Puedes usar los instaladores oficiales independientes para macOS/Linux o Windows sin Node.js. Si prefieres npm, instala primero Node.js y ejecuta:

npm install -g @openai/codex

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 por línea de comandos

El script de configuración automática de BetterToken escribe la configuración del proveedor para Codex. Requiere Node.js y solicita la API Key o el Model ID si no se proporcionan como argumentos.

macOS / Linux

curl -fsSL "https://bettertoken.ai/install-codex-provider.sh" | bash

Windows

iwr "https://bettertoken.ai/install-codex-provider.ps1" -OutFile "$env:TEMP\install-codex-provider.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-codex-provider.ps1"

Tras la instalación, compara ambos archivos con la configuración manual siguiente y corrige las diferencias antes de iniciar Codex.

Configuración manual

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

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.

Verificar la conexión

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.

Codex CLI 0.164.0 también superó las pruebas de autenticación con variables de entorno, incluidas las llamadas a herramientas de lectura de archivos: env_key funcionó con requires_openai_auth = false y al omitir ese campo.

Cambiar de modelo

Cambia model y, de forma opcional, review_model. Guarda el archivo, detén el proceso actual de Codex y vuelve a iniciarlo. Usa el Model ID del cuadro de diálogo Setup o del model plaza.

Errores frecuentes

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.

Configuración avanzada

Extensión de Codex

CLI, App y Extension comparten configuración con el mismo CODEX_HOME. Elige autenticación según el objetivo: API Key o conservar la sesión oficial.

guía de configuración de la extensión de Codex

Preguntas relacionadas

• Usa las API directamente con ejemplos de SDK

• Diagnostica errores de la API y límites de solicitudes

• Qué es Codex CLI

• Codex CLI frente a Codex App y Codex Web

• Guía de configuración de config.toml en Codex

• Qué son model_provider, base_url y wire_api

• Qué significan review_model y reasoning_effort

• Qué es AGENTS.md y cómo debe escribirse

• Qué son los modos sandbox y approval de Codex CLI

• Cómo conservar el inicio de sesión oficial de Codex con una API de terceros

• API compatible con OpenAI frente a API compatible con Anthropic

• Claude Code frente a Codex CLI

• Administrar el proveedor de Codex con CC Switch

• Compara todas las herramientas compatibles

Referencia oficial

• Referencia de configuración de Codex
• Referencia oficial de autenticación

Detalles técnicos

Protocolo Responses

Codex usa OpenAI Responses. Configura base_url como https://bettertoken.ai/v1 y mantén wire_api = "responses". Codex añade /responses.