Hetzner

Aprovisionar el VPS

Crea un VPS Ubuntu o Debian en Hetzner.

Conéctate como root:

ssh root@YOUR_VPS_IP

Esta guía presupone que el VPS es con estado. No lo trates como infraestructura desechable.

Instalar Docker (en el VPS)

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

Verifica:

docker --version
docker compose version

Clonar el repositorio de OpenClaw

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Esta guía presupone que compilarás una imagen personalizada para garantizar la persistencia de los binarios.

Crear directorios persistentes en el host

Los contenedores Docker son efímeros. Todo estado de larga duración debe vivir en el host.

mkdir -p /root/.openclaw/workspace

# Set ownership to the container user (uid 1000):
chown -R 1000:1000 /root/.openclaw

Configurar variables de entorno

Crea .env en la raíz del repositorio.

OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789

OPENCLAW_CONFIG_DIR=/root/.openclaw
OPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace

GOG_KEYRING_PASSWORD=
XDG_CONFIG_HOME=/home/node/.openclaw

Define OPENCLAW_GATEWAY_TOKEN cuando quieras gestionar el token estable del gateway mediante .env; de lo contrario, configura gateway.auth.token antes de depender de clientes entre reinicios. Si ninguna de las dos fuentes existe, OpenClaw usa un token solo de runtime para ese arranque. Genera una contraseña de llavero y pégala en GOG_KEYRING_PASSWORD:

openssl rand -hex 32

No confirmes este archivo en git.

Este archivo .env es para env de contenedor/runtime, como OPENCLAW_GATEWAY_TOKEN. La autenticación OAuth/clave API de proveedores almacenada vive en el archivo montado ~/.openclaw/agents/<agentId>/agent/auth-profiles.json.

Configuración de Docker Compose

Crea o actualiza docker-compose.yml.

services:
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE}
    build: .
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - HOME=/home/node
      - NODE_ENV=production
      - TERM=xterm-256color
      - OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND}
      - OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT}
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
      - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    ports:
      # Recommended: keep the Gateway loopback-only on the VPS; access via SSH tunnel.
      # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND}",
        "--port",
        "${OPENCLAW_GATEWAY_PORT}",
        "--allow-unconfigured",
      ]

--allow-unconfigured es solo para facilitar el arranque inicial, no sustituye una configuración de Gateway adecuada. Aun así, configura la autenticación (gateway.auth.token o contraseña) y usa ajustes de enlace seguros para tu despliegue.

Pasos compartidos del runtime de VM Docker

Usa la guía de runtime compartido para el flujo común de host Docker:

• Integrar los binarios requeridos en la imagen
• Compilar y lanzar
• Qué persiste y dónde
• Actualizaciones

Acceso específico de Hetzner

Después de los pasos compartidos de compilación y lanzamiento, completa la siguiente configuración para abrir el túnel:

Requisito previo: Asegúrate de que la configuración de sshd de tu VPS permite el reenvío TCP. Si has reforzado tu configuración de SSH, revisa /etc/ssh/sshd_config y define:

AllowTcpForwarding local

local permite reenvíos locales ssh -L desde tu portátil y bloquea reenvíos remotos desde el servidor. Configurarlo en no hará que el túnel falle con: channel 3: open failed: administratively prohibited: open failed

Después de confirmar que el reenvío TCP está habilitado, reinicia el servicio SSH (systemctl restart ssh) y ejecuta el túnel desde tu portátil:

ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP

Abre:

http://127.0.0.1:18789/

Pega el secreto compartido configurado. Esta guía usa el token del gateway de forma predeterminada; si cambiaste a autenticación por contraseña, usa esa contraseña en su lugar.