Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Déployer OpenClaw sur des instances Cloud Run

1. Introduction

Présentation

Dans cet atelier, vous allez déployer une instance sécurisée et entièrement persistante d'OpenClaw, un framework d'agent d'IA Open Source, sur Cloud Run Instances. Vous interagirez directement avec votre agent d'IA à l'aide de l'interface utilisateur Web intégrée d'OpenClaw (avec la possibilité de connecter des canaux de messagerie tels que Telegram ou WhatsApp), sauvegarderez son espace de travail d'origine avec Google Cloud Storage et gérerez les identifiants API de manière sécurisée à l'aide de Google Cloud Secret Manager.

Avant de commencer, vous pouvez explorer la documentation OpenClaw pour vous familiariser avec l'architecture, les outils et les workflows d'agent d'OpenClaw.

Objectifs de l'atelier

Activez les API Google Cloud requises et créez un compte de service dédié avec les autorisations IAM nécessaires.
Stockez les clés API et les mots de passe de la passerelle de manière sécurisée dans Secret Manager.
Préparez un fichier de configuration openclaw.json avec les paramètres du modèle Gemini et l'interface utilisateur de la passerelle activée.
Préparez un bucket Cloud Storage pour conserver l'état du conteneur.
Déployez OpenClaw à l'aide de gcloud beta run instances deploy.
Interagissez directement avec votre agent IA OpenClaw à l'aide de son interface utilisateur Web intégrée.
(Facultatif) Configurez un canal de messagerie (Telegram ou WhatsApp).
(Facultatif) Étendez les capacités de votre agent en ajoutant des compétences personnalisées à Cloud Storage.

Points abordés

Déployer OpenClaw sur des instances Cloud Run avec son UI Web de contrôle intégrée
Comment installer des buckets Cloud Storage sur des instances Cloud Run.
Découvrez comment injecter de manière sécurisée des secrets Secret Manager en tant que variables d'environnement dans Cloud Run.
Découvrez comment exécuter des charges de travail d'agent persistantes et de longue durée sur des instances Cloud Run.
Configurer et importer des compétences d'agent personnalisées dans Cloud Storage

2. Préparation

Configurer un projet GCP

Connectez-vous à la console Google Cloud.
Créez ou sélectionnez un projet Google Cloud.
Assurez-vous que la facturation est activée pour votre projet Google Cloud.

Ouvrir Cloud Shell

Activez Google Cloud Shell depuis la barre d'outils supérieure de la console Cloud.

Définir le projet et installer gcloud beta

Tout d'abord, définissez votre projet et votre région en tant que variables d'environnement.

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

Définissez maintenant votre projet et confirmez.

gcloud config set project $PROJECT_ID
gcloud config get project

Assurez-vous que le composant beta est installé pour gcloud beta run instances :

gcloud components install beta --quiet

Assurez-vous également que gcloud est à jour.

gcloud components update

Activer les API Google Cloud requises

Dans Cloud Shell, activez les API Cloud Run, Secret Manager, Cloud Storage et Gemini :

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

3. (Facultatif) Configurer les intégrations de messagerie (Telegram ou WhatsApp)

Vous pouvez associer OpenClaw à Telegram ou WhatsApp. Choisissez l'option A ou l'option B ci-dessous.

Option A : Configurer un bot Telegram

Ouvrez Telegram et recherchez @BotFather.
Envoyez la commande /newbot et suivez les instructions pour spécifier un nom et un nom d'utilisateur pour le bot.
Copiez le jeton d'API HTTP généré (par exemple, 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).
Recherchez @userinfobot sur Telegram, envoyez /start, puis copiez votre ID utilisateur numérique (par exemple, 8035936176).

Option B : Configuration de WhatsApp

Obtenez votre numéro de téléphone WhatsApp personnel au format international, sans espaces ni symboles (par exemple, +15551234567).
OpenClaw se connecte via la règle concernant la liste d'autorisation des chaînes WhatsApp.

4. Créer un compte de service dédié

