Codex en VS Code: clave API, modelos externos y prueba final

Configurar Codex en VS Code no consiste en pegar una clave en el primer campo que contenga “API”. La extensión, la autenticación y el proveedor del modelo son capas distintas. Incluso pueden pertenecer a tres empresas diferentes.

Una configuración útil debe responder, sin mostrar ningún secreto, a estas preguntas: ¿es la extensión oficial?, ¿la sesión pertenece a ChatGPT o a un proyecto de OpenAI Platform?, ¿qué proveedor y modelo están activos?, ¿el endpoint soporta las capacidades necesarias?, ¿el cambio final aparece en un diff limitado y supera la comprobación del proyecto?

Elige cómo acceder y quién facturará el uso

La documentación oficial de autenticación separa el acceso con ChatGPT del acceso con clave API. Una clave de Platform se factura a tarifas estándar de API y puede no ofrecer funciones que dependan del espacio de trabajo o de servicios en la nube de ChatGPT. Una suscripción de ChatGPT tampoco paga automáticamente las llamadas de un tercero.

Si todavía no sabes qué cuenta debe pagar el uso, consulta primero Codex con clave API o suscripción.

Instala la extensión oficial y confirma la barra lateral

Abre la página oficial de Codex para IDE y sigue su enlace para Visual Studio Code. Comprueba en Marketplace que el nombre de la extensión y su editor coinciden con los del enlace oficial. No te fíes solo del icono o de la palabra Codex: una extensión distinta tendrá otro sistema de ajustes y otro tratamiento de credenciales.

Después de instalarla:

1. Abre un repositorio Git que conozcas y que puedas usar para una prueba pequeña.
2. Selecciona el icono de Codex en la barra de actividad.
3. Si no aparece, abre la paleta de comandos y ejecuta Codex: Open Codex Sidebar.
4. Confirma que puedes iniciar una conversación desde la barra lateral.

Este resultado solo prueba que VS Code cargó la extensión. Aún no prueba el acceso a la cuenta, el contexto del proyecto ni el modelo activo.

Inicia sesión sin confundir las dos claves

En la pantalla sin autenticar puedes elegir Sign in with ChatGPT o Use API Key. Para la segunda opción, usa una clave creada en un proyecto de OpenAI Platform que tú controles.

Si la extensión ya tiene otra sesión, revisa el método en el menú de perfil y usa Log out antes de cambiar. No vacíes ~/.codex/auth.json como paso normal. El CLI y la extensión comparten la caché de acceso; borrar el archivo oculta el estado original y convierte un cambio sencillo en un problema de credenciales.

Una clave de OpenAI y una clave de un proveedor externo no son intercambiables. Cada una autentica ante su propio servicio. Nunca guardes ninguna de ellas en:

• el código o un archivo que pueda entrar en Git;
• config.toml como texto literal;
• una instrucción, incidencia, captura o conversación de soporte;
• un registro con cabeceras completas.

Abre el config.toml que utiliza Codex

VS Code tiene ajustes propios, pero el agente Codex lee su configuración de config.toml. La distinción es concreta:

• las opciones chatgpt.* controlan el comportamiento de la extensión dentro del editor;
• config.toml controla el modelo, el proveedor, los permisos, el aislamiento y otras opciones del agente.

Según los fundamentos de configuración de Codex, el CLI y la extensión IDE comparten las mismas capas. En la barra lateral, selecciona el engranaje y después Codex Settings > Open config.toml.

Para un proveedor personal, trabaja en:

~/.codex/config.toml

No copies un bloque de Continue, Cline o CodeGPT a settings.json y asumas que Codex lo leerá. Campos como extension.provider o extension.apiBaseUrl pertenecen a la extensión que los define. Tampoco guardes un endpoint privado en .codex/config.toml del repositorio: abrir un proyecto no debería redirigir silenciosamente el tráfico del desarrollador.

Declara un proveedor personalizado con valores exactos

