carlostellocba/llm-server-setup

Fork 0

Files

T

Carlos Tello 9bd3d1052d Document OpenClaw with local LLM server

2026-09-21 10:13:30 -03:00

8.3 KiB

Raw Blame History

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. Esta guía adapta el flujo de configuración a este servidor local y no depende de un proveedor cloud.

Arquitectura

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:

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:

sudo reboot

2. Verificar Ollama y LiteLLM

Ejecuta estas comprobaciones en el servidor:

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:

ollama list

La configuración generada por setup_llm_server.sh está en:

~/litellm_config.yaml

El servicio LiteLLM debe ejecutarse con esa configuración y escuchar en el puerto 8000. Para revisar errores:

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:

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:

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 install_openclaw.sh

El script instala OpenClaw sin iniciar el asistente. También puedes ejecutar el instalador oficial directamente:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

Comprueba Node.js y OpenClaw:

node --version
openclaw --version

5. Configurar OpenClaw con LiteLLM local

La configuración de OpenClaw se guarda en:

~/.openclaw/openclaw.json

Crea o edita ese archivo como 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:

openclaw doctor
openclaw models list --provider litellm --refresh --json

6. Configurar con el asistente

Como alternativa a editar JSON5, ejecuta el onboarding indicando LiteLLM:

openclaw onboard --auth-choice litellm-api-key

Cuando solicite la URL del proxy, usa:

http://127.0.0.1:8000/v1

Y como API key local:

local

Si el asistente permite modo no interactivo en tu versión instalada:

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:

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:

openclaw gateway install
openclaw gateway status

El Gateway normalmente escucha en el puerto 18789. Abre el dashboard:

openclaw dashboard

También puedes verificarlo desde el navegador en:

http://127.0.0.1:18789

Prueba un mensaje desde el dashboard. En otra terminal puedes observar los logs del Gateway:

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:

{
  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:

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

sudo systemctl restart ollama litellm
sudo systemctl status ollama litellm
sudo journalctl -u litellm -n 100 --no-pager

LiteLLM no encuentra el modelo

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:

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:

openclaw config get models.providers.litellm.baseUrl

Debe devolver:

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:

nvidia-smi

La configuración no es válida

openclaw doctor
openclaw doctor --fix

OpenClaw valida estrictamente openclaw.json; un campo desconocido o un tipo incorrecto puede impedir que el Gateway arranque.

8.3 KiB Raw Blame History