carlostellocba/llm-server-setup

Fork 0

Files

T

Carlos Tello 2b3e0e605a Document Windows SSH access to OpenClaw

2026-09-21 11:02:32 -03:00

11 KiB

Raw Permalink 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. Acceder desde Windows con PuTTY o PowerShell

En este servidor, la IP de la máquina Ubuntu es:

192.168.0.225

El Gateway está enlazado intencionalmente a 127.0.0.1:18789, por lo que no debes abrir 192.168.0.225:18789 directamente. Usa un túnel SSH desde el PC Windows.

PowerShell

Ejecuta este comando en PowerShell del PC cliente:

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

Introduce la contraseña de ctello y deja esa ventana abierta. El parámetro -L significa:

Puerto local del PC:18789 -> servidor:127.0.0.1:18789

En otra ventana de PowerShell, comprueba el túnel:

Test-NetConnection 127.0.0.1 -Port 18789

Debe mostrar:

TcpTestSucceeded : True

Después abre el dashboard en el navegador del PC:

http://127.0.0.1:18789

Si el puerto local 18789 ya está ocupado, usa otro puerto solo en el PC:

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

En ese caso abre:

http://127.0.0.1:18790

El destino remoto sigue siendo siempre 127.0.0.1:18789.

PuTTY

Configura la sesión con:

Host Name: 192.168.0.225
Port: 22
Connection type: SSH

Después ve a Connection > SSH > Tunnels y añade:

Source port: 18789
Destination: 127.0.0.1:18789
Type: Local

Pulsa Add, conecta la sesión y abre en el navegador:

http://127.0.0.1:18789

Mantén abierta la sesión SSH mientras uses el dashboard.

9. 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

Gateway activo, pero el navegador muestra `ERR_CONNECTION_REFUSED`

Comprueba el estado en Ubuntu:

openclaw gateway status
ss -ltnp | grep 18789

Debe aparecer:

Runtime: running
Connectivity probe: ok
Listening: 127.0.0.1:18789

Si el Gateway no está activo, configura el modo local y arráncalo:

openclaw config set gateway.mode local
openclaw gateway install
openclaw gateway status

Si el servicio de usuario necesita una sesión persistente, habilita el linger para ctello desde una cuenta con sudo:

sudo loginctl enable-linger ctello

Después vuelve a iniciar sesión SSH como ctello y ejecuta:

systemctl --user daemon-reload
systemctl --user enable --now openclaw-gateway.service

Si systemctl --user muestra que faltan DBUS_SESSION_BUS_ADDRESS o XDG_RUNTIME_DIR, vuelve a conectarte por SSH después de habilitar linger. No ejecutes un segundo openclaw gateway run si el servicio ya está activo.

Para revisar errores:

journalctl --user -u openclaw-gateway.service -n 100 --no-pager

El túnel de PowerShell no conecta

En el PC cliente verifica primero que SSH funciona:

Test-NetConnection 192.168.0.225 -Port 22

Si SSH responde pero el puerto del túnel no, comprueba en Ubuntu que el Gateway esté escuchando en 127.0.0.1:18789. No abras el puerto 18789 en UFW ni cambies el Gateway a 0.0.0.0 solo para evitar el túnel.

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

11 KiB Raw Permalink Blame History