Document OpenClaw with local LLM server

2026-09-21 10:13:30 -03:00
parent b77d275fe0
commit 9bd3d1052d
2 changed files with 382 additions and 0 deletions
@@ -0,0 +1,379 @@
+# OpenClaw con servidor local
+
+Guía para ejecutar OpenClaw usando el modelo local administrado por Ollama y
+expuesto mediante LiteLLM.
+
+> El video de referencia es [Aprende OpenClaw Ahora! curso completo desde cero
+> para programadores](https://www.youtube.com/watch?v=4UtyJt2rMfo). Esta guía
+> adapta el flujo de configuración a este servidor local y no depende de un
+> proveedor cloud.
+
+## Arquitectura
+
+```text
+OpenClaw Gateway
+      |
+      | OpenAI-compatible: http://127.0.0.1:8000/v1
+      v
+LiteLLM Proxy
+      |
+      | Ollama native API: http://127.0.0.1:11434
+      v
+Ollama -> qwen2.5-coder:14b -> NVIDIA GPU
+```
+
+Cuando OpenClaw y el servidor LLM están en la misma máquina, usa `127.0.0.1`.
+Si OpenClaw corre en otro equipo, reemplaza esa dirección por la IP privada del
+servidor, por ejemplo `http://192.168.1.50:8000/v1`.
+
+## Requisitos
+
+En el servidor LLM:
+
+- Ubuntu 22.04 o 24.04.
+- Node.js 24.16 o superior para OpenClaw.
+- GPU NVIDIA con controladores funcionales.
+- 16 GB de RAM como mínimo y espacio para el modelo.
+- `sudo`, `curl`, `git`, Python 3 y conexión a Internet.
+
+En el cliente remoto solo necesitas Node.js compatible con OpenClaw y acceso de
+red al puerto `8000` del servidor.
+
+## 1. Preparar el servidor LLM
+
+Clona este repositorio y ejecuta el instalador principal:
+
+```bash
+git clone https://gitea.oemspot.com.ar/carlostellocba/llm-server-setup.git
+cd llm-server-setup
+chmod +x setup_llm_server.sh
+sudo ./setup_llm_server.sh
+```
+
+El script instala y configura:
+
+- controladores NVIDIA y un límite de potencia de 300 W;
+- 8 GB de swap;
+- Ollama como servicio systemd en `0.0.0.0:11434`;
+- el modelo `qwen2.5-coder:14b`;
+- LiteLLM en `/opt/litellm-env`;
+- LiteLLM como `litellm.service` en `0.0.0.0:8000`;
+- reglas UFW para SSH y LiteLLM.
+
+Si se instalaron nuevos controladores, reinicia antes de continuar:
+
+```bash
+sudo reboot
+```
+
+## 2. Verificar Ollama y LiteLLM
+
+Ejecuta estas comprobaciones en el servidor:
+
+```bash
+systemctl is-active ollama
+systemctl is-active litellm
+nvidia-smi
+curl http://127.0.0.1:11434/api/tags
+curl http://127.0.0.1:8000/health/liveliness
+```
+
+Confirma que el modelo existe:
+
+```bash
+ollama list
+```
+
+La configuración generada por `setup_llm_server.sh` está en:
+
+```text
+~/litellm_config.yaml
+```
+
+El servicio LiteLLM debe ejecutarse con esa configuración y escuchar en el
+puerto `8000`. Para revisar errores:
+
+```bash
+sudo journalctl -u ollama -n 100 --no-pager
+sudo journalctl -u litellm -n 100 --no-pager
+```
+
+## 3. Probar el endpoint OpenAI-compatible
+
+Antes de instalar OpenClaw, prueba LiteLLM directamente:
+
+```bash
+curl http://127.0.0.1:8000/v1/models
+```
+
+Después envía una consulta usando una clave local de prueba. El proxy de este
+repositorio no configura autenticación, pero OpenClaw espera un valor de API
+key para el proveedor LiteLLM; `local` sirve como valor de configuración local:
+
+```bash
+curl http://127.0.0.1:8000/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer local' \
+  -d '{
+    "model": "qwen2.5-coder:14b",
+    "messages": [{"role": "user", "content": "Responde exactamente: OK"}],
+    "temperature": 0
+  }'
+```
+
+La respuesta debe contener `OK` y no un error de conexión o de modelo.
+
+## 4. Instalar OpenClaw
+
+En el servidor o en el equipo donde se ejecutará el Gateway:
+
+```bash
+bash install_openclaw.sh
+```
+
+El script instala OpenClaw sin iniciar el asistente. También puedes ejecutar el
+instalador oficial directamente:
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
+```
+
+Comprueba Node.js y OpenClaw:
+
+```bash
+node --version
+openclaw --version
+```
+
+## 5. Configurar OpenClaw con LiteLLM local
+
+La configuración de OpenClaw se guarda en:
+
+```text
+~/.openclaw/openclaw.json
+```
+
+Crea o edita ese archivo como JSON5:
+
+```json5
+{
+  models: {
+    providers: {
+      litellm: {
+        baseUrl: "http://127.0.0.1:8000/v1",
+        apiKey: "local",
+        api: "openai-completions",
+        models: [
+          {
+            id: "qwen2.5-coder:14b",
+            name: "Qwen 2.5 Coder 14B local",
+            reasoning: false,
+            input: ["text"],
+            contextWindow: 32768,
+            maxTokens: 32768
+          }
+        ]
+      }
+    }
+  },
+  agents: {
+    defaults: {
+      model: {
+        primary: "litellm/qwen2.5-coder:14b"
+      }
+    }
+  }
+}
+```
+
+Puntos importantes:
+
+- En `baseUrl` incluye `/v1` porque OpenClaw usa la API compatible con OpenAI de
+  LiteLLM.
+- No uses `http://127.0.0.1:11434/v1` directamente con el proveedor LiteLLM.
+- Para Ollama nativo, OpenClaw usa otra configuración y no debe mezclarse con
+  esta ruta.
+- `apiKey: "local"` coincide con el valor usado en las pruebas. No es una
+  credencial real porque el servicio actual no habilita autenticación.
+
+Valida la configuración:
+
+```bash
+openclaw doctor
+openclaw models list --provider litellm --refresh --json
+```
+
+## 6. Configurar con el asistente
+
+Como alternativa a editar JSON5, ejecuta el onboarding indicando LiteLLM:
+
+```bash
+openclaw onboard --auth-choice litellm-api-key
+```
+
+Cuando solicite la URL del proxy, usa:
+
+```text
+http://127.0.0.1:8000/v1
+```
+
+Y como API key local:
+
+```text
+local
+```
+
+Si el asistente permite modo no interactivo en tu versión instalada:
+
+```bash
+export LITELLM_API_KEY=local
+openclaw onboard --non-interactive --accept-risk --skip-health \
+  --auth-choice litellm-api-key \
+  --litellm-api-key "$LITELLM_API_KEY" \
+  --custom-base-url "http://127.0.0.1:8000/v1"
+```
+
+Después revisa el modelo primario con:
+
+```bash
+openclaw config get agents.defaults.model.primary
+```
+
+Debe devolver `litellm/qwen2.5-coder:14b`.
+
+## 7. Instalar y verificar el Gateway
+
+Instala el servicio de usuario de OpenClaw:
+
+```bash
+openclaw gateway install
+openclaw gateway status
+```
+
+El Gateway normalmente escucha en el puerto `18789`. Abre el dashboard:
+
+```bash
+openclaw dashboard
+```
+
+También puedes verificarlo desde el navegador en:
+
+```text
+http://127.0.0.1:18789
+```
+
+Prueba un mensaje desde el dashboard. En otra terminal puedes observar los
+logs del Gateway:
+
+```bash
+openclaw logs --follow
+```
+
+## 8. Usar OpenClaw desde otro equipo
+
+Si el Gateway corre en otro equipo distinto al servidor LLM, cambia únicamente
+`baseUrl` en `~/.openclaw/openclaw.json`:
+
+```json5
+{
+  models: {
+    providers: {
+      litellm: {
+        baseUrl: "http://192.168.1.50:8000/v1",
+        apiKey: "local",
+        api: "openai-completions",
+        models: [
+          {
+            id: "qwen2.5-coder:14b",
+            name: "Qwen 2.5 Coder 14B local",
+            input: ["text"],
+            contextWindow: 32768,
+            maxTokens: 32768
+          }
+        ]
+      }
+    }
+  },
+  agents: {
+    defaults: {
+      model: { primary: "litellm/qwen2.5-coder:14b" }
+    }
+  }
+}
+```
+
+En el servidor, permite el acceso solo desde la red privada. Por ejemplo,
+reemplaza la regla abierta actual de UFW por una regla limitada a tu subred:
+
+```bash
+sudo ufw delete allow 8000/tcp
+sudo ufw allow from 192.168.1.0/24 to any port 8000 proto tcp
+sudo ufw status verbose
+```
+
+No expongas el puerto `8000` directamente a Internet: el proxy actual no tiene
+una API key real ni TLS.
+
+## Solución de problemas
+
+### `Connection refused` en el puerto 8000
+
+```bash
+sudo systemctl restart ollama litellm
+sudo systemctl status ollama litellm
+sudo journalctl -u litellm -n 100 --no-pager
+```
+
+### LiteLLM no encuentra el modelo
+
+```bash
+ollama list
+ollama pull qwen2.5-coder:14b
+curl http://127.0.0.1:8000/v1/models
+```
+
+El nombre debe coincidir exactamente en los tres lugares:
+
+```text
+qwen2.5-coder:14b
+```
+
+### OpenClaw muestra respuestas de herramientas como texto
+
+Comprueba que OpenClaw usa LiteLLM con `/v1` y no la URL equivocada de Ollama:
+
+```bash
+openclaw config get models.providers.litellm.baseUrl
+```
+
+Debe devolver:
+
+```text
+http://127.0.0.1:8000/v1
+```
+
+### El modelo se queda sin memoria
+
+Reduce `contextWindow` y `maxTokens` en la configuración de OpenClaw y revisa
+la VRAM disponible:
+
+```bash
+nvidia-smi
+```
+
+### La configuración no es válida
+
+```bash
+openclaw doctor
+openclaw doctor --fix
+```
+
+OpenClaw valida estrictamente `openclaw.json`; un campo desconocido o un tipo
+incorrecto puede impedir que el Gateway arranque.
+
+## Referencias
+
+- [Documentación oficial de OpenClaw](https://docs.openclaw.ai/)
+- [Proveedor LiteLLM en OpenClaw](https://docs.openclaw.ai/providers/litellm)
+- [Proveedor Ollama en OpenClaw](https://docs.openclaw.ai/providers/ollama)
+- [Configuración del Gateway](https://docs.openclaw.ai/gateway/configuration)