Cara Men-deploy OpenClaw di Instance Cloud Run

1. Pengantar

Ringkasan

Di lab ini, Anda akan men-deploy instance OpenClaw yang sepenuhnya persisten dan aman—framework agen AI open source—ke Instance Cloud Run. Anda akan berinteraksi dengan agen AI secara langsung menggunakan UI Web bawaan OpenClaw (dengan opsi untuk menghubungkan saluran pesan seperti Telegram atau WhatsApp), mencadangkan ruang kerja utamanya dengan Google Cloud Storage, dan mengelola kredensial API secara aman menggunakan Google Cloud Secret Manager.

Sebelum memulai, Anda dapat mempelajari Dokumentasi OpenClaw untuk memahami arsitektur, alat, dan alur kerja agen OpenClaw.

Yang akan Anda lakukan

  • Aktifkan Google Cloud API yang diperlukan dan buat akun layanan khusus dengan izin IAM yang diperlukan.
  • Simpan kunci API dan sandi gateway dengan aman di Secret Manager.
  • Siapkan file konfigurasi openclaw.json dengan setelan model Gemini dan UI gateway yang diaktifkan.
  • Siapkan bucket Cloud Storage untuk mempertahankan status penampung.
  • Deploy OpenClaw menggunakan gcloud beta run instances deploy.
  • Berinteraksi langsung dengan agen AI OpenClaw menggunakan UI Web bawaannya.
  • (Opsional) Konfigurasi saluran pesan (Telegram atau WhatsApp).
  • (Opsional) Perluas kemampuan agen Anda dengan menambahkan Keterampilan kustom ke Cloud Storage.

Yang akan Anda pelajari

  • Cara men-deploy OpenClaw ke Instance Cloud Run dengan UI Web Kontrol bawaannya.
  • Cara memasang bucket Cloud Storage ke Instance Cloud Run.
  • Cara memasukkan secret Secret Manager secara aman sebagai variabel lingkungan ke dalam Cloud Run.
  • Cara menjalankan beban kerja agen persisten yang berjalan lama di Instance Cloud Run.
  • Cara mengonfigurasi dan mengupload kemampuan agen kustom ke Cloud Storage.

2. Penyiapan dan Persyaratan

Penyiapan Project GCP

  1. Login ke Konsol Google Cloud.
  2. Buat atau pilih Project Google Cloud.
  3. Pastikan penagihan diaktifkan untuk project Google Cloud Anda.

Buka Cloud Shell

Aktifkan Google Cloud Shell dari toolbar atas Konsol Cloud.

Menetapkan Project & Menginstal gcloud beta

Pertama, tetapkan project dan region Anda sebagai variabel lingkungan.

export PROJECT_ID=<YOUR_PROJECT_ID>
export REGION=<YOUR_REGION>

Sekarang tetapkan project Anda dan konfirmasi.

gcloud config set project $PROJECT_ID
gcloud config get project

Pastikan komponen beta diinstal untuk gcloud beta run instances:

gcloud components install beta --quiet

Selain itu, pastikan gcloud Anda sudah diupdate.

gcloud components update

Mengaktifkan Google Cloud API yang Diperlukan

Di Cloud Shell, aktifkan Cloud Run, Secret Manager, Cloud Storage, dan Gemini API:

gcloud services enable \
  run.googleapis.com \
  secretmanager.googleapis.com \
  storage.googleapis.com \
  generativelanguage.googleapis.com \
  compute.googleapis.com

3. (Opsional) Menyiapkan Integrasi Pesan (Telegram atau WhatsApp)

Anda dapat menghubungkan OpenClaw ke Telegram atau WhatsApp. Pilih Opsi A atau Opsi B di bawah.

Opsi A: Penyiapan Bot Telegram

  1. Buka Telegram dan telusuri @BotFather.
  2. Kirim perintah /newbot dan ikuti petunjuk untuk menentukan nama dan nama pengguna bot.
  3. Salin Token HTTP API yang dibuat (misalnya, 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).
  4. Telusuri @userinfobot di Telegram, kirim /start, lalu salin ID Pengguna numerik Anda (misalnya, 8035936176).

Opsi B: Penyiapan WhatsApp

  1. Dapatkan nomor telepon WhatsApp pribadi Anda dalam format internasional tanpa spasi atau simbol (misalnya, +15551234567).
  2. OpenClaw terhubung melalui kebijakan daftar yang diizinkan untuk saluran WhatsApp.

4. Buat Akun Layanan Khusus

Untuk mematuhi prinsip hak istimewa terendah, buat akun layanan IAM khusus untuk OpenClaw:

export SERVICE_ACCOUNT_NAME="openclaw-sa"
gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME} \
  --display-name="OpenClaw Service Account"

export SERVICE_ACCOUNT="${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

5. Menyimpan Kredensial di Secret Manager

Kita akan menyimpan kredensial API sensitif di Google Cloud Secret Manager sehingga Cloud Run dapat menyuntikkannya secara aman ke dalam container saat waktu booting.

1. Mendapatkan dan Menyimpan Kunci Gemini API

  1. Buka Google AI Studio dan login dengan Akun Google Anda.
  2. Klik Buat kunci API dan pilih project Google Cloud Anda (${PROJECT_ID}).
  3. Salin kunci API yang dibuat.

Simpan kunci API di Secret Manager dan beri akun layanan akses:

echo -n "YOUR_GEMINI_API_KEY" | gcloud secrets create gemini-api-key \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding gemini-api-key \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"

2. Membuat dan Menyimpan Sandi Gateway

Untuk melindungi instance OpenClaw Anda yang dapat diakses publik, buat sandi acak yang aman dan simpan di Secret Manager:

export OPENCLAW_GATEWAY_PASSWORD=$(openssl rand -hex 16)
echo "Generated Gateway Password: ${OPENCLAW_GATEWAY_PASSWORD}"

echo -n "${OPENCLAW_GATEWAY_PASSWORD}" | gcloud secrets create openclaw-gateway-password \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding openclaw-gateway-password \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"

3. (Opsional) Buat Secret Channel (Telegram atau WhatsApp)

  • Untuk Telegram:
    echo -n "YOUR_TELEGRAM_BOT_TOKEN" | gcloud secrets create telegram-bot-token \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding telegram-bot-token \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"
  • Untuk WhatsApp:
    echo -n "YOUR_WHATSAPP_TOKEN_OR_KEY" | gcloud secrets create whatsapp-token \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding whatsapp-token \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"

6. Menyiapkan Konfigurasi Bucket Cloud Storage & openclaw.json

OpenClaw memerlukan file konfigurasi bernama openclaw.json di /home/node/.openclaw/openclaw.json.

  1. Membuat Bucket Cloud Storage & Memberikan Akses:
    export BUCKET_NAME="openclaw-state-${PROJECT_ID}"
gcloud storage buckets create gs://${BUCKET_NAME} --location=${REGION}

gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/storage.objectUser"
  2. Buat openclaw.json: Buat file bernama openclaw.json di Cloud Shell. Perbarui bagian channels agar sesuai dengan channel pilihan Anda (Telegram atau WhatsApp):
    {
  "gateway": {
    "mode": "local",
    "port": 18789,
    "trustedProxies": ["0.0.0.0/0"],
    "bind": "lan",
    "auth": {
      "password": "${OPENCLAW_GATEWAY_PASSWORD}"
    },
    "controlUi": {
      "dangerouslyDisableDeviceAuth": true,
      "allowedOrigins": ["*"],
      "enabled": true
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "google/gemini-3.1-pro-preview"
      },
      "sandbox": {
        "mode": "off"
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "defaultAccount": "default",
      "accounts": {
        "default": {
          "enabled": true,
          "dmPolicy": "allowlist",
          "allowFrom": [
            "YOUR_TELEGRAM_USER_ID"
          ]
        }
      }
    },
    "whatsapp": {
      "enabled": false,
      "defaultAccount": "default",
      "accounts": {
        "default": {
          "enabled": false,
          "dmPolicy": "allowlist",
          "allowFrom": [
            "+15551234567"
          ]
        }
      }
    }
  },
  "plugins": {
    "entries": {
      "google": { "enabled": true },
      "telegram": { "enabled": true },
      "whatsapp": { "enabled": false }
    }
  }
}
  3. Upload openclaw.json ke Root Bucket Cloud Storage:
    gcloud storage cp openclaw.json gs://${BUCKET_NAME}/openclaw.json
    Verifikasi Tata Letak Bucket Cloud Storage:Pastikan struktur bucket Anda berisi openclaw.json di root:
    gs://${BUCKET_NAME}/
└── openclaw.json

7. Men-deploy OpenClaw di Instance Cloud Run

Deploy OpenClaw menggunakan gcloud beta run instances deploy:

gcloud beta run instances deploy openclaw-instance \
  --image ghcr.io/openclaw/openclaw:2026.7.1 \
  --service-account ${SERVICE_ACCOUNT} \
  --port 18789 \
  --cpu 4 \
  --memory 4Gi \
  --public \
  --add-volume mount-path=/home/node/.openclaw,type=cloud-storage,mount-options="uid=1000;gid=1000;file-mode=0700;dir-mode=0700",bucket=${BUCKET_NAME} \
  --set-secrets GEMINI_API_KEY=gemini-api-key:latest,OPENCLAW_GATEWAY_PASSWORD=openclaw-gateway-password:latest \
  --region ${REGION}

Perincian Parameter Utama:

  • --image ghcr.io/openclaw/openclaw:2026.7.1: Image container OpenClaw (disematkan ke 2026.7.1, rilis 1.x stabil terbaru).
  • --service-account ...: Melampirkan akun layanan openclaw-sa khusus.
  • --add-volume ...: Memasang bucket Cloud Storage langsung ke /home/node/.openclaw. Menggunakan file-mode=0700;dir-mode=0700 memastikan izin yang tepat untuk OpenClaw.
  • --set-secrets ...: Memasukkan kredensial langsung dari Secret Manager ke dalam variabel lingkungan. (Opsional: Jika Anda mengonfigurasi Telegram di langkah-langkah opsional, tambahkan ,TELEGRAM_BOT_TOKEN=telegram-bot-token:latest ke --set-secrets.)
  • --public: Mengizinkan akses publik ke URL.

8. Berinteraksi Langsung melalui UI Web OpenClaw

OpenClaw menyertakan UI Web Kontrol bawaan yang memungkinkan Anda mengelola dan memulai percakapan dengan agen AI langsung dari browser:

  1. Ambil URL Instance Cloud Run Anda: Di Cloud Shell, jalankan:
    gcloud beta run instances describe openclaw-instance \
  --region ${REGION} \
  --format="value(status.urls[0])"
  2. Mengakses UI Kontrol OpenClaw:
    • Buka URL output di browser web Anda.
    • Saat diminta untuk melakukan autentikasi di UI Kontrol OpenClaw:
      • Masukkan sandi gateway yang dibuat (${OPENCLAW_GATEWAY_PASSWORD}) dari Secret Manager.
      • Jika modal login menampilkan kolom Nama Pengguna dan Sandi yang terpisah, biarkan kolom nama pengguna kosong (atau masukkan admin) dan masukkan ${OPENCLAW_GATEWAY_PASSWORD} di kolom sandi.
  3. Memberi Perintah kepada Agen Anda (Instance dalam Tindakan):
    • Setelah diautentikasi, Anda akan melihat Dasbor Kontrol OpenClaw.
    • Uji agen OpenClaw Anda dengan mengirimkan perintah di UI chat, seperti, "Halo".
    • Untuk menguji siklus proses yang berjalan lama pada instance Cloud Run, Anda dapat meminta agen OpenClaw untuk melakukan tugas yang lebih canggih dan berjalan lama. Misalnya, Anda dapat membuatnya melacak feed berita atau pasar saham dan membuat laporan:
      Track the USD-to-EUR exchange rate every 15 minutes for the next 24 hours, while also checking for any recent news updates in the US or the EU that may have an impact on the exchange rate. Generate an end-of-day report for me in this chat that tells me what you expect tomorrow's exchange rate will be.
    • Kemudian, agen harus melakukan tugas ini selama 24 jam berikutnya.

9. (Opsional) Memverifikasi Integrasi Channel Pesan

Jika Anda mengonfigurasi Telegram atau WhatsApp dalam langkah-langkah penyiapan opsional di atas, Anda dapat memverifikasi pengiriman pesan:

  1. Periksa log instance di Cloud Shell:
    gcloud run instances logs read openclaw-instance --region ${REGION} --limit 20
  2. Buka Telegram (atau WhatsApp) dan kirim pesan (misalnya, /start atau Hello OpenClaw!).
  3. Bot akan mengautentikasi ID pengguna Anda terhadap daftar yang diizinkan di openclaw.json dan merespons menggunakan Gemini.

10. Memantau dan Memeriksa Log Instance

Instance Cloud Run merekam stdout dan stderr dari container Anda dan mengalirkan data tersebut langsung ke Google Cloud Logging. Anda dapat menggunakan Cloud Shell atau Konsol Cloud untuk memantau traffic gateway dan memeriksa eksekusi alat agen secara real time.

