Langsung ke konten utama

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Jalankan OpenClaw Gateway yang persisten di VM GCP Compute Engine menggunakan Docker, dengan state yang tahan lama, biner yang sudah dibundel, dan perilaku restart yang aman. Jika Anda menginginkan “OpenClaw 24/7 dengan biaya sekitar ~$5-12/bln”, ini adalah penyiapan yang andal di Google Cloud. Harga bervariasi berdasarkan tipe mesin dan region; pilih VM terkecil yang sesuai dengan beban kerja Anda dan tingkatkan skalanya jika mengalami OOM.

​
Apa yang kita lakukan (secara sederhana)?

  • Membuat project GCP dan mengaktifkan billing
  • Membuat VM Compute Engine
  • Menginstal Docker (runtime aplikasi terisolasi)
  • Memulai OpenClaw Gateway di Docker
  • Menyimpan ~/.openclaw + ~/.openclaw/workspace secara persisten di host (tetap ada setelah restart/rebuild)
  • Mengakses UI Kontrol dari laptop Anda melalui tunnel SSH
State ~/.openclaw yang di-mount tersebut mencakup openclaw.json, per-agent agents/<agentId>/agent/auth-profiles.json, dan .env. Gateway dapat diakses melalui:
  • Penerusan port SSH dari laptop Anda
  • Eksposur port langsung jika Anda mengelola firewall dan token sendiri
Panduan ini menggunakan Debian di GCP Compute Engine. Ubuntu juga berfungsi; petakan paketnya sesuai kebutuhan. Untuk alur Docker generik, lihat Docker.

​
Jalur cepat (operator berpengalaman)

  1. Buat project GCP + aktifkan Compute Engine API
  2. Buat VM Compute Engine (e2-small, Debian 12, 20GB)
  3. SSH ke VM
  4. Instal Docker
  5. Clone repositori OpenClaw
  6. Buat direktori host persisten
  7. Konfigurasikan .env dan docker-compose.yml
  8. Bundel biner yang diperlukan, build, dan jalankan

​
Yang Anda perlukan

  • Akun GCP (memenuhi syarat free tier untuk e2-micro)
  • gcloud CLI terinstal (atau gunakan Cloud Console)
  • Akses SSH dari laptop Anda
  • Kenyamanan dasar dengan SSH + salin/tempel
  • ~20-30 menit
  • Docker dan Docker Compose
  • Kredensial auth model
  • Kredensial provider opsional
    • WhatsApp QR
    • Token bot Telegram
    • Gmail OAuth
1

Instal gcloud CLI (atau gunakan Console)

Opsi A: gcloud CLI (direkomendasikan untuk otomatisasi)Instal dari https://cloud.google.com/sdk/docs/installInisialisasi dan autentikasi:
gcloud init
gcloud auth login
Opsi B: Cloud ConsoleSemua langkah dapat dilakukan melalui UI web di https://console.cloud.google.com
2

Buat project GCP

CLI:
gcloud projects create my-openclaw-project --name="OpenClaw Gateway"
gcloud config set project my-openclaw-project
Aktifkan billing di https://console.cloud.google.com/billing (diperlukan untuk Compute Engine).Aktifkan Compute Engine API:
gcloud services enable compute.googleapis.com
Console:
  1. Buka IAM & Admin > Create Project
  2. Beri nama dan buat
  3. Aktifkan billing untuk project
  4. Buka APIs & Services > Enable APIs > cari “Compute Engine API” > Enable
3

Buat VM

Tipe mesin:
TipeSpesifikasiBiayaCatatan
e2-medium2 vCPU, 4GB RAM~$25/blnPaling andal untuk build Docker lokal
e2-small2 vCPU, 2GB RAM~$12/blnMinimum yang direkomendasikan untuk build Docker
e2-micro2 vCPU (shared), 1GB RAMMemenuhi syarat free tierSering gagal dengan OOM build Docker (exit 137)
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. Buka Compute Engine > VM instances > Create instance
  2. Nama: openclaw-gateway
  3. Region: us-central1, Zone: us-central1-a
  4. Tipe mesin: e2-small
  5. Boot disk: Debian 12, 20GB
  6. Buat
4

SSH ke VM

CLI:
gcloud compute ssh openclaw-gateway --zone=us-central1-a
Console:Klik tombol “SSH” di samping VM Anda pada dasbor Compute Engine.Catatan: Propagasi kunci SSH dapat memerlukan 1-2 menit setelah VM dibuat. Jika koneksi ditolak, tunggu dan coba lagi.
5

