Una clave válida no basta para que Codex funcione con un proveedor externo. El servicio debe implementar la API Responses, aceptar un identificador de modelo disponible en esa cuenta, aplicar el esquema de autenticación esperado y devolver un flujo que Codex pueda interpretar hasta el final.
La etiqueta «compatible con OpenAI» no demuestra todo eso. Puede referirse únicamente a /v1/chat/completions. Añadir /responses a una URL no implementa el protocolo que falta; antes de editar la configuración, la documentación oficial del proveedor debe indicar expresamente un endpoint Responses.
También conviene fijar el alcance. Aquí se cambia el proveedor del modelo que usa Codex. MCP conecta herramientas y datos externos, mientras que integrar Meta Ads, un CRM u otra API de negocio es trabajo que Codex puede ayudarte a programar. Son tareas distintas aunque las tres se describan a veces como “integrar una API”.
La compatibilidad es una cadena, no un interruptor
Antes del primer intento, reúne cuatro datos del proveedor:
| Dato | Evidencia suficiente | Señal que no basta |
|---|---|---|
| Base URL de Responses | Página del proveedor que documenta esa ruta | Ejemplo de Chat Completions |
| ID de modelo | ID exacto habilitado para la cuenta y esa ruta | Nombre comercial o alias de otro proveedor |
| Autenticación | Bearer token, header o query documentados | Tener una sesión de ChatGPT abierta |
| Streaming | Respuesta Codex completa o contrato explícito | Respuesta no streaming de otro SDK |
La referencia actual de configuración de Codex establece responses como único valor admitido de wire_api. Por tanto, una comparación de precios o modelos no sirve si el contrato de transporte falla primero.
La cuenta también cambia. La suscripción de ChatGPT no concede saldo, permisos ni límites en un tercero. La facturación, retención, registros, disponibilidad regional y soporte pertenecen al proveedor que recibe la petición.
Prueba el provider sin reemplazar tu ruta habitual
Las claves model_provider y model_providers son configuración local de la máquina. Codex las ignora dentro del .codex/config.toml del repositorio; deben vivir en ~/.codex/config.toml o en un profile de usuario situado junto a él.
Un profile independiente permite probar y volver atrás sin mezclar el cambio con sandbox, MCP o reglas existentes. Crea ~/.codex/third-party.config.toml:
tomlmodel = "provider-model-id" model_provider = "acme" [model_providers.acme] name = "Acme Model API" base_url = "https://api.example.com/v1" env_key = "ACME_API_KEY" wire_api = "responses"
Los valores del modelo y de la URL son ficticios. Sustitúyelos por los valores literales de la documentación del proveedor. El ID local acme debe coincidir en model_provider y en la tabla. openai, ollama y lmstudio están reservados y no pueden redefinirse. La configuración avanzada oficial muestra el contrato vigente de los proveedores personalizados.
El TOML apunta al secreto; no debe contenerlo
env_key = "ACME_API_KEY" nombra una variable de entorno. No es el valor de la clave. En macOS, Linux o WSL, inicia Codex desde el mismo shell:
bashexport ACME_API_KEY="clave-real" codex --profile third-party
En la sesión actual de PowerShell:
powershell$env:ACME_API_KEY = "clave-real" codex --profile third-party
No guardes la clave en TOML, un repositorio de dotfiles, .env.example, capturas o tickets. El campo literal experimental_bearer_token existe, pero la referencia de OpenAI desaconseja su uso y dirige a env_key. Si el proveedor requiere headers o parámetros especiales, usa únicamente su forma documentada con env_http_headers, http_headers o query_params.
Una aplicación abierta desde Dock, el menú de Windows o un IDE puede no heredar una variable exportada en otro terminal. Si CLI funciona y Desktop no encuentra la clave, comprueba primero el entorno del proceso que lo inicia; cambiar la base URL no resuelve ese límite.
Verifica la ruta, no solo el nombre visible
Que Codex muestre el modelo personalizado confirma que leyó el profile. No confirma el destino de red. Para una primera prueba, abre un directorio vacío, ejecuta codex --profile third-party y pide una cadena breve y fija sin leer archivos ni llamar herramientas.
La prueba queda demostrada cuando coinciden tres señales:
- la sesión activa muestra el ID esperado;
- la respuesta termina sin error de parseo ni reconexión del stream;
- el panel del proveedor o gateway registra a la misma hora la petición, el modelo, el estado y el uso.
Conserva el request ID y la hora cuando estén disponibles, pero no la clave ni contenido innecesario del prompt. Esta correlación detecta un profile antiguo, aliases de modelo y gateways que reescriben el destino.
Las guías de primera parte sirven dentro de su alcance. DeepSeek, por ejemplo, declara en su documentación oficial para Codex que su API admite Responses y explica sus propios modelos. Esa página prueba la ruta de DeepSeek, no la de otro servicio “compatible”.
El primer síntoma decide dónde mirar
| Síntoma | Propietario probable | Comprobación inicial |
|---|---|---|
| Clave de config desconocida o error TOML | Versión de Codex o sintaxis | codex --version, tablas, comillas y referencia vigente |
| Variable inexistente | Entorno del proceso | Lanzar desde el mismo shell o corregir Desktop/IDE |
| 401 / 403 | Credencial, header, proyecto o permisos | Estado de la clave y acceso al modelo en el proveedor |
| 404 / model not found | Base URL o mapeo de modelo | Ruta Responses e ID exactos |
| Error de parseo inmediato | Formato incompatible | Abandonar el endpoint solo Chat Completions |
| Salida parcial o reconexiones | SSE, timeout del intermediario o upstream | Cruzar hora y request ID en ambos registros |
| 429 | Cuenta externa, gateway o límite del modelo | Revisar el sistema que realmente devolvió el estado |
Si el problema confirmado es 429, sigue el diagnóstico de límites de Codex. Para una petición que queda esperando, usa la guía de timeout. Si los valores no se aplican, revisa las capas y límites de config.toml.
Una respuesta de texto correcta tampoco garantiza paridad funcional. La búsqueda web independiente para custom providers parte desactivada; un flag no sustituye el endpoint, el modelo, el runtime ni la política necesarios. Entrada de imágenes, tool calls, reasoning summaries, WebSocket, plugins y funciones cloud se validan por separado cuando el flujo los necesita.
Para un uso ocasional, conserva el profile. Para regresar a la ruta oficial, cierra la sesión personalizada y ejecuta Codex sin --profile third-party. Si copiaste la configuración al archivo principal, elimina solo model, model_provider y la tabla añadida. Borrar todo ~/.codex puede llevarse autenticación, MCP, reglas, profiles e historial sin reparar un protocolo incompatible.