1. Membaca Log Instance Terbaru

Untuk mengambil entri log terbaru dari instance di Cloud Shell:

gcloud beta run instances logs read openclaw-instance \
  --region ${REGION} \
  --limit 50

2. Tanda Tangan Log Kunci yang Harus Diamati

Saat mengamati agen yang sedang berjalan, cari peristiwa log runtime utama berikut:

  • [gateway] ready: Mengonfirmasi bahwa gateway HTTP dan WebSocket OpenClaw telah diinisialisasi dan memproses di port 18789.
  • [gateway] agent model: ...: Menampilkan model Gemini yang aktif (misalnya, google/gemini-3.1-pro-preview atau google/gemini-3.5-flash).
  • [agents/tool-policy]: Menampilkan alat yang diizinkan atau dibatasi berdasarkan kebijakan Anda.
  • [agent/embedded]: Melacak eksekusi dan pemanggilan alat oleh agen.

3. Memeriksa Log di Konsol Google Cloud

Anda juga dapat melihat dan memfilter log menggunakan Logs Explorer di Konsol Cloud:

resource.type="cloud_run_instance"
resource.labels.instance_name="openclaw-instance"

11. (Opsional) Memperluas Agen Anda dengan Keahlian

OpenClaw mendukung Keahlian—paket kemampuan modular yang mengajarkan alur kerja tertentu, alat CLI khusus, dan petunjuk khusus domain kepada agen Anda.

Cara Kerja Keterampilan

Setiap keahlian adalah direktori yang berisi file SKILL.md. File ini dimulai dengan frontmatter YAML yang menentukan metadata (name dan description), diikuti dengan petunjuk Markdown:

---
name: summarize-logs
description: Summarize Cloud Run error logs into actionable bullet points.
---

# Log Summarizer Skill

When asked to analyze or summarize logs:
1. Parse error stack traces and group similar errors by frequency.
2. Identify root causes such as memory limits, timeouts, or permission errors.
3. Propose concrete remediation steps.
  • name: ID skill (juga dapat dipanggil langsung sebagai perintah garis miring, misalnya /summarize-logs).
  • description: Memberi tahu model OpenClaw kapan harus otomatis memanggil keahlian ini dalam percakapan alami.

Menambahkan Keterampilan Kustom ke Bucket Cloud Storage Anda

Karena bucket Cloud Storage Anda dipasang langsung ke /home/node/.openclaw, keterampilan yang ditempatkan di gs://${BUCKET_NAME}/skills/ akan otomatis dimuat saat booting dan dipertahankan di seluruh mulai ulang instance:

  1. Membuat Direktori Keahlian Lokal:
    mkdir -p my-skill
cat << 'EOF' > my-skill/SKILL.md
---
name: summarize-logs
description: Summarize Cloud Run error logs into actionable bullet points.
---

# Log Summarizer Skill

When asked to analyze or summarize logs, group errors by frequency and suggest actionable fixes.
EOF
  2. Upload Skill ke Cloud Storage:
    gcloud storage cp -r my-skill gs://${BUCKET_NAME}/skills/
  3. Menggunakan Skill di Chat:
    • Kembali ke UI Web Kontrol OpenClaw.
    • Sekarang Anda dapat memberikan perintah ke agen menggunakan /summarize-logs atau mengajukan pertanyaan dalam bahasa alami yang sesuai dengan deskripsi kemampuan!

12. Pembersihan

Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam codelab ini:

  1. Hapus Instance Cloud Run:
    gcloud beta run instances delete openclaw-instance --region ${REGION} --quiet
  2. Menghapus Secret Manager Secrets:
    gcloud secrets delete gemini-api-key --quiet
gcloud secrets delete telegram-bot-token --quiet
gcloud secrets delete openclaw-gateway-password --quiet
  3. Menghapus Bucket Cloud Storage:
    gcloud storage rm -r gs://${BUCKET_NAME}
  4. Menghapus Akun Layanan Khusus:
    gcloud iam service-accounts delete ${SERVICE_ACCOUNT} --quiet

13. Kesimpulan

Selamat! Anda telah berhasil men-deploy instance OpenClaw yang aman dan sepenuhnya persisten di Instance Cloud Run yang didukung oleh Cloud Storage, Secret Manager, dan saluran pesan pilihan Anda.