Run OpenClaw Gateway on GCP Compute Engine with Docker

Run a persistent OpenClaw Gateway on a GCP Compute Engine VM using Docker. The setup includes durable state, pre-baked binaries, and safe restart behavior.

Pricing depends on the machine type and region you choose. Start with the smallest VM that handles your workload and scale up if you run into out-of-memory errors.

You can reach the Gateway through SSH port forwarding from your laptop, or by exposing ports directly if you handle firewalling and tokens yourself.

This guide uses Debian on GCP Compute Engine. Ubuntu works too; adjust the packages accordingly. For the generic Docker workflow, see Docker.

What you need

• A GCP account (e2-micro qualifies for the free tier)
• The gcloud CLI, or the Cloud Console
• SSH access from your laptop
• Docker and Docker Compose installed
• Model authentication credentials
• Optional provider credentials (WhatsApp QR, Telegram bot token, Gmail OAuth)
• About 20-30 minutes

Quick path

1. Create a GCP project, enable billing, and turn on the Compute Engine API
2. Provision a Compute Engine VM (e2-small, Debian 12, 20GB disk)
3. SSH into the VM and install Docker
4. Clone the OpenClaw repository
5. Set up persistent directories on the host
6. Configure .env and docker-compose.yml
7. Bake the required binaries, build the image, and start the container

Install gcloud CLI (or use Console)

Install from cloud.google.com/sdk/docs/install, then:

gcloud init
gcloud auth login

Alternatively, you can do every step through the Cloud Console web interface instead.

Create a GCP project

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

Enable billing at console.cloud.google.com/billing (required for Compute Engine).

Console equivalent: go to IAM & Admin, create a project, enable billing, then navigate to APIs & Services, enable APIs, find "Compute Engine API", and enable it.

Create the 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

SSH into the VM

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

Console: click "SSH" next to the VM in the Compute Engine dashboard.

SSH key propagation can take 1-2 minutes after VM creation; wait and retry if connection is refused.

Install Docker (on the 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

Log out and back in for the group change to take effect, then SSH back in:

exit

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

Verify:

docker --version
docker compose version

Clone the OpenClaw repository

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

This guide builds a custom image so any binaries you bake in survive restarts.

Create persistent host directories

Docker containers are ephemeral; all long-lived state must live on the host.

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

Configure environment variables

Create .env in the repository root:

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

Set OPENCLAW_GATEWAY_TOKEN to manage the stable gateway token through .env; otherwise configure gateway.auth.token before relying on clients across restarts. If neither is set, OpenClaw uses a runtime-only token for that startup. Generate a keyring password for GOG_KEYRING_PASSWORD:

openssl rand -hex 32

Do not commit this file. It holds container/runtime env such as OPENCLAW_GATEWAY_TOKEN. Stored provider OAuth/API-key auth lives in the mounted ~/.openclaw/agents/<agentId>/agent/auth-profiles.json.

Docker Compose configuration

Create or update 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 is only for bootstrap convenience, not a substitute for real gateway configuration. Still set auth (gateway.auth.token or password) and a safe bind mode for your deployment.

Shared Docker VM runtime steps

Follow the shared runtime guide for the common Docker host flow:

• Bake required binaries into the image
• Build and launch
• What persists where
• Updates

GCP-specific launch notes

If the build fails with Killed or exit code 137 during pnpm install --frozen-lockfile, the VM is out of memory. Use e2-small at minimum, or e2-medium for more reliable first builds.

When binding to LAN (OPENCLAW_GATEWAY_BIND=lan), configure a trusted browser origin before continuing:

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

Replace 18789 with your configured port if you changed it.

Access from your laptop

Create an SSH tunnel to forward the Gateway port:

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

Open http://127.0.0.1:18789/ in your browser.

Reprint a clean dashboard link:

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

If the UI prompts for shared-secret auth, paste the configured token or password into Control UI settings (this Docker flow writes a token by default; use your configured password instead if you switched to password auth).

If Control UI shows unauthorized or disconnected (1008): pairing required, approve the browser device:

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

See Docker VM Runtime for the shared persistence map and update flow.

Troubleshooting

SSH connection refused

SSH key propagation can take 1-2 minutes after VM creation. Wait and retry.

OS Login issues

Check your OS Login profile:

gcloud compute os-login describe-profile

Ensure your account has the required IAM permissions (Compute OS Login or Compute OS Admin Login).

Out of memory (OOM)

If the Docker build fails with Killed and exit code 137, the VM was OOM-killed:

# Stop the VM first
gcloud compute instances stop openclaw-gateway --zone=us-central1-a

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

# Start the VM
gcloud compute instances start openclaw-gateway --zone=us-central1-a

Service accounts (security best practice)

For personal use, your default user account works fine. For automation or CI/CD, create a dedicated service account with minimal permissions:

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"

Avoid the Owner role for automation; use the narrowest role that works. See Understanding roles.

Next steps

• Set up messaging channels: Channels
• Pair local devices as nodes: Nodes
• Configure the Gateway: Gateway configuration

Related

• Install overview
• Azure
• VPS hosting