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é provider 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 el contrato antes de instalar nada más

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 workspace o de servicios cloud de ChatGPT. Una suscripción de ChatGPT tampoco paga automáticamente las llamadas de un tercero.

Si todavía no sabes qué propietario de facturación necesitas, 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 la identidad y el publisher coinciden con la ruta oficial. No te fíes solo del icono o de la palabra Codex: una extensión distinta tendrá otro sistema de settings 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 Command Palette 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 provider 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;
• un prompt, issue, captura o conversación de soporte;
• un log con headers completos.

Abre el config.toml que utiliza Codex

VS Code tiene settings 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 modelo, provider, permisos, sandbox 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 provider personal, trabaja en:

text
~/.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 provider personalizado con valores exactos

El siguiente bloque es un mapa de relaciones, no un servicio listo para usar. Sustituye el host, la variable y el ID por los valores documentados por tu provider:

toml
# ~/.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 provider custom.
• 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 contrato necesario.

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

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

En PowerShell para la sesión actual:

powershell
$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 providers 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

OpenAI-compatible puede significar que un endpoint acepta un JSON parecido. No garantiza streaming, tool calls, modelos, reasoning metadata, web search, errores ni límites compatibles con un agente Codex.

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

1. Base URL y wire API documentados.
2. Permiso de la credencial para el model ID exacto.
3. Respuesta normal y stream completo.
4. Tool calls requeridas por la tarea.
5. Propietario de cuotas, billing, retención e incidencias.

Que TOML se pueda parsear 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:

bash
git status --short

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

text
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:

bash
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 el diff queda dentro del alcance con el test/check aprobado. Si falta uno, conserva ese límite en vez de declarar toda la configuración correcta.

Devuelve cada error a su primera capa

Si el archivo se carga pero otra capa gana o el provider 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 extension, método de auth, provider ID, hostname, model ID, texto del error, alcance del diff y comando de prueba. Esa evidencia permite detectar qué owner cambió después de una actualización sin volver a instalar ni reconfigurar todo a ciegas.