OpenClaw en GCP Compute Engine (Docker, Guía VPS de Producción)

Objetivo

Ejecutar un Gateway de OpenClaw persistente en una VM de GCP Compute Engine usando Docker, con estado duradero, binarios incluidos en la imagen y comportamiento seguro de reinicio.

Si quieres “OpenClaw 24/7 por ~$5-12/mes”, esta es una configuración confiable en Google Cloud. El precio varía según el tipo de máquina y la región; elige la VM más pequeña que se ajuste a tu carga de trabajo y escala si encuentras OOMs.

¿Qué vamos a hacer (en términos simples)?

Crear un proyecto GCP y habilitar facturación
Crear una VM de Compute Engine
Instalar Docker (runtime aislado de aplicaciones)
Iniciar el Gateway de OpenClaw en Docker
Persistir ~/.openclaw + ~/.openclaw/workspace en el host (sobrevive a reinicios/recompilaciones)
Acceder al Control UI desde tu portátil vía túnel SSH

El Gateway se puede acceder vía:

Reenvío de puertos SSH desde tu portátil
Exposición directa de puertos si gestionas el firewall y tokens tú mismo

Esta guía usa Debian en GCP Compute Engine. Ubuntu también funciona; adapta los paquetes en consecuencia. Para el flujo genérico de Docker, consulta Docker.

Ruta rápida (operadores experimentados)

Crear proyecto GCP + habilitar Compute Engine API
Crear VM de Compute Engine (e2-small, Debian 12, 20GB)
SSH a la VM
Instalar Docker
Clonar el repositorio de OpenClaw
Crear directorios persistentes en el host
Configurar .env y docker-compose.yml
Incluir binarios requeridos, compilar y lanzar

Qué necesitas

Cuenta GCP (el tier gratuito aplica para e2-micro)
gcloud CLI instalado (o usar la Consola Cloud)
Acceso SSH desde tu portátil
Familiaridad básica con SSH + copiar/pegar
~20-30 minutos
Docker y Docker Compose
Credenciales de autenticación del modelo
Credenciales opcionales de proveedores
- QR de WhatsApp
- Token de bot de Telegram
- OAuth de Gmail

1) Instalar gcloud CLI (o usar la Consola)

Opción A: gcloud CLI (recomendado para automatización)

Instalar desde https://cloud.google.com/sdk/docs/install

Inicializar y autenticar:

gcloud init
gcloud auth login

Opción B: Consola Cloud

Todos los pasos se pueden hacer vía la interfaz web en https://console.cloud.google.com

2) Crear un proyecto GCP

CLI:

gcloud projects create my-openclaw-project --name="OpenClaw Gateway"
gcloud config set project my-openclaw-project

Habilita la facturación en https://console.cloud.google.com/billing (requerido para Compute Engine).

Habilita la API de Compute Engine:

gcloud services enable compute.googleapis.com

Consola:

Ve a IAM y Admin > Crear proyecto
Nombra el proyecto y créalo
Habilita la facturación para el proyecto
Navega a APIs y Servicios > Habilitar APIs > busca “Compute Engine API” > Habilitar

3) Crear la VM

Tipos de máquina:

Tipo	Especificaciones	Costo	Notas
e2-medium	2 vCPU, 4GB RAM	~$25/mes	La más confiable para builds Docker locales
e2-small	2 vCPU, 2GB RAM	~$12/mes	Mínimo recomendado para build Docker
e2-micro	2 vCPU (compartida), 1GB RAM	Elegible para tier gratuito	Suele fallar con OOM en build Docker (exit 137)

CLI:

gcloud compute instances create openclaw-gateway \
  --zone=us-central1-a \
  --machine-type=e2-small \
  --boot-disk-size=20GB \
  --image-family=debian-12 \
  --image-project=debian-cloud

Consola:

Ve a Compute Engine > Instancias de VM > Crear instancia
Nombre: openclaw-gateway
Región: us-central1, Zona: us-central1-a
Tipo de máquina: e2-small
Disco de arranque: Debian 12, 20GB
Crear

4) Conectar por SSH a la VM

CLI:

gcloud compute ssh openclaw-gateway --zone=us-central1-a

Consola:

Haz clic en el botón “SSH” junto a tu VM en el panel de Compute Engine.

Nota: La propagación de claves SSH puede tardar 1-2 minutos después de la creación de la VM. Si la conexión es rechazada, espera y reintenta.

5) Instalar Docker (en la VM)

sudo apt-get update
sudo apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

Cierra sesión y vuelve a entrar para que el cambio de grupo tome efecto:

