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 项目设置
- 登录 Google Cloud 控制台。
- 创建或选择 Google Cloud 项目。
- 确保您的 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 聊天机器人设置
- 打开 Telegram 并搜索
@BotFather。 - 发送
/newbot命令,然后按照提示指定机器人名称和用户名。 - 复制生成的 HTTP API 令牌(例如
123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ)。 - 在 Telegram 上搜索
@userinfobot,发送/start,然后复制您的数字用户 ID(例如8035936176)。
您将在 terraform.tfvars 文件中以 Terraform 输入变量的形式提供这些值。
选项 B:WhatsApp 设置
- 获取您的个人 WhatsApp 电话号码,采用国际电话号码格式,不含空格或符号(例如
+15551234567)。 - 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 密钥,请执行以下操作:
- 访问 Google AI Studio,然后使用 Google 账号登录。
- 点击创建 API 密钥,然后选择您的 Google Cloud 项目。
- 复制生成的 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 控制界面
- 在网络浏览器中打开
$INSTANCE_URL。 - 当系统提示进行身份验证时,请输入网关密码 (
$GATEWAY_PASSWORD)。 - 由于这是一个新的浏览器会话,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 控制信息中心!
- 在聊天界面中发送提示(例如
"Hello"),测试 OpenClaw 智能体。 - 如需测试 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. - 由于 OpenClaw 状态、工作区文件和 SQLite 数据库通过 Cloud Storage FUSE 直接持久化到 Cloud Storage,因此计划任务、对话历史记录和生成的摘要文件在实例重启和容器升级后仍会保留。
7. (可选)验证消息传递渠道集成
如果您在上述可选设置步骤中配置了 Telegram 或 WhatsApp,则可以验证消息传递情况:
- 在 Cloud Shell 中查看实例日志:
gcloud beta run instances logs read openclaw-instance --region ${REGION} --limit 20 - 打开 Telegram(或 WhatsApp)并发送消息(例如
/start或Hello OpenClaw!)。 - 该聊天机器人会根据
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/ 下的技能会自动加载,并在实例重启后保持不变:
- 检索存储桶名称:
export BUCKET_NAME=$(terraform output -raw storage_bucket) - 创建本地技能目录:
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 - 将技能上传到 Cloud Storage:
gcloud storage cp -r my-skill gs://${BUCKET_NAME}/skills/ - 在 Chat 中使用技能:
- 返回 OpenClaw 控制 Web 界面。
- 现在,您可以使用
/summarize-logs向智能体发出提示,或提出与技能说明相符的自然语言问题!
10. 清理
为避免系统因本 Codelab 中使用的资源向您的 Google Cloud 账号持续收取费用,您可以使用 Terraform 一步销毁所有预配的基础设施:
- 确保您位于
openclaw-terraform目录中:cd openclaw-terraform - 销毁所有资源:
terraform destroy - 出现提示时,查看要移除的资源,然后输入
yes进行确认。Terraform 将彻底删除 Cloud Run 实例、Secret Manager 密钥、IAM 政策绑定、服务账号和 Cloud Storage 存储桶。
11. 总结
恭喜!您已成功使用声明式 Terraform 在 Cloud Run 实例上部署了一个安全的、完全持久化的 OpenClaw 实例,该实例由 Cloud Storage 状态持久化、Secret Manager 凭据安全性和 Cloud Run 实例原生 SSH 提供支持,可实现安全的设备身份验证!