GCP

Installare la CLI gcloud (o utilizzare Console)

Esegui l'installazione da cloud.google.com/sdk/docs/install, quindi:

gcloud initgcloud auth login

In alternativa, esegui tutti i passaggi seguenti tramite l'interfaccia web di Cloud Console.

Creare un progetto GCP

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

Abilita la fatturazione su console.cloud.google.com/billing, necessaria per Compute Engine.

Procedura equivalente in Console: IAM & Admin > Create Project, abilita la fatturazione, quindi APIs & Services > Enable APIs > "Compute Engine API" > Enable.

Creare la VM

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

Accedere alla VM tramite SSH

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

Console: fai clic su "SSH" accanto alla VM nella dashboard di Compute Engine.

La propagazione della chiave SSH può richiedere 1-2 minuti dopo la creazione della VM; attendi e riprova se la connessione viene rifiutata.

Installare Docker (sulla VM)

sudo apt-get updatesudo apt-get install -y git curl ca-certificatescurl -fsSL https://get.docker.com | sudo shsudo usermod -aG docker $USER

Disconnettiti e accedi nuovamente affinché la modifica al gruppo abbia effetto, quindi riconnettiti tramite SSH:

exit

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

Verifica:

docker --versiondocker compose version

Clonare il repository OpenClaw

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

Questa guida crea un'immagine personalizzata, in modo che tutti i binari integrati rimangano disponibili dopo i riavvii.

Creare directory persistenti sull'host

I container Docker sono effimeri; tutto lo stato persistente deve risiedere sull'host.

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

Configurare le variabili di ambiente

Crea .env nella radice del repository:

OPENCLAW_IMAGE=openclaw:latestOPENCLAW_GATEWAY_TOKEN=OPENCLAW_GATEWAY_BIND=lanOPENCLAW_GATEWAY_PORT=18789 OPENCLAW_CONFIG_DIR=/home/$USER/.openclawOPENCLAW_WORKSPACE_DIR=/home/$USER/.openclaw/workspace GOG_KEYRING_PASSWORD=XDG_CONFIG_HOME=/home/node/.openclaw

Imposta OPENCLAW_GATEWAY_TOKEN per gestire il token stabile del Gateway tramite .env; in alternativa, configura gateway.auth.token prima di fare affidamento sui client tra un riavvio e l'altro. Se nessuno dei due è impostato, OpenClaw utilizza per quell'avvio un token valido solo in fase di esecuzione. Genera una password per il portachiavi da assegnare a GOG_KEYRING_PASSWORD:

openssl rand -hex 32

Non eseguire il commit di questo file. Contiene variabili di ambiente del container e dell'esecuzione, come OPENCLAW_GATEWAY_TOKEN. L'autenticazione OAuth o tramite chiave API memorizzata per i provider si trova nel file ~/.openclaw/agents/<agentId>/agent/auth-profiles.json montato.

Configurazione di Docker Compose

Crea o aggiorna 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:      # Consigliato: mantieni il Gateway accessibile solo tramite loopback sulla VM; accedi tramite tunnel SSH.      # Per esporlo pubblicamente, rimuovi il prefisso `127.0.0.1:` e configura il firewall di conseguenza.      - "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 serve solo a semplificare l'avvio iniziale e non sostituisce una configurazione effettiva del Gateway. Imposta comunque l'autenticazione (gateway.auth.token o una password) e una modalità di associazione sicura per la distribuzione.

Passaggi di esecuzione condivisi per una VM Docker

Segui la guida di esecuzione condivisa per la procedura comune su un host Docker:

• Integrare i binari richiesti nell'immagine
• Compilazione e avvio
• Cosa viene conservato e dove
• Aggiornamenti

Note di avvio specifiche per GCP

Se la compilazione non riesce mostrando Killed o exit code 137 durante pnpm install --frozen-lockfile, la VM ha esaurito la memoria. Utilizza almeno e2-small oppure e2-medium per rendere più affidabili le prime compilazioni.

Quando esegui l'associazione alla LAN (OPENCLAW_GATEWAY_BIND=lan), configura un'origine attendibile per il browser prima di continuare:

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

Sostituisci 18789 con la porta configurata, se l'hai modificata.

Accedere dal laptop

Crea un tunnel SSH per inoltrare la porta del Gateway:

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

Apri http://127.0.0.1:18789/ nel browser.

Visualizza nuovamente un collegamento pulito alla dashboard:

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

Se l'interfaccia richiede l'autenticazione tramite segreto condiviso, incolla il token o la password configurati nelle impostazioni dell'interfaccia di controllo (questa procedura Docker scrive un token per impostazione predefinita; se sei passato all'autenticazione tramite password, utilizza invece la password configurata).

Se l'interfaccia di controllo mostra unauthorized o disconnected (1008): pairing required, approva il dispositivo del browser:

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

Consulta Ambiente di esecuzione per VM Docker per la mappa condivisa della persistenza e il flusso di aggiornamento.