Pour respecter le principe du moindre privilège, créez un compte de service IAM dédié pour 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. Stocker les identifiants dans Secret Manager

Nous stockerons les identifiants API sensibles dans Google Cloud Secret Manager afin que Cloud Run puisse les injecter de manière sécurisée dans le conteneur au moment du démarrage.

1. Obtenir et stocker une clé API Gemini

Accédez à Google AI Studio et connectez-vous avec votre compte Google.
Cliquez sur Créer une clé API, puis sélectionnez votre projet Google Cloud (${PROJECT_ID}).
Copiez la clé API générée.

Stockez la clé API dans Secret Manager et accordez l'accès au compte de service :

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. Générer et stocker le mot de passe de la passerelle

Pour protéger votre instance OpenClaw accessible publiquement, générez un mot de passe aléatoire sécurisé et stockez-le dans 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. (Facultatif) Créer un secret de canal (Telegram ou WhatsApp)

Pour 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"

Pour 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. Préparer le bucket Cloud Storage et la configuration openclaw.json

OpenClaw nécessite un fichier de configuration nommé openclaw.json dans /home/node/.openclaw/openclaw.json.

Créer un bucket Cloud Storage et accorder l'accès :

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"

Créer openclaw.json : créez un fichier nommé openclaw.json dans Cloud Shell. Mettez à jour la section channels pour qu'elle corresponde au canal de votre choix (Telegram ou 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 }
    }
  }
}

Importer openclaw.json à la racine du bucket Cloud Storage :
```
gcloud storage cp openclaw.json gs://${BUCKET_NAME}/openclaw.json
```
Vérifier la mise en page du bucket Cloud Storage : vérifiez que la structure de votre bucket contient openclaw.json à la racine :
```
gs://${BUCKET_NAME}/
└── openclaw.json
```

7. Déployer OpenClaw sur des instances Cloud Run

Déployez OpenClaw à l'aide de 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}

Répartition des paramètres clés :

--image ghcr.io/openclaw/openclaw:2026.7.1 : image de conteneur OpenClaw (épinglée à 2026.7.1, la dernière version stable 1.x).
--service-account ... : associe le compte de service openclaw-sa dédié.
--add-volume ... : monte le bucket Cloud Storage directement sur /home/node/.openclaw. L'utilisation de file-mode=0700;dir-mode=0700 garantit les autorisations appropriées pour OpenClaw.
--set-secrets ... : injecte les identifiants directement depuis Secret Manager dans les variables d'environnement. (Facultatif : si vous avez configuré Telegram dans les étapes facultatives, ajoutez ,TELEGRAM_BOT_TOKEN=telegram-bot-token:latest à --set-secrets.)
--public : permet d'accéder publiquement à l'URL.

8. Interagir directement via l'interface utilisateur Web OpenClaw

OpenClaw inclut une UI Web de contrôle intégrée qui vous permet de gérer votre agent d'IA et de discuter avec lui directement depuis votre navigateur :

Récupérez l'URL de votre instance Cloud Run : dans Cloud Shell, exécutez la commande suivante :

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

Accéder à l'interface utilisateur de contrôle OpenClaw :
- Ouvrez l'URL de sortie dans votre navigateur Web.
- Lorsque vous êtes invité à vous authentifier dans l'interface utilisateur OpenClaw Control :
  - Saisissez le mot de passe de la passerelle généré (${OPENCLAW_GATEWAY_PASSWORD}) depuis Secret Manager.
  - Si la fenêtre modale de connexion affiche des champs Nom d'utilisateur et Mot de passe distincts, laissez le champ du nom d'utilisateur vide (ou saisissez admin) et saisissez ${OPENCLAW_GATEWAY_PASSWORD} dans le champ du mot de passe.
Demander à votre agent (instances en action) :
- Une fois l'authentification effectuée, le tableau de bord OpenClaw Control s'affiche.
- Testez votre agent OpenClaw en envoyant une requête dans l'interface utilisateur du chat, par exemple "Bonjour".
- Pour tester le cycle de vie de longue durée de l'instance Cloud Run, vous pouvez demander à votre agent OpenClaw d'effectuer une tâche plus complexe et de longue durée. Par exemple, vous pouvez lui demander de suivre un flux d'actualités ou le marché boursier et de générer des rapports :
```
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'agent doit ensuite effectuer cette tâche au cours des 24 heures suivantes.

9. (Facultatif) Vérifier les intégrations des canaux de messagerie

Si vous avez configuré Telegram ou WhatsApp dans les étapes de configuration facultatives ci-dessus, vous pouvez vérifier la distribution des messages :

Vérifiez les journaux d'instance dans Cloud Shell :

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

Ouvrez Telegram (ou WhatsApp) et envoyez un message (par exemple, /start ou Hello OpenClaw!).
Le bot authentifiera votre ID utilisateur par rapport à la liste d'autorisation dans openclaw.json et répondra à l'aide de Gemini.

10. Surveiller et inspecter les journaux d'instance

Les instances Cloud Run capturent les flux stdout et stderr de votre conteneur et les transmettent directement à Google Cloud Logging. Vous pouvez utiliser Cloud Shell ou la console Cloud pour surveiller le trafic de la passerelle et inspecter les exécutions des outils de l'agent en temps réel.

1. Lire les journaux d'instance récents

Pour extraire les entrées de journal récentes de l'instance dans Cloud Shell :

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

2. Signatures de journaux clés à observer

Lorsque vous observez votre agent en cours d'exécution, recherchez les événements de journal d'exécution clés suivants :

[gateway] ready : confirme que la passerelle OpenClaw HTTP et WebSocket a été initialisée et écoute sur le port 18789.
[gateway] agent model: ... : affiche le modèle Gemini actif (par exemple, google/gemini-3.1-pro-preview ou google/gemini-3.5-flash).
[agents/tool-policy] : affiche les outils autorisés ou restreints par votre règlement.
[agent/embedded] : suit l'exécution et l'appel d'outil par l'agent.

3. Inspecter les journaux dans la console Google Cloud

Vous pouvez également afficher et filtrer les journaux à l'aide de l'explorateur de journaux de la console Cloud :

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

11. (Facultatif) Étendre votre agent avec des compétences

OpenClaw est compatible avec les compétences, qui sont des packages de fonctionnalités modulaires qui enseignent à votre agent des workflows spécifiques, des outils CLI spécialisés et des instructions spécifiques à un domaine.

Fonctionnement des compétences

Chaque compétence est un répertoire contenant un fichier SKILL.md. Il commence par un frontmatter YAML spécifiant les métadonnées (name et description), suivi des instructions 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 : identifiant de la compétence (peut également être appelé directement en tant que commande à barre oblique, par exemple /summarize-logs).
description : indique au modèle d'OpenClaw quand invoquer automatiquement cette compétence dans une conversation naturelle.

Ajouter une compétence personnalisée à votre bucket Cloud Storage

Étant donné que votre bucket Cloud Storage est monté directement sur /home/node/.openclaw, les compétences placées sous gs://${BUCKET_NAME}/skills/ sont automatiquement chargées au démarrage et conservées lors des redémarrages de l'instance :

Créer un répertoire de compétences local :

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

Importez la compétence dans Cloud Storage :

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

Utiliser la skill dans Chat :
- Revenez à l'interface utilisateur Web OpenClaw Control.
- Vous pouvez désormais solliciter votre agent à l'aide de /summarize-logs ou poser des questions en langage naturel correspondant à la description de la compétence.

12. Effectuer un nettoyage

Pour éviter que les ressources utilisées dans cet atelier de programmation soient facturées sur votre compte Google Cloud :

Supprimez l'instance Cloud Run :

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

Supprimer les secrets Secret Manager :

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

Supprimer le bucket Cloud Storage :

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

Supprimer le compte de service dédié :

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

13. Conclusion

Félicitations ! Vous avez déployé une instance OpenClaw sécurisée et entièrement persistante sur les instances Cloud Run, avec Cloud Storage, Secret Manager et votre canal de messagerie préféré.