Codex CLI con un proveedor personalizado: config.toml, modelos GPT y Claude, extensión para IDE y soluciones

Codex lee un único archivo, ~/.codex/config.toml, compartido por la CLI, codex exec y la extensión para IDE. Un proveedor personalizado en ese archivo dirige Codex a esta pasarela, donde la misma configuración ejecuta modelos GPT y modelos Claude. Las versiones actuales de Codex solo utilizan Responses API (wire_api = "responses"), por lo que las guías antiguas que usan wire_api = "chat" ya no funcionan.

Instalar Codex

# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# or with a package manager
npm install -g @openai/codex
brew install --cask codex

codex --version

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

La extensión de Codex para VS Code, Cursor y Windsurf se instala desde el mercado de extensiones del editor y usa el mismo ~/.codex/config.toml que la CLI, así que todo lo que se indica a continuación se aplica a ambos.

Usa una clave del grupo adecuado

Cada clave de la pasarela pertenece a un grupo, y ese grupo determina a qué modelos puede llamar la clave. Para los modelos GPT, crea la clave en el grupo **Codex** del panel de control. Para los modelos Claude, sirve cualquier clave de Claude de pago por uso. Una clave de un grupo Unlimited necesita un plan activo; sin él, todas las solicitudes fallan con No active subscription found for this group.

export AIPRIME_CODEX_KEY=key_from_the_codex_group    # GPT models
export AIPRIME_CLAUDE_KEY=key_from_a_claude_group    # Claude models

setx AIPRIME_CODEX_KEY "key_from_the_codex_group"
setx AIPRIME_CLAUDE_KEY "key_from_a_claude_group"
# open a new terminal afterwards

config.toml para modelos GPT

model_provider = "aiprime"
model = "gpt-6-astra"
model_reasoning_effort = "high"

[model_providers.aiprime]
name = "AI Prime Tech"
base_url = "https://aiprimetech.io/v1"
env_key = "AIPRIME_CODEX_KEY"
wire_api = "responses"
supports_websockets = false

Ejecutar Codex con modelos Claude

La pasarela acepta solicitudes de Responses API para modelos Claude y las traduce, de modo que Codex también puede utilizar Claude. Añade un segundo proveedor que use tu clave de Claude y, después, un perfil para cambiar a él.

[model_providers.aiprime_claude]
name = "AI Prime Tech (Claude)"
base_url = "https://aiprimetech.io/v1"
env_key = "AIPRIME_CLAUDE_KEY"
wire_api = "responses"
supports_websockets = false

model_provider = "aiprime_claude"
model = "claude-sonnet-5"
model_reasoning_effort = "high"

codex --profile claude
codex exec --profile claude "review the last commit for bugs"

Desde Codex 0.134.0, cada perfil tiene su propio archivo, ~/.codex/<name>.config.toml, con sus claves en el nivel superior; [profiles.<name>] las tablas dentro de config.toml ya no se leen. Los perfiles y los proveedores solo pueden definirse en tu configuración de usuario: el archivo de un proyecto .codex/config.toml ignora model_provider y model_providers.

Modelos y esfuerzo de razonamiento

model_reasoning_effort acepta low, medium, high, xhigh o max, según el modelo. No establezcas none: estos modelos lo rechazan con 'none' is not supported. review_model establece un modelo diferente para /review si quieres usar uno. El panel de control muestra todos los modelos a los que puede llamar el grupo de tu clave.

Extensión para IDE y codex exec

La extensión para IDE lee el mismo config.toml, pero env_key se resuelve a partir del entorno del propio editor. Un editor iniciado desde el Dock o el menú Inicio no ve las variables exportadas en .bashrc, y entonces Codex falla con Invalid API key mientras que la CLI funciona. Configura la variable a nivel de sistema (en Windows, setx lo hace), o inicia el editor desde una terminal, por ejemplo, code ..

codex exec ejecuta una tarea sin la interfaz interactiva, lo que resulta adecuado para scripts y CI. Usa la misma configuración y los mismos perfiles:

codex exec "write unit tests for utils.py"
codex exec --profile claude "summarise the changes on this branch"
codex login status        # which authentication method is active

Reintentos y tiempos de espera

Cada proveedor tiene sus propios ajustes de reintentos y streaming. Los valores predeterminados son 4 reintentos de solicitud, 5 reconexiones del flujo y un tiempo de espera por inactividad de 5 minutos por flujo. Los turnos de razonamiento largos pueden pasar un tiempo sin emitir datos, por lo que aumentar el tiempo de espera por inactividad ayuda con niveles de esfuerzo altos.

[model_providers.aiprime]
# ...settings from above...
request_max_retries = 6
stream_max_retries = 8
stream_idle_timeout_ms = 600000

Solución de problemas: errores que encuentran los usuarios de Codex

Los siguientes errores son los que realmente generan los clientes de Codex en esta pasarela, ordenados del más habitual al menos habitual.

¿Estás comparando Codex con Claude Code antes de elegir uno? Consulta Claude Code frente a Codex.

Preguntas frecuentes

AI Prime Tech es una pasarela de API independiente. No está afiliada a Anthropic, no cuenta con su respaldo ni es un distribuidor de Anthropic. Claude y los nombres de los modelos relacionados son marcas comerciales de sus respectivos propietarios.