Codex CLI es el agente de programación de terminal de OpenAI: lee código, modifica archivos y ejecuta comandos. Muchos equipos quieren conectarlo a su propio gateway o a un punto de acceso compatible con OpenAI, para gestionar con una sola clave la facturación y los límites. Cuando se habla de «conectar una API personalizada», en la configuración solo hay tres puntos: dónde se envía la solicitud (Base URL), con qué credencial se autentica (clave) y qué modelo se invoca (nombre del modelo). Donde de verdad aparecen los errores es en el método de autenticación, la coincidencia de protocolos y los límites de permisos.

Este artículo toma como referencia las versiones habituales de octubre de 2026 y recorre el proceso en este orden: instalación, autenticación, configuración, verificación, sandbox y aprobaciones, despliegue en equipo y seguridad. Codex evoluciona rápido; para comandos y opciones de configuración, consulta codex --help y la documentación oficial.

Nota: OpenAI, Codex y ChatGPT son marcas comerciales o marcas registradas de OpenAI. Este artículo solo ofrece una explicación técnica de integración y no tiene relación de afiliación con OpenAI. Los requisitos de la interfaz, los identificadores de modelo y la facturación pueden cambiar según la versión; consulta la documentación oficial y los precios de modelos del sitio.

1. Confirma primero el protocolo y la autenticación

El proveedor personalizado de Codex CLI usa el protocolo Responses y, actualmente, wire_api solo acepta responses; la forma antigua chat está obsoleta y en muchas versiones produce un error directo. El gateway debe cumplir al menos dos condiciones: ofrecer un endpoint /v1/responses compatible y admitir salida en streaming con el evento de finalización response.completed. Un endpoint que solo ofrezca Chat Completions necesita una capa de conversión de protocolo; no basta con pegar la dirección.

Hay tres vías de autenticación; elige una:

Método Comando o configuración típica Caso adecuado Atención
Inicio de sesión con cuenta ChatGPT codex login Pruebas personales, uso temporal Consume la cuota de la cuenta; no sirve para CI
Inicio de sesión con API Key codex login --with-api-key (lee la clave desde stdin) Uso personal por consumo La credencial se guarda en auth.json o en el llavero del sistema
Proveedor personalizado env_key apunta a una variable de entorno Gateway de equipo, facturación unificada La clave no se escribe en TOML; facilita límites y revocación

Para ver el estado actual de la sesión usa codex login status; para borrar las credenciales locales, codex logout. Si coexisten varias credenciales, confirma primero cuál está activa antes de revisar la configuración.

2. Instala Codex CLI

Elige un método según tu sistema y confirma la versión después de instalar:

# Script de instalación oficial para macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# También puedes usar un gestor de paquetes; consulta la documentación oficial vigente
npm install -g @openai/codex
brew install --cask codex

codex --version

Para el primer arranque, usa un repositorio de prueba vacío. No experimentes en un directorio con claves de producción, datos de clientes o configuración sin anonimizar. Codex lee el contexto del directorio actual: cuanto más limpio esté, más fácil será diagnosticar.

3. Configura Base URL, clave y modelo

La configuración de usuario está en ~/.codex/config.toml; en Windows, en %USERPROFILE%\.codex\config.toml. Hay un error muy frecuente: las claves de nivel superior deben ir antes del primer encabezado de tabla. Si escribes model o model_provider después de [model_providers.xxx], se interpretan como campos de esa tabla y parece que «la configuración no surte efecto».

# ~/.codex/config.toml
model = "tu-model-id"
model_provider = "zsqh"
web_search = "disabled"

[model_providers.zsqh]
name = "ZSQH AI Gateway"
base_url = "https://ai.zhongshangqihang.com/v1"
wire_api = "responses"
env_key = "ZSQH_API_KEY"

