Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Cómo implementar OpenClaw en instancias de Cloud Run

1. Introducción

Descripción general

En este lab, implementarás una instancia segura y completamente persistente de OpenClaw, un framework de agentes de IA de código abierto, en instancias de Cloud Run. Interactuarás con tu agente de IA directamente a través de la IU web integrada de OpenClaw (con la opción de conectar canales de mensajería como Telegram o WhatsApp), respaldarás tu espacio de trabajo principal con Google Cloud Storage y administrarás las credenciales de la API de forma segura con Google Cloud Secret Manager.

Antes de comenzar, puedes explorar la Documentación de OpenClaw para familiarizarte con la arquitectura, las herramientas y los flujos de trabajo de los agentes de OpenClaw.

Actividades

Habilita las APIs de Google Cloud requeridas y crea una cuenta de servicio dedicada con los permisos de IAM necesarios.
Almacena de forma segura las claves de API y las contraseñas de la puerta de enlace en Secret Manager.
Prepara un archivo de configuración openclaw.json con la configuración del modelo de Gemini y la IU de la puerta de enlace habilitada.
Prepara un bucket de Cloud Storage para conservar el estado del contenedor.
Implementa OpenClaw con gcloud beta run instances deploy.
Interactúa directamente con tu agente de IA de OpenClaw a través de su IU web integrada.
(Opcional) Configura un canal de mensajería (Telegram o WhatsApp).
(Opcional) Extiende las capacidades de tu agente agregando habilidades personalizadas a Cloud Storage.

Qué aprenderás

Cómo implementar OpenClaw en instancias de Cloud Run con su IU web de control integrada
Cómo activar buckets de Cloud Storage en instancias de Cloud Run
Cómo insertar de forma segura secretos de Secret Manager como variables de entorno en Cloud Run
Cómo ejecutar cargas de trabajo de agentes persistentes y de larga duración en instancias de Cloud Run
Cómo configurar y subir habilidades de agentes personalizadas a Cloud Storage

2. Configuración y requisitos

Configuración del proyecto de GCP

Accede a la consola de Google Cloud.
Crea o selecciona un proyecto de Google Cloud.
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

Abre Cloud Shell

Activa Google Cloud Shell desde la barra de herramientas superior de Cloud Console.

Configura el proyecto y, luego, instala gcloud beta

Primero, configura tu proyecto y región como variables de entorno.

export PROJECT_ID=<YOUR_PROJECT_ID>
export REGION=<YOUR_REGION>

Ahora configura tu proyecto y confirma.

gcloud config set project $PROJECT_ID
gcloud config get project

Asegúrate de que el componente beta esté instalado para gcloud beta run instances:

gcloud components install beta --quiet

Además, asegúrate de que gcloud esté actualizado.

gcloud components update

Habilita las APIs de Google Cloud requeridas

En Cloud Shell, habilita las APIs de Cloud Run, Secret Manager, Cloud Storage y Gemini:

gcloud services enable \
  run.googleapis.com \
  secretmanager.googleapis.com \
  storage.googleapis.com \
  generativelanguage.googleapis.com \
  compute.googleapis.com

3. (Opcional) Configura las integraciones de mensajería (Telegram o WhatsApp)

Puedes conectar OpenClaw a Telegram o WhatsApp. Elige la opción A o la opción B a continuación.

Opción A: Configuración del bot de Telegram

Abre Telegram y busca @BotFather.
Envía el comando /newbot y sigue las instrucciones para especificar un nombre y un nombre de usuario para el bot.
Copia el token de API de HTTP generado (p.ej., 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).
Busca @userinfobot en Telegram, envía /start y copia tu ID de usuario numérico (p.ej., 8035936176).

Opción B: Configuración de WhatsApp

Obtén tu número de teléfono personal de WhatsApp en formato internacional sin espacios ni símbolos (p.ej., +15551234567).
OpenClaw se conecta a través de la política de lista de entidades permitidas del canal de WhatsApp.

4. Crea una cuenta de servicio dedicada

Para cumplir con el principio de privilegio mínimo, crea una cuenta de servicio de IAM dedicada para OpenClaw:

