How to Deploy OpenClaw on Cloud Run Instances

1. Introduction

Overview

In this lab, you will deploy a fully persistent, secure instance of OpenClaw—an open-source AI agent framework—to Cloud Run Instances. You will interact with your AI agent directly using OpenClaw's built-in Web UI (with the option to connect messaging channels like Telegram or WhatsApp), back its home workspace with Google Cloud Storage, and manage API credentials securely using Google Cloud Secret Manager.

Before getting started, you can explore the OpenClaw Documentation to familiarize yourself with OpenClaw's architecture, tools, and agent workflows.

What you'll do

  • Enable required Google Cloud APIs and create a dedicated service account with required IAM permissions.
  • Store API keys and gateway passwords securely in Secret Manager.
  • Prepare an openclaw.json configuration file with Gemini model settings and gateway UI enabled.
  • Prepare a Cloud Storage bucket to persist container state.
  • Deploy OpenClaw using gcloud beta run instances deploy.
  • Interact directly with your OpenClaw AI agent using its built-in Web UI.
  • (Optional) Configure a messaging channel (Telegram or WhatsApp).
  • (Optional) Extend your agent's capabilities by adding custom Skills to Cloud Storage.

What you'll learn

  • How to deploy OpenClaw to Cloud Run Instances with its built-in Control Web UI.
  • How to mount Cloud Storage buckets to Cloud Run Instances.
  • How to securely inject Secret Manager secrets as environment variables into Cloud Run.
  • How to run long-running, persistent agent workloads on Cloud Run Instances.
  • How to configure and upload custom agent skills to Cloud Storage.

2. Setup and Requirements

GCP Project Setup

  1. Sign in to the Google Cloud Console.
  2. Create or select a Google Cloud Project.
  3. Ensure billing is enabled for your Google Cloud project.

Open Cloud Shell

Activate Google Cloud Shell from the top toolbar of the Cloud Console.

Set Project & Install gcloud beta

First, set your project and region as environment variables.

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

Now set your project and confirm.

gcloud config set project $PROJECT_ID
gcloud config get project

Ensure the beta component is installed for gcloud beta run instances:

gcloud components install beta --quiet

And make sure your gcloud is up-to-date.

gcloud components update

Enable Required Google Cloud APIs

In Cloud Shell, enable the Cloud Run, Secret Manager, Cloud Storage, and Gemini APIs:

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

3. (Optional) Set Up Messaging Integrations (Telegram or WhatsApp)

You can connect OpenClaw to Telegram or WhatsApp. Choose Option A or Option B below.

Option A: Telegram Bot Setup

  1. Open Telegram and search for @BotFather.
  2. Send the /newbot command and follow the prompts to specify a bot name and username.
  3. Copy the generated HTTP API Token (e.g., 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).
  4. Search for @userinfobot on Telegram, send /start, and copy your numeric User ID (e.g., 8035936176).

Option B: WhatsApp Setup

  1. Obtain your personal WhatsApp phone number in international format without spaces or symbols (e.g., +15551234567).
  2. OpenClaw connects via the WhatsApp channel allowlist policy.

4. Create Dedicated Service Account

To adhere to the principle of least privilege, create a dedicated IAM service account for 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. Store Credentials in Secret Manager

We will store sensitive API credentials in Google Cloud Secret Manager so Cloud Run can securely inject them into the container at boot time.

1. Obtain and Store Gemini API Key

  1. Visit Google AI Studio and sign in with your Google account.
  2. Click Create API key and select your Google Cloud project (${PROJECT_ID}).
  3. Copy the generated API key.

Store the API key in Secret Manager and grant the service account access:

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. Generate and Store Gateway Password

To protect your publicly accessible OpenClaw instance, generate a secure random password and store it in 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) Create Channel Secret (Telegram or WhatsApp)

  • For 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"
  • For 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. Prepare Cloud Storage Bucket & openclaw.json Configuration

OpenClaw requires a configuration file named openclaw.json at /home/node/.openclaw/openclaw.json.

  1. Create a Cloud Storage Bucket & Grant Access:
    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. Create openclaw.json: Create a file named openclaw.json in Cloud Shell. Update the channels section to match your chosen channel (Telegram or 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 to Cloud Storage Bucket Root:
    gcloud storage cp openclaw.json gs://${BUCKET_NAME}/openclaw.json
    Verify Cloud Storage Bucket Layout:Confirm your bucket structure contains openclaw.json at the root:
    gs://${BUCKET_NAME}/
└── openclaw.json

7. Deploy OpenClaw on Cloud Run Instances

Deploy OpenClaw using 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}

