1. Por qué instalar OpenClaw en un VPS Linux
OpenClaw permite ejecutar un agente de IA en tu propio servidor Linux, con tu configuración, tus claves API y tus integraciones. En un VPS, esto te permite mantener el control del entorno de ejecución mientras el agente sigue funcionando de forma continua.
Este tipo de despliegue es útil si quieres:
- centralizar varias herramientas detrás de una sola interfaz de IA
- ejecutar un bot o un asistente de forma continua
- mantener los datos y la configuración del lado del servidor
- acceder al panel a distancia sin depender de que un ordenador local esté encendido
En esta guía veremos la instalación, el acceso remoto, la configuración del proveedor de IA, la gestión del servicio, el mantenimiento y los puntos de seguridad más importantes en un VPS.
2. Preparar tu VPS Linux
Para seguir este tutorial necesitas:
- un VPS Linux con acceso SSH
- un usuario con permisos para instalar paquetes si hace falta
curlygitsi usas el script de instalación o la instalación desde el código fuentecorepacksi piensas usar la vía avanzada desde el repositorio Git conpnpm- una clave API de un proveedor de modelos para terminar la configuración
Para el runtime, OpenClaw recomienda Node 24. Node 22 sigue siendo compatible a partir de Node 22.16.
En Debian o Ubuntu, puedes instalar las utilidades básicas si hace falta:
sudo apt update
sudo apt install -y curl git
3. Instalación rápida con el script de instalación
Si quieres el método más sencillo, el script oficial de instalación puede preparar el entorno y lanzar la instalación automáticamente.
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
En un VPS Linux, este script detecta la distribución, instala Node si hace falta y luego instala OpenClaw.
Si prefieres instalar OpenClaw sin iniciar el onboarding inmediatamente:
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard
Después puedes terminar la instalación con el comando recomendado para un VPS:
openclaw onboard --install-daemon
4. Instalación manual recomendada con Node y npm
Si prefieres controlar cada paso, instala primero Node y después el CLI de OpenClaw.
Empieza comprobando tu versión de Node:
node -v
Si Node todavía no está instalado, instala Node 24, o como mínimo Node 22.16, con el método adecuado para tu distribución.
Después ejecuta:
npm i -g openclaw@latest
openclaw onboard --install-daemon
El comando de onboarding configura OpenClaw e instala el daemon del gateway, que encaja con la mayoría de despliegues en VPS.
5. Instalación desde el código fuente, caso avanzado
Si tienes una razón concreta para ejecutar OpenClaw desde el repositorio Git en lugar del paquete npm, usa este método:
git clone https://github.com/openclaw/openclaw.git
cd openclaw
corepack enable
corepack prepare pnpm@latest --activate
pnpm install
pnpm build
pnpm ui:build
pnpm link --global
openclaw onboard --install-daemon
Para un VPS clásico, es mejor quedarse con la instalación vía npm mostrada más arriba.
6. Acceder al panel de forma remota y segura
En un VPS, la buena práctica es mantener el gateway de OpenClaw accesible solo en local y abrir un túnel desde tu propio ordenador.
Empieza comprobando el estado del Gateway y el puerto realmente configurado:
openclaw gateway status
Si necesitas acceso remoto, prioriza un túnel SSH:
ssh -N -L 18789:127.0.0.1:18789 user@your-vps
Después abre esto en tu navegador local:
http://127.0.0.1:18789/
Después usarás el token o la contraseña configurados durante el onboarding para autenticarte.
En la pantalla de acceso del Gateway, comprueba la URL WebSocket local, el modo de autenticación y el secreto de conexión. Con un túnel SSH, mantén una URL local como esta:
ws://127.0.0.1:18789
Evita sustituir ese campo por la IP pública en bruto del VPS.
Una vez aplicada la conexión, el panel debe mostrar un estado de conexión correcto. Si la interfaz no conecta, vuelve a comprobar primero el túnel SSH, el secreto de conexión y el puerto del Gateway antes de cambiar la configuración.
Si prefieres una URL pública en lugar de un túnel SSH, la variante con Nginx + HTTPS de abajo te permite publicar el acceso correctamente sin exponer directamente el puerto del Gateway.
6.1. Acceso público con Nginx y HTTPS
Si prefieres acceder con el navegador mediante una URL pública en lugar de un túnel SSH, no expongas directamente el puerto del Gateway en Internet. Mantén OpenClaw escuchando en 127.0.0.1:18789 y coloca Nginx delante con HTTPS.
Así obtienes una URL sencilla como:
https://openclaw.example.com
mientras mantienes el servicio real de OpenClaw privado en el VPS.
Arquitectura recomendada:
Internet
↓
Nginx en HTTPS
↓
OpenClaw Gateway en local sobre 127.0.0.1:18789
Antes de empezar, haz que el dominio o subdominio elegido apunte a la IP pública del VPS.
Instala los paquetes necesarios:
sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx
Crea un vhost dedicado de Nginx:
sudo nano /etc/nginx/sites-available/openclaw
Empieza con una configuración HTTP sencilla para que Certbot pueda emitir el certificado:
server {
listen 80;
server_name openclaw.example.com;
location / {
return 200 "OpenClaw Nginx vhost is ready\n";
add_header Content-Type text/plain;
}
}
Activa el sitio, valida la configuración, recarga Nginx y luego genera el certificado HTTPS:
sudo ln -sf /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/openclaw
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d openclaw.example.com
Una vez generado el certificado, sustituye la configuración por esta versión final:
server {
listen 80;
server_name openclaw.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
server_name openclaw.example.com;
ssl_certificate /etc/letsencrypt/live/openclaw.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/openclaw.example.com/privkey.pem;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
client_max_body_size 20m;
location / {
proxy_pass http://127.0.0.1:18789;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}
}
Valida y recarga Nginx:
sudo nginx -t
sudo systemctl reload nginx
Para un acceso mediante dominio público, añade también el origen HTTPS permitido en la configuración de OpenClaw. Si el archivo todavía no existe, créalo:
nano ~/.openclaw/openclaw.json
Ejemplo mínimo para un Nginx local ejecutándose en el mismo VPS que OpenClaw:
{
gateway: {
controlUi: {
allowedOrigins: ["https://openclaw.example.com"]
},
trustedProxies: ["127.0.0.1/32", "::1/128"]
}
}
Abre ~/.openclaw/openclaw.json y añade estas claves dentro de la configuración existente. No sobrescribas todo el archivo con este ejemplo.
En este tutorial, con Nginx ejecutándose en el mismo VPS que OpenClaw, configura siempre estos tres puntos:
gateway.controlUi.allowedOriginscon tu dominio HTTPS públicogateway.trustedProxiescon127.0.0.1/32y::1/128- la autenticación nativa del Gateway por contraseña o token
trustedProxies es obligatorio en este escenario local Nginx → OpenClaw. Sin él, la primera conexión web pública puede tratarse como no fiable, lo que acaba en errores de pairing o de autorización difíciles de entender.
Si el HTTPS termina en otra máquina, sustituye 127.0.0.1/32 y ::1/128 por la IP o el CIDR real de ese proxy.
Después reinicia el Gateway:
openclaw gateway restart
Cuando abras el panel desde la URL pública, usa:
https://openclaw.example.com
Si la interfaz te pide una URL WebSocket del Gateway, usa esta en su lugar:
wss://openclaw.example.com
No uses la IP pública en bruto del VPS como URL del Gateway. En esta configuración, el acceso público debe pasar por el dominio HTTPS expuesto por Nginx: es lo que coincide con el certificado TLS, con gateway.controlUi.allowedOrigins y con la ruta pública configurada a través del proxy. Con la IP en bruto, es fácil que falle la verificación del certificado o del origen, o que termines saltándote la ruta prevista hacia el Gateway.
Si quieres añadir más adelante una Basic Auth HTTP delante de Nginx, hazlo solo después de validar que el conjunto HTTPS + autenticación nativa de OpenClaw ya funciona correctamente. Según el cliente o el navegador, una capa HTTP adicional puede romper el flujo WebSocket del Control UI si está mal colocada o mal probada.
6.2. Primera conexión pública y pairing del navegador
En la primera conexión desde un navegador nuevo, OpenClaw puede pedir una aprobación one-shot del dispositivo antes de abrir por completo el Control UI público. Este comportamiento es normal.
Si la interfaz muestra Device pairing required, conéctate al VPS por SSH y ejecuta primero:
openclaw devices list
Después aprueba la solicitud pendiente más reciente:
openclaw devices approve --latest
Si quieres aprobar una solicitud concreta, también puedes usar el identificador exacto:
openclaw devices approve <requestId>
Y si el CLI te pide explícitamente el secreto del Gateway, añade simplemente la contraseña configurada durante el onboarding:
openclaw devices approve --latest --password 'your-gateway-password'
Una vez completada la aprobación, recarga la página o vuelve a pulsar Connect. En la mayoría de los casos solo tendrás que hacer esto una vez por navegador o dispositivo aprobado.
Si usas UFW, comprueba primero su estado:
sudo ufw status
Si UFW ya está activo, añade simplemente las reglas útiles. El perfil OpenSSH solo sirve para conservar tu acceso SSH de administración al VPS y el túnel mostrado más arriba, no OpenClaw en sí:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw deny 18789/tcp
Si UFW todavía no está activado en tu VPS y quieres usarlo, actívalo después:
sudo ufw enable
Si gestionas el filtrado directamente con iptables, mantén la misma lógica: deja pasar SSH, HTTP y HTTPS, y luego bloquea el puerto 18789 desde el exterior. No bloquees el tráfico local loopback, porque Nginx todavía necesita alcanzar OpenClaw en 127.0.0.1.
Si tu servidor SSH escucha en un puerto diferente, sustituye 22 por el valor correcto.
Ejemplo:
sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT
sudo iptables -A INPUT ! -i lo -p tcp --dport 18789 -j DROP
Si quieres mantener un acceso puramente privado, el túnel SSH sigue siendo la opción más simple. Un VPN privado o una red privada mallada equivalente también es una buena alternativa si quieres un acceso privado más permanente, sin exponer directamente el Gateway en Internet.
7. Verificar la instalación y hacer una primera prueba
Una vez instalado OpenClaw, estos son los comandos más útiles:
openclaw --version
openclaw doctor
openclaw status
openclaw gateway status --deep
Estos comandos te ayudan a detectar rápidamente un problema de PATH, de versión de Node, de configuración o del gateway.
Te permiten verificar:
- que el CLI está disponible en tu
PATH - que la configuración no contiene un error evidente
- que el gateway está instalado y responde correctamente
Para seguir los logs en tiempo real:
openclaw logs --follow
La idea no es leer toda la salida línea por línea, sino confirmar que no aparece ningún error bloqueante durante el arranque. Si el CLI está sano y el panel se abre correctamente, puedes pasar a la configuración del proveedor antes de la primera prueba real en el chat.
7.1. Configurar el proveedor de IA y la clave API antes de la primera prueba
El lugar clave para conectar OpenAI u otro proveedor es Settings > AI & Agents > Models. En esta vista añades o editas una entrada de proveedor y luego le indicas a OpenClaw cómo debe hablar con tu backend de IA.
El campo Model Provider API Adapter sirve para elegir el protocolo esperado por tu proveedor. Para un backend compatible con OpenAI, normalmente elegirás openai-responses o azure-openai-responses. Para Anthropic, el valor esperado suele ser anthropic-messages, y para Gemini google-generative-ai.
Justo debajo, Model Provider API Key es el lugar donde pegas tu clave API. La misma tarjeta también te permite ajustar el modo de autenticación, la URL base del proveedor y la lista de modelos expuestos en la interfaz.
La ruta que debes recordar es sencilla: abre Settings, entra en AI & Agents, cambia a Models y luego edita la entrada de tu proveedor antes de guardar. Ahí es donde conectas OpenClaw con tu clave de OpenAI, Anthropic, Gemini o cualquier otro backend compatible.
Una vez guardada esta configuración, vuelve a la pestaña Chat. Es en ese momento cuando puedes lanzar un primer intercambio útil y comprobar que la interfaz responde de verdad a través del proveedor que acabas de conectar.
8. Gestionar el servicio en un VPS
En un VPS típico, normalmente no hace falta escribir a mano un servicio systemd. Los siguientes comandos cubren el caso estándar:
openclaw onboard --install-daemon
o
openclaw gateway install
Para las operaciones habituales del servicio:
openclaw gateway status
openclaw gateway restart
openclaw logs --follow
Estos comandos te permiten comprobar el estado del servicio, reiniciarlo limpiamente y seguir los logs inmediatamente.
En Linux, OpenClaw suele instalar una unidad systemd a nivel de usuario. Si el servicio no sigue activo después de cerrar tu sesión SSH, activa el linger para tu cuenta:
sudo loginctl enable-linger $USER
En un VPS headless, comprueba esto si el servicio se detiene después de desconectarte por SSH.
Para confirmar visualmente que OpenClaw conserva tus conversaciones en la interfaz, la vista Sessions ofrece un resumen rápido de las sesiones activas que sigue actualmente el agente.
Si necesitas volver a activar explícitamente la unidad de usuario:
systemctl --user enable --now openclaw-gateway.service
Si utilizas un perfil de OpenClaw con nombre, el servicio puede llamarse así:
systemctl --user enable --now openclaw-gateway-<profile>.service
Si quieres un servicio de sistema dedicado, también puedes crear una unidad manual en /etc/systemd/system/openclaw-gateway.service en lugar de depender solo de la unidad a nivel de usuario.
9. Mantenimiento, actualizaciones y desinstalación
Para mantener tu instancia actualizada:
openclaw update
openclaw doctor
openclaw gateway restart
Si quieres desinstalar OpenClaw limpiamente, primero mira qué se va a eliminar:
openclaw uninstall --dry-run
Después ejecuta la desinstalación si el resultado te parece correcto:
openclaw uninstall
10. Proteger los canales de mensajería
Si conectas OpenClaw a Discord, Telegram, WhatsApp, Slack u otros canales, no abras los DMs públicamente sin protecciones.
Quédate con estas reglas simples:
- mantén una política de tipo pairing o allowlist para los mensajes privados
- permite explícitamente solo los remitentes o cuentas que esperas
- evita el modo abierto hasta haber validado tu configuración de acceso
- separa claramente el acceso normal de usuario de las acciones de administración o aprobación
En varias integraciones, el modo pairing existe precisamente para evitar que un remitente desconocido pueda hablar libremente con tu agente desde el primer mensaje.
11. Problemas frecuentes y soluciones
11.1. openclaw: command not found
Lo habitual es que el CLI no esté en tu PATH.
Primero comprueba el prefijo global de npm:
npm prefix -g
Después añade el directorio bin relacionado a tu perfil de shell:
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Luego vuelve a probar:
openclaw --version
11.2. Versión de Node demasiado antigua
Comprueba tu versión:
node -v
Si estás por debajo de Node 22.16, actualiza Node antes de volver a lanzar la instalación.
11.3. El gateway no arranca o el puerto ya está en uso
Los comandos más útiles son:
openclaw gateway status
openclaw gateway status --deep
openclaw doctor
Comprueba primero el puerto realmente configurado y luego adapta tu túnel SSH o tu configuración si ese puerto ya está siendo usado por otro servicio.
11.4. El servicio se detiene después de cerrar SSH
En un servidor headless, comprueba que el linger de systemd a nivel de usuario está activado:
sudo loginctl enable-linger $USER
11.5. Errores de permisos en ~/.openclaw
Si ves Permission denied o EACCES, asegúrate de usar siempre el mismo usuario para ejecutar OpenClaw y luego corrige los permisos:
sudo chown -R $USER:$USER ~/.openclaw
12. Buenas prácticas de seguridad
Para un despliegue limpio en VPS:
- mantén el gateway ligado a
127.0.0.1 - prioriza un túnel SSH, o un VPN privado o una red privada mallada equivalente si quieres un acceso privado más permanente
- si expones una URL pública, usa HTTPS, Nginx y la autenticación nativa del Gateway de OpenClaw
- si añades una capa de autenticación delante de Nginx, vuelve a validar siempre el flujo WebSocket del Control UI antes de dejarla en producción
- no publiques nunca directamente el puerto del Gateway de OpenClaw en Internet
- comprueba siempre el modo de autenticación del Gateway antes de abrir acceso remoto
- haz copias de seguridad de
~/.openclawcon regularidad - evita mezclar varios usos sensibles bajo la misma cuenta del sistema
13. Qué hacer después
Una vez que OpenClaw funcione en tu VPS, podrás añadir canales, conectar herramientas y hacer evolucionar tu agente según tus necesidades. Si quieres probar esta instalación en una máquina adecuada para este tipo de uso, puedes lanzar tu servidor VPS gratis y seguir los mismos pasos de esta guía.