exit

Luego reconéctate por SSH:

gcloud compute ssh openclaw-gateway --zone=us-central1-a

Verifica:

docker --version
docker compose version

6) Clonar el repositorio de OpenClaw

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

Esta guía asume que vas a compilar una imagen personalizada para garantizar la persistencia de binarios.

7) Crear directorios persistentes en el host

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

mkdir -p ~/.openclaw
mkdir -p ~/.openclaw/workspace

8) Configurar variables de entorno

Crea .env en la raíz del repositorio.

OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=change-me-now
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789

OPENCLAW_CONFIG_DIR=/home/$USER/.openclaw
OPENCLAW_WORKSPACE_DIR=/home/$USER/.openclaw/workspace

GOG_KEYRING_PASSWORD=change-me-now
XDG_CONFIG_HOME=/home/node/.openclaw

Genera secretos fuertes:

openssl rand -hex 32

No hagas commit de este archivo.

9) 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:
      # Recomendado: mantener el Gateway en loopback en la VM; acceder vía túnel SSH.
      # Para exponerlo públicamente, quita el prefijo `127.0.0.1:` y configura el firewall.
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND}",
        "--port",
        "${OPENCLAW_GATEWAY_PORT}",
      ]

10) Pasos compartidos del runtime Docker en VM

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

11) Notas específicas de lanzamiento en GCP

En GCP, si el build falla con Killed o exit code 137 durante pnpm install --frozen-lockfile, la VM se quedó sin memoria. Usa e2-small como mínimo, o e2-medium para builds iniciales más confiables.

Al enlazar a LAN (OPENCLAW_GATEWAY_BIND=lan), configura un origen de navegador de confianza antes de continuar:

docker compose run --rm openclaw-cli config set gateway.controlUi.allowedOrigins '["http://127.0.0.1:18789"]' --strict-json

Si cambiaste el puerto del gateway, reemplaza 18789 con tu puerto configurado.

12) Acceder desde tu portátil

Crea un túnel SSH para reenviar el puerto del Gateway:

gcloud compute ssh openclaw-gateway --zone=us-central1-a -- -L 18789:127.0.0.1:18789

Abre en tu navegador:

http://127.0.0.1:18789/

Obtén un enlace fresco del dashboard con token:

docker compose run --rm openclaw-cli dashboard --no-open

Pega el token de esa URL.

Si el Control UI muestra unauthorized o disconnected (1008): pairing required, aprueba el dispositivo del navegador:

docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

¿Necesitas la referencia de persistencia y actualizaciones de nuevo? Consulta Docker VM Runtime y actualizaciones de Docker VM Runtime.

Troubleshooting

Conexión SSH rechazada

La propagación de claves SSH puede tardar 1-2 minutos después de la creación de la VM. Espera y reintenta.

Problemas con OS Login

Verifica tu perfil de OS Login:

gcloud compute os-login describe-profile

Asegúrate de que tu cuenta tiene los permisos IAM requeridos (Compute OS Login o Compute OS Admin Login).

Out of memory (OOM)

Si el build de Docker falla con Killed y exit code 137, la VM fue terminada por OOM. Actualiza a e2-small (mínimo) o e2-medium (recomendado para builds locales confiables):

# Detener la VM primero
gcloud compute instances stop openclaw-gateway --zone=us-central1-a

# Cambiar tipo de máquina
gcloud compute instances set-machine-type openclaw-gateway \
  --zone=us-central1-a \
  --machine-type=e2-small

# Iniciar la VM
gcloud compute instances start openclaw-gateway --zone=us-central1-a

Service accounts (buena práctica de seguridad)

Para uso personal, tu cuenta de usuario por defecto funciona bien.

Para automatización o pipelines CI/CD, crea una cuenta de servicio dedicada con permisos mínimos:

Crear una cuenta de servicio:

gcloud iam service-accounts create openclaw-deploy \
  --display-name="OpenClaw Deployment"

Otorgar el rol de Compute Instance Admin (o un rol personalizado más restringido):

gcloud projects add-iam-policy-binding my-openclaw-project \
  --member="serviceAccount:[email protected]" \
  --role="roles/compute.instanceAdmin.v1"

Evita usar el rol Owner para automatización. Aplica el principio de mínimo privilegio.

Consulta https://cloud.google.com/iam/docs/understanding-roles para detalles de roles IAM.

Siguientes pasos

Configurar canales de mensajería: Channels
Parear dispositivos locales como nodos: Nodes
Configurar el Gateway: Configuración del Gateway