export SERVICE_ACCOUNT_NAME="openclaw-sa"
gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME} \
  --display-name="OpenClaw Service Account"

export SERVICE_ACCOUNT="${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

5. Almacena credenciales en Secret Manager

Almacenaremos las credenciales sensibles de la API en Google Cloud Secret Manager para que Cloud Run pueda insertarlas de forma segura en el contenedor durante el inicio.

1. Cómo obtener y almacenar la clave de API de Gemini

Visita Google AI Studio y accede con tu Cuenta de Google.
Haz clic en Crear clave de API y selecciona tu proyecto de Google Cloud (${PROJECT_ID}).
Copia la clave de API generada.

Almacena la clave de API en Secret Manager y otorga acceso a la cuenta de servicio:

echo -n "YOUR_GEMINI_API_KEY" | gcloud secrets create gemini-api-key \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding gemini-api-key \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"

2. Genera y almacena la contraseña de la puerta de enlace

Para proteger tu instancia de OpenClaw accesible de forma pública, genera una contraseña aleatoria segura y almacénala en Secret Manager:

export OPENCLAW_GATEWAY_PASSWORD=$(openssl rand -hex 16)
echo "Generated Gateway Password: ${OPENCLAW_GATEWAY_PASSWORD}"

echo -n "${OPENCLAW_GATEWAY_PASSWORD}" | gcloud secrets create openclaw-gateway-password \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding openclaw-gateway-password \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"

3. (Opcional) Crea un secreto del canal (Telegram o WhatsApp)

Para Telegram:

echo -n "YOUR_TELEGRAM_BOT_TOKEN" | gcloud secrets create telegram-bot-token \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding telegram-bot-token \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"

Para WhatsApp:

echo -n "YOUR_WHATSAPP_TOKEN_OR_KEY" | gcloud secrets create whatsapp-token \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding whatsapp-token \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"

6. Prepara el bucket de Cloud Storage y la configuración de openclaw.json

OpenClaw requiere un archivo de configuración llamado openclaw.json en /home/node/.openclaw/openclaw.json.

Crea un bucket de Cloud Storage y otorga acceso:

export BUCKET_NAME="openclaw-state-${PROJECT_ID}"
gcloud storage buckets create gs://${BUCKET_NAME} --location=${REGION}

gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/storage.objectUser"

Crear openclaw.json: Crea un archivo llamado openclaw.json en Cloud Shell. Actualiza la sección channels para que coincida con el canal que elegiste (Telegram o WhatsApp):

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "trustedProxies": ["0.0.0.0/0"],
    "bind": "lan",
    "auth": {
      "password": "${OPENCLAW_GATEWAY_PASSWORD}"
    },
    "controlUi": {
      "dangerouslyDisableDeviceAuth": true,
      "allowedOrigins": ["*"],
      "enabled": true
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "google/gemini-3.1-pro-preview"
      },
      "sandbox": {
        "mode": "off"
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "defaultAccount": "default",
      "accounts": {
        "default": {
          "enabled": true,
          "dmPolicy": "allowlist",
          "allowFrom": [
            "YOUR_TELEGRAM_USER_ID"
          ]
        }
      }
    },
    "whatsapp": {
      "enabled": false,
      "defaultAccount": "default",
      "accounts": {
        "default": {
          "enabled": false,
          "dmPolicy": "allowlist",
          "allowFrom": [
            "+15551234567"
          ]
        }
      }
    }
  },
  "plugins": {
    "entries": {
      "google": { "enabled": true },
      "telegram": { "enabled": true },
      "whatsapp": { "enabled": false }
    }
  }
}

Sube openclaw.json a la raíz del bucket de Cloud Storage:
```
gcloud storage cp openclaw.json gs://${BUCKET_NAME}/openclaw.json
```
Verifica el diseño del bucket de Cloud Storage:Confirma que la estructura de tu bucket contenga openclaw.json en la raíz:
```
gs://${BUCKET_NAME}/
└── openclaw.json
```

7. Implementa OpenClaw en instancias de Cloud Run

Implementa OpenClaw con gcloud beta run instances deploy:

