如何使用 Terraform 在 Cloud Run 实例上部署 OpenClaw

1. 简介

概览

在本实验中,您将使用声明式基础设施即代码 (Terraform) 将一个完全持久的生产级 OpenClaw(一种开源 AI 智能体框架)实例部署到 Cloud Run 实例。您将使用 google 提供方的 google_cloud_run_v2_instance 资源预配 Cloud Run 实例,通过 Cloud Storage FUSE 装载 Google Cloud Storage 以持久保存智能体工作区状态,使用 Google Cloud Secret Manager 安全地管理 API 凭证,并通过 OpenClaw 的内置 Web 界面使用 Cloud Run 实例原生 SSH 与 AI 智能体进行交互,以实现安全的设备配对。

在开始之前,您可以浏览 OpenClaw 文档,熟悉 OpenClaw 的架构、工具和 Agentic Workflows。

您将执行的操作

  • 在 Terraform (main.tf) 中以声明方式定义整个基础设施,包括 API、服务账号、IAM 绑定、Secret、存储桶和 Cloud Run 实例。
  • 使用 google_cloud_run_v2_instance 部署 OpenClaw 2.0+ (ghcr.io/openclaw/openclaw:latest)。
  • 在 Secret Manager 中自动生成并存储安全网关凭证。
  • 通过 Cloud Storage FUSE 装载 Cloud Storage 存储桶,并同步 /home/node/.openclaw,以实现持久状态、工作区和 SQLite 持久性。
  • 使用 gcloud beta run instances ssh 进行身份验证并批准浏览器设备配对请求,以便进入 OpenClaw Control Web 界面。
  • (可选)配置即时通讯渠道(Telegram 或 WhatsApp)。
  • (可选)通过向 Cloud Storage 添加自定义技能,扩展智能体的功能。

学习内容

  • 如何使用 Terraform 声明和部署 Cloud Run 实例。
  • 如何在 Terraform 中配置 Cloud Storage FUSE 卷装载。
  • 如何将 Secret Manager 密钥作为环境变量安全地注入 Cloud Run 实例。
  • 如何使用 Cloud Run 实例原生 SSH 管理 OpenClaw 2.0 设备身份验证。
  • 如何在 Cloud Run 实例上运行长时间运行的持久性智能体工作负载。

2. 设置和要求

GCP 项目设置

  1. 登录 Google Cloud 控制台。
  2. 创建或选择 Google Cloud 项目。
  3. 确保您的 Google Cloud 项目已启用结算功能。

打开 Cloud Shell

从 Cloud 控制台的顶部工具栏中激活 Google Cloud Shell。Cloud Shell 预安装了 Terraform 和 Google Cloud SDK。

设置项目和区域

将项目 ID 和区域设置为环境变量,并配置 gcloud:

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

gcloud config set project $PROJECT_ID
gcloud config get project

安装 gcloud Beta 版组件

确保已安装 beta 组件(Cloud Run 实例 SSH 和日志流式传输需要此组件):

gcloud components install beta --quiet
gcloud components update

验证 Terraform

确认 Terraform 已安装且符合版本要求:

terraform version

您应该会看到 Terraform v1.5.0 或更高版本。

3. (可选)设置消息传递集成(Telegram 或 WhatsApp)

您可以将 OpenClaw 连接到 Telegram 或 WhatsApp。请从下方的选项 A 或选项 B 中选择。

方案 A:Telegram 聊天机器人设置

  1. 打开 Telegram 并搜索 @BotFather。
  2. 发送 /newbot 命令,然后按照提示指定机器人名称和用户名。
  3. 复制生成的 HTTP API 令牌(例如 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ)。
  4. 在 Telegram 上搜索 @userinfobot,发送 /start,然后复制您的数字用户 ID(例如 8035936176)。

您将在 terraform.tfvars 文件中以 Terraform 输入变量的形式提供这些值。

选项 B:WhatsApp 设置

  1. 获取您的个人 WhatsApp 电话号码,采用国际电话号码格式,不含空格或符号(例如 +15551234567)。
  2. OpenClaw 通过 WhatsApp 渠道许可清单政策进行连接。

4. 在 Terraform 中定义基础设施

