GCP

Install gcloud CLI (or use Console)

گزینه A: gcloud CLI (پیشنهادی برای automation)

از https://cloud.google.com/sdk/docs/install نصب کنید

مقداردهی اولیه و احراز هویت:

gcloud init
gcloud auth login

گزینه B: Cloud Console

همه مراحل را می‌توان از طریق رابط وب در https://console.cloud.google.com انجام داد

Create a GCP project

CLI:

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

صورتحساب را در https://console.cloud.google.com/billing فعال کنید (برای Compute Engine لازم است).

API مربوط به Compute Engine را فعال کنید:

gcloud services enable compute.googleapis.com

Console:

1. به IAM & Admin > Create Project بروید
2. نامی برای آن بگذارید و ایجاد کنید
3. صورتحساب را برای پروژه فعال کنید
4. به APIs & Services > Enable APIs بروید > عبارت "Compute Engine API" را جست‌وجو کنید > Enable را بزنید

Create the VM

انواع ماشین:

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. به Compute Engine > VM instances > Create instance بروید
2. نام: openclaw-gateway
3. Region: us-central1، Zone: us-central1-a
4. نوع ماشین: e2-small
5. دیسک راه‌انداز: Debian 12، 20GB
6. ایجاد کنید

SSH into the VM

CLI:

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

Console:

در داشبورد Compute Engine، کنار VM خود روی دکمه "SSH" کلیک کنید.

نکته: انتشار کلید SSH پس از ایجاد VM ممکن است ۱ تا ۲ دقیقه طول بکشد. اگر اتصال رد شد، صبر کنید و دوباره تلاش کنید.

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

برای اعمال تغییر گروه، خارج شوید و دوباره وارد شوید:

exit

سپس دوباره با SSH وارد شوید:

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

بررسی کنید:

docker --version
docker compose version

Clone the OpenClaw repository

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

این راهنما فرض می‌کند برای تضمین ماندگاری باینری‌ها، یک image سفارشی build می‌کنید.

Create persistent host directories

کانتینرهای Docker ناپایدار هستند. تمام وضعیت‌های بلندمدت باید روی میزبان قرار بگیرند.

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

Configure environment variables

در ریشه مخزن، .env بسازید.

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

زمانی OPENCLAW_GATEWAY_TOKEN را تنظیم کنید که می‌خواهید token پایدار Gateway را از طریق .env مدیریت کنید؛ در غیر این صورت پیش از اتکا به clientها در بین راه‌اندازی‌های مجدد، gateway.auth.token را پیکربندی کنید. اگر هیچ‌کدام از این منابع وجود نداشته باشد، OpenClaw برای آن اجرا از یک token فقط زمان اجرا استفاده می‌کند. یک گذرواژه keyring بسازید و آن را در GOG_KEYRING_PASSWORD وارد کنید:

openssl rand -hex 32

این فایل را commit نکنید.

این فایل .env برای env مربوط به کانتینر/زمان اجرا مانند OPENCLAW_GATEWAY_TOKEN است. احراز هویت ذخیره‌شده provider از نوع OAuth/API-key در فایل mountشده‌ی ~/.openclaw/agents/<agentId>/agent/auth-profiles.json قرار دارد.

Docker Compose configuration

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 فقط برای سهولت bootstrap است و جایگزین پیکربندی درست Gateway نیست. همچنان auth (gateway.auth.token یا گذرواژه) را تنظیم کنید و برای استقرار خود از تنظیمات bind امن استفاده کنید.

Shared Docker VM runtime steps

برای جریان رایج میزبان Docker، از راهنمای runtime مشترک استفاده کنید:

• آماده‌سازی باینری‌های لازم داخل image
• Build و اجرا
• چه چیزی کجا ماندگار می‌شود
• به‌روزرسانی‌ها

GCP-specific launch notes

در GCP، اگر build هنگام pnpm install --frozen-lockfile با Killed یا exit code 137 شکست خورد، حافظه VM تمام شده است. حداقل از e2-small استفاده کنید، یا برای buildهای اولیه قابل‌اتکاتر از e2-medium استفاده کنید.

هنگام bind کردن به LAN (OPENCLAW_GATEWAY_BIND=lan)، پیش از ادامه یک browser origin مورد اعتماد پیکربندی کنید:

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

اگر پورت Gateway را تغییر داده‌اید، 18789 را با پورت پیکربندی‌شده خود جایگزین کنید.

Access from your laptop

یک تونل SSH بسازید تا پورت Gateway را forward کند:

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

در مرورگر خود باز کنید:

http://127.0.0.1:18789/

یک لینک تمیز داشبورد را دوباره چاپ کنید:

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

اگر رابط کاربری برای احراز هویت shared-secret درخواست داد، token یا گذرواژه پیکربندی‌شده را در تنظیمات رابط کاربری کنترل وارد کنید. این جریان Docker به‌صورت پیش‌فرض یک token می‌نویسد؛ اگر پیکربندی کانتینر را به احراز هویت با گذرواژه تغییر دهید، به‌جای آن از همان گذرواژه استفاده کنید.

اگر رابط کاربری کنترل unauthorized یا disconnected (1008): pairing required نشان داد، دستگاه مرورگر را تأیید کنید:

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

دوباره به مرجع مشترک ماندگاری و به‌روزرسانی نیاز دارید؟ Docker VM Runtime و به‌روزرسانی‌های Docker VM Runtime را ببینید.