Significado de los campos:

  • model: el identificador de la API, no el nombre que se muestra en la web; debe coincidir exactamente con la página de precios.
  • model_provider: debe coincidir con el ID del proveedor de abajo; no uses nombres reservados como openai, ollama o lmstudio.
  • base_url: incluye la ruta de la API, normalmente termina en /v1; no la concatenes dos veces.
  • wire_api: escribe responses.
  • env_key: el nombre de la variable de entorno, no la clave en sí.
  • web_search: si el gateway no admite búsqueda web, déjalo en disabled para no enviar solicitudes a una capacidad no habilitada.

Después, exporta la clave en la misma shell desde la que inicias Codex:

export ZSQH_API_KEY="sk-tu-clave"

En Windows PowerShell: $env:ZSQH_API_KEY="sk-tu-clave". Para que la variable persista, escríbela en el archivo de configuración de tu shell o en las variables del sistema, y comprueba que los editores lanzados desde la interfaz gráfica también la lean.

Si el gateway exige encabezados personalizados, puedes usar env_http_headers = { "X-API-Key" = "ZSQH_API_KEY" }; esta vía no usa el descubrimiento remoto de catálogo y requiere además un catálogo local model_catalog_json. Si la clave la emite dinámicamente una herramienta de gestión de secretos, puedes obtener el token con command dentro de [model_providers.zsqh.auth], pero no puede combinarse con env_key. Si hay muchos alias de modelos, considera model_catalog_url o un model_catalog_json local; si no lo necesitas, no añadas complejidad.

Ten en cuenta también que los proyectos de confianza cargan .codex/config.toml, pero se ignoran model_provider, model_providers y las definiciones de perfil que contenga. El proveedor debe definirse siempre en la configuración de usuario.

4. Verifica que la conexión realmente funcione

Sigue este orden para distinguir rápido entre «la herramienta está mal configurada» y «el gateway no responde»:

  1. Ejecuta codex login status para confirmar el método de autenticación; después verifica que la variable indicada por env_key no esté vacía en el entorno de arranque. No imprimas la clave completa en una terminal compartida.
  2. Ejecuta codex doctor para revisar la ubicación de los archivos de configuración, las variables de entorno y los conflictos habituales.
  3. En el repositorio de prueba ejecuta codex exec "Reply with exactly: gateway-ok"; si devuelve gateway-ok, la cadena básica funciona. codex exec usa por defecto un sandbox de solo lectura, adecuado para una prueba de humo.
  4. Entra en modo interactivo y ejecuta /status para comprobar que el modelo y el proveedor son los configurados.
  5. Consulta los registros de solicitudes en la consola del gateway para confirmar usuario, alias de modelo y ruta ascendente. Que el cliente reciba respuesta no basta: puede venir de caché o de una configuración antigua.
  6. Si sigue fallando, revisa primero las rutas /v1 y /responses de la Base URL y después si el proxy reescribe o elimina el encabezado Authorization.

5. Sandbox y aprobaciones: dos interruptores independientes

Mucha gente confunde «ejecución automática» con «qué archivos puede modificar». Codex separa ambos controles: la política de aprobación decide cuándo se detiene a preguntar, y el sandbox decide a qué archivos y a qué red puede acceder el proceso.

En las versiones actuales, el valor habitual de approval_policy es on-request, adecuado para la mayoría del desarrollo diario; never solo debería usarse en entornos automatizados aislados. El antiguo untrusted ya no es compatible y on-failure está obsoleto; copiar tutoriales antiguos suele provocar errores de configuración.

sandbox_mode tiene tres valores: read-only, workspace-write y danger-full-access. Empieza por solo lectura; cuando necesites modificar código usa workspace-write y limita los directorios escribibles con sandbox_workspace_write.writable_roots; danger-full-access solo debería aparecer en contenedores o runners de un solo uso. Si necesitas red, habilita por separado sandbox_workspace_write.network_access; no amplíes todos los permisos de golpe.

En modo no interactivo puedes especificar el sandbox con codex exec --sandbox workspace-write; si la organización permite la revisión automática, añade --approve-for-me. Ten en cuenta que --full-auto ya no es compatible: los scripts antiguos deben cambiar ese parámetro. En modo interactivo puedes ver y ajustar los permisos actuales con /permissions.

6. Despliegue en equipo: primero un piloto, luego configuración común

