OpenClaw'u Cloud Run örneklerine dağıtma

1. Giriş

Genel Bakış

Bu laboratuvarda, açık kaynaklı bir yapay zeka aracısı çerçevesi olan OpenClaw'ın tamamen kalıcı ve güvenli bir örneğini Cloud Run örneklerine dağıtacaksınız. OpenClaw'un yerleşik web kullanıcı arayüzünü kullanarak (Telegram veya WhatsApp gibi mesajlaşma kanallarını bağlama seçeneğiyle) yapay zeka aracınızla doğrudan etkileşim kurabilir, Google Cloud Storage ile ana çalışma alanını destekleyebilir ve Google Cloud Secret Manager'ı kullanarak API kimlik bilgilerini güvenli bir şekilde yönetebilirsiniz.

Başlamadan önce OpenClaw'un mimarisi, araçları ve aracı iş akışları hakkında bilgi edinmek için OpenClaw Belgeleri'ni inceleyebilirsiniz.

Yapacaklarınız

  • Gerekli Google Cloud API'lerini etkinleştirin ve gerekli IAM izinlerine sahip özel bir hizmet hesabı oluşturun.
  • API anahtarlarını ve ağ geçidi şifrelerini Secret Manager'da güvenli bir şekilde saklayın.
  • Gemini model ayarları ve ağ geçidi kullanıcı arayüzü etkinleştirilmiş bir openclaw.json yapılandırma dosyası hazırlayın.
  • Kapsayıcı durumunu kalıcı hale getirmek için bir Cloud Storage paketi hazırlayın.
  • gcloud beta run instances deploy kullanarak OpenClaw'ı dağıtın.
  • Yerleşik web kullanıcı arayüzünü kullanarak OpenClaw yapay zeka aracınızla doğrudan etkileşim kurun.
  • (İsteğe bağlı) Mesajlaşma kanalı (Telegram veya WhatsApp) yapılandırın.
  • (İsteğe bağlı) Cloud Storage'a özel beceriler ekleyerek aracınızın yeteneklerini genişletin.

Neler öğreneceksiniz?

  • OpenClaw'ı yerleşik Control Web kullanıcı arayüzüyle Cloud Run örneklerine dağıtma
  • Cloud Storage paketlerini Cloud Run örneklerine bağlama
  • Secret Manager gizli anahtarlarını Cloud Run'a ortam değişkenleri olarak güvenli bir şekilde ekleme
  • Cloud Run örneklerinde uzun süren, kalıcı aracı iş yüklerini çalıştırma
  • Özel aracı becerilerini Cloud Storage'a yapılandırma ve yükleme

2. Kurulum ve Gereksinimler

GCP Projesi Kurulumu

  1. Google Cloud Console'da oturum açın.
  2. Google Cloud projesi oluşturun veya seçin.
  3. Google Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun.

Cloud Shell'i açın

Cloud Console'un üst araç çubuğundan Google Cloud Shell'i etkinleştirin.

Projeyi ayarlama ve gcloud beta'yı yükleme

Öncelikle projenizi ve bölgenizi ortam değişkenleri olarak ayarlayın.

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

Şimdi projenizi ayarlayın ve onaylayın.

gcloud config set project $PROJECT_ID
gcloud config get project

gcloud beta run instances için beta bileşeninin yüklendiğinden emin olun:

gcloud components install beta --quiet

Ayrıca gcloud'unuzun güncel olduğundan emin olun.

gcloud components update

Gerekli Google Cloud API'lerini etkinleştirme

Cloud Shell'de Cloud Run, Secret Manager, Cloud Storage ve Gemini API'lerini etkinleştirin:

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

3. (İsteğe bağlı) Mesajlaşma entegrasyonlarını (Telegram veya WhatsApp) ayarlama

OpenClaw'u Telegram veya WhatsApp'a bağlayabilirsiniz. Aşağıdaki A seçeneği veya B seçeneği'ni belirleyin.

A seçeneği: Telegram bot kurulumu

  1. Telegram'ı açıp @BotFather ifadesini arayın.
  2. /newbot komutunu gönderin ve bot adı ile kullanıcı adı belirtmek için istemleri uygulayın.
  3. Oluşturulan HTTP API Jetonu'nu (ör. 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ) kopyalayın.
  4. Telegram'da @userinfobot'ı arayın, /start'ı gönderin ve sayısal kullanıcı kimliğinizi (ör. 8035936176) kopyalayın.

B seçeneği: WhatsApp Kurulumu

  1. WhatsApp kişisel telefon numaranızı uluslararası standartta, boşluk veya sembol içermeyen (ör. +15551234567) biçimde alın.
  2. OpenClaw, WhatsApp kanalı izin verilenler listesi politikası üzerinden bağlanır.

4. Özel Hizmet Hesabı Oluşturma

En az ayrıcalık ilkesine uymak için OpenClaw'a özel bir IAM hizmet hesabı oluşturun:

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. Kimlik bilgilerini Secret Manager'da saklama

