llm-server-setup/README.md

LLM Server

Despliegue automatizado de un servidor LLM local con Ollama, LiteLLM y OpenClaw sobre Ubuntu 22.04/24.04.

Requisitos

• Ubuntu 22.04 o 24.04
• CPU de 4 núcleos o superior
• 16 GB de RAM como mínimo
• GPU NVIDIA compatible con sus controladores Linux
• Acceso sudo y conexión a Internet

La configuración está orientada a una NVIDIA RTX 3090 de 24 GB, pero el script puede utilizarse con otras GPU compatibles ajustando el modelo si es necesario.

Instalación

Clona el repositorio en el servidor:

git clone https://gitea.oemspot.com.ar/carlostellocba/llm-server-setup.git
cd llm-server-setup

Ejecuta el instalador principal como root o mediante sudo:

chmod +x setup_llm_server.sh
sudo ./setup_llm_server.sh

El instalador:

• actualiza los paquetes del sistema e instala dependencias;
• configura un archivo de swap de 8 GB;
• instala los controladores NVIDIA si no están disponibles;
• instala y configura Ollama en 0.0.0.0:11434;
• crea un entorno virtual de LiteLLM en /opt/litellm-env;
• descarga qwen2.5-coder:14b;
• crea el servicio litellm.service en el puerto 8000;
• permite SSH y LiteLLM mediante UFW.

El proceso puede tardar varios minutos y requiere espacio suficiente para el modelo. Si se instalan controladores NVIDIA nuevos, reinicia el servidor:

sudo reboot

Verificación

Después de la instalación, comprueba los servicios:

systemctl status ollama
systemctl status litellm
nvidia-smi
curl http://127.0.0.1:11434/api/tags
curl http://127.0.0.1:8000/health/liveliness

La configuración de LiteLLM se genera en el directorio personal del usuario 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.

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:

bash install_openclaw.sh

Para instalarlo y ejecutar el asistente inmediatamente:

bash install_openclaw.sh --onboard

Si la instalación se hizo sin asistente, puedes iniciarlo después y configurar el servicio de Gateway:

openclaw onboard --install-daemon

Comprueba la instalación con:

openclaw --version
openclaw doctor
openclaw gateway status

Si OpenClaw devuelve respuestas vacías o de un token, ejecuta el reparador local como el usuario que ejecuta OpenClaw (ctello, no root):

chmod +x fix_openclaw_local.sh
bash ./fix_openclaw_local.sh

El script respalda openclaw.json, fuerza el Gateway local, desactiva el razonamiento predeterminado y la memoria semántica sin embeddings, inicializa el workspace Git y reinicia el Gateway. No borra sesiones ni secretos.

Después crea una sesión nueva en el dashboard y prueba:

Responde exactamente: SESION NUEVA OK

Para acceder al dashboard desde Windows mediante PowerShell, usa un túnel SSH hacia el servidor Ubuntu:

ssh -N -L 18789:127.0.0.1:18789 ctello@192.168.0.225

Mantén la sesión abierta y entra desde el navegador en:

http://127.0.0.1:18789

La guía completa de acceso desde PuTTY, PowerShell y solución de problemas está en OPENCLAW_LOCAL_SERVER.md.

Respaldo y recuperación

Para ejecutar un diagnóstico independiente y de solo lectura del servidor usa ubuntu_server_diagnostic.sh. Comprueba Ubuntu, hardware, servicios, puertos, Ollama, LiteLLM, OpenClaw y UFW:

chmod +x ubuntu_server_diagnostic.sh
sudo ./ubuntu_server_diagnostic.sh --report /tmp/ubuntu-server-test.txt

Puedes cambiar los endpoints o el modelo esperado mediante variables de entorno:

OLLAMA_URL=http://127.0.0.1:11434 \
LITELLM_URL=http://127.0.0.1:8000 \
MODEL_NAME=qwen2.5-coder:14b \
sudo -E ./ubuntu_server_diagnostic.sh

Para guardar la configuración del servidor antes de realizar cambios, ejecuta el script como root:

chmod +x backup_ubuntu_config.sh restore_ubuntu_config.sh
sudo ./backup_ubuntu_config.sh

El respaldo se guarda por defecto en /var/backups e incluye inventario de hardware, paquetes, servicios, red, UFW, systemd, NVIDIA, Ollama, LiteLLM, OpenClaw y configuraciones de usuario. No incluye modelos Ollama, el entorno virtual de LiteLLM, bases de datos ni logs completos.

Las claves SSH, certificados privados y credenciales de OpenClaw quedan fuera por defecto. Para incluirlos explícitamente, protege el archivo resultante:

sudo ./backup_ubuntu_config.sh --include-secrets
sudo chmod 600 /var/backups/ubuntu-config-*.tar.gz

En una instalación Ubuntu nueva, instala primero el sistema base y crea los usuarios necesarios. Después copia el archivo de respaldo y usa el restaurador en modo vista previa:

sudo ./restore_ubuntu_config.sh /ruta/al/respaldo.tar.gz

Para aplicar la configuración:

sudo ./restore_ubuntu_config.sh /ruta/al/respaldo.tar.gz --yes

Puedes reinstalar los paquetes APT y arrancar los servicios habilitados de la máquina original de forma explícita:

sudo ./restore_ubuntu_config.sh /ruta/al/respaldo.tar.gz \
  --yes --install-packages --start-services

Revisa siempre los servicios y el firewall después de restaurar:

systemctl --failed
systemctl status ollama litellm
sudo ufw status verbose
nvidia-smi

Tool calling y rutas de Windows

Cuando un modelo envía rutas de Windows dentro de argumentos JSON, las barras invertidas deben estar escapadas. Por ejemplo:

{
  "path": "C:\\Users\\name\\file.txt"
}

Si las barras no están escapadas, el parser JSON puede fallar antes de que la herramienta llegue a ejecutarse.

Archivos principales

• setup_llm_server.sh: instala y configura Ollama, LiteLLM, NVIDIA y UFW.
• install_openclaw.sh: instala OpenClaw mediante el instalador oficial.
• litellm_config.yaml: configuración local opcional para LiteLLM.
• tool_call_demo.py: ejemplo local de manejo de llamadas a herramientas.

Seguridad

El instalador expone Ollama en todas las interfaces y abre el puerto 8000 en UFW. En un servidor conectado a Internet, limita esos puertos a la red privada o protégelos detrás de un proxy con autenticación y HTTPS.