Diagnóstico de integración OpenClaw, Ollama y LiteLLM

Fecha: 2026-04-12
Modo: solo lectura
Objetivo: entender por qué OpenClaw no estaba usando con normalidad los modelos locales servidos por Ollama y expuestos por LiteLLM

1. Resumen ejecutivo

La buena noticia es esta: la base técnica sí está viva.

• Ollama está funcionando correctamente.
• LiteLLM está funcionando correctamente.
• Los modelos locales sí existen y están publicados.
• OpenClaw ya tiene configurado LiteLLM como provider.

Por tanto, el problema no parece ser “no hay modelos” ni “Ollama está roto”.

La causa más probable es una combinación de estas tres fricciones:

1. OpenClaw no está usando esos modelos como default activo del agente principal.
2. LiteLLM requiere API key, así que cualquier prueba manual directa sin esa clave falla y da sensación de que no funciona.
3. Los nombres efectivos de modelo expuestos a OpenClaw no coinciden intuitivamente con los nombres nativos de Ollama, lo que hace muy fácil equivocarse al configurarlos o probarlos.

En otras palabras: el stack existe, pero la experiencia de uso está poco alineada y por eso resulta frustrante.

2. Estado real de Ollama

Servicio

Ollama está activo como servicio systemd:

• ollama.service activo desde hace varios días
• proceso principal: ollama serve

Modelos detectados en Ollama

Se confirmaron estos modelos locales:

• gemma4:31b
• gemma4:26b
• mixtral:8x7b-instruct-v0.1-q4_K_M
• codellama:7b-instruct
• llama3.1:8b-instruct-q4_0
• phi3:latest
• nomic-embed-text:latest

Conclusión sobre Ollama

Ollama no es el problema. Está levantado y responde por API.

3. Estado real de LiteLLM

Endpoints observados

LiteLLM está accesible en http://127.0.0.1:4001.

Cuando se consulta sin credenciales responde con error de autenticación, por ejemplo:

• Authentication Error, No api key passed in.

Eso es importante, porque hace que desde fuera parezca que “no funciona”, cuando en realidad sí funciona, pero exige clave.

API key observada en OpenClaw

La configuración de OpenClaw apunta al provider litellm con:

• baseUrl: http://localhost:4001
• una API key local configurada

Modelos publicados por LiteLLM

LiteLLM expone estos ids de modelo:

• mixtral-8x7b
• gemma4-31b
• gemma4-26b
• codellama-7b
• llama3.1-8b
• phi3
• nomic-embed-text

Mapeo real LiteLLM → Ollama

LiteLLM está haciendo de puente correctamente, por ejemplo:

• gemma4-31b → ollama/gemma4:31b
• gemma4-26b → ollama/gemma4:26b
• mixtral-8x7b → ollama/mixtral:8x7b-instruct-v0.1-q4_K_M
• codellama-7b → ollama/codellama:7b-instruct
• llama3.1-8b → ollama/llama3.1:8b-instruct-q4_0
• phi3 → ollama/phi3:latest
• nomic-embed-text → ollama/nomic-embed-text:latest

Conclusión sobre LiteLLM

LiteLLM sí está funcionando y sí está publicando modelos de Ollama.

4. Estado de OpenClaw

OpenClaw tiene configurado el provider litellm dentro de models.providers.

Eso confirma que la intención de integración ya existía.

Sin embargo, en el uso real de la sesión se ha visto que el agente principal sigue trabajando con modelos remotos tipo gpt-5.4, no con los modelos locales publicados por LiteLLM.

Qué significa esto

Que probablemente el problema no es de conectividad entre OpenClaw y LiteLLM, sino de selección efectiva de modelo.

5. Causa probable del problema

5.1 La integración existe, pero no está aterrizada en el flujo principal

Todo indica que:

• Ollama sirve modelos
• LiteLLM los publica
• OpenClaw conoce LiteLLM

Pero no está claro que el agente principal esté configurado para usar uno de esos modelos como opción normal de trabajo.

Traducción práctica

Puedes tener el proveedor bien montado y aun así sentir que “no funciona”, porque el agente sigue yéndose a otro provider por defecto.

5.2 Nombres de modelo poco intuitivos

Aquí hay una fuente de fricción muy clara.

En Ollama ves nombres como:

• gemma4:31b
• llama3.1:8b-instruct-q4_0

Pero LiteLLM publica ids más amigables como:

• gemma4-31b
• llama3.1-8b

Si intentas usar en OpenClaw el nombre “de Ollama” cuando espera el “de LiteLLM”, o viceversa, fallas aunque el backend esté bien.

5.3 Pruebas manuales engañosas por autenticación

Si consultas LiteLLM sin API key, devuelve error. Eso da la impresión de que está caído.

Pero en realidad está protegido y operativo.

Ese detalle por sí solo explica mucha frustración al probar a mano.

6. Lo importante, qué sí funciona ya

A día de hoy, lo que ya está confirmado es:

1. OpenClaw tiene provider litellm configurado.
2. LiteLLM responde con API key válida.
3. LiteLLM publica modelos respaldados por Ollama.
4. Ollama sirve los modelos correctamente.

Eso significa que no estás lejos. No es una integración rota, es una integración incompleta o mal aterrizada a nivel de configuración operativa.

7. Qué creo que falta para que te funcione “de verdad”

La siguiente fase debería validar estas piezas concretas:

1. Qué nombres exactos de modelo espera OpenClaw

Hay que comprobar si OpenClaw debe usar algo como:

• litellm/gemma4-31b
• litellm/phi3
• litellm/llama3.1-8b

O alguna variante concreta de canonicalización.

2. Cómo está definido el modelo por defecto del agente principal

Aunque LiteLLM exista, si el agente principal sigue apuntando a openai-codex/gpt-5.4, nunca sentirás que Ollama funciona “dentro de OpenClaw”.

3. Si OpenClaw acepta bien estos modelos en el selector o en override de sesión

Es decir, no basta con que el provider exista. Hay que comprobar cómo se selecciona de forma real y persistente.

8. Hipótesis principal

Mi hipótesis principal ahora mismo es esta:

La integración técnica entre OpenClaw, LiteLLM y Ollama existe y funciona, pero falta cerrar la configuración de selección de modelo en OpenClaw para que el agente use de verdad esos modelos locales.

Y la segunda hipótesis complementaria es:

El naming de los modelos y la autenticación de LiteLLM hacen que la experiencia de prueba sea engañosa y parezca rota cuando no lo está.

9. Qué haría yo a continuación

La siguiente revisión útil sería ya operativa, no solo diagnóstica:

1. probar un override real del agente principal hacia un modelo LiteLLM concreto
2. verificar el nombre exacto que OpenClaw acepta
3. dejar uno o dos modelos locales listos para usar en serio
4. documentar el procedimiento final en una guía corta

Mis candidatos para empezar serían:

• phi3, por ligereza
• llama3.1-8b, por equilibrio
• gemma4-26b o gemma4-31b, si el hardware aguanta bien y buscas calidad

10. Conclusión final

No estás bloqueado por una instalación rota. Estás bloqueado por una integración que está casi hecha, pero no bien rematada en la capa final de uso.

Eso es mucho mejor de lo que parecía.

La parte difícil, tener Ollama, LiteLLM y los modelos vivos, ya la tienes. Lo que falta ahora es una cosa más ingrata, pero totalmente resoluble:

• cuadrar nombres
• cuadrar selección de modelo
• cuadrar provider por defecto en OpenClaw

Y entonces sí, OpenClaw podrá usar de verdad tus modelos locales.

11. Estado del documento

Documento generado en modo solo lectura, sin cambios aplicados.