Instal Docker (di 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
Logout dan login kembali agar perubahan grup berlaku:
exit
Lalu SSH kembali:
gcloud compute ssh openclaw-gateway --zone=us-central1-a
Verifikasi:
docker --version
docker compose version
6

Clone repositori OpenClaw

git clone https://github.com/openclaw/openclaw.git
cd openclaw
Panduan ini mengasumsikan Anda akan membuat image kustom untuk menjamin persistensi biner.
7

Buat direktori host persisten

Container Docker bersifat efemeral. Semua state jangka panjang harus berada di host.
mkdir -p ~/.openclaw
mkdir -p ~/.openclaw/workspace
8

Konfigurasikan variabel lingkungan

Buat .env di root repositori.
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
Setel OPENCLAW_GATEWAY_TOKEN ketika Anda ingin mengelola token gateway stabil melalui .env; jika tidak, konfigurasikan gateway.auth.token sebelum mengandalkan klien lintas restart. Jika kedua sumber tidak ada, OpenClaw menggunakan token khusus runtime untuk startup tersebut. Buat password keyring dan tempelkan ke GOG_KEYRING_PASSWORD:
openssl rand -hex 32
Jangan commit file ini.File .env ini untuk env container/runtime seperti OPENCLAW_GATEWAY_TOKEN. Auth OAuth/API-key provider yang disimpan berada di ~/.openclaw/agents/<agentId>/agent/auth-profiles.json yang di-mount.
9

Konfigurasi Docker Compose

Buat atau perbarui 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 hanya untuk kemudahan bootstrap, bukan pengganti konfigurasi gateway yang tepat. Tetap setel auth (gateway.auth.token atau password) dan gunakan pengaturan bind yang aman untuk deployment Anda.
10

Langkah runtime VM Docker bersama

Gunakan panduan runtime bersama untuk alur host Docker umum:
11

Catatan peluncuran khusus GCP

Di GCP, jika build gagal dengan Killed atau exit code 137 selama pnpm install --frozen-lockfile, VM kehabisan memori. Gunakan minimum e2-small, atau e2-medium untuk build pertama yang lebih andal.Saat bind ke LAN (OPENCLAW_GATEWAY_BIND=lan), konfigurasikan origin browser tepercaya sebelum melanjutkan:
docker compose run --rm openclaw-cli config set gateway.controlUi.allowedOrigins '["http://127.0.0.1:18789"]' --strict-json
Jika Anda mengubah port gateway, ganti 18789 dengan port yang Anda konfigurasikan.
12

Akses dari laptop Anda

Buat tunnel SSH untuk meneruskan port Gateway:
gcloud compute ssh openclaw-gateway --zone=us-central1-a -- -L 18789:127.0.0.1:18789
Buka di browser Anda:http://127.0.0.1:18789/Cetak ulang tautan dasbor yang bersih:
docker compose run --rm openclaw-cli dashboard --no-open
Jika UI meminta auth shared-secret, tempelkan token atau password yang dikonfigurasi ke pengaturan UI Kontrol. Alur Docker ini menulis token secara default; jika Anda mengubah konfigurasi container ke auth password, gunakan password tersebut sebagai gantinya.Jika UI Kontrol menampilkan unauthorized atau disconnected (1008): pairing required, setujui perangkat browser:
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>
Perlu referensi persistensi dan pembaruan bersama lagi? Lihat Runtime VM Docker dan pembaruan Runtime VM Docker.

​
Pemecahan masalah

Koneksi SSH ditolak Propagasi kunci SSH dapat memerlukan 1-2 menit setelah VM dibuat. Tunggu dan coba lagi. Masalah OS Login Periksa profil OS Login Anda: 
gcloud compute os-login describe-profile
Pastikan akun Anda memiliki izin IAM yang diperlukan (Compute OS Login atau Compute OS Admin Login). Kehabisan memori (OOM) Jika build Docker gagal dengan Killed dan exit code 137, VM dihentikan karena OOM. Upgrade ke e2-small (minimum) atau e2-medium (direkomendasikan untuk build lokal yang andal): 
# 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

​
Akun layanan (praktik terbaik keamanan)

Untuk penggunaan pribadi, akun pengguna default Anda sudah cukup. Untuk otomatisasi atau pipeline CI/CD, buat akun layanan khusus dengan izin minimal:
  1. Buat akun layanan: 
    gcloud iam service-accounts create openclaw-deploy \
  --display-name="OpenClaw Deployment"
  2. Berikan role Compute Instance Admin (atau role kustom yang lebih sempit): 
    gcloud projects add-iam-policy-binding my-openclaw-project \
  --member="serviceAccount:openclaw-deploy@my-openclaw-project.iam.gserviceaccount.com" \
  --role="roles/compute.instanceAdmin.v1"
Hindari menggunakan role Owner untuk otomatisasi. Gunakan prinsip hak akses paling sedikit. Lihat https://cloud.google.com/iam/docs/understanding-roles untuk detail role IAM.

​
Langkah berikutnya

​
Terkait