openclaw/docs/platforms/gcp.md

summary	read_when
Run OpenClaw Gateway 24/7 on a GCP Compute Engine VM with durable state	You want OpenClaw running 24/7 on GCP You want a production-grade, always-on Gateway on your own VM You want full control over persistence, binaries, and restart behavior

OpenClaw on GCP Compute Engine

Goal

Run a persistent OpenClaw Gateway on a GCP Compute Engine VM with durable state and safe restart behavior.

Pricing varies by machine type and region; pick the smallest VM that fits your workload and scale up if needed.

Two installation paths:

• Docker (recommended for ops teams) — isolated runtime, baked binaries
• Native (recommended for personal use) — simpler setup, uses systemd

---

What you need

• GCP account (free tier eligible for e2-micro)
• gcloud CLI installed (or use Cloud Console)
• SSH access from your laptop
• Basic comfort with SSH + copy/paste
• ~20-30 minutes
• Model auth credentials (Anthropic API key recommended)
• Optional: Tailscale account (free) for secure remote access
• Optional provider credentials:
  • WhatsApp QR
  • Telegram bot token
  • Gmail OAuth

---

Quick path (experienced operators)

1. Create GCP project + enable Compute Engine API
2. Create Compute Engine VM (e2-small, Ubuntu 24.04, 20-50GB)
3. SSH into the VM
4. Install OpenClaw (Docker or native)
5. Configure channels (Telegram, WhatsApp, etc.)
6. Access via SSH tunnel or Tailscale

---

1) Install gcloud CLI (or use Console)

Option A: gcloud CLI (recommended for automation)

Install from https://cloud.google.com/sdk/docs/install

Initialize and authenticate:

gcloud init
gcloud auth login

Option B: Cloud Console

All steps can be done via the web UI at https://console.cloud.google.com

---

2) Create a GCP project

CLI:

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

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

Enable the Compute Engine API:

gcloud services enable compute.googleapis.com

Set up budget alerts (recommended):

gcloud services enable billingbudgets.googleapis.com

gcloud billing budgets create \
  --billing-account=<BILLING_ACCOUNT_ID> \
  --display-name="openclaw-budget" \
  --budget-amount=50USD \
  --filter-projects="projects/my-openclaw-project" \
  --threshold-rule=percent=50 \
  --threshold-rule=percent=90 \
  --threshold-rule=percent=100

Console:

1. Go to IAM & Admin > Create Project
2. Name it and create
3. Enable billing for the project
4. Navigate to APIs & Services > Enable APIs > search "Compute Engine API" > Enable

---

3) Create the VM

Machine types:

Type	Specs	Cost	Notes
e2-micro	2 vCPU (shared), 1GB RAM	Free tier eligible	May OOM under load
e2-small	2 vCPU, 2GB RAM	~$12/mo	Minimum recommended
e2-standard-2	2 vCPU, 8GB RAM	~$49/mo	Comfortable for heavy use

CLI:

gcloud compute instances create openclaw-gateway \
  --zone=us-central1-a \
  --machine-type=e2-small \
  --boot-disk-size=30GB \
  --boot-disk-type=pd-ssd \
  --image-family=ubuntu-2404-lts-amd64 \
  --image-project=ubuntu-os-cloud \
  --metadata=enable-oslogin=TRUE

Console:

1. Go to Compute Engine > VM instances > Create instance
2. Name: openclaw-gateway
3. Region: us-central1, Zone: us-central1-a
4. Machine type: e2-small
5. Boot disk: Ubuntu 24.04 LTS, 30GB SSD
6. Create

---

4) SSH into the VM

CLI:

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

Console:

Click the "SSH" button next to your VM in the Compute Engine dashboard.

Note: SSH key propagation can take 1-2 minutes after VM creation. If connection is refused, wait and retry.

---

5) Choose installation method

Option A: Native installation (recommended for personal use)

Install Node.js 22:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt-get install -y nodejs

Install OpenClaw:

curl -fsSL https://openclaw.bot/install.sh | bash

Or via npm:

sudo npm install -g openclaw@latest

Run onboarding:

openclaw onboard --install-daemon

The wizard configures:

• Model authentication (Anthropic API key recommended)
• Gateway as systemd service
• Messaging channels
• Security defaults

Verify:

openclaw status
openclaw gateway status

Option B: Docker installation (recommended for ops teams)

For the generic Docker flow, see Docker.

Install Docker:

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.

Clone and configure:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
mkdir -p ~/.openclaw ~/.openclaw/workspace

Create .env:

OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=<generate-with-openssl-rand-hex-32>
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_CONFIG_DIR=/home/$USER/.openclaw
OPENCLAW_WORKSPACE_DIR=/home/$USER/.openclaw/workspace
GOG_KEYRING_PASSWORD=<generate-with-openssl-rand-hex-32>
XDG_CONFIG_HOME=/home/node/.openclaw

Generate strong secrets with openssl rand -hex 32. Do not commit this file.

