GCP

Exécutez un Gateway OpenClaw persistant sur une VM GCP Compute Engine à l’aide de Docker, avec un état durable, des binaires intégrés et un comportement de redémarrage sûr. Les tarifs varient selon le type de machine et la région ; choisissez la plus petite VM adaptée à votre charge de travail et augmentez sa capacité si vous rencontrez des erreurs de mémoire insuffisante. Vous pouvez accéder au Gateway depuis votre ordinateur portable au moyen d’une redirection de port SSH, ou en exposant directement le port si vous gérez vous-même le pare-feu et les jetons. Ce guide utilise Debian sur GCP Compute Engine. Ubuntu fonctionne également ; adaptez les paquets en conséquence. Pour la procédure Docker générique, consultez Docker.

Prérequis

Un compte GCP (e2-micro est éligible à l’offre gratuite)
La CLI gcloud, ou la Cloud Console
Un accès SSH depuis votre ordinateur portable
Docker et Docker Compose
Des identifiants d’authentification au modèle
Des identifiants de fournisseur facultatifs (code QR WhatsApp, jeton de bot Telegram, OAuth Gmail)
Environ 20 à 30 minutes

Procédure rapide

Créez un projet GCP, activez la facturation et l’API Compute Engine
Créez une VM Compute Engine (e2-small, Debian 12, 20 Go)
Connectez-vous à la VM par SSH et installez Docker
Clonez le dépôt OpenClaw
Créez des répertoires persistants sur l’hôte
Configurez .env et docker-compose.yml
Intégrez les binaires requis, puis générez et lancez l’image

Installer la CLI gcloud (ou utiliser la Console)

Installez-la depuis cloud.google.com/sdk/docs/install, puis exécutez :

gcloud init
gcloud auth login

Vous pouvez également effectuer toutes les étapes ci-dessous dans l’interface web de la Cloud Console.

Créer un projet GCP

gcloud projects create my-openclaw-project --name="OpenClaw Gateway"
gcloud config set project my-openclaw-project
gcloud services enable compute.googleapis.com

Activez la facturation sur console.cloud.google.com/billing (obligatoire pour Compute Engine).Équivalent dans la Console : IAM & Admin > Create Project, activez la facturation, puis APIs & Services > Enable APIs > “Compute Engine API” > Enable.

Créer la VM

Type	Caractéristiques	Coût	Remarques
e2-medium	2 vCPU, 4 Go de RAM	Environ 25 $ US par mois	Le plus fiable pour les générations Docker locales
e2-small	2 vCPU, 2 Go de RAM	Environ 12 $ US par mois	Minimum recommandé pour générer une image Docker
e2-micro	2 vCPU (partagés), 1 Go de RAM	Éligible à l’offre gratuite	Échoue souvent par manque de mémoire pendant la génération Docker (code de sortie 137)

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

Se connecter à la VM par SSH

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

Dans la Console : cliquez sur “SSH” à côté de la VM dans le tableau de bord Compute Engine.La propagation de la clé SSH peut prendre une à deux minutes après la création de la VM ; attendez et réessayez si la connexion est refusée.

