# Informe para retomar la integración OpenClaw + LiteLLM + Ollama

**Fecha:** 2026-04-13  
**Estado:** investigación pausada con diagnóstico bastante acotado

---

## 1. Situación general

Se investigó por qué OpenClaw no estaba usando bien los modelos locales servidos por Ollama y expuestos a través de LiteLLM.

La conclusión más importante es esta:

> **El problema no parece estar en Ollama ni en LiteLLM de forma aislada. El bloqueo probable está en una capa puente/intermedia que modifica respuestas JSON y rompe el flujo normal de OpenClaw.**

---

## 2. Qué se comprobó y sí funciona

### Ollama

Ollama está operativo como servicio y responde correctamente.

Modelos observados:

- `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`

### LiteLLM

LiteLLM está operativo y expone modelos compatibles.

Modelos observados en LiteLLM:

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

### Prueba directa contra LiteLLM

Se hicieron llamadas reales a la API OpenAI-compatible de LiteLLM y respondieron bien.

Pruebas confirmadas:

- `phi3` → responde correctamente
- `llama3.1-8b` → responde correctamente

Esto demuestra que:

- Ollama funciona
- LiteLLM funciona
- el endpoint OpenAI-compatible funciona

---

## 3. Qué pasa dentro de OpenClaw

OpenClaw:

- reconoce el provider `litellm`
- ve el catálogo de modelos
- llega a intentar usar `litellm/phi3`

Pero luego cae al fallback al modelo principal remoto.

### Síntoma importante observado

En datos de sesión anteriores apareció una respuesta de este tipo:

```json
{"label":"openclaw-assistant","id":"openclaw-assistant"}
```

Eso sugiere que OpenClaw no estaba recibiendo una respuesta conversacional normal del modelo, sino una estructura JSON ajena al flujo esperado.

---

## 4. Pista clave confirmada por Silvio

Silvio confirmó que había creado un **puente / capa intermedia** para interpretar o solucionar respuestas JSON.

Esa información encaja perfectamente con el síntoma anterior.

### Hipótesis principal

La integración real estaría así:

`OpenClaw -> capa puente -> LiteLLM -> Ollama`

Y el fallo estaría en esa capa puente, no en Ollama ni LiteLLM.

---

## 5. Conclusión diagnóstica

### Lo que NO parece ser el problema

- Ollama roto
- LiteLLM roto
- falta de modelos
- fallo básico de red o endpoint

### Lo que SÍ parece el problema

- una adaptación o bridge que transforma la respuesta
- salida JSON no esperada por OpenClaw
- caída posterior al fallback por respuesta no utilizable

---

## 6. Qué se hizo además durante esta fase

Mientras se trabajaba en esto, se dejó implantado:

- sistema de backup de María/OpenClaw + workspace
- restore points automáticos antes de cambios delicados
- portal NEXUS con botones de backup/restore
- renderizado HTML de `.md` en NEXUS

Eso significa que si se retoma más adelante, ya hay red de seguridad para seguir tocando cosas sin tanto miedo.

---

## 7. Cómo retomar este tema más adelante

El camino recomendado para retomarlo es este:

### Paso 1

Localizar exactamente el bridge/proxy intermedio que se añadió para manejar JSON.

### Paso 2

Ver cómo está enganchado:

- servicio systemd
- proxy local
- script Python o Node
- wrapper de LiteLLM
- middleware de OpenClaw

### Paso 3

Aislarlo temporalmente.

### Paso 4

Probar el camino limpio:

`OpenClaw -> LiteLLM -> Ollama`

### Paso 5

Si el camino limpio funciona:

- eliminar el bridge
- o dejarlo solo para casos específicos
- o reescribirlo para que no rompa el flujo normal de chat

---

## 8. Si se quiere reintentar, candidatos de prueba

Modelos recomendados para las primeras pruebas:

- `litellm/phi3`
- `litellm/llama3.1-8b`

Motivo:

- son más ligeros
- responden bien por API directa
- sirven para validar rápido si la integración ya quedó limpia

---

## 9. Estado final

Tema pausado por ahora.

No se considera “imposible”, pero sí **ingrato y bloqueado por una capa intermedia rara**. La base técnica local sí está viva.

---

## 10. Resumen en una frase

**Si esto se retoma, no empezar desde Ollama. Empezar desde el bridge que altera JSON y desmontar primero esa interferencia.**