Dos formas de usar modelos DeepSeek con Codex: gateway local y OpenRouter BYOK

Si quieres que Codex use DeepSeek, la primera reacción suele ser editar ~/.codex/config.toml:

1
2


model = "deepseek-chat"
base_url = "https://api.deepseek.com"

Esa idea puede funcionar en algunas versiones antiguas o en escenarios normales con el SDK de OpenAI. Pero con el Codex CLI actual, es fácil chocar con un problema más profundo: los proveedores de modelos personalizados de Codex usan el protocolo OpenAI Responses, mientras que la API oficial de DeepSeek se expone principalmente mediante una interfaz compatible con Chat Completions.

Mi versión local actual es codex-cli 0.111.0. codex --help muestra entradas de configuración como --config, --model y --profile. La referencia oficial de configuración de OpenAI Codex también es clara: model_providers.<id>.wire_api actualmente solo admite responses, y si se omite también usa responses por defecto.

La documentación oficial de DeepSeek, en cambio, muestra la ruta https://api.deepseek.com/chat/completions, con ejemplos como client.chat.completions.create(...). Así que el problema no es que DeepSeek no pueda llamarse con herramientas de estilo OpenAI. El problema es que la semántica de las solicitudes que envía Codex no coincide por completo con lo que entiende la API nativa de DeepSeek.

Por eso, si cambias directamente base_url a https://api.deepseek.com, puedes ver síntomas como estos:

La ruta de la solicitud no coincide, lo que produce un 404 o un formato de respuesta inesperado.
Fallos al analizar conversaciones de varias rondas, llamadas a herramientas o generación de parches.
El orden de tool_calls, la estructura de mensajes o el formato de eventos en streaming no encajan.
El modelo parece responder a una pregunta simple, pero falla cuando Codex empieza a hacer trabajo real.

El enfoque más estable es poner una capa de traducción entre Codex y DeepSeek. Hay dos rutas comunes.

Método 1: usar un gateway local para conectar DeepSeek

Un gateway local no debería limitarse a reenviar tráfico. Su función es convertir las solicitudes de estilo Responses de Codex en solicitudes de estilo Chat Completions que DeepSeek pueda procesar, y luego convertir el resultado de DeepSeek de vuelta a un formato que Codex pueda consumir.

Si usas un gateway local como ccx, la idea de configuración es aproximadamente esta:

1
2
3
4
5
6
7
8


[profiles.deepseek-ccx]
model = "deepseek-v4-flash"
model_provider = "ccx-bridge"

[model_providers.ccx-bridge]
name = "Local CCX Gateway"
base_url = "http://localhost:3000/v1"
env_key = "DEEPSEEK_API_KEY"

Luego configura la clave de DeepSeek en la terminal y arranca Codex con ese profile:

1
2


export DEEPSEEK_API_KEY="your-deepseek-key"
codex --profile deepseek-ccx

En PowerShell:

1
2


$env:DEEPSEEK_API_KEY="your-deepseek-key"
codex --profile deepseek-ccx

Hay dos detalles importantes.

Primero, base_url debe apuntar a la dirección que el gateway expone a Codex, no a la dirección oficial de DeepSeek. El gateway será quien llame a DeepSeek por detrás.

Segundo, el valor correcto de env_key depende de cómo autentique el gateway. Algunos gateways leen directamente la clave oficial de DeepSeek. Otros te piden una clave local de proxy y guardan la clave de DeepSeek en su propio panel. En ese caso, env_key debe cambiarse al nombre de variable de entorno que espere el gateway.

Esta ruta es local y controlable, y facilita razonar sobre latencia y coste. La desventaja es que debes confirmar que el gateway realmente soporta la semántica Responses que usa Codex actualmente, y que no es solo un proxy básico de Chat Completions.

Método 2: usar OpenRouter BYOK como puente en línea

Si no quieres desplegar un gateway local, OpenRouter BYOK es otra opción. BYOK significa vincular tu propia clave de proveedor ascendente a OpenRouter, para que OpenRouter se encargue del enrutamiento y el reenvío.

El error más común aquí está en la variable de entorno. Codex llama a OpenRouter, por lo que env_key normalmente debería ser OPENROUTER_API_KEY, no DEEPSEEK_API_KEY. La clave de DeepSeek debe añadirse en la configuración BYOK o provider key de OpenRouter.

Ejemplo de configuración:

1
2
3
4
5
6
7
8


[profiles.deepseek-openrouter]
model = "deepseek/deepseek-chat"
model_provider = "openrouter"

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"

Arranque:

1
2


export OPENROUTER_API_KEY="your-openrouter-key"
codex --profile deepseek-openrouter