我们将在 Terraform 中声明整个基础设施。这包括启用所需的 Google Cloud API、创建专用服务账号和 IAM 角色、在 Secret Manager 中生成和存储 Secret、预配 Cloud Storage 状态存储桶、生成 openclaw.json 配置以及部署 Cloud Run 实例。

1. 创建 Terraform 目录

在 Cloud Shell 中,为 Terraform 文件创建一个目录并进入该目录:

mkdir openclaw-terraform && cd openclaw-terraform

2. 创建“main.tf”

创建一个名为 main.tf 的文件。此配置使用 Google 提供程序来定义所有基础架构组件:

terraform {
  required_version = ">= 1.5.0"
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 8.8.0"
    }
    random = {
      source  = "hashicorp/random"
      version = ">= 3.5.0"
    }
  }
}

provider "google" {
  project = var.project_id
  region  = var.region
}

# 1. Enable Required APIs
resource "google_project_service" "services" {
  for_each = toset([
    "run.googleapis.com",
    "secretmanager.googleapis.com",
    "storage.googleapis.com",
    "generativelanguage.googleapis.com",
    "compute.googleapis.com"
  ])
  project            = var.project_id
  service            = each.key
  disable_on_destroy = false
}

# 2. Dedicated Service Account
resource "google_service_account" "openclaw_sa" {
  account_id   = "openclaw-sa"
  display_name = "OpenClaw Service Account"
  depends_on   = [google_project_service.services]
}

# 3. Secret Manager: Gateway Password
resource "random_password" "gateway_password" {
  length  = 32
  special = false
}

resource "google_secret_manager_secret" "gateway_password" {
  secret_id = "openclaw-gateway-password"
  replication {
    auto {}
  }
  depends_on = [google_project_service.services]
}

resource "google_secret_manager_secret_version" "gateway_password" {
  secret      = google_secret_manager_secret.gateway_password.id
  secret_data = random_password.gateway_password.result
}

resource "google_secret_manager_secret_iam_member" "sa_gateway_password" {
  secret_id = google_secret_manager_secret.gateway_password.id
  role      = "roles/secretmanager.secretAccessor"
  member    = "serviceAccount:${google_service_account.openclaw_sa.email}"
}

# 4. Secret Manager: Gemini API Key
resource "google_secret_manager_secret" "gemini_api_key" {
  secret_id = "gemini-api-key"
  replication {
    auto {}
  }
  depends_on = [google_project_service.services]
}

resource "google_secret_manager_secret_version" "gemini_api_key" {
  secret      = google_secret_manager_secret.gemini_api_key.id
  secret_data = var.gemini_api_key
}

resource "google_secret_manager_secret_iam_member" "sa_gemini_api_key" {
  secret_id = google_secret_manager_secret.gemini_api_key.id
  role      = "roles/secretmanager.secretAccessor"
  member    = "serviceAccount:${google_service_account.openclaw_sa.email}"
}

# 5. Optional Secret Manager: Telegram Bot Token
resource "google_secret_manager_secret" "telegram_bot_token" {
  count     = var.telegram_bot_token != "" ? 1 : 0
  secret_id = "telegram-bot-token"
  replication {
    auto {}
  }
  depends_on = [google_project_service.services]
}

resource "google_secret_manager_secret_version" "telegram_bot_token" {
  count       = var.telegram_bot_token != "" ? 1 : 0
  secret      = google_secret_manager_secret.telegram_bot_token[0].id
  secret_data = var.telegram_bot_token
}

resource "google_secret_manager_secret_iam_member" "sa_telegram_bot_token" {
  count     = var.telegram_bot_token != "" ? 1 : 0
  secret_id = google_secret_manager_secret.telegram_bot_token[0].id
  role      = "roles/secretmanager.secretAccessor"
  member    = "serviceAccount:${google_service_account.openclaw_sa.email}"
}

# 6. Cloud Storage Bucket for State Persistence
resource "google_storage_bucket" "openclaw_state" {
  name                        = "openclaw-state-${var.project_id}"
  location                    = var.region
  uniform_bucket_level_access = true
  force_destroy               = true
  depends_on                  = [google_project_service.services]
}

resource "google_storage_bucket_iam_member" "sa_storage" {
  bucket = google_storage_bucket.openclaw_state.name
  role   = "roles/storage.objectUser"
  member = "serviceAccount:${google_service_account.openclaw_sa.email}"
}

