Desplegar Codex a través de una pasarela

Despliega Codex a través de la pasarela de LLM de tu organización. Configura las rutas de los modelos, emite credenciales para desarrolladores y distribuye una configuración de Codex verificada.

Requisitos previos

Antes de desplegar Codex para los desarrolladores, confirma que dispones de:

• Una pasarela que sirva HTTPS en la URL base exacta que distribuirás.
• Una credencial del proveedor de origen almacenada en la pasarela.
• Alias de modelos aprobados para Codex, asignados a los modelos de origen previstos.
• Una credencial de prueba de la pasarela con alcance limitado.
• Un mecanismo de entrega de secretos o un asistente de credenciales probado.
• Una forma de distribuir la configuración, los ejecutables auxiliares y los archivos de catálogo necesarios.

Requisitos de la pasarela

Antes de conectar Codex, verifica que el producto de pasarela conserve estos comportamientos obligatorios:

• Aceptar solicitudes de Codex a la Responses API en POST /v1/responses.
• Transmitir eventos SSE sin almacenarlos en búfer y finalizar con response.completed.
• Conservar la continuación de la conversación con entradas reenviadas.
• Conservar previous_response_id solo cuando WebSocket o el transporte incremental estén habilitados.
• Conservar las llamadas a funciones y sus elementos function_call_output correspondientes.
• Dirigir cada alias de modelo para Codex al modelo de origen previsto.
• Autenticar a los usuarios por separado y devolver errores útiles sin ocultar la causa.

Un endpoint de estado, /v1/models, una respuesta de Chat Completions o una única respuesta de texto sin formato no bastan para validar la pasarela. Consulta Requisitos de compatibilidad de las pasarelas para conocer el contrato detallado.

Implementar la pasarela

Para pasar de una pasarela desplegada a una experiencia de desarrollo verificada, completa estos cinco pasos en orden:

1. Elegir los nombres de los modelos y verificar las rutas.
2. Emitir credenciales para desarrolladores.
3. Probar Codex a través de la pasarela.
4. Distribuir la configuración.
5. Verificar desde el equipo de un desarrollador.

Elegir los nombres y las rutas de los modelos

Establece model de Codex en el nombre del modelo de la pasarela. Configura la pasarela para dirigir ese nombre al modelo de origen aprobado.

Usar un catálogo de modelos para nombres personalizados

Usa model_catalog_json cuando tu pasarela utilice un nombre de modelo que Codex no reconozca. El catálogo proporciona las instrucciones, las opciones de razonamiento, los límites de contexto y las capacidades de herramientas que Codex utiliza para ese nombre. Sin una entrada coincidente, una solicitud puede llegar al modelo de origen previsto mientras Codex utiliza ajustes genéricos.

Por ejemplo, para usar company-coding-model como alias de gpt-6-luna:

1. Crea el alias company-coding-model en la pasarela y dirígelo al modelo de origen aprobado gpt-6-luna.
2. Descarga el catálogo de modelos de Codex para tu versión de Codex y guarda una copia como gateway-models.json. Usa este archivo como punto de partida.
3. Edita la entrada gpt-6-luna en tu copia: establece slug en company-coding-model y comprueba que los demás metadatos coincidan con el modelo de origen y las capacidades de la pasarela. Para un alias sin migración de modelo, establece upgrade en null.
4. Mantén las entradas en el arreglo models de nivel superior y distribuye el archivo a cada cliente. Un catálogo personalizado reemplaza el catálogo incluido, así que incorpora todos los modelos que los usuarios necesiten seleccionar.

Para Bedrock a través de LiteLLM, aplica los cambios obligatorios del catálogo.

Establece el alias de la pasarela, slug del catálogo y model de Codex en company-coding-model. Añade estos ajustes antes de la primera tabla TOML en la configuración de Codex que distribuyas, utilizando la ruta absoluta real del archivo:

model = "company-coding-model"
model_catalog_json = "/absolute/path/to/gateway-models.json"

Reinicia la CLI o la aplicación de escritorio después de cambiar el catálogo, porque Codex lo carga al iniciarse.

Verificar las rutas de los modelos

Para cada modelo, verifica la ruta con una solicitud real de Responses y los registros de la pasarela. Una respuesta de /v1/models puede ayudar a descubrir nombres, pero no demuestra que un modelo admita el comportamiento requerido de solicitudes y herramientas.

El enrutamiento de modelos y la autorización de herramientas son partes independientes de la implementación. Configura las conexiones MCP, la distribución de plugins y sus políticas por separado.

Emitir credenciales para desarrolladores

1. Emite una credencial de pasarela con alcance limitado por desarrollador para poder atribuir el uso y revocar el acceso individualmente.
2. Establece los modelos aprobados, los límites de frecuencia, el presupuesto, el vencimiento y el período de renovación de cada credencial.
3. Entrega las credenciales mediante tu gestor de secretos o un asistente de credenciales instalado. Mantén las credenciales del proveedor de origen y del administrador de la pasarela fuera de los equipos de los desarrolladores.
4. Si utilizas un asistente, sigue el contrato de autenticación mediante comandos y prueba la obtención y la renovación de tokens antes de distribuirlo.
5. Explica a los desarrolladores cómo renovar sus credenciales y a quién contactar para obtener ayuda.

Probar Codex a través de la pasarela

Antes de distribuir nada, sigue Conectarse a una pasarela para configurar un usuario de prueba aislado con el bloque de proveedor y el mecanismo de credenciales que planeas distribuir.