gcloud beta run instances deploy openclaw-instance \
  --image ghcr.io/openclaw/openclaw:2026.7.1 \
  --service-account ${SERVICE_ACCOUNT} \
  --port 18789 \
  --cpu 4 \
  --memory 4Gi \
  --public \
  --add-volume mount-path=/home/node/.openclaw,type=cloud-storage,mount-options="uid=1000;gid=1000;file-mode=0700;dir-mode=0700",bucket=${BUCKET_NAME} \
  --set-secrets GEMINI_API_KEY=gemini-api-key:latest,OPENCLAW_GATEWAY_PASSWORD=openclaw-gateway-password:latest \
  --region ${REGION}

Desglose de parámetros clave:

--image ghcr.io/openclaw/openclaw:2026.7.1: Imagen del contenedor de OpenClaw (fijada en 2026.7.1, la versión estable 1.x más reciente).
--service-account ...: Adjunta la cuenta de servicio openclaw-sa dedicada.
--add-volume ...: Se monta el bucket de Cloud Storage directamente en /home/node/.openclaw. Usar file-mode=0700;dir-mode=0700 garantiza los permisos adecuados para OpenClaw.
--set-secrets ...: Inserta credenciales directamente desde Secret Manager en variables de entorno. (Opcional: Si configuraste Telegram en los pasos opcionales, agrega ,TELEGRAM_BOT_TOKEN=telegram-bot-token:latest a --set-secrets).
--public: Permite el acceso público a la URL.

8. Interactúa directamente a través de la IU web de OpenClaw

OpenClaw incluye una IU web de Control integrada que te permite administrar y chatear con tu agente de IA directamente desde el navegador:

Recupera la URL de la instancia de Cloud Run: En Cloud Shell, ejecuta el siguiente comando:

gcloud beta run instances describe openclaw-instance \
  --region ${REGION} \
  --format="value(status.urls[0])"

Accede a la IU de control de OpenClaw:
- Abre la URL de salida en tu navegador web.
- Cuando se te solicite la autenticación en la IU de OpenClaw Control, haz lo siguiente:
  - Ingresa la contraseña de la puerta de enlace generada (${OPENCLAW_GATEWAY_PASSWORD}) desde Secret Manager.
  - Si la ventana modal de acceso muestra campos separados para Nombre de usuario y Contraseña, deja el campo de nombre de usuario en blanco (o ingresa admin) y proporciona ${OPENCLAW_GATEWAY_PASSWORD} en el campo de contraseña.
Cómo solicitarle información a tu agente (instancias en acción):
- Una vez que te autentiques, verás el panel de control de OpenClaw.
- Para probar tu agente de OpenClaw, envía una instrucción en la IU del chat, como "Hola".
- Para probar el ciclo de vida prolongado de la instancia de Cloud Run, puedes solicitarle a tu agente de OpenClaw que realice una tarea más sofisticada y de larga duración. Por ejemplo, puedes hacer que haga un seguimiento de un feed de noticias o del mercado de valores y que genere informes:
```
Track the USD-to-EUR exchange rate every 15 minutes for the next 24 hours, while also checking for any recent news updates in the US or the EU that may have an impact on the exchange rate. Generate an end-of-day report for me in this chat that tells me what you expect tomorrow's exchange rate will be.
```
- Luego, el agente debería realizar esta tarea en las próximas 24 horas.

9. Verifica las integraciones de canales de mensajería (opcional)

Si configuraste Telegram o WhatsApp en los pasos de configuración opcionales anteriores, puedes verificar la entrega de mensajes:

Verifica los registros de la instancia en Cloud Shell:

gcloud run instances logs read openclaw-instance --region ${REGION} --limit 20

Abre Telegram (o WhatsApp) y envía un mensaje (p.ej., /start o Hello OpenClaw!).
El bot autenticará tu ID de usuario en la lista de entidades permitidas de openclaw.json y responderá con Gemini.

10. Supervisa e inspecciona los registros de instancias

Las instancias de Cloud Run capturan stdout y stderr de tu contenedor y los transmiten directamente a Google Cloud Logging. Puedes usar Cloud Shell o Cloud Console para supervisar el tráfico de la puerta de enlace y, también, inspeccionar las ejecuciones de herramientas del agente en tiempo real.