PowerShell:

1
2


$env:OPENROUTER_API_KEY="your-openrouter-key"
codex --profile deepseek-openrouter

Después añade tu provider key de DeepSeek en el panel de OpenRouter. La documentación BYOK de OpenRouter indica que las provider keys vinculadas se guardan cifradas y se usan para enrutar al proveedor correspondiente.

Esta ruta evita mantener un gateway local y se parece más a usar un proxy API de terceros. La desventaja es que hay un servicio en línea adicional en medio, así que al depurar tendrás que revisar mensajes de error de Codex, OpenRouter y DeepSeek.

¿Conviene seguir usando el nombre deepseek-chat?

En la documentación de DeepSeek de mayo de 2026, los nombres recomendados incluyen deepseek-v4-flash y deepseek-v4-pro, con una nota de que los alias compatibles deepseek-chat y deepseek-reasoner serán retirados después del 2026-07-24.

Para configuraciones nuevas, es mejor probar primero:

1

model = "deepseek-v4-flash"

Si usas OpenRouter, sigue el formato de nombres de modelos de OpenRouter, por ejemplo:

1

model = "deepseek/deepseek-chat"

Los nombres disponibles reales dependen del gateway que uses o de la página de modelos de OpenRouter. Cuando el nombre del modelo no es correcto, el error suele aparecer como model not found, 404, o un provider que no encuentra el endpoint correspondiente.

Por qué no se recomienda apuntar directamente al base_url oficial de DeepSeek

Por supuesto, puedes probar algo así como experimento:

1
2
3
4
5
6
7
8


[profiles.deepseek-direct]
model = "deepseek-v4-flash"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"

Pero esto se parece más a una prueba de diagnóstico que a una configuración estable. Codex habla con proveedores personalizados mediante el protocolo Responses, mientras que los ejemplos oficiales de DeepSeek usan /chat/completions. Si DeepSeek o Codex completan una capa de compatibilidad en el futuro, la conexión directa podría volverse sencilla. Hasta entonces, una capa puente es más fiable.

Qué hacer si Codex sigue usando OpenAI después de editar la configuración

Primero confirma la ubicación del archivo de configuración. La configuración global debería estar en:

1

~/.codex/config.toml

El archivo .codex/config.toml dentro del proyecto no es el lugar adecuado para ajustes de proveedor a nivel de máquina como model_provider y model_providers. La documentación oficial de OpenAI también advierte que la configuración de proyecto no sobrescribe estos campos locales de proveedor y autenticación.

Si Codex todavía pide iniciar sesión por web, o parece seguir usando el modelo OpenAI predeterminado, cierra primero la sesión actual:

1

codex logout

Algunos tutoriales antiguos lo escriben como /logout dentro de la interfaz interactiva. En el CLI actual, es más fiable ejecutar directamente codex logout en la terminal.

También puedes hacer una verificación rápida con un profile temporal:

1

codex --profile deepseek-ccx

1

codex -c model_provider=ccx-bridge -c model=deepseek-v4-flash

Si eso funciona, la configuración se está leyendo. Si no funciona, revisa primero el nombre del profile, la sintaxis TOML y si la variable de entorno solo existe en la shell actual.

Lista de diagnóstico

401: la clave es incorrecta, o env_key apunta a la variable de entorno equivocada.
404: base_url o el nombre del modelo es incorrecto, o se está enviando una solicitud Responses a un endpoint que solo soporta Chat Completions.
Errores de tool_calls, patch o parsing de streaming: probablemente el puente de protocolo está incompleto.
Todavía pide iniciar sesión en OpenAI: ejecuta codex logout y confirma que usas el profile correcto.
La variable de entorno configurada en PowerShell desaparece en una ventana nueva: $env:... solo aplica a la sesión actual. Usa variables de entorno de usuario si necesitas persistencia.
OpenRouter BYOK no usa tu propia clave de DeepSeek: revisa si el provider key está vinculado en OpenRouter, si el OpenRouter API Key actual puede usarlo y si fallback está activado.

Conclusión

Usar DeepSeek con Codex no es imposible mediante config.toml. El punto es que cambiar solo base_url normalmente no basta.

Las dos rutas más estables hoy son:

Usar un gateway local como puente de protocolo: Codex habla con el gateway local, y el gateway habla con DeepSeek.
Usar OpenRouter BYOK como proxy en línea: Codex habla con OpenRouter, y la clave de DeepSeek queda vinculada en el panel de OpenRouter.

Si solo quieres probar rápido, OpenRouter es más cómodo. Si quieres controlar mejor claves, coste y logs, un gateway local encaja mejor para un uso a largo plazo.

Referencias: