Anatomía de un agente IA
en un servidor real.

El VPS — Tu Servidor en la Nube

Un VPS (Virtual Private Server) es una computadora virtual alquilada en un datacenter. OpenClaw corre ahí 24/7, sin depender de que tu PC esté encendida.

# Verificar recursos del servidor
echo "--- CPU ---"; lscpu | grep "CPU(s):"
echo "--- RAM ---"; free -h
echo "--- DISCO ---"; df -h /

Instalación — De Cero a Agente Corriendo

La documentación oficial ofrece dos caminos para instalar OpenClaw. Cuál elegir depende de si querés correrlo directamente en el sistema o dentro de un contenedor Docker.

El comando oficial (one-liner)

Según la documentación oficial, la forma más rápida de instalar es un solo comando que hace todo automáticamente:

# ⭐ INSTALACIÓN OFICIAL — Un solo comando
# Detecta tu SO, instala Node.js si falta, instala OpenClaw, y lanza el onboarding
curl -fsSL https://openclaw.ai/install.sh | bash

Eso es literalmente todo. El script:

→ Verifica que tengas Node.js 24 (o 22.14+) — si no, lo instala.
→ Instala OpenClaw globalmente vía npm.
→ Lanza el wizard de onboarding que te guía para elegir modelo, API key, canal de chat y skills.
→ Instala el daemon como servicio del sistema (launchd en macOS, systemd en Linux) para que quede corriendo 24/7.

Si preferís hacerlo paso a paso

# Paso 1: Instalar OpenClaw globalmente
npm install -g openclaw@latest
# Alternativa: pnpm add -g openclaw@latest

# Paso 2: Lanzar onboarding + instalar daemon
openclaw onboard --install-daemon

# Paso 3: Verificar la instalación
openclaw --version       # versión instalada
openclaw doctor          # diagnóstico del entorno
openclaw gateway status  # verificar que el Gateway escucha

¿Qué pasa durante el onboarding?

Instalación vía Docker (para VPS)

# Levantar OpenClaw como contenedor — ideal para servidores
docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -e OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN} \
  -e HOME=/home/node \
  -e OPENCLAW_STATE_DIR=/home/node/.openclaw \
  -e OPENCLAW_CONFIG_DIR=/home/node/.openclaw \
  -e OPENCLAW_WORKSPACE_DIR=/home/node/.openclaw/workspace \
  -v /home/openclaw/.openclaw:/home/node/.openclaw \
  -p 18789:18789 \
  ghcr.io/openclaw/openclaw:latest

# Luego correr el wizard dentro del contenedor
docker exec -it openclaw openclaw onboard

Fuente oficial

📖 docs.openclaw.ai/install — Guía completa de instalación
💻 github.com/openclaw/openclaw — Repositorio oficial y README
📦 npmjs.com/package/openclaw — Paquete npm

Docker — El Contenedor

Docker encapsula OpenClaw y todas sus dependencias en un contenedor aislado. Si algo falla adentro, el sistema base del VPS no se ve afectado. Pensalo como una caja fuerte: lo que pasa adentro, queda adentro.

El flag -v en Docker monta la carpeta del host dentro del contenedor. Así tus archivos de configuración y memoria sobreviven a reinicios, actualizaciones y recreaciones del contenedor.

# Instalar Docker
apt install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sh

# Agregar usuario al grupo docker
usermod -aG docker openclaw

# Crear directorios persistentes
mkdir -p ~/.openclaw/workspace
mkdir -p ~/.openclaw/credentials

Gateway — La Centralita

El Gateway es el componente más importante de OpenClaw. Funciona como un servidor WebSocket local que recibe mensajes de todos los canales, los rutea al Agent, y devuelve las respuestas. También sirve el Control UI (panel web) y gestiona sesiones, eventos y herramientas.

Cuando arrancás el contenedor con -p 18789:18789, exponés el Gateway para que puedas acceder al panel de control. Pero nunca lo expongas directamente a internet — usá un túnel SSH.

# Configuración mínima del Gateway (openclaw.json)
{
  "gateway": {
    "mode": "local",
    "bind": "lan",
    "port": 18789,
    "auth": { "mode": "token" }
  },
  "agents": {
    "defaults": {
      "workspace": "/home/node/.openclaw/workspace"
    }
  }
}

Agent — El Cerebro

El Agent es el componente que piensa. Recibe las instrucciones del Gateway, las procesa usando el LLM externo, y decide qué herramientas usar, qué archivos leer o escribir, y qué responder. Es la pieza que tiene "personalidad" — configurada en los archivos del Workspace.