# 7. Upload openclaw.json to Cloud Storage Root
resource "google_storage_bucket_object" "openclaw_config" {
  name   = "openclaw.json"
  bucket = google_storage_bucket.openclaw_state.name
  content = jsonencode({
    gateway = {
      mode           = "local"
      port           = 18789
      trustedProxies = ["127.0.0.1", "::1", "169.254.0.0/16", "10.0.0.0/8"]
      bind           = "lan"
      auth = {
        password = "$${OPENCLAW_GATEWAY_PASSWORD}"
      }
      controlUi = {
        allowedOrigins = ["*"]
        enabled        = true
      }
    }
    memory = {
      search = {
        provider = "gemini"
      }
    }
    agents = {
      defaults = {
        model = {
          primary = "google/gemini-3.1-pro-preview"
        }
        sandbox = {
          mode = "off"
        }
      }
    }
    skills = {
      load = {
        extraDirs = ["/mnt/openclaw/skills"]
      }
    }
    channels = {
      telegram = {
        enabled        = var.telegram_bot_token != ""
        defaultAccount = "default"
        accounts = {
          default = {
            enabled   = var.telegram_bot_token != ""
            dmPolicy  = "allowlist"
            allowFrom = var.telegram_user_id != "" ? [var.telegram_user_id] : []
          }
        }
      }
    }
    plugins = {
      entries = {
        google   = { enabled = true }
        telegram = { enabled = var.telegram_bot_token != "" }
      }
    }
  })
}

# 8. Cloud Run Instance
resource "google_cloud_run_v2_instance" "openclaw" {
  name     = "openclaw-instance"
  location = var.region

  ingress              = "INGRESS_TRAFFIC_ALL"
  invoker_iam_disabled = true
  restart_policy       = "ON_FAILURE"
  service_account      = google_service_account.openclaw_sa.email

  containers {
    image = "ghcr.io/openclaw/openclaw:latest"
    args = [
      "/bin/sh",
      "-c",
      "cp /mnt/openclaw/openclaw.json /home/node/.openclaw/ && exec node /app/openclaw.mjs gateway"
    ]

    ports {
      container_port = 18789
    }

    resources {
      limits = {
        cpu    = "4"
        memory = "4Gi"
      }
    }

    env {
      name = "GEMINI_API_KEY"
      value_source {
        secret_key_ref {
          secret  = google_secret_manager_secret.gemini_api_key.secret_id
          version = "latest"
        }
      }
    }

    env {
      name = "OPENCLAW_GATEWAY_PASSWORD"
      value_source {
        secret_key_ref {
          secret  = google_secret_manager_secret.gateway_password.secret_id
          version = "latest"
        }
      }
    }

    dynamic "env" {
      for_each = toset(var.telegram_bot_token != "" ? ["telegram"] : [])
      content {
        name = "TELEGRAM_BOT_TOKEN"
        value_source {
          secret_key_ref {
            secret  = google_secret_manager_secret.telegram_bot_token[0].secret_id
            version = "latest"
          }
        }
      }
    }

    volume_mounts {
      name       = "openclaw-storage"
      mount_path = "/mnt/openclaw"
    }
  }

  volumes {
    name = "openclaw-storage"
    gcs {
      bucket        = google_storage_bucket.openclaw_state.name
      read_only     = false
      mount_options = ["uid=1000", "gid=1000", "file-mode=0700", "dir-mode=0700"]
    }
  }

  depends_on = [
    google_project_service.services,
    google_storage_bucket_object.openclaw_config,
    google_secret_manager_secret_version.gateway_password,
    google_secret_manager_secret_version.gemini_api_key,
    google_secret_manager_secret_iam_member.sa_gateway_password,
    google_secret_manager_secret_iam_member.sa_gemini_api_key,
    google_storage_bucket_iam_member.sa_storage
  ]
}

3. 创建“variables.tf”

创建一个名为 variables.tf 的文件,用于定义输入变量:

variable "project_id" {
  type        = string
  description = "Google Cloud Project ID"
}

variable "region" {
  type        = string
  default     = "us-west1"
  description = "Google Cloud Region for Cloud Run and Storage"
}