Ejecuta las siguientes comprobaciones desde la misma CLI o interfaz de escritorio que utilizarán los desarrolladores:

Cuando estas comprobaciones se completen correctamente, dirige a los desarrolladores a Conectarse a una pasarela para configurar y verificar su propio equipo.

Distribuir la configuración

Para que todos los equipos utilicen la misma ruta de conexión, distribuye la URL base de la pasarela, el ID del proveedor, el alias de modelo aprobado y el mecanismo de credenciales.

Qué distribuir

Para establecer los valores predeterminados del proveedor, distribuye este bloque config.toml mediante la capa de configuración que hayas elegido. Usa un modelo reconocido por tu versión de Codex o proporciona el catálogo correspondiente descrito anteriormente. Instala tu resolvedor de tokens en la ruta del comando configurada:

model = "gpt-6-sol"
model_provider = "enterprise-gateway"
web_search = "disabled"

[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"

[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000

Para una clave de prueba estática de corta duración, elimina el bloque de autenticación, coloca env_key = "CODEX_GATEWAY_API_KEY" dentro de [model_providers.enterprise-gateway] y establece esa variable fuera de TOML. No combines env_key con la autenticación mediante comandos.

Distribuir valores predeterminados y requisitos

Usa Precedencia de la configuración para elegir dónde distribuir los valores predeterminados. Para los ajustes obligatorios y las cargas de configuración MDM de macOS, consulta Configuración administrada.

Para los valores predeterminados de todo el equipo en macOS o Linux, usa /etc/codex/config.toml. En Windows, coloca config.toml en %ProgramData%\OpenAI\Codex\. Los usuarios y los perfiles pueden sobrescribir estos valores predeterminados. Las referencias enlazadas describen los requisitos compatibles y las ubicaciones de sus archivos.

Distribuye por separado los ejecutables auxiliares y los archivos de catálogo a los que se haga referencia.

model_catalog_json apunta a un archivo JSON local. Si lo impones mediante requirements.toml, el requisito fija la ruta; no distribuye el archivo. Coloca el catálogo en esa ruta absoluta antes de que se inicie Codex.

Escribe rutas absolutas de Windows ya resueltas en TOML. Codex no expande %ProgramData% dentro de model_catalog_json ni en los valores de command de autenticación del proveedor. Por ejemplo, usa estas rutas solo si tu despliegue colocó los archivos allí:

model_catalog_json = 'C:\ProgramData\OpenAI\Codex\models.json'

[model_providers.enterprise-gateway.auth]
command = 'C:\ProgramData\OpenAI\Codex\fetch-gateway-token.cmd'
args = ["print-token"]

Una CLI dentro de WSL lee rutas de Linux y el CODEX_HOME de Linux; no hereda automáticamente la configuración nativa de Windows.

Entregar los valores de configuración a los desarrolladores

Si no dispones de distribución administrada, entrega a cada desarrollador la URL de la pasarela, el ID del proveedor, el alias del modelo, la variable de credenciales o el resolvedor, y las rutas de catálogo necesarias. Dirígelos a Conectarse a una pasarela para configurar y verificar su propio equipo.

La configuración manual no es un canal para imponer ajustes. El .codex/config.toml local del proyecto no puede sobrescribir claves sensibles del proveedor o del enrutamiento de autenticación.

Verificar desde el equipo de un desarrollador

Para confirmar que los ajustes distribuidos llegaron al equipo de un desarrollador:

1. Reinicia Codex y confirma el proveedor y el modelo esperados.
2. Ejecuta la prueba breve de Conectarse a una pasarela.
3. Haz una pregunta de seguimiento para confirmar la continuación y, después, busca en los registros de la pasarela la solicitud de ese desarrollador.

Solucionar fallos de implementación

Utiliza el problema para identificar la capa de configuración, credenciales o pasarela que necesita atención:

Reutilizar un despliegue de pasarela existente

Si tu organización ya utiliza Claude Code a través de una pasarela, es posible que puedas reutilizar el producto de pasarela, la ruta de red, el registro y el acceso a Bedrock. Añade una ruta de Responses para Codex, una credencial, alias de modelos y config.toml, y conserva la configuración existente que funciona. Los ajustes del cliente Claude y el contrato de /v1/messages no configuran Codex.

Para migrar de forma segura, completa estos pasos en orden:

1. Haz un inventario de la ruta actual de Claude: URL de la pasarela, origen de las credenciales, encabezados obligatorios, alias de modelos, asignaciones de perfiles de Bedrock y canal de entrega administrado.
2. Añade una ruta de Responses paralela para Codex y alias de modelos de Codex.
3. Emite una credencial de Codex con alcance limitado. Si Codex utilizará una credencial estática, expón esa nueva credencial mediante env_key; si Claude utiliza un asistente de credenciales, implementa y prueba el contrato del resolvedor de Codex mediante comandos.
4. Configura a ese desarrollador con el bloque de proveedor. Para una implementación administrada, adapta la carga de configuración a las rutas y la precedencia de Codex descritas en Desplegar Codex a través de una pasarela.
5. Ejecuta la comprobación breve de conexión en la CLI o interfaz de escritorio real del desarrollador y, después, ejecuta todas las comprobaciones de transmisión, continuación, llamadas a herramientas, errores, registro y enrutamiento de alias de Probar Codex a través de la pasarela.
6. Cuando la prueba piloto se complete correctamente, distribuye la configuración al resto de los desarrolladores.

Documentación relacionada

• Conectarse a una pasarela
• MCP
• Plugins
• Configuración administrada