Key Parameter Breakdown:

  • --image ghcr.io/openclaw/openclaw:2026.7.1: OpenClaw container image (pinned to 2026.7.1, the latest stable 1.x release).
  • --service-account ...: Attaches the dedicated openclaw-sa service account.
  • --add-volume ...: Mounts the Cloud Storage bucket directly to /home/node/.openclaw. Using file-mode=0700;dir-mode=0700 ensures proper permissions for OpenClaw.
  • --set-secrets ...: Injects credentials directly from Secret Manager into environment variables. (Optional: If you configured Telegram in the optional steps, append ,TELEGRAM_BOT_TOKEN=telegram-bot-token:latest to --set-secrets.)
  • --public: Allows public access to the URL.

8. Interact Directly via the OpenClaw Web UI

OpenClaw includes a built-in Control Web UI that allows you to manage and chat with your AI agent directly from your browser:

  1. Retrieve your Cloud Run Instance URL: In Cloud Shell, run:
    gcloud beta run instances describe openclaw-instance \
  --region ${REGION} \
  --format="value(status.urls[0])"
  2. Access the OpenClaw Control UI:
    • Open the output URL in your web browser.
    • When prompted for authentication in the OpenClaw Control UI:
      • Enter the generated gateway password (${OPENCLAW_GATEWAY_PASSWORD}) from Secret Manager.
      • If the login modal displays separate Username and Password fields, leave the username field blank (or enter admin) and supply ${OPENCLAW_GATEWAY_PASSWORD} in the password field.
  3. Prompt Your Agent (Instances in Action):
    • Once authenticated, you will see the OpenClaw Control Dashboard.
    • Test your OpenClaw agent by sending a prompt in the chat UI, such as, "Hello".
    • To test the Cloud Run instance's long-lived lifecycle, you can prompt your OpenClaw agent to perform a more sophisticated, long-lived task. For example, you can have it track a news feed or the stock market and generate reports:
      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.
    • The agent should then perform this task over the next 24 hours.

9. (Optional) Verify Messaging Channel Integrations

If you configured Telegram or WhatsApp in the optional setup steps above, you can verify messaging delivery:

  1. Check instance logs in Cloud Shell:
    gcloud run instances logs read openclaw-instance --region ${REGION} --limit 20
  2. Open Telegram (or WhatsApp) and send a message (e.g. /start or Hello OpenClaw!).
  3. The bot will authenticate your user ID against the allowlist in openclaw.json and respond using Gemini!

10. Monitor and Inspect Instance Logs

Cloud Run Instances captures stdout and stderr from your container and streams it directly to Google Cloud Logging. You can use Cloud Shell or the Cloud Console to monitor gateway traffic and inspect agent tool runs in real time.

1. Read Recent Instance Logs

To fetch recent log entries from the instance in Cloud Shell:

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

2. Key Log Signatures to Observe

When observing your running agent, look for the following key runtime log events:

  • [gateway] ready: Confirms the OpenClaw HTTP and WebSocket gateway has initialized and is listening on port 18789.
  • [gateway] agent model: ...: Displays the active Gemini model (e.g. google/gemini-3.1-pro-preview or google/gemini-3.5-flash).
  • [agents/tool-policy]: Shows the tools permitted or restricted under your policy.
  • [agent/embedded]: Traces execution and tool invocation by the agent.

3. Inspect Logs in Google Cloud Console

You can also view and filter logs using the Logs Explorer in Cloud Console:

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

11. (Optional) Extend Your Agent with Skills

OpenClaw supports Skills—modular capability packages that teach your agent specific workflows, specialized CLI tools, and domain-specific instructions.

How Skills Work

Every skill is a directory containing a SKILL.md file. It begins with YAML frontmatter specifying metadata (name and description), followed by Markdown instructions:

---
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: The skill identifier (also callable directly as a slash command, for example /summarize-logs).
  • description: Tells OpenClaw's model when to automatically invoke this skill in natural conversation.

Add a Custom Skill to Your Cloud Storage Bucket

Because your Cloud Storage bucket is mounted directly to /home/node/.openclaw, skills placed under gs://${BUCKET_NAME}/skills/ are automatically loaded on boot and persisted across instance restarts:

  1. Create a Local Skill Directory:
    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 the Skill to Cloud Storage:
    gcloud storage cp -r my-skill gs://${BUCKET_NAME}/skills/
  3. Use the Skill in Chat:
    • Return to the OpenClaw Control Web UI.
    • You can now prompt your agent using /summarize-logs or ask natural-language questions matching the skill description!

12. Clean Up

To avoid incurring charges to your Google Cloud account for the resources used in this codelab:

  1. Delete the Cloud Run Instance:
    gcloud beta run instances delete openclaw-instance --region ${REGION} --quiet
  2. Delete 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. Delete Cloud Storage Bucket:
    gcloud storage rm -r gs://${BUCKET_NAME}
  4. Delete Dedicated Service Account:
    gcloud iam service-accounts delete ${SERVICE_ACCOUNT} --quiet

13. Conclusion

Congratulations! You have successfully deployed a secure, fully persistent instance of OpenClaw on Cloud Run Instances backed by Cloud Storage, Secret Manager, and your preferred messaging channel!