variable "gemini_api_key" {
  type        = string
  sensitive   = true
  description = "Gemini API Key from Google AI Studio"
}

variable "telegram_bot_token" {
  type        = string
  default     = ""
  sensitive   = true
  description = "(Optional) Telegram Bot HTTP API Token"
}

variable "telegram_user_id" {
  type        = string
  default     = ""
  description = "(Optional) Telegram User ID for allowlist policy"
}

4. 创建“outputs.tf”

创建一个名为 outputs.tf 的文件,以公开已部署的实例网址、生成的网关密码和存储桶名称:

output "instance_url" {
  description = "Public URL for OpenClaw Cloud Run Instance"
  value       = google_cloud_run_v2_instance.openclaw.urls[0]
}

output "gateway_password" {
  description = "Generated OpenClaw Gateway Password"
  value       = random_password.gateway_password.result
  sensitive   = true
}

output "storage_bucket" {
  description = "Cloud Storage bucket persisting OpenClaw state"
  value       = google_storage_bucket.openclaw_state.name
}

5. 创建“terraform.tfvars”

如需获取 Gemini API 密钥,请执行以下操作:

  1. 访问 Google AI Studio,然后使用 Google 账号登录。
  2. 点击创建 API 密钥,然后选择您的 Google Cloud 项目。
  3. 复制生成的 API 密钥。

创建一个名为 terraform.tfvars 的文件,其中包含您的项目坐标:

project_id     = "YOUR_PROJECT_ID"
region         = "YOUR_REGION"
gemini_api_key = "YOUR_GEMINI_API_KEY"

# Optional: Uncomment if configuring Telegram
# telegram_bot_token = "YOUR_TELEGRAM_BOT_TOKEN"
# telegram_user_id   = "YOUR_TELEGRAM_USER_ID"

5. 使用 Terraform 部署基础设施

1. 初始化并应用

初始化 Terraform 工作目录并下载提供程序插件:

terraform init

部署基础架构:

terraform apply

出现提示时,查看计划的资源,然后输入 yes 进行确认。

2. 提取部署输出

从 Terraform 状态中导出实例网址和生成的网关密码:

export INSTANCE_URL=$(terraform output -raw instance_url)
export GATEWAY_PASSWORD=$(terraform output -raw gateway_password)

echo "Instance URL: ${INSTANCE_URL}"
echo "Gateway Password: ${GATEWAY_PASSWORD}"

6. 通过 Web 界面进行交互并通过 Cloud Run SSH 进行身份验证

OpenClaw 2.0+ 强制执行加密设备身份验证。从新浏览器连接时,网关会生成配对请求,您可以通过 Cloud Run 实例原生 SSH 直接批准该请求。

1. 打开 OpenClaw 控制界面

  1. 在网络浏览器中打开 $INSTANCE_URL。
  2. 当系统提示进行身份验证时,请输入网关密码 ($GATEWAY_PASSWORD)。
  3. 由于这是一个新的浏览器会话,OpenClaw Control 界面会显示一个待处理的设备配对提示,其中包含一个请求 ID(例如:b56143fc-1654-49da-a1d8-5d40479ddc66)。复制此请求 ID。

2. 通过 SSH 连接到 Cloud Run 实例

在 Cloud Shell 中,启动一个连接到正在运行的实例的安全交互式 shell:

gcloud beta run instances ssh openclaw-instance --region=${REGION}

3. 批准设备配对

在 SSH 会话中,批准浏览器请求:

openclaw devices approve <REQUEST_ID> --password ${GATEWAY_PASSWORD}

4. 向智能体发出提示(实例实际应用)

获得批准后,您的浏览器会立即连接到 OpenClaw 控制信息中心!

  1. 在聊天界面中发送提示(例如 "Hello"),测试 OpenClaw 智能体。
  2. 如需测试 Cloud Run 实例的长生命周期和永久性存储,请提示 OpenClaw 智能体执行预定的自主任务。例如,让它监控 GitHub 代码库中的版本并起草摘要:
    Check the GitHub repository openclaw/openclaw every hour for the next 24 hours. Track any new releases, merged pull requests, and breaking changes. Save a structured markdown digest titled `daily-release-digest.md` to your workspace, and notify me in this chat with a summary whenever a new release is detected.
    
  3. 由于 OpenClaw 状态、工作区文件和 SQLite 数据库通过 Cloud Storage FUSE 直接持久化到 Cloud Storage,因此计划任务、对话历史记录和生成的摘要文件在实例重启和容器升级后仍会保留。

