Come eseguire il deployment di OpenClaw sulle istanze Cloud Run

1. Introduzione

Panoramica

In questo lab, eseguirai il deployment di un'istanza sicura e completamente persistente di OpenClaw, un framework di agenti AI open source, in Cloud Run Instances. Interagirai direttamente con il tuo agente AI utilizzando la UI web integrata di OpenClaw (con la possibilità di connettere canali di messaggistica come Telegram o WhatsApp), esegui il backup del suo spazio di lavoro principale con Google Cloud Storage e gestisci le credenziali API in modo sicuro utilizzando Google Cloud Secret Manager.

Prima di iniziare, puoi esplorare la documentazione di OpenClaw per familiarizzare con l'architettura, gli strumenti e i flussi di lavoro degli agenti di OpenClaw.

In questo lab proverai a:

  • Abilita le API Google Cloud richieste e crea un service account dedicato con le autorizzazioni IAM richieste.
  • Archivia in modo sicuro chiavi API e password del gateway in Secret Manager.
  • Prepara un file di configurazione openclaw.json con le impostazioni del modello Gemini e l'interfaccia utente del gateway abilitata.
  • Prepara un bucket Cloud Storage per rendere persistente lo stato del container.
  • Esegui il deployment di OpenClaw utilizzando gcloud beta run instances deploy.
  • Interagisci direttamente con il tuo agente AI OpenClaw utilizzando la sua UI web integrata.
  • (Facoltativo) Configura un canale di messaggistica (Telegram o WhatsApp).
  • (Facoltativo) Estendi le funzionalità dell'agente aggiungendo skill personalizzate a Cloud Storage.

Obiettivi didattici

  • Come eseguire il deployment di OpenClaw nelle istanze Cloud Run con la relativa UI web di controllo integrata.
  • Come montare i bucket Cloud Storage sulle istanze Cloud Run.
  • Come inserire in modo sicuro i secret di Secret Manager come variabili di ambiente in Cloud Run.
  • Come eseguire carichi di lavoro degli agenti persistenti e di lunga durata sulle istanze Cloud Run.
  • Come configurare e caricare skill dell'agente personalizzate su Cloud Storage.

2. Configurazione e requisiti

Configurazione del progetto Google Cloud

  1. Accedi alla console Google Cloud.
  2. Crea o seleziona un progetto Google Cloud.
  3. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

Apri Cloud Shell

Attiva Google Cloud Shell dalla barra degli strumenti in alto della console Google Cloud.

Imposta il progetto e installa gcloud beta

Innanzitutto, imposta il progetto e la regione come variabili di ambiente.

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

Ora imposta il progetto e conferma.

gcloud config set project $PROJECT_ID
gcloud config get project

Assicurati che il componente beta sia installato per gcloud beta run instances:

gcloud components install beta --quiet

Inoltre, assicurati che gcloud sia aggiornato.

gcloud components update

Abilita le API Google Cloud richieste

In Cloud Shell, abilita le API Cloud Run, Secret Manager, Cloud Storage e Gemini:

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

3. (Facoltativo) Configurare le integrazioni di messaggistica (Telegram o WhatsApp)

Puoi connettere OpenClaw a Telegram o WhatsApp. Scegli l'opzione A o l'opzione B di seguito.

Opzione A: configurazione del bot Telegram

  1. Apri Telegram e cerca @BotFather.
  2. Invia il comando /newbot e segui le istruzioni per specificare un nome e un nome utente per il bot.
  3. Copia il token API HTTP generato (ad es. 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).
  4. Cerca @userinfobot su Telegram, invia /start e copia il tuo ID utente numerico (ad es. 8035936176).

Opzione B: configurazione di WhatsApp

  1. Ottieni il tuo numero di telefono WhatsApp personale in formato internazionale senza spazi o simboli (ad es. +15551234567).
  2. OpenClaw si connette tramite la policy della lista consentita dei canali WhatsApp.

4. Crea service account dedicato

Per rispettare il principio del privilegio minimo, crea un service account IAM dedicato per 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. Archivia le credenziali in Secret Manager