El siguiente bloque muestra cómo se relacionan los campos, no un servicio listo para usar. Sustituye el host, la variable y el ID por los valores documentados por tu proveedor:

# ~/.codex/config.toml
model = "EXACT_MODEL_ID"
model_provider = "work_gateway"

[model_providers.work_gateway]
name = "Work gateway"
base_url = "https://gateway.example.com/v1"
env_key = "WORK_GATEWAY_API_KEY"
wire_api = "responses"

Revísalo campo por campo:

• model_provider debe coincidir exactamente con work_gateway.
• No reutilices los IDs integrados reservados openai, ollama o lmstudio para un proveedor personalizado.
• base_url es la raíz de API documentada, no la página web del panel.
• env_key contiene el nombre de una variable de entorno, no el valor secreto.
• model es el ID exacto que expone esa API, no un nombre comercial aproximado.
• wire_api = "responses" exige que el endpoint implemente realmente el protocolo necesario.

En una terminal de macOS o Linux, una prueba temporal puede iniciar VS Code desde el mismo entorno:

export WORK_GATEWAY_API_KEY="<provider-key>"
code .

En PowerShell para la sesión actual:

$env:WORK_GATEWAY_API_KEY = "<provider-key>"
code .

Una ventana abierta desde Dock, menú Inicio, WSL, Remote SSH o un dev container puede heredar variables diferentes. Ante un 401, comprueba el entorno del proceso que ejecuta Codex antes de rotar la clave. No necesitas imprimir su valor.

La configuración avanzada de proveedores también contempla autenticación OpenAI, comandos que obtienen tokens y servicios locales sin autenticación. Elige un único método coherente con el servicio para que los errores sigan siendo atribuibles.

Verifica “compatible” por capacidad, no por etiqueta

«Compatible con OpenAI» puede significar que un endpoint acepta un JSON parecido. No garantiza compatibilidad con la transmisión de respuestas, las llamadas a herramientas, los metadatos de razonamiento, la búsqueda web ni los errores y límites que debe gestionar Codex.

Antes de delegar una refactorización grande, confirma por separado:

1. URL base y protocolo documentados.
2. Permiso de la credencial para el identificador exacto del modelo.
3. Respuesta normal y transmisión completa.
4. Llamadas a herramientas requeridas por la tarea.
5. Servicio responsable de cuotas, facturación, retención e incidencias.

Que TOML se pueda analizar solo demuestra la forma del archivo. Que funcione un chat solo demuestra una ruta de texto. Ninguna prueba permite afirmar que todas las funciones son compatibles.

Haz una primera edición que puedas rechazar

Elige una función cuyo comportamiento entiendas. Registra el estado inicial:

git status --short

Abre el archivo, selecciona esa función y limita la petición:

Revisa únicamente la función parseConfig seleccionada.
Una cadena vacía debe devolver el tipo de error existente.
No cambies la API pública, otros archivos ni dependencias.
Muestra el cambio previsto e indica la prueba existente que debo ejecutar.

Cuando termine, revisa el diff real:

git diff -- path/to/file
git status --short

La prueba completa tiene cuatro resultados distintos: no aparece un error de autenticación, no aparece un error de endpoint/modelo, la respuesta usa nombres reales del código seleccionado y los cambios quedan dentro del alcance y superan la prueba del proyecto. Si falta uno, conserva ese límite en vez de declarar toda la configuración correcta.

Localiza qué componente causa el error

Si el archivo se carga pero otro archivo tiene prioridad o el proveedor no se activa, continúa con Codex config.toml no funciona. Separa siempre un fallo de carga de configuración de un fallo posterior del endpoint.

Guarda finalmente un registro sin secretos: versiones de VS Code y de la extensión, método de autenticación, identificador del proveedor, dominio del servicio e identificador del modelo, texto del error, alcance del diff y comando de prueba. Esa evidencia permite detectar qué componente cambió después de una actualización sin volver a instalar ni reconfigurar todo a ciegas.