7. (可选)验证消息传递渠道集成

如果您在上述可选设置步骤中配置了 Telegram 或 WhatsApp,则可以验证消息传递情况:

  1. 在 Cloud Shell 中查看实例日志:
    gcloud beta run instances logs read openclaw-instance --region ${REGION} --limit 20
    
  2. 打开 Telegram(或 WhatsApp)并发送消息(例如 /start 或 Hello OpenClaw!)。
  3. 该聊天机器人会根据 openclaw.json 中的许可清单对您的用户 ID 进行身份验证,并使用 Gemini 进行回复!

8. 监控和检查实例日志

Cloud Run 实例会捕获容器中的 stdout 和 stderr,并将其直接流式传输到 Google Cloud Logging。您可以使用 Cloud Shell 或 Cloud 控制台实时监控网关流量并检查智能体工具运行情况。

1. 读取最近的实例日志

如需在 Cloud Shell 中从实例提取近期日志条目,请运行以下命令:

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

2. 需要观察的关键日志签名

观察正在运行的代理时,请留意以下关键运行时日志事件:

  • [gateway] ready:确认 OpenClaw HTTP 和 WebSocket 网关已初始化,并正在监听端口 18789。
  • [gateway] agent model: ...:显示当前使用的 Gemini 模型(例如 google/gemini-3.1-pro-preview 或 google/gemini-3.5-flash)。
  • [agents/tool-policy]:显示政策允许或限制的工具。
  • [agent/embedded]:跟踪智能体的执行和工具调用。

3. 在 Google Cloud 控制台中检查日志

您还可以使用 Cloud 控制台中的 Logs Explorer 查看和过滤日志:

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

9. (可选)使用技能扩展智能体

OpenClaw 支持技能,即模块化功能包,可让智能体掌握特定工作流、专用 CLI 工具和特定领域的指令。

技能的工作原理

每项技能都是一个包含 SKILL.md 文件的目录。它以指定元数据(name 和 description)的 YAML 前置元数据开头,后跟 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:技能标识符(也可直接作为斜杠命令调用,例如 /summarize-logs)。
  • description:告知 OpenClaw 的模型何时在自然对话中自动调用此技能。

向 Cloud Storage 存储桶添加自定义技能

由于您的 Cloud Storage 存储桶已装载到 /mnt/openclaw 并在 skills.load.extraDirs 中配置,因此放置在 gs://${BUCKET_NAME}/skills/ 下的技能会自动加载,并在实例重启后保持不变:

  1. 检索存储桶名称:
    export BUCKET_NAME=$(terraform output -raw storage_bucket)
    
  2. 创建本地技能目录:
    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
    
  3. 将技能上传到 Cloud Storage:
    gcloud storage cp -r my-skill gs://${BUCKET_NAME}/skills/
    
  4. 在 Chat 中使用技能:
    • 返回 OpenClaw 控制 Web 界面。
    • 现在,您可以使用 /summarize-logs 向智能体发出提示,或提出与技能说明相符的自然语言问题!

10. 清理

为避免系统因本 Codelab 中使用的资源向您的 Google Cloud 账号持续收取费用,您可以使用 Terraform 一步销毁所有预配的基础设施:

  1. 确保您位于 openclaw-terraform 目录中:
    cd openclaw-terraform
    
  2. 销毁所有资源:
    terraform destroy
    
  3. 出现提示时,查看要移除的资源,然后输入 yes 进行确认。Terraform 将彻底删除 Cloud Run 实例、Secret Manager 密钥、IAM 政策绑定、服务账号和 Cloud Storage 存储桶。

11. 总结

恭喜!您已成功使用声明式 Terraform 在 Cloud Run 实例上部署了一个安全的、完全持久化的 OpenClaw 实例,该实例由 Cloud Storage 状态持久化、Secret Manager 凭据安全性和 Cloud Run 实例原生 SSH 提供支持,可实现安全的设备身份验证!