Create 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}
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    ports:
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
    command:
      ["node", "dist/index.js", "gateway", "--bind", "${OPENCLAW_GATEWAY_BIND}", "--port", "${OPENCLAW_GATEWAY_PORT}"]

Bake required binaries (critical for Docker):

Binaries installed at runtime are lost on restart. Add them to the Dockerfile:

FROM node:22-bookworm

RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*

# Example: Gmail CLI
RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog

# Example: WhatsApp CLI
RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli

WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN corepack enable
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production
CMD ["node","dist/index.js"]

Build and launch:

docker compose build
docker compose up -d openclaw-gateway

Verify:

docker compose logs -f openclaw-gateway

Success: [gateway] listening on ws://0.0.0.0:18789

---

6) Secure remote access

Option A: Tailscale (recommended)

Tailscale creates an encrypted mesh network. No public IP needed, no firewall rules to manage.

Install Tailscale on VM:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --ssh

Authorize the device in your browser when prompted.

Install Tailscale locally:

Install from https://tailscale.com/download and sign in to the same account.

Remove public IP (security hardening):

# Set up Cloud NAT first (for outbound traffic)
gcloud compute routers create nat-router \
  --network=default \
  --region=us-central1

gcloud compute routers nats create nat-config \
  --router=nat-router \
  --region=us-central1 \
  --nat-all-subnet-ip-ranges \
  --auto-allocate-nat-external-ips

# Remove public IP
gcloud compute instances delete-access-config openclaw-gateway \
  --zone=us-central1-a \
  --access-config-name="external-nat"

Access via Tailscale:

ssh user@openclaw-gateway  # Tailscale SSH

Access Control UI via Tailscale Serve:

Add to ~/.openclaw/openclaw.json:

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" }
  }
}

Access at https://openclaw-gateway.<tailnet>.ts.net/

Option B: SSH tunnel

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

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

---

7) Configure messaging channels

Telegram

1. Message @BotFather on Telegram
2. Send /newbot and follow prompts
3. Copy the bot token

Configure via environment:

export TELEGRAM_BOT_TOKEN="your_token_here"

Or in config (~/.openclaw/openclaw.json):

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your_token_here",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } }
    }
  }
}

Approve first user:

When someone messages your bot, they receive a pairing code. Approve with:

openclaw pairing approve telegram <CODE>

WhatsApp

openclaw channels login

Scan the QR code with WhatsApp on your phone.

---

8) Management commands

Command	Description
openclaw status	Overview of Gateway and providers
openclaw gateway status	Gateway service status
openclaw gateway restart	Restart Gateway
openclaw channels status	Channel connection status
openclaw logs --follow	Live logs
openclaw doctor	Diagnose and fix issues
openclaw security audit	Security audit
openclaw security audit --fix	Auto-fix security issues

---

What persists where

Component	Location	Persistence	Notes
Gateway config	~/.openclaw/openclaw.json	Host filesystem	Tokens, settings
Model auth	~/.openclaw/credentials/	Host filesystem	API keys, OAuth
Agent workspace	~/.openclaw/workspace/	Host filesystem	SOUL.md, MEMORY.md, skills
Sessions	~/.openclaw/agents/<id>/sessions/	Host filesystem	Conversation logs
WhatsApp session	~/.openclaw/credentials/whatsapp/	Host filesystem	Preserves QR login
External binaries	/usr/local/bin/	Docker image	Must be baked at build time
Node runtime	Container filesystem	Docker image	Rebuilt every image build

For Docker: all ~/.openclaw paths are mounted from host via volumes. Container filesystem is ephemeral.

---

Security checklist

Check	Status
Gateway on loopback only	Required
No public IP (use Tailscale)	Recommended
Cloud NAT for outbound	Required if no public IP
Pairing mode for DMs	Default
Require mention in groups	Recommended
File permissions 600/700	Required
Regular security audits	Recommended

Recommended permissions:

chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/credentials/*

---

Updates

Native installation:

sudo npm install -g openclaw@latest
openclaw gateway restart

Docker installation:

cd ~/openclaw
git pull
docker compose build
docker compose up -d

---

Troubleshooting

SSH connection refused

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

OS Login issues

gcloud compute os-login describe-profile

Ensure your account has the required IAM permissions.

Out of memory (OOM)

Upgrade machine type:

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

No internet after removing public IP

Ensure Cloud NAT is configured (see section 6).

Gateway won't start

# Check if already running
ps aux | grep openclaw

# Force restart
openclaw gateway --force --verbose

---

Service accounts (CI/CD)

For automation or CI/CD pipelines, create a dedicated service account with minimal permissions:

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

# Grant Compute Instance Admin role
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 using the Owner role for automation. Use the principle of least privilege.

See https://cloud.google.com/iam/docs/understanding-roles for IAM role details.

---

Cost summary

Component	Cost/month
e2-small VM	~$12
30GB SSD	~$5
Cloud NAT	~$1
Total	~$18

Free tier: e2-micro is eligible but may OOM under load.

Set up budget alerts to avoid surprises.

---

Next steps

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