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