526 lines
11 KiB
Markdown
526 lines
11 KiB
Markdown
# 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)
|