OpenClaw auf Cloud Run-Instanzen bereitstellen

1. Einführung

Übersicht

In diesem Lab stellen Sie eine vollständig persistente, sichere Instanz von OpenClaw – einem Open-Source-Framework für KI-Agenten – in Cloud Run-Instanzen bereit. Sie interagieren direkt mit Ihrem KI-Agenten über die integrierte Weboberfläche von OpenClaw (mit der Option, Messaging-Kanäle wie Telegram oder WhatsApp zu verbinden), sichern den zugehörigen Arbeitsbereich mit Google Cloud Storage und verwalten API-Anmeldedaten sicher mit Google Cloud Secret Manager.

Bevor Sie loslegen, können Sie sich in der OpenClaw-Dokumentation mit der Architektur, den Tools und den Agent-Workflows von OpenClaw vertraut machen.

Aufgaben

  • Aktivieren Sie die erforderlichen Google Cloud APIs und erstellen Sie ein dediziertes Dienstkonto mit den erforderlichen IAM-Berechtigungen.
  • Speichern Sie API-Schlüssel und Gateway-Passwörter sicher in Secret Manager.
  • Bereiten Sie eine openclaw.json-Konfigurationsdatei mit Gemini-Modelleinstellungen vor, in der die Gateway-Benutzeroberfläche aktiviert ist.
  • Cloud Storage-Bucket zum Speichern des Containerstatus vorbereiten
  • Stellen Sie OpenClaw mit gcloud beta run instances deploy bereit.
  • Über die integrierte Web-UI können Sie direkt mit Ihrem OpenClaw-KI-Agenten interagieren.
  • Optional: Konfigurieren Sie einen Messaging-Kanal (Telegram oder WhatsApp).
  • (Optional) Erweitern Sie die Funktionen Ihres Agents, indem Sie benutzerdefinierte Skills in Cloud Storage hinzufügen.

Lerninhalte

  • OpenClaw in Cloud Run-Instanzen mit der integrierten Control Web-UI bereitstellen
  • Cloud Storage-Buckets für Cloud Run-Instanzen bereitstellen
  • Secret Manager-Secrets sicher als Umgebungsvariablen in Cloud Run einfügen.
  • Lang laufende, persistente Agent-Arbeitslasten in Cloud Run-Instanzen ausführen
  • Benutzerdefinierte Agent-Skills konfigurieren und in Cloud Storage hochladen

2. Einrichtung und Anforderungen

GCP-Projekt einrichten

  1. Melden Sie sich in der Google Cloud Console an.
  2. Erstellen Sie ein Google Cloud-Projekt oder wählen Sie eines aus.
  3. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

Cloud Shell öffnen

Aktivieren Sie Google Cloud Shell über die obere Symbolleiste der Cloud Console.

Projekt festlegen und gcloud beta installieren

Legen Sie zuerst Ihr Projekt und Ihre Region als Umgebungsvariablen fest.

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

Legen Sie jetzt Ihr Projekt fest und bestätigen Sie es.

gcloud config set project $PROJECT_ID
gcloud config get project

Prüfen Sie, ob die Komponente beta für gcloud beta run instances installiert ist:

gcloud components install beta --quiet

Achten Sie außerdem darauf, dass Ihre gcloud-Version auf dem neuesten Stand ist.

gcloud components update

Erforderliche Google Cloud APIs aktivieren

Aktivieren Sie in Cloud Shell die Cloud Run-, Secret Manager-, Cloud Storage- und Gemini-APIs:

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

3. (Optional) Messaging-Integrationen einrichten (Telegram oder WhatsApp)

Sie können OpenClaw mit Telegram oder WhatsApp verbinden. Wählen Sie unten Option A oder Option B aus.

Option A: Telegram-Bot einrichten

  1. Öffnen Sie Telegram und suchen Sie nach @BotFather.
  2. Senden Sie den Befehl /newbot und folgen Sie der Anleitung, um einen Bot-Namen und einen Nutzernamen anzugeben.
  3. Kopieren Sie das generierte HTTP API-Token (z.B. 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).
  4. Suchen Sie in Telegram nach @userinfobot, senden Sie /start und kopieren Sie Ihre numerische Nutzer-ID (z.B. 8035936176).

Option B: WhatsApp-Einrichtung

  1. Ihre private WhatsApp-Telefonnummer im internationalen Format ohne Leerzeichen oder Symbole (z. B. +15551234567)
  2. OpenClaw stellt die Verbindung über die Richtlinie für die Zulassungsliste für WhatsApp-Kanäle her.

4. Dediziertes Dienstkonto erstellen

Um das Prinzip der geringsten Berechtigung einzuhalten, erstellen Sie ein dediziertes IAM-Dienstkonto für 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. Anmeldedaten in Secret Manager speichern

Wir speichern vertrauliche API-Anmeldedaten in Google Cloud Secret Manager, damit Cloud Run sie beim Start sicher in den Container einfügen kann.

1. Gemini API-Schlüssel abrufen und speichern

  1. Rufen Sie Google AI Studio auf und melden Sie sich mit Ihrem Google-Konto an.
  2. Klicken Sie auf API-Schlüssel erstellen und wählen Sie Ihr Google Cloud-Projekt (${PROJECT_ID}) aus.
  3. Kopieren Sie den generierten API-Schlüssel.

Speichern Sie den API-Schlüssel in Secret Manager und gewähren Sie dem Dienstkonto Zugriff:

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. Gateway-Passwort generieren und speichern

Um Ihre öffentlich zugängliche OpenClaw-Instanz zu schützen, generieren Sie ein sicheres zufälliges Passwort und speichern Sie es im 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. Optional: Channel-Secret erstellen (Telegram oder WhatsApp)

  • Für 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"
  • Für 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. Cloud Storage-Bucket und openclaw.json-Konfiguration vorbereiten

OpenClaw erfordert eine Konfigurationsdatei mit dem Namen openclaw.json unter /home/node/.openclaw/openclaw.json.

  1. Cloud Storage-Bucket erstellen und Zugriff gewähren:
    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. Erstellenopenclaw.json: Erstellen Sie in Cloud Shell eine Datei mit dem Namen openclaw.json. Aktualisieren Sie den channels-Abschnitt entsprechend dem von Ihnen ausgewählten Kanal (Telegram oder 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. openclaw.json in das Stammverzeichnis des Cloud Storage-Buckets hochladen:
    gcloud storage cp openclaw.json gs://${BUCKET_NAME}/openclaw.json
    Cloud Storage-Bucket-Layout prüfen:Bestätigen Sie, dass Ihre Bucket-Struktur openclaw.json im Stammverzeichnis enthält:
    gs://${BUCKET_NAME}/
└── openclaw.json

7. OpenClaw in Cloud Run-Instanzen bereitstellen

Stellen Sie OpenClaw mit gcloud beta run instances deploy bereit:

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}

Aufschlüsselung der wichtigsten Parameter:

  • --image ghcr.io/openclaw/openclaw:2026.7.1: OpenClaw-Container-Image (an 2026.7.1 angepinnt, die aktuelle stabile 1.x-Version).
  • --service-account ...: Hängt das dedizierte openclaw-sa-Dienstkonto an.
  • --add-volume ...: Der Cloud Storage-Bucket wird direkt in /home/node/.openclaw eingebunden. Die Verwendung von file-mode=0700;dir-mode=0700 sorgt für die richtigen Berechtigungen für OpenClaw.
  • --set-secrets ...: Fügt Anmeldedaten direkt aus Secret Manager in Umgebungsvariablen ein. (Optional: Wenn Sie Telegram in den optionalen Schritten konfiguriert haben, hängen Sie ,TELEGRAM_BOT_TOKEN=telegram-bot-token:latest an --set-secrets an.)
  • --public: Ermöglicht öffentlichen Zugriff auf die URL.

8. Direkt über die OpenClaw-Web-UI interagieren

OpenClaw enthält eine integrierte Control Web-Benutzeroberfläche, über die Sie Ihren KI-Agenten direkt über Ihren Browser verwalten und mit ihm chatten können:

  1. Cloud Run-Instanz-URL abrufen: Führen Sie in Cloud Shell folgenden Befehl aus:
    gcloud beta run instances describe openclaw-instance \
  --region ${REGION} \
  --format="value(status.urls[0])"
  2. Auf die OpenClaw Control-Benutzeroberfläche zugreifen:
    • Öffnen Sie die Ausgabewebadresse in Ihrem Webbrowser.
    • Wenn Sie in der OpenClaw Control-Benutzeroberfläche zur Authentifizierung aufgefordert werden:
      • Geben Sie das generierte Gateway-Passwort (${OPENCLAW_GATEWAY_PASSWORD}) aus Secret Manager ein.
      • Wenn im Anmelde-Modal separate Felder für Nutzername und Passwort angezeigt werden, lassen Sie das Feld für den Nutzernamen leer (oder geben Sie admin ein) und geben Sie ${OPENCLAW_GATEWAY_PASSWORD} im Feld für das Passwort ein.
  3. Agenten auffordern (Instanzen in Aktion):
    • Nach der Authentifizierung wird das OpenClaw Control-Dashboard angezeigt.
    • Testen Sie Ihren OpenClaw-Agenten, indem Sie in der Chat-Benutzeroberfläche einen Prompt wie „Hallo“ senden.
    • Um den langlebigen Lebenszyklus der Cloud Run-Instanz zu testen, können Sie Ihren OpenClaw-Agenten auffordern, eine komplexere, langlebige Aufgabe auszuführen. Sie können beispielsweise einen Nachrichten-Feed oder den Aktienmarkt im Blick behalten und Berichte erstellen lassen:
      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.
    • Der Agent sollte diese Aufgabe dann innerhalb der nächsten 24 Stunden ausführen.

9. (Optional) Messaging-Kanalintegrationen prüfen

Wenn Sie Telegram oder WhatsApp in den optionalen Einrichtungsschritten oben konfiguriert haben, können Sie die Zustellung von Nachrichten so überprüfen:

  1. Prüfen Sie die Instanzlogs in Cloud Shell:
    gcloud run instances logs read openclaw-instance --region ${REGION} --limit 20
  2. Öffnen Sie Telegram (oder WhatsApp) und senden Sie eine Nachricht (z.B. /start oder Hello OpenClaw!).
  3. Der Bot authentifiziert Ihre Nutzer-ID anhand der Zulassungsliste in openclaw.json und antwortet mit Gemini.

10. Instanzlogs überwachen und prüfen

Cloud Run-Instanzen erfassen stdout und stderr aus Ihrem Container und streamen sie direkt an Google Cloud Logging. Sie können Cloud Shell oder die Cloud Console verwenden, um den Gateway-Traffic zu überwachen und Agent-Tool-Ausführungen in Echtzeit zu prüfen.

1. Letzte Instanzprotokolle lesen

So rufen Sie die letzten Logeinträge der Instanz in Cloud Shell ab:

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

2. Wichtige Log-Signaturen, die Sie im Blick behalten sollten

Achten Sie beim Beobachten des ausgeführten Agents auf die folgenden wichtigen Laufzeit-Logereignisse:

  • [gateway] ready: Bestätigt, dass das OpenClaw-HTTP- und WebSocket-Gateway initialisiert wurde und Port 18789 überwacht.
  • [gateway] agent model: ...: Hier wird das aktive Gemini-Modell angezeigt, z.B. google/gemini-3.1-pro-preview oder google/gemini-3.5-flash.
  • [agents/tool-policy]: Hier sehen Sie die Tools, die gemäß Ihrer Richtlinie zulässig oder eingeschränkt sind.
  • [agent/embedded]: Verfolgt die Ausführung und den Toolaufruf durch den Agenten.

3. Logs in der Google Cloud Console ansehen

Sie können Logs auch mit dem Log-Explorer in der Cloud Console aufrufen und filtern:

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

11. Optional: Agent mit Skills erweitern

OpenClaw unterstützt Skills – modulare Fähigkeitspakete, mit denen Ihr Agent bestimmte Workflows, spezialisierte CLI-Tools und domainspezifische Anweisungen erlernen kann.

Funktionsweise von Skills

Jede Fähigkeit ist ein Verzeichnis mit einer SKILL.md-Datei. Es beginnt mit YAML-Frontmatter, in der Metadaten (name und description) angegeben werden, gefolgt von Markdown-Anweisungen:

---
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: Die Skill-ID (kann auch direkt als Slash-Befehl aufgerufen werden, z. B. /summarize-logs).
  • description: Gibt dem Modell von OpenClaw an, wann dieser Skill automatisch in einer natürlichen Unterhaltung aufgerufen werden soll.

Benutzerdefinierten Skill Ihrem Cloud Storage-Bucket hinzufügen

Da Ihr Cloud Storage-Bucket direkt in /home/node/.openclaw eingebunden ist, werden Skills, die sich unter gs://${BUCKET_NAME}/skills/ befinden, automatisch beim Start geladen und bleiben auch nach Neustarts der Instanz erhalten:

  1. Lokales Skill-Verzeichnis erstellen:
    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. Skill in Cloud Storage hochladen:
    gcloud storage cp -r my-skill gs://${BUCKET_NAME}/skills/
  3. Skill im Chat verwenden:
    • Kehren Sie zur OpenClaw Control Web-UI zurück.
    • Sie können Ihren Agenten jetzt mit /summarize-logs auffordern oder Fragen in natürlicher Sprache stellen, die der Skillbeschreibung entsprechen.

12. Bereinigen

So vermeiden Sie, dass Ihrem Google Cloud-Konto die in diesem Codelab verwendeten Ressourcen in Rechnung gestellt werden:

  1. Cloud Run-Instanz löschen:
    gcloud beta run instances delete openclaw-instance --region ${REGION} --quiet
  2. Secret Manager-Secrets löschen:
    gcloud secrets delete gemini-api-key --quiet
gcloud secrets delete telegram-bot-token --quiet
gcloud secrets delete openclaw-gateway-password --quiet
  3. Cloud Storage-Bucket löschen:
    gcloud storage rm -r gs://${BUCKET_NAME}
  4. Dediziertes Dienstkonto löschen:
    gcloud iam service-accounts delete ${SERVICE_ACCOUNT} --quiet

13. Fazit

Glückwunsch! Sie haben erfolgreich eine sichere, vollständig persistente Instanz von OpenClaw in Cloud Run-Instanzen bereitgestellt, die von Cloud Storage, Secret Manager und Ihrem bevorzugten Messaging-Kanal unterstützt werden.