From 9bd3d1052d5c66c078982a0d85908cd5b9db4049 Mon Sep 17 00:00:00 2001 From: Carlos Tello Date: Mon, 21 Sep 2026 10:13:30 -0300 Subject: [PATCH] Document OpenClaw with local LLM server --- OPENCLAW_LOCAL_SERVER.md | 379 +++++++++++++++++++++++++++++++++++++++ README.md | 3 + 2 files changed, 382 insertions(+) create mode 100644 OPENCLAW_LOCAL_SERVER.md diff --git a/OPENCLAW_LOCAL_SERVER.md b/OPENCLAW_LOCAL_SERVER.md new file mode 100644 index 0000000..fc94a0d --- /dev/null +++ b/OPENCLAW_LOCAL_SERVER.md @@ -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) diff --git a/README.md b/README.md index 4178b9d..2427f1b 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,9 @@ que ejecuta `sudo` y queda guardada como `~/litellm_config.yaml`. ## Instalación de OpenClaw +Para la configuración completa de OpenClaw con el servidor local, consulta +[OPENCLAW_LOCAL_SERVER.md](OPENCLAW_LOCAL_SERVER.md). + El script `install_openclaw.sh` utiliza el instalador oficial de OpenClaw y está pensado para Linux y WSL2. Para instalarlo sin abrir el asistente inicial: