llm-server-setup/OPENCLAW_LOCAL_SERVER.md

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

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

```text
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:

```powershell
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:

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

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

```powershell
Test-NetConnection 127.0.0.1 -Port 18789
```

Debe mostrar:

```text
TcpTestSucceeded : True
```

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

```text
http://127.0.0.1:18789
```

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

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

En ese caso abre:

```text
http://127.0.0.1:18790
```

El destino remoto sigue siendo siempre `127.0.0.1:18789`.

### PuTTY

Configura la sesión con:

```text
Host Name: 192.168.0.225
Port: 22
Connection type: SSH
```

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

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

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

```text
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`:

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

### Gateway activo, pero el navegador muestra `ERR_CONNECTION_REFUSED`

Comprueba el estado en Ubuntu:

```bash
openclaw gateway status
ss -ltnp | grep 18789
```

Debe aparecer:

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

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

```bash
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`:

```bash
sudo loginctl enable-linger ctello
```

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

```bash
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:

```bash
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:

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

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