Archivieremo le credenziali API sensibili in Google Cloud Secret Manager in modo che Cloud Run possa inserirle in modo sicuro nel container al momento dell'avvio.

1. Ottenere e archiviare la chiave API Gemini

  1. Visita Google AI Studio e accedi con il tuo Account Google.
  2. Fai clic su Crea chiave API e seleziona il tuo progetto Google Cloud (${PROJECT_ID}).
  3. Copia la chiave API generata.

Archivia la chiave API in Secret Manager e concedi l'accesso al service account:

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. Generare e memorizzare la password del gateway

Per proteggere l'istanza OpenClaw accessibile pubblicamente, genera una password casuale sicura e archiviala in 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. (Facoltativo) Crea il segreto del canale (Telegram o WhatsApp)

  • Per 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"
  • Per 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 il bucket Cloud Storage e la configurazione openclaw.json

OpenClaw richiede un file di configurazione denominato openclaw.json in /home/node/.openclaw/openclaw.json.

  1. Crea un bucket Cloud Storage e concedi l'accesso:
    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"
  2. Crea openclaw.json: crea un file denominato openclaw.json in Cloud Shell. Aggiorna la sezione channels in modo che corrisponda al canale scelto (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 }
    }
  }
}
  3. Carica openclaw.json nella radice del bucket Cloud Storage:
    gcloud storage cp openclaw.json gs://${BUCKET_NAME}/openclaw.json
    Verifica il layout del bucket Cloud Storage:verifica che la struttura del bucket contenga openclaw.json nella radice:
    gs://${BUCKET_NAME}/
└── openclaw.json

7. Esegui il deployment di OpenClaw sulle istanze Cloud Run

Esegui il deployment di OpenClaw utilizzando 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}