Se recomienda empezar con dos o tres personas y un repositorio no crítico, y extenderlo después de validarlo. Lo importante no es «cuánta gente lo instaló», sino si la configuración se puede replicar y si las fallas se pueden localizar.

  • Una clave por persona, subdividida por proyecto o entorno; no compartas una sola clave para todo el equipo.
  • Configura presupuesto, concurrencia y lista blanca de modelos en el gateway para evitar que un bucle del agente consuma la cuota.
  • Unifica approval_policy, sandbox_mode y cli_auth_credentials_store con configuración gestionada por la empresa; requirements.toml puede prohibir combinaciones de alto riesgo como never y danger-full-access.
  • Si necesitas forzar el método de inicio de sesión, usa forced_login_method = "chatgpt" o "api" para evitar que los miembros mezclen credenciales.
  • Mantén una plantilla de configuración sin claves, con Base URL, identificadores de modelo y comandos de diagnóstico.
  • Revisa cada mes el consumo del gateway por persona, proyecto y modelo para detectar anomalías.

7. Lista de seguridad

  • Guarda las claves solo en variables de entorno, el llavero del sistema o un servicio de gestión de secretos; nunca en config.toml ni en Git. Aunque experimental_bearer_token existe en la configuración, no se recomienda.
  • Usa una clave independiente para Codex, con límites, fecha de caducidad y revocación por separado.
  • Sandbox de solo lectura por defecto; cuando necesites escritura, limita los directorios al repositorio concreto y retira el permiso al terminar.
  • No pongas .env, auth.json, configuración de producción ni datos de clientes en el contexto; en repositorios grandes, excluye antes los artefactos de compilación y los directorios de dependencias.
  • Revisa los comandos y parches que genera Codex, sobre todo eliminaciones, solicitudes de red y operaciones que elevan privilegios.
  • Fija la versión de Codex en las imágenes del equipo y valida la compatibilidad de la configuración en un entorno de prueba antes de actualizar.
  • Activa alertas de consumo en el gateway; ante llamadas anómalas, detén primero la clave y revisa después los registros.

Preguntas frecuentes

¿Codex CLI debe usar el protocolo Responses?

Actualmente, wire_api de un proveedor personalizado solo acepta responses; la forma antigua chat está obsoleta. Si el gateway solo ofrece Chat Completions, necesitas una capa de conversión de protocolo o un endpoint compatible con Responses.

Ya escribí la configuración, ¿por qué las solicitudes siguen yendo a la dirección predeterminada?

Confirma primero que modificaste ~/.codex/config.toml, luego que las claves de nivel superior están antes de los encabezados de tabla y que model_provider coincide exactamente con el ID del proveedor. Las definiciones de proveedor en la configuración de proyecto se ignoran; esta es la causa más común.

¿Se puede escribir la clave directamente en config.toml?

No se recomienda. Usa env_key para referenciar una variable de entorno o llama a un comando externo mediante [model_providers.xxx.auth]. Una clave en texto plano se filtra con facilidad en copias de seguridad, capturas o repositorios.

¿El inicio de sesión con ChatGPT y la facturación por API Key son iguales?

No. El inicio de sesión con ChatGPT usa el sistema de cuentas; la API Key factura por consumo de la interfaz. Las cuotas, facturas y permisos son distintos, y un equipo debe contabilizarlos por separado.

¿Puede un equipo compartir una sola clave?

No se recomienda. Una clave compartida impide saber quién hizo cada llamada y no se puede revocar individualmente si alguien la filtra o deja la empresa. Emite claves por persona y por entorno, con límites y caducidad.

Próximos pasos

La dificultad de conectar Codex no está en la instalación, sino en la coincidencia del protocolo y los límites de permisos: confirma que el gateway admite Responses y el evento de finalización del streaming, configura después Base URL, clave y modelo, y termina con una prueba de humo en sandbox de solo lectura. Si necesitas un punto de acceso unificado y gestión de consumo, puedes registrarte en ZSQH AI Gateway; el alcance de modelos e interfaces figura en la página de precios de modelos.

Lecturas relacionadas: