Jak wdrożyć OpenClaw na instancjach Cloud Run

1. Wprowadzenie

Przegląd

W tym module wdrożysz w instancjach Cloud Run w pełni trwałą i bezpieczną instancję OpenClaw – platformy agentów AI typu open source. Będziesz wchodzić w interakcję z agentem AI bezpośrednio za pomocą wbudowanego interfejsu internetowego OpenClaw (z możliwością połączenia kanałów komunikacyjnych, takich jak Telegram czy WhatsApp), tworzyć kopie zapasowe w Google Cloud Storage i bezpiecznie zarządzać danymi logowania interfejsu API za pomocą Google Cloud Secret Manager.

Zanim zaczniesz, zapoznaj się z dokumentacją OpenClaw, aby poznać architekturę, narzędzia i procesy agenta OpenClaw.

Jakie zadania wykonasz

  • Włącz wymagane interfejsy Google Cloud API i utwórz dedykowane konto usługi z wymaganymi uprawnieniami IAM.
  • Bezpiecznie przechowuj klucze interfejsu API i hasła do bramy w usłudze Secret Manager.
  • Przygotuj openclaw.json plik konfiguracyjny z ustawieniami modelu Gemini i włączonym interfejsem bramy.
  • Przygotuj zasobnik Cloud Storage do przechowywania stanu kontenera.
  • Wdróż OpenClaw za pomocą gcloud beta run instances deploy.
  • Bezpośrednio wchodź w interakcje z agentem AI OpenClaw za pomocą wbudowanego interfejsu internetowego.
  • (Opcjonalnie) skonfiguruj kanał do przesyłania wiadomości (Telegram lub WhatsApp).
  • (Opcjonalnie) Rozszerz możliwości agenta, dodając niestandardowe umiejętności do Cloud Storage.

Czego się nauczysz

  • Jak wdrożyć OpenClaw na instancjach Cloud Run za pomocą wbudowanego interfejsu internetowego Control.
  • Jak montować zasobniki Cloud Storage w instancjach Cloud Run.
  • Jak bezpiecznie wstrzykiwać obiekty tajne z Secret Manager jako zmienne środowiskowe do Cloud Run.
  • Jak uruchamiać długotrwałe, trwałe zbiory zadań agenta w instancjach Cloud Run.
  • Dowiedz się, jak skonfigurować i przesłać niestandardowe umiejętności agenta do Cloud Storage.

2. Konfiguracja i wymagania

Konfiguracja projektu GCP

  1. Zaloguj się w konsoli Google Cloud.
  2. Utwórz lub wybierz projekt Google Cloud.
  3. Sprawdź, czy w projekcie Google Cloud włączone są płatności.

Otwórz Cloud Shell

Aktywuj Google Cloud Shell na pasku narzędzi u góry konsoli Cloud.

Ustawianie projektu i instalowanie wersji beta gcloud

Najpierw ustaw projekt i region jako zmienne środowiskowe.

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

Teraz skonfiguruj projekt i potwierdź.

gcloud config set project $PROJECT_ID
gcloud config get project

Sprawdź, czy komponent beta jest zainstalowany w przypadku gcloud beta run instances:

gcloud components install beta --quiet

Sprawdź też, czy gcloud jest aktualny.

gcloud components update

Włączanie wymaganych interfejsów Google Cloud API

W Cloud Shell włącz interfejsy Cloud Run, Secret Manager, Cloud Storage i Gemini API:

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

3. (Opcjonalnie) Konfigurowanie integracji z komunikatorami (Telegram lub WhatsApp)

Możesz połączyć OpenClaw z Telegramem lub WhatsAppem. Wybierz Opcję A lub Opcję B poniżej.

Opcja A. Konfiguracja bota Telegrama

  1. Otwórz Telegram i wyszukaj @BotFather.
  2. Wyślij polecenie /newbot i postępuj zgodnie z instrukcjami, aby podać nazwę i nazwę użytkownika bota.
  3. Skopiuj wygenerowany token interfejsu HTTP API (np. 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).
  4. Wyszukaj @userinfobot w Telegramie, wyślij /start i skopiuj swój numeryczny identyfikator użytkownika (np. 8035936176).

Opcja B: konfiguracja WhatsAppa

  1. Uzyskaj swój osobisty numer telefonu WhatsApp w formacie międzynarodowym bez spacji i symboli (np. +15551234567).
  2. OpenClaw łączy się za pomocą zasad listy dozwolonych kanałów WhatsApp.

4. Utwórz dedykowane konto usługi

Aby zachować zasadę jak najmniejszych uprawnień, utwórz dedykowane konto usługi IAM dla 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. Przechowywanie danych logowania w usłudze Secret Manager

Poufne dane logowania do interfejsu API będziemy przechowywać w usłudze Google Cloud Secret Manager, aby Cloud Run mogła bezpiecznie wstrzykiwać je do kontenera podczas uruchamiania.

1. Uzyskiwanie i przechowywanie klucza interfejsu Gemini API

  1. Otwórz Google AI Studio i zaloguj się na swoje konto Google.
  2. Kliknij Utwórz klucz interfejsu API i wybierz projekt w chmurze Google (${PROJECT_ID}).
  3. Skopiuj wygenerowany klucz interfejsu API.

Zapisz klucz interfejsu API w usłudze Secret Manager i przyznaj dostęp do konta usługi:

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. Generowanie i przechowywanie hasła bramy

Aby chronić publicznie dostępną instancję OpenClaw, wygeneruj bezpieczne losowe hasło i zapisz je w Secret Managerze:

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. (Opcjonalnie) Utwórz tajny klucz kanału (Telegram lub WhatsApp)

  • 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"
  • W przypadku WhatsAppa:
    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. Przygotowywanie zasobnika Cloud Storage i konfiguracji openclaw.json

OpenClaw wymaga pliku konfiguracji o nazwie openclaw.json w lokalizacji /home/node/.openclaw/openclaw.json.

  1. Utwórz zasobnik Cloud Storage i przyznaj do niego dostęp:
    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. Utwórzopenclaw.json: utwórz w Cloud Shell plik o nazwie openclaw.json. Zaktualizuj sekcję channels, aby pasowała do wybranego kanału (Telegram lub 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. Prześlij openclaw.json do katalogu głównego zasobnika Cloud Storage:
    gcloud storage cp openclaw.json gs://${BUCKET_NAME}/openclaw.json
    Sprawdź układ zasobnika Cloud Storage: upewnij się, że struktura zasobnika zawiera openclaw.json w katalogu głównym:
    gs://${BUCKET_NAME}/
└── openclaw.json

7. Wdrażanie OpenClaw na instancjach Cloud Run

Wdróż OpenClaw za pomocą 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}

Analiza kluczowych parametrów:

  • --image ghcr.io/openclaw/openclaw:2026.7.1: obraz kontenera OpenClaw (przypięty do 2026.7.1, czyli najnowszej stabilnej wersji 1.x).
  • --service-account ...: dołącza dedykowane konto usługi openclaw-sa.
  • --add-volume ...: montuje zasobnik Cloud Storage bezpośrednio w /home/node/.openclaw. Użycie file-mode=0700;dir-mode=0700 zapewnia odpowiednie uprawnienia dla OpenClaw.
  • --set-secrets ...: wstrzykuje dane logowania bezpośrednio z usługi Secret Manager do zmiennych środowiskowych. (Opcjonalnie: jeśli w krokach opcjonalnych skonfigurowano Telegram, dodaj ,TELEGRAM_BOT_TOKEN=telegram-bot-token:latest do --set-secrets).
  • --public: umożliwia publiczny dostęp do adresu URL.

8. Bezpośrednia interakcja za pomocą interfejsu internetowego OpenClaw

OpenClaw zawiera wbudowany interfejs internetowy Control, który umożliwia zarządzanie agentem AI i czatowanie z nim bezpośrednio w przeglądarce:

  1. Pobierz adres URL instancji Cloud Run: w Cloud Shell uruchom:
    gcloud beta run instances describe openclaw-instance \
  --region ${REGION} \
  --format="value(status.urls[0])"
  2. Otwórz interfejs sterowania OpenClaw:
    • Otwórz adres URL wyjściowy w przeglądarce.
    • Gdy w interfejsie OpenClaw Control pojawi się prośba o uwierzytelnienie:
      • Wpisz wygenerowane hasło do bramy (${OPENCLAW_GATEWAY_PASSWORD}) z usługi Secret Manager.
      • Jeśli w oknie modalnym logowania wyświetlają się osobne pola Nazwa użytkownika i Hasło, pozostaw pole nazwy użytkownika puste (lub wpisz admin) i wpisz ${OPENCLAW_GATEWAY_PASSWORD} w polu hasła.
  3. Prompt Your Agent (Instances in Action):
    • Po uwierzytelnieniu zobaczysz panel sterowania OpenClaw.
    • Przetestuj agenta OpenClaw, wysyłając prompta w interfejsie czatu, np. „Cześć”.
    • Aby przetestować długi cykl życia instancji Cloud Run, możesz poprosić agenta OpenClaw o wykonanie bardziej złożonego, długotrwałego zadania. Możesz na przykład śledzić kanał wiadomości lub giełdę i generować raporty:
      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.
    • Agent powinien wykonać to zadanie w ciągu najbliższych 24 godzin.

9. (Opcjonalnie) Sprawdzanie integracji kanału Messaging

Jeśli w opcjonalnych krokach konfiguracji powyżej skonfigurowano Telegram lub WhatsApp, możesz sprawdzić dostarczanie wiadomości:

  1. Sprawdź logi instancji w Cloud Shell:
    gcloud run instances logs read openclaw-instance --region ${REGION} --limit 20
  2. Otwórz Telegram (lub WhatsApp) i wyślij wiadomość (np. /start lub Hello OpenClaw!).
  3. Bot uwierzytelni Twój identyfikator użytkownika na podstawie listy dozwolonych w openclaw.json i odpowie za pomocą Gemini.

10. Monitorowanie i sprawdzanie logów instancji

Instancje Cloud Run przechwytują dane stdout i stderr z kontenera i przesyłają je strumieniowo bezpośrednio do Google Cloud Logging. Do monitorowania ruchu bramy i sprawdzania działania narzędzi agenta w czasie rzeczywistym możesz używać Cloud Shell lub konsoli Cloud.

1. Odczytywanie ostatnich dzienników instancji

Aby pobrać najnowsze wpisy logów z instancji w Cloud Shell:

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

2. Kluczowe sygnatury logów, na które warto zwrócić uwagę

Podczas obserwowania działającego agenta zwróć uwagę na te kluczowe zdarzenia w logu czasu działania:

  • [gateway] ready: potwierdza, że brama OpenClaw HTTP i WebSocket została zainicjowana i nasłuchuje na porcie 18789.
  • [gateway] agent model: ...: wyświetla aktywny model Gemini (np. google/gemini-3.1-pro-preview lub google/gemini-3.5-flash).
  • [agents/tool-policy]: pokazuje narzędzia dozwolone lub objęte ograniczeniami zgodnie z Twoimi zasadami.
  • [agent/embedded]: śledzi wykonanie i wywołanie narzędzia przez agenta.

3. Sprawdzanie logów w konsoli Google Cloud

Możesz też wyświetlać i filtrować logi za pomocą Eksploratora logów w Cloud Console:

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

11. (Opcjonalnie) Rozszerzanie możliwości agenta za pomocą umiejętności

OpenClaw obsługuje umiejętności, czyli modułowe pakiety funkcji, które uczą agenta konkretnych przepływów pracy, specjalistycznych narzędzi CLI i instrukcji dotyczących konkretnych domen.

Jak działają umiejętności

Każda umiejętność to katalog zawierający plik SKILL.md. Zaczyna się od sekcji z metadanymi YAML określającej metadane (name i description), a następnie zawiera instrukcje 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: identyfikator umiejętności (można go też wywołać bezpośrednio jako polecenie po ukośniku, np. /summarize-logs).
  • description: informuje model OpenClaw kiedy automatycznie wywołać tę umiejętność w naturalnej rozmowie.

Dodawanie umiejętności niestandardowej do zasobnika Cloud Storage

Ponieważ zasobnik Cloud Storage jest montowany bezpośrednio w /home/node/.openclaw, umiejętności umieszczone w gs://${BUCKET_NAME}/skills/ są automatycznie wczytywane podczas uruchamiania i utrzymywane po ponownym uruchomieniu instancji:

  1. Utwórz katalog lokalnych umiejętności:
    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. Prześlij Skill do Cloud Storage:
    gcloud storage cp -r my-skill gs://${BUCKET_NAME}/skills/
  3. Korzystanie z umiejętności w Google Chat:
    • Wróć do interfejsu internetowego OpenClaw Control.
    • Możesz teraz wywoływać agenta za pomocą symbolu /summarize-logs lub zadawać pytania w języku naturalnym zgodne z opisem umiejętności.

12. Czyszczenie

Aby uniknąć obciążenia konta Google Cloud opłatami za zasoby zużyte w tym samouczku:

  1. Usuń instancję Cloud Run:
    gcloud beta run instances delete openclaw-instance --region ${REGION} --quiet
  2. Usuwanie obiektów tajnych usługi Secret Manager:
    gcloud secrets delete gemini-api-key --quiet
gcloud secrets delete telegram-bot-token --quiet
gcloud secrets delete openclaw-gateway-password --quiet
  3. Usuwanie zasobnika Cloud Storage:
    gcloud storage rm -r gs://${BUCKET_NAME}
  4. Usuwanie dedykowanego konta usługi:
    gcloud iam service-accounts delete ${SERVICE_ACCOUNT} --quiet

13. Podsumowanie

Gratulacje! Udało Ci się wdrożyć bezpieczną, w pełni trwałą instancję OpenClaw w instancjach Cloud Run obsługiwanych przez Cloud Storage, Secret Manager i wybrany kanał przesyłania wiadomości.