1. Leer registros recientes de instancias

Para recuperar las entradas de registro recientes de la instancia en Cloud Shell, haz lo siguiente:

gcloud beta run instances logs read openclaw-instance \
  --region ${REGION} \
  --limit 50

2. Firmas de registros clave para observar

Cuando observes el agente en ejecución, busca los siguientes eventos clave del registro de tiempo de ejecución:

[gateway] ready: Confirma que la puerta de enlace HTTP y WebSocket de OpenClaw se inicializó y está escuchando en el puerto 18789.
[gateway] agent model: ...: Muestra el modelo de Gemini activo (p.ej., google/gemini-3.1-pro-preview o google/gemini-3.5-flash).
[agents/tool-policy]: Muestra las herramientas permitidas o restringidas según tu política.
[agent/embedded]: Registra la ejecución y la invocación de herramientas por parte del agente.

3. Inspecciona los registros en la consola de Google Cloud

También puedes ver y filtrar los registros con el Explorador de registros en la consola de Cloud:

resource.type="cloud_run_instance"
resource.labels.instance_name="openclaw-instance"

11. (Opcional) Extiende tu agente con habilidades

OpenClaw admite habilidades, que son paquetes de capacidades modulares que enseñan a tu agente flujos de trabajo específicos, herramientas de CLI especializadas e instrucciones específicas del dominio.

Cómo funcionan las Skills

Cada habilidad es un directorio que contiene un archivo SKILL.md. Comienza con metadatos iniciales en formato YAML que especifican metadatos (name y description), seguidos de instrucciones en formato Markdown:

---
name: summarize-logs
description: Summarize Cloud Run error logs into actionable bullet points.
---

# Log Summarizer Skill

When asked to analyze or summarize logs:
1. Parse error stack traces and group similar errors by frequency.
2. Identify root causes such as memory limits, timeouts, or permission errors.
3. Propose concrete remediation steps.

name: Es el identificador de la habilidad (también se puede llamar directamente como un comando de barra, por ejemplo, /summarize-logs).
description: Indica al modelo de OpenClaw cuándo invocar automáticamente esta habilidad en una conversación natural.

Agrega una habilidad personalizada a tu bucket de Cloud Storage

Debido a que tu bucket de Cloud Storage se activa directamente en /home/node/.openclaw, las habilidades ubicadas en gs://${BUCKET_NAME}/skills/ se cargan automáticamente durante el inicio y se conservan en los reinicios de la instancia:

Crea un directorio de habilidades locales:

mkdir -p my-skill
cat << 'EOF' > my-skill/SKILL.md
---
name: summarize-logs
description: Summarize Cloud Run error logs into actionable bullet points.
---

# Log Summarizer Skill

When asked to analyze or summarize logs, group errors by frequency and suggest actionable fixes.
EOF

Sube la skill a Cloud Storage:

gcloud storage cp -r my-skill gs://${BUCKET_NAME}/skills/

Usa la habilidad en Chat:
- Regresa a la IU web de OpenClaw Control.
- Ahora puedes darle instrucciones a tu agente con /summarize-logs o hacer preguntas en lenguaje natural que coincidan con la descripción de la habilidad.

12. Limpieza

Para evitar que se generen cargos en tu cuenta de Google Cloud por los recursos que usaste en este codelab, sigue estos pasos:

Borra la instancia de Cloud Run:

gcloud beta run instances delete openclaw-instance --region ${REGION} --quiet

Borra secretos de Secret Manager:

gcloud secrets delete gemini-api-key --quiet
gcloud secrets delete telegram-bot-token --quiet
gcloud secrets delete openclaw-gateway-password --quiet

Borra el bucket de Cloud Storage:

gcloud storage rm -r gs://${BUCKET_NAME}

Borra la cuenta de servicio dedicada:

gcloud iam service-accounts delete ${SERVICE_ACCOUNT} --quiet

13. Conclusión

¡Felicitaciones! Implementaste correctamente una instancia segura y completamente persistente de OpenClaw en instancias de Cloud Run respaldadas por Cloud Storage, Secret Manager y tu canal de mensajería preferido.