# 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.