El Agent no es directamente configurable con un archivo propio — se configura indirectamente a través de los archivos del Workspace (su personalidad), del modelo LLM que le asignes (su inteligencia), y de las skills instaladas (sus capacidades).

Workspace — La Memoria Persistente

El Workspace es una carpeta en el host (no dentro del contenedor) que se monta vía volumen Docker. Contiene archivos Markdown que definen quién es tu agente, qué puede hacer, y qué recuerda. Si destruís el contenedor, el Workspace permanece intacto.

Channels — Los Canales de Comunicación

Los Channels son las plataformas de mensajería por las que hablás con tu agente. Cada channel tiene su propia librería de conexión (Baileys para WhatsApp, grammY para Telegram, discord.js para Discord, etc.) y se configura con un token o credencial específica.

Configurar Telegram (el más rápido)

# 1. En Telegram: buscar @BotFather → /newbot → copiar token
# 2. En el VPS:
openclaw config set channels.telegram.botToken "TU_TOKEN"
docker restart openclaw

# 3. Verificar conexión:
docker logs openclaw --tail 20 | grep -i telegram
# Debe decir: [telegram] [default] starting provider

Skills — Las Herramientas

Las Skills son extensiones que amplían lo que el Agent puede hacer. Van desde búsqueda web (DuckDuckGo) hasta lectura de PDFs, control de Home Assistant, o integración con GitHub. Se instalan desde ClawHub o durante el wizard de onboarding.

LLM Externo — La Inteligencia

OpenClaw no tiene inteligencia propia — se la da el modelo que le conectes. Puede ser ChatGPT, Claude, Gemini, DeepSeek, o un modelo local vía Ollama. El método de conexión más conveniente para ChatGPT es OAuth, que usa tu suscripción Plus/Pro sin cargos adicionales por token.

Autenticar con ChatGPT vía OAuth

# Usar tu suscripción ChatGPT Plus/Pro (sin cargos por API)
docker exec -it openclaw openclaw models auth login --provider openai-codex

# 1. Copiar la URL que imprime
# 2. Abrirla en tu browser → loguear con tu cuenta ChatGPT
# 3. Copiar la URL de callback final y pegarla en la terminal

# Setear modelo por defecto
openclaw config set agents.defaults.model.primary "openai/gpt-5.4-mini"
docker restart openclaw

Autenticación y Tokens

OpenClaw usa dos tipos de credenciales que es crucial no confundir:

Ambos se almacenan en texto plano en archivos locales (.env y openclaw.json). Tratá ~/.openclaw/ como si fuera un password vault — si alguien accede a esa carpeta, tiene control total de tu agente y de las APIs conectadas.

Pairing — La Verificación de Identidad

El sistema de pairing es la capa de seguridad que controla quién puede usar tu bot. Cuando alguien le escribe por primera vez, el agente genera un código que vos tenés que aprobar desde el servidor. Sin tu aprobación, nadie puede interactuar con él.

Después del pairing, arranca el bootstrap: el agente te pregunta tu nombre, elige el suyo, y llena IDENTITY.md y USER.md a partir de esa primera conversación.

Control UI — El Panel de Administración

El Control UI es un panel web que corre en el puerto 18789. Desde ahí podés chatear con el agente, ver logs, cambiar configuración, y monitorear el estado del Gateway. Se accede exclusivamente vía túnel SSH por seguridad.

# Crear túnel SSH desde tu PC local
ssh -L 18789:localhost:18789 -p TU_PUERTO_SSH openclaw@TU_IP

# Obtener el token del Gateway (desde el VPS)
docker exec openclaw cat /home/node/.openclaw/openclaw.json | grep -A3 '"mode": "token"'

# Luego abrir en el browser:
# http://localhost:18789
# Pegar el token que devolvió el comando anterior

Aprobación del dispositivo (paso obligatorio)

Al abrir el Control UI por primera vez, el browser te va a mostrar un mensaje de "Emparejamiento de dispositivo requerido". No es un error — es una capa de seguridad. Cada navegador nuevo necesita aprobación explícita desde el VPS antes de poder usar el panel.

# 1. Listar dispositivos pendientes de aprobación
openclaw devices list

# 2. Aprobar el navegador (copiar el ID que apareció)
openclaw devices approve xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 3. Volver al browser y recargar la página
# El Control UI ya carga completo