LiteLLM es la pasarela central de modelos del repositorio. Ofrece una API compatible con OpenAI a aplicaciones como Open WebUI, n8n y Paperless AI, mientras mantiene las credenciales reales de los proveedores en un único servicio.

Qué despliega

litellm: proxy, catálogo de modelos y proveedor personalizado de Codex.
litellm-db: PostgreSQL para configuración y estado persistente de LiteLLM.
config.yaml: alias públicos y proveedor asociado a cada modelo.
codex_provider.py: adaptación entre la API de LiteLLM y la API Responses de Codex.

Esta separación evita configurar una credencial de OpenAI o Codex distinta en cada consumidor. Las aplicaciones sólo conocen la URL de LiteLLM, una clave de acceso de LiteLLM y el alias del modelo.

Redes y exposición

LiteLLM pertenece a su red interna litellm y a la red externa proxy. PostgreSQL sólo está en la red interna. Los consumidores conectados a proxy pueden usar:

http://litellm:4000/v1

El acceso público y la interfaz se enrutan mediante la configuración dinámica de Traefik en /opt/traefik/dynamic/litellm.yml. La API debe exigir LITELLM_MASTER_KEY; la protección SSO de la interfaz no sustituye esa clave.

Configuración

El .env local debe definir, como mínimo:

Variable	Función	Motivo
`LITELLM_MASTER_KEY`	Autentica a los consumidores de la API	Impide usar los modelos sólo por alcanzar la red
`LITELLM_SALT_KEY`	Cifra datos sensibles almacenados por LiteLLM	Debe permanecer estable tras el primer arranque
`POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`	Base de datos interna	No se exponen fuera de la red `litellm`
`LITELLM_DB_DATA_PATH`	Persistencia de PostgreSQL	Permite recrear contenedores sin perder estado
`DEEPSEEK_API_KEY`	Acceso directo a DeepSeek	Sólo se necesita para los alias `thsllm-*`

config.yaml publica alias estables. Los consumidores deben pedir el alias, no el identificador interno del proveedor. Así se puede cambiar el backend sin reconfigurar cada aplicación.

Autenticación de Codex

El Compose monta:

/home/felidae/.codex/auth.json -> /root/.codex/auth.json

La variable CODEX_AUTH_FILE apunta a la ruta interior. El montaje es de lectura y escritura porque codex_provider.py renueva el access token mediante el refresh token y guarda el resultado en el mismo archivo.

Flujo:

El usuario inicia sesión con Codex en el host y genera ~/.codex/auth.json.
Docker monta ese archivo únicamente dentro de LiteLLM.
El proveedor lee access_token, refresh_token y account_id.
Si el JWT vence en menos de 60 segundos, solicita un token nuevo y actualiza el archivo montado.
LiteLLM envía la petición a Codex y devuelve una respuesta compatible con OpenAI al consumidor.

El archivo contiene credenciales reutilizables. No debe copiarse al repositorio, incluirse en imágenes, logs, backups sin cifrar ni montarse en Paperless, n8n u Open WebUI. .gitignore excluye .codex, pero conviene comprobar antes de cada commit:

git status --ignored --short | grep codex

El usuario que ejecuta Docker debe poder leer y escribir el archivo. Si el host o usuario cambia, actualiza la ruta del volumen en docker-compose.yml; una ruta inexistente puede terminar creada como directorio y provocar errores de autenticación.

Modelos Codex

Los alias gpt-* configurados con custom_llm_provider: codex pasan por codex_provider.py. Internamente se usa el prefijo cx- para evitar colisiones con los modelos OpenAI nativos de LiteLLM; el proveedor vuelve a convertirlo antes de llamar a Codex.

El proveedor admite llamadas síncronas, asíncronas y streaming. Codex responde siempre mediante streaming; para una llamada no streaming, el proveedor agrega los fragmentos antes de responder.

Configurar consumidores

Un consumidor compatible con OpenAI necesita:

Base URL: http://litellm:4000/v1
API key: valor de LITELLM_MASTER_KEY
Model: gpt-5.6-sol

Usa la URL interna cuando ambos contenedores compartan proxy. Usa la URL HTTPS sólo para clientes externos. Nunca uses el token de Codex como API key del consumidor.

Despliegue

cd litellm
docker compose --env-file .env config
docker compose --env-file .env up -d

Verificación

docker compose --env-file .env ps
docker compose --env-file .env logs -f litellm
curl -sS http://127.0.0.1:4000/v1/models \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

Si no se publica el puerto en el host, ejecuta la prueba desde un contenedor unido a proxy o usa el dominio HTTPS.

Errores 401 que mencionen Codex suelen indicar que auth.json falta, no tiene permisos o ya no puede renovarse. Errores 401 devueltos antes de seleccionar modelo suelen indicar una LITELLM_MASTER_KEY incorrecta.

Persistencia y copias de seguridad

Respalda la ruta LITELLM_DB_DATA_PATH. Trata auth.json como un secreto independiente: si se respalda, debe hacerse cifrado y con acceso restringido. No restaures simultáneamente versiones distintas del archivo desde varios hosts, porque la rotación del refresh token puede invalidar la copia anterior.