Hassas API kimlik bilgilerini Google Cloud Secret Manager'da saklayacağız. Böylece Cloud Run, bunları başlatma sırasında kapsayıcıya güvenli bir şekilde yerleştirebilir.

1. Gemini API anahtarını edinme ve saklama

  1. Google AI Studio'yu ziyaret edip Google Hesabınızla oturum açın.
  2. API anahtarı oluştur'u tıklayın ve Google Cloud projenizi seçin (${PROJECT_ID}).
  3. Oluşturulan API anahtarını kopyalayın.

API anahtarını Secret Manager'da saklayın ve hizmet hesabına erişim izni verin:

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. Ağ Geçidi Şifresi Oluşturma ve Saklama

Herkese açık OpenClaw örneğinizi korumak için güvenli bir rastgele şifre oluşturun ve bunu Secret Manager'da saklayın:

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. (İsteğe bağlı) Kanal gizli anahtarı oluşturma (Telegram veya WhatsApp)

  • Telegram için:
    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"
  • WhatsApp için:
    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. Cloud Storage paketi ve openclaw.json yapılandırmasını hazırlama

OpenClaw için /home/node/.openclaw/openclaw.json konumunda openclaw.json adlı bir yapılandırma dosyası gerekir.

  1. Cloud Storage paketi oluşturma ve erişim izni verme:
    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. Oluşturopenclaw.json: Cloud Shell'de openclaw.json adlı bir dosya oluşturun. channels bölümünü, seçtiğiniz kanala (Telegram veya WhatsApp) uyacak şekilde güncelleyin:
    {
  "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. Cloud Storage paketi köküne openclaw.json yükleyin:
    gcloud storage cp openclaw.json gs://${BUCKET_NAME}/openclaw.json
    Cloud Storage paket düzenini doğrulayın:Paket yapınızın kökte openclaw.json içerdiğini onaylayın:
    gs://${BUCKET_NAME}/
└── openclaw.json

7. OpenClaw'u Cloud Run örneklerine dağıtma

gcloud beta run instances deploy kullanarak OpenClaw'ı dağıtın:

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}

Temel Parametre Dökümü:

  • --image ghcr.io/openclaw/openclaw:2026.7.1: OpenClaw kapsayıcı resmi (2026.7.1'e, yani en son kararlı 1.x sürümüne sabitlenmiş).
  • --service-account ...: Özel openclaw-sa hizmet hesabını ekler.
  • --add-volume ...: Cloud Storage paketini doğrudan /home/node/.openclaw'ye bağlar. file-mode=0700;dir-mode=0700 kullanmak OpenClaw için uygun izinleri sağlar.
  • --set-secrets ...: Kimlik bilgilerini doğrudan Secret Manager'dan ortam değişkenlerine yerleştirir. (İsteğe bağlı: İsteğe bağlı adımlarda Telegram'ı yapılandırdıysanız ,TELEGRAM_BOT_TOKEN=telegram-bot-token:latest simgesini --set-secrets simgesine ekleyin.)
  • --public: URL'ye herkese açık erişim izni verir.

8. OpenClaw web kullanıcı arayüzü üzerinden doğrudan etkileşim kurma

OpenClaw, yapay zeka aracınızı doğrudan tarayıcınızdan yönetmenize ve onunla sohbet etmenize olanak tanıyan yerleşik bir Control Web kullanıcı arayüzü içerir:

  1. Cloud Run örneğinizin URL'sini alma: Cloud Shell'de şu komutu çalıştırın:
    gcloud beta run instances describe openclaw-instance \
  --region ${REGION} \
  --format="value(status.urls[0])"
  2. OpenClaw Control kullanıcı arayüzüne erişme:
    • Çıkış URL'sini web tarayıcınızda açın.
    • OpenClaw Control kullanıcı arayüzünde kimlik doğrulama istenirse:
      • Secret Manager'dan oluşturulan ağ geçidi şifresini (${OPENCLAW_GATEWAY_PASSWORD}) girin.
      • Giriş kalıcı öğesinde ayrı Kullanıcı adı ve Şifre alanları gösteriliyorsa kullanıcı adı alanını boş bırakın (veya admin girin) ve şifre alanına ${OPENCLAW_GATEWAY_PASSWORD} girin.
  3. Ajanınıza İstem Girme (İşlemdeki Örnekler):
    • Kimlik doğrulama tamamlandıktan sonra OpenClaw Control Dashboard'u görürsünüz.
    • Sohbet kullanıcı arayüzünde "Merhaba" gibi bir istem göndererek OpenClaw temsilcinizi test edin.
    • Cloud Run örneğinin uzun süreli yaşam döngüsünü test etmek için OpenClaw aracınızdan daha karmaşık ve uzun süreli bir görev gerçekleştirmesini isteyebilirsiniz. Örneğin, haber feed'ini veya borsa piyasasını takip edip rapor oluşturmasını sağlayabilirsiniz:
      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.
    • Temsilci, bu görevi önümüzdeki 24 saat içinde gerçekleştirmelidir.

9. (İsteğe bağlı) Mesajlaşma kanalı entegrasyonlarını doğrulama

Yukarıdaki isteğe bağlı kurulum adımlarında Telegram veya WhatsApp'ı yapılandırdıysanız mesaj teslimini doğrulayabilirsiniz:

  1. Cloud Shell'de örnek günlüklerini kontrol edin:
    gcloud run instances logs read openclaw-instance --region ${REGION} --limit 20
  2. Telegram'ı (veya WhatsApp'ı) açıp bir mesaj gönderin (ör. /start veya Hello OpenClaw!).
  3. Bot, kullanıcı kimliğinizi openclaw.json içindeki izin verilenler listesine göre kimlik doğrulaması yapar ve Gemini'ı kullanarak yanıt verir.

10. Örnek günlüklerini izleme ve inceleme

Cloud Run örnekleri, container'ınızdaki stdout ve stderr'yi yakalar ve doğrudan Google Cloud Logging'e aktarır. Ağ geçidi trafiğini izlemek ve aracı aracı çalıştırmalarını gerçek zamanlı olarak incelemek için Cloud Shell veya Cloud Console'u kullanabilirsiniz.

1. Son Örnek Günlüklerini Okuma

Cloud Shell'de örnekten son günlük girişlerini getirmek için:

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

2. İzlenecek Önemli Günlük İmzaları

Çalışan aracınızı gözlemlerken aşağıdaki önemli çalışma zamanı günlük etkinliklerini arayın:

  • [gateway] ready: OpenClaw HTTP ve WebSocket ağ geçidinin başlatıldığını ve 18789 numaralı bağlantı noktasında dinleme yaptığını onaylar.
  • [gateway] agent model: ...: Etkin Gemini modelini (ör. google/gemini-3.1-pro-preview veya google/gemini-3.5-flash) gösterir.
  • [agents/tool-policy]: Politikanız kapsamında izin verilen veya kısıtlanan araçları gösterir.
  • [agent/embedded]: Ajan tarafından yürütme ve araç çağrısı izlenir.

3. Google Cloud Console'da günlükleri inceleme

Ayrıca, Cloud Console'daki Günlük Gezgini'ni kullanarak günlükleri görüntüleyebilir ve filtreleyebilirsiniz:

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

11. (İsteğe bağlı) Ajanınızı becerilerle genişletin

OpenClaw, becerileri (ajanınıza belirli iş akışlarını, özel KSA araçlarını ve alana özgü talimatları öğreten modüler özellik paketleri) destekler.

Becerilerin işleyiş şekli

Her beceri, SKILL.md dosyası içeren bir dizindir. Bu işlem, meta verileri belirten YAML frontmatter ile başlar (name ve description), ardından Markdown talimatları gelir:

---
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: Beceri tanımlayıcısı (örneğin, /summarize-logs gibi eğik çizgi komutu olarak da doğrudan çağrılabilir).
  • description: OpenClaw'un modeline bu beceriyi doğal sohbette ne zaman otomatik olarak çağırması gerektiğini söyler.

Cloud Storage paketinize özel beceri ekleme

Cloud Storage paketiniz doğrudan /home/node/.openclaw'ya monte edildiğinden gs://${BUCKET_NAME}/skills/ altına yerleştirilen beceriler, başlatma sırasında otomatik olarak yüklenir ve örnek yeniden başlatıldığında kalıcı olarak saklanır:

  1. Yerel Beceri Dizini Oluşturma:
    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. Beceri dosyasını Cloud Storage'a yükleyin:
    gcloud storage cp -r my-skill gs://${BUCKET_NAME}/skills/
  3. Chat'te beceriyi kullanma:
    • OpenClaw Control Web UI'ye dönün.
    • Artık /summarize-logs kullanarak temsilcinize istem girebilir veya beceri açıklamasına uygun doğal dil soruları sorabilirsiniz.

12. Temizleme

Bu codelab'de kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini istemiyorsanız:

  1. Cloud Run örneğini silin:
    gcloud beta run instances delete openclaw-instance --region ${REGION} --quiet
  2. Secret Manager gizli anahtarlarını silme:
    gcloud secrets delete gemini-api-key --quiet
gcloud secrets delete telegram-bot-token --quiet
gcloud secrets delete openclaw-gateway-password --quiet
  3. Cloud Storage paketini silme:
    gcloud storage rm -r gs://${BUCKET_NAME}
  4. Özel hizmet hesabını silme:
    gcloud iam service-accounts delete ${SERVICE_ACCOUNT} --quiet

13. Sonuç

Tebrikler! Cloud Storage, Secret Manager ve tercih ettiğiniz mesajlaşma kanalı tarafından desteklenen Cloud Run örneklerinde OpenClaw'ın güvenli ve tamamen kalıcı bir örneğini başarıyla dağıttınız.