Installer Docker (sur 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

Déconnectez-vous puis reconnectez-vous pour que la modification du groupe prenne effet, puis rétablissez la connexion SSH :

exit

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

Vérifiez l’installation :

docker --version
docker compose version

Cloner le dépôt OpenClaw

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

Ce guide génère une image personnalisée afin que tous les binaires intégrés persistent après les redémarrages.

Créer des répertoires persistants sur l’hôte

Les conteneurs Docker sont éphémères ; tout état à conserver à long terme doit résider sur l’hôte.

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

Configurer les variables d’environnement

Créez .env à la racine du dépôt :

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

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

GOG_KEYRING_PASSWORD=
XDG_CONFIG_HOME=/home/node/.openclaw

Définissez OPENCLAW_GATEWAY_TOKEN pour gérer le jeton stable du Gateway au moyen de .env ; sinon, configurez gateway.auth.token avant de compter sur des clients persistants entre les redémarrages. Si aucun des deux n’est défini, OpenClaw utilise, pour ce démarrage, un jeton limité à l’exécution en cours. Générez un mot de passe de trousseau pour GOG_KEYRING_PASSWORD :

openssl rand -hex 32

Ne validez pas ce fichier dans le dépôt. Il contient des variables d’environnement du conteneur et de l’exécution, telles que OPENCLAW_GATEWAY_TOKEN. Les authentifications OAuth et par clé API des fournisseurs enregistrées résident dans le fichier monté ~/.openclaw/agents/<agentId>/agent/auth-profiles.json.

Configuration de Docker Compose

Créez ou mettez à jour 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:
      # Recommandé : limitez le Gateway à l’interface de bouclage de la VM ; accédez-y au moyen d’un tunnel SSH.
      # Pour l’exposer publiquement, supprimez le préfixe `127.0.0.1:` et configurez le pare-feu en conséquence.
      - "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 sert uniquement à faciliter l’amorçage et ne remplace pas une véritable configuration du Gateway. Définissez tout de même l’authentification (gateway.auth.token ou un mot de passe) et un mode de liaison sûr pour votre déploiement.

Étapes d’exécution communes pour une VM Docker

Suivez le guide d’exécution commun pour la procédure standard sur un hôte Docker :

Remarques de lancement propres à GCP

Si la génération échoue avec Killed ou exit code 137 pendant pnpm install --frozen-lockfile, la VM manque de mémoire. Utilisez au minimum e2-small, ou e2-medium pour des premières générations plus fiables.Lorsque la liaison s’effectue au réseau local (OPENCLAW_GATEWAY_BIND=lan), configurez une origine de navigateur approuvée avant de continuer :

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

Remplacez 18789 par le port configuré si vous l’avez modifié.

Accéder au service depuis votre ordinateur portable

Créez un tunnel SSH pour rediriger le port du Gateway :

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

Ouvrez http://127.0.0.1:18789/ dans votre navigateur.Affichez de nouveau un lien propre vers le tableau de bord :

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

Si l’interface vous demande une authentification par secret partagé, collez le jeton configuré ou le mot de passe dans les paramètres de Control UI (cette procédure Docker écrit un jeton par défaut ; utilisez plutôt le mot de passe configuré si vous avez adopté l’authentification par mot de passe).Si Control UI affiche unauthorized ou disconnected (1008): pairing required, approuvez l’appareil correspondant au navigateur :

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

Consultez Exécution sur une VM Docker pour connaître la répartition commune des données persistantes et la procédure de mise à jour.

Résolution des problèmes

Connexion SSH refusée La propagation de la clé SSH peut prendre une à deux minutes après la création de la VM. Attendez et réessayez. Problèmes avec OS Login Vérifiez votre profil OS Login :

gcloud compute os-login describe-profile

Assurez-vous que votre compte dispose des autorisations IAM requises (Compute OS Login ou Compute OS Admin Login). Mémoire insuffisante Si la génération Docker échoue avec Killed et exit code 137, le système a arrêté le processus de la VM par manque de mémoire :

# Arrêtez d’abord la VM
gcloud compute instances stop openclaw-gateway --zone=us-central1-a

# Modifiez le type de machine
gcloud compute instances set-machine-type openclaw-gateway \
  --zone=us-central1-a \
  --machine-type=e2-small

# Démarrez la VM
gcloud compute instances start openclaw-gateway --zone=us-central1-a

Comptes de service (bonne pratique de sécurité)

Pour un usage personnel, votre compte utilisateur par défaut convient. Pour l’automatisation ou l’intégration et le déploiement continus, créez un compte de service dédié doté des autorisations minimales :

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

gcloud projects add-iam-policy-binding my-openclaw-project \
  --member="serviceAccount:openclaw-deploy@my-openclaw-project.iam.gserviceaccount.com" \
  --role="roles/compute.instanceAdmin.v1"

Évitez le rôle Owner pour l’automatisation ; utilisez le rôle le plus restreint qui répond à vos besoins. Consultez Comprendre les rôles.

Étapes suivantes

Configurez les canaux de messagerie : Canaux
Associez des appareils locaux en tant que nœuds : Nœuds
Configurez le Gateway : Configuration du Gateway

Install overview

Maintenance

Containers

Hosting

Advanced setup

Prérequis

Procédure rapide

Résolution des problèmes

Comptes de service (bonne pratique de sécurité)

Étapes suivantes

Pages connexes

​Prérequis

​Procédure rapide

​Résolution des problèmes

​Comptes de service (bonne pratique de sécurité)

​Étapes suivantes

​Pages connexes

Prérequis

Procédure rapide

Résolution des problèmes

Comptes de service (bonne pratique de sécurité)

Étapes suivantes

Pages connexes