GCP

Installer gcloud CLI (ou utiliser Console)

Option A : gcloud CLI (recommandé pour l’automatisation)

Installez depuis https://cloud.google.com/sdk/docs/install

Initialisez et authentifiez-vous :

gcloud init
gcloud auth login

Option B : Cloud Console

Toutes les étapes peuvent être effectuées via l’UI web à l’adresse https://console.cloud.google.com

Créer un projet GCP

CLI :

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

Activez la facturation sur https://console.cloud.google.com/billing (requise pour Compute Engine).

Activez l’API Compute Engine :

gcloud services enable compute.googleapis.com

Console :

1. Accédez à IAM & Admin > Create Project
2. Nommez-le et créez-le
3. Activez la facturation pour le projet
4. Accédez à APIs & Services > Enable APIs > recherchez « Compute Engine API » > Enable

Créer la VM

Types de machines :

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

Console :

1. Accédez à Compute Engine > VM instances > Create instance
2. Nom : openclaw-gateway
3. Région : us-central1, Zone : us-central1-a
4. Type de machine : e2-small
5. Disque de démarrage : Debian 12, 20 Go
6. Créez

Se connecter à la VM en SSH

CLI :

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

Console :

Cliquez sur le bouton « SSH » à côté de votre VM dans le tableau de bord Compute Engine.

Remarque : la propagation des clés SSH peut prendre 1 à 2 minutes après la création de la VM. Si la connexion est refusée, attendez puis réessayez.

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 le changement de groupe prenne effet :

exit

Ensuite, reconnectez-vous en SSH :

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

Vérifiez :

docker --version
docker compose version

Cloner le dépôt OpenClaw

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

Ce guide suppose que vous construirez une image personnalisée pour garantir la persistance des binaires.

Créer des répertoires hôtes persistants

Les conteneurs Docker sont éphémères. Tout état durable doit vivre 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 lorsque vous voulez gérer le jeton stable du gateway via .env ; sinon, configurez gateway.auth.token avant de vous appuyer sur les clients entre les redémarrages. Si aucune source n’existe, OpenClaw utilise un jeton valable uniquement pour le runtime lors de ce démarrage. Générez un mot de passe de trousseau et collez-le dans GOG_KEYRING_PASSWORD :

openssl rand -hex 32

Ne committez pas ce fichier.

Ce fichier .env sert aux variables d’environnement du conteneur/runtime comme OPENCLAW_GATEWAY_TOKEN. L’authentification OAuth/clé API des fournisseurs stockée réside dans le fichier monté ~/.openclaw/agents/<agentId>/agent/auth-profiles.json.

Configuration 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:
      # Recommended: keep the Gateway loopback-only on the VM; access via SSH tunnel.
      # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
      - "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 ; ce n’est pas un remplacement d’une configuration de gateway appropriée. Définissez tout de même l’authentification (gateway.auth.token ou mot de passe) et utilisez des paramètres de liaison sûrs pour votre déploiement.

Étapes partagées du runtime de VM Docker

Utilisez le guide de runtime partagé pour le flux hôte Docker commun :

• Intégrer les binaires requis dans l’image
• Construire et lancer
• Ce qui persiste et où
• Mises à jour

Notes de lancement spécifiques à GCP

Sur GCP, si le build é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 premiers builds plus fiables.

Lors de la liaison au LAN (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

Si vous avez changé le port du gateway, remplacez 18789 par votre port configuré.

Accéder depuis votre ordinateur portable

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

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

Ouvrez dans votre navigateur :

http://127.0.0.1:18789/

Réaffichez un lien de tableau de bord propre :

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

Si l’UI demande une authentification par secret partagé, collez le jeton configuré ou le mot de passe dans les paramètres de l’UI de contrôle. Ce flux Docker écrit un jeton par défaut ; si vous basculez la configuration du conteneur vers l’authentification par mot de passe, utilisez plutôt ce mot de passe.

Si l’UI de contrôle affiche unauthorized ou disconnected (1008): pairing required, approuvez l’appareil du navigateur :

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

Besoin à nouveau de la référence sur la persistance partagée et les mises à jour ? Consultez Runtime de VM Docker et mises à jour du runtime de VM Docker.