Suddivisione dei parametri chiave:

  • --image ghcr.io/openclaw/openclaw:2026.7.1: immagine container OpenClaw (bloccata su 2026.7.1, l'ultima release stabile 1.x).
  • --service-account ...: collega il service account openclaw-sa dedicato.
  • --add-volume ...: monta il bucket Cloud Storage direttamente su /home/node/.openclaw. L'utilizzo di file-mode=0700;dir-mode=0700 garantisce le autorizzazioni corrette per OpenClaw.
  • --set-secrets ...: inserisce le credenziali direttamente da Secret Manager nelle variabili di ambiente. (Facoltativo: se hai configurato Telegram nei passaggi facoltativi, aggiungi ,TELEGRAM_BOT_TOKEN=telegram-bot-token:latest a --set-secrets.)
  • --public: Consente l'accesso pubblico all'URL.

8. Interagire direttamente tramite l'interfaccia utente web di OpenClaw

OpenClaw include una UI web di controllo integrata che ti consente di gestire e chattare con il tuo agente AI direttamente dal browser:

  1. Recupera l'URL dell'istanza Cloud Run: in Cloud Shell, esegui:
    gcloud beta run instances describe openclaw-instance \
  --region ${REGION} \
  --format="value(status.urls[0])"
  2. Accedere alla UI di controllo OpenClaw:
    • Apri l'URL di output nel browser web.
    • Quando ti viene chiesto di eseguire l'autenticazione nella UI di controllo di OpenClaw:
      • Inserisci la password del gateway generata (${OPENCLAW_GATEWAY_PASSWORD}) da Secret Manager.
      • Se la finestra modale di accesso mostra campi separati per Nome utente e Password, lascia vuoto il campo del nome utente (o inserisci admin) e fornisci ${OPENCLAW_GATEWAY_PASSWORD} nel campo della password.
  3. Prompt Your Agent (istanze in azione):
    • Una volta autenticato, vedrai la dashboard di controllo OpenClaw.
    • Prova l'agente OpenClaw inviando un prompt nella UI della chat, ad esempio "Buongiorno".
    • Per testare il ciclo di vita a lunga durata dell'istanza Cloud Run, puoi chiedere all'agente OpenClaw di eseguire un'attività più sofisticata e di lunga durata. Ad esempio, puoi monitorare un feed di notizie o il mercato azionario e generare report:
      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.
    • L'agente dovrebbe quindi eseguire questa attività nelle 24 ore successive.

9. (Facoltativo) Verifica le integrazioni dei canali di messaggistica

Se hai configurato Telegram o WhatsApp nei passaggi di configurazione facoltativi precedenti, puoi verificare la consegna dei messaggi:

  1. Controlla i log dell'istanza in Cloud Shell:
    gcloud run instances logs read openclaw-instance --region ${REGION} --limit 20
  2. Apri Telegram (o WhatsApp) e invia un messaggio (ad es. /start o Hello OpenClaw!).
  3. Il bot autenticherà il tuo ID utente rispetto alla lista consentita in openclaw.json e risponderà utilizzando Gemini.

10. Monitorare e ispezionare i log delle istanze

Cloud Run Instances acquisisce stdout e stderr dal container e li trasmette in streaming direttamente a Google Cloud Logging. Puoi utilizzare Cloud Shell o Cloud Console per monitorare il traffico del gateway ed esaminare le esecuzioni degli strumenti dell'agente in tempo reale.

1. Lettura dei log delle istanze recenti

Per recuperare le voci di log recenti dall'istanza in Cloud Shell:

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

2. Firme dei log chiave da osservare

Quando osservi l'agente in esecuzione, cerca i seguenti eventi di log di runtime chiave:

  • [gateway] ready: conferma che il gateway HTTP e WebSocket OpenClaw è stato inizializzato ed è in ascolto sulla porta 18789.
  • [gateway] agent model: ...: mostra il modello Gemini attivo (ad es. google/gemini-3.1-pro-preview o google/gemini-3.5-flash).
  • [agents/tool-policy]: mostra gli strumenti consentiti o limitati ai sensi della tua policy.
  • [agent/embedded]: traccia l'esecuzione e la chiamata allo strumento da parte dell'agente.

3. Esaminare i log nella console Google Cloud

Puoi anche visualizzare e filtrare i log utilizzando Esplora log nella console Cloud:

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

11. (Facoltativo) Estendere l'agente con le competenze

OpenClaw supporta le skill, pacchetti di funzionalità modulari che insegnano all'agente workflow specifici, strumenti CLI specializzati e istruzioni specifiche per il dominio.

Come funzionano le skill

Ogni skill è una directory contenente un file SKILL.md. Inizia con il frontmatter YAML che specifica i metadati (name e description), seguito dalle istruzioni 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: l'identificatore della skill (richiamabile anche direttamente come comando slash, ad esempio /summarize-logs).
  • description: indica al modello di OpenClaw quando richiamare automaticamente questa skill in una conversazione naturale.

Aggiungere una skill personalizzata al bucket Cloud Storage

Poiché il bucket Cloud Storage è montato direttamente su /home/node/.openclaw, le competenze inserite in gs://${BUCKET_NAME}/skills/ vengono caricate automaticamente all'avvio e mantenute durante i riavvii dell'istanza:

  1. Creare una directory delle skill locali:
    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
  2. Carica la skill su Cloud Storage:
    gcloud storage cp -r my-skill gs://${BUCKET_NAME}/skills/
  3. Utilizzare la skill in Chat:
    • Torna alla UI web di OpenClaw Control.
    • Ora puoi richiedere al tuo agente di utilizzare /summarize-logs o porre domande in linguaggio naturale che corrispondono alla descrizione dell'abilità.

12. Elimina

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo codelab:

  1. Elimina l'istanza Cloud Run:
    gcloud beta run instances delete openclaw-instance --region ${REGION} --quiet
  2. Elimina i secret di Secret Manager:
    gcloud secrets delete gemini-api-key --quiet
gcloud secrets delete telegram-bot-token --quiet
gcloud secrets delete openclaw-gateway-password --quiet
  3. Elimina il bucket Cloud Storage:
    gcloud storage rm -r gs://${BUCKET_NAME}
  4. Elimina service account dedicato:
    gcloud iam service-accounts delete ${SERVICE_ACCOUNT} --quiet

13. Conclusione

Complimenti! Hai eseguito correttamente il deployment di un'istanza sicura e completamente persistente di OpenClaw su Cloud Run Instances supportata da Cloud Storage, Secret Manager e dal tuo canale di messaggistica preferito.