Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

如何在 Cloud Run 实例上部署 OpenClaw

1. 简介

概览

在本实验中，您将把 OpenClaw（一个开源 AI 智能体框架）的完全持久化安全实例部署到 Cloud Run 实例。您将使用 OpenClaw 的内置 Web 界面（可以选择连接 Telegram 或 WhatsApp 等即时通讯渠道）直接与 AI 智能体互动，使用 Google Cloud Storage 将其备份到主工作区，并使用 Google Cloud Secret Manager 安全地管理 API 凭据。

在开始之前，您可以浏览 OpenClaw 文档，熟悉 OpenClaw 的架构、工具和智能体工作流。

您将执行的操作

启用所需的 Google Cloud API，并创建一个具有所需 IAM 权限的专用服务账号。
在 Secret Manager 中安全地存储 API 密钥和网关密码。
准备一个 openclaw.json 配置文件，其中包含 Gemini 模型设置并启用了网关界面。
准备一个 Cloud Storage 存储桶来持久保留容器状态。
使用 gcloud beta run instances deploy 部署 OpenClaw。
使用 OpenClaw AI 智能体的内置 Web 界面直接与之互动。
（可选）配置即时通讯渠道（Telegram 或 WhatsApp）。
（可选）通过向 Cloud Storage 添加自定义技能来扩展代理的功能。

学习内容

如何将 OpenClaw 部署到 Cloud Run 实例，并使用其内置的控制 Web 界面。
如何将 Cloud Storage 存储桶装载到 Cloud Run 实例。
如何将 Secret Manager 密文安全地注入到 Cloud Run 中作为环境变量。
如何在 Cloud Run 实例上运行需要长时间运行的持久性代理工作负载。
如何配置自定义智能体 skill 并将其上传到 Cloud Storage。

2. 设置和要求

GCP 项目设置

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

打开 Cloud Shell

从 Cloud 控制台的顶部工具栏中激活 Google Cloud Shell。

设置项目并安装 gcloud beta

首先，将项目和区域设置为环境变量。

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

现在，设置您的项目并进行确认。

gcloud config set project $PROJECT_ID
gcloud config get project

确保已为 gcloud beta run instances 安装 beta 组件：

gcloud components install beta --quiet

并确保您的 gcloud 是最新版本。

gcloud components update

启用必需的 Google Cloud API

在 Cloud Shell 中，启用 Cloud Run、Secret Manager、Cloud Storage 和 Gemini API：

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

3. （可选）设置即时通讯集成（Telegram 或 WhatsApp）

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

选项 A：Telegram 聊天机器人设置

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

选项 B：WhatsApp 设置

获取您的个人 WhatsApp 电话号码，该号码应采用国际电话号码格式，不含空格或符号（例如 +15551234567）。
OpenClaw 通过 WhatsApp 频道许可名单政策进行连接。

4. 创建专用服务账号

为了遵循最小权限原则，请为 OpenClaw 创建专用 IAM 服务账号：

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. 在 Secret Manager 中存储凭据

我们将敏感的 API 凭据存储在 Google Cloud Secret Manager 中，以便 Cloud Run 在启动时安全地将其注入容器。

1. 获取和存储 Gemini API 密钥

前往 Google AI Studio，然后使用 Google 账号登录。
点击创建 API 密钥，然后选择您的 Google Cloud 项目 (${PROJECT_ID})。
复制生成的 API 密钥。

将 API 密钥存储在 Secret Manager 中，并向服务账号授予访问权限：

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. 生成并存储网关密码

为了保护可公开访问的 OpenClaw 实例，请生成一个安全的随机密码并将其存储在 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. （可选）创建渠道密钥（Telegram 或 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"

对于 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 存储桶和 openclaw.json 配置

OpenClaw 需要在 /home/node/.openclaw/openclaw.json 中提供名为 openclaw.json 的配置文件。

创建 Cloud Storage 存储桶并授予访问权限：

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"

创建 openclaw.json：在 Cloud Shell 中创建一个名为 openclaw.json 的文件。更新 channels 部分，使其与您选择的渠道（Telegram 或 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 }
    }
  }
}

将 openclaw.json 上传到 Cloud Storage 存储桶根目录：
```
gcloud storage cp openclaw.json gs://${BUCKET_NAME}/openclaw.json
```
验证 Cloud Storage 存储桶布局：确认您的存储桶结构在根目录下包含 openclaw.json：
```
gs://${BUCKET_NAME}/
└── openclaw.json
```

7. 在 Cloud Run 实例上部署 OpenClaw

使用 gcloud beta run instances deploy 部署 OpenClaw：

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}

主要参数细分：

--image ghcr.io/openclaw/openclaw:2026.7.1：OpenClaw 容器映像（固定为 2026.7.1，即最新的稳定版 1.x）。
--service-account ...：附加专用 openclaw-sa 服务账号。
--add-volume ...：将 Cloud Storage 存储桶直接挂载到 /home/node/.openclaw。使用 file-mode=0700;dir-mode=0700 可确保 OpenClaw 具有适当的权限。
--set-secrets ...：直接将凭据从 Secret Manager 注入到环境变量中。（可选：如果您在可选步骤中配置了 Telegram，请将 ,TELEGRAM_BOT_TOKEN=telegram-bot-token:latest 附加到 --set-secrets。）
--public：允许公开访问网址。

8. 通过 OpenClaw 网页界面直接互动

OpenClaw 包含一个内置的控制 Web 界面，可让您直接在浏览器中管理 AI 智能体并与之对话：

检索 Cloud Run 实例网址：在 Cloud Shell 中，运行以下命令：

gcloud beta run instances describe openclaw-instance \
  --region ${REGION} \
  --format="value(status.urls[0])"

访问 OpenClaw 控制界面：
- 在网络浏览器中打开输出网址。
- 当 OpenClaw Control 界面提示进行身份验证时：
  - 输入从 Secret Manager 生成的网关密码 (${OPENCLAW_GATEWAY_PASSWORD})。
  - 如果登录模态框显示单独的用户名和密码字段，请将用户名字段留空（或输入 admin），并在密码字段中提供 ${OPENCLAW_GATEWAY_PASSWORD}。
提示您的代理（实例在行动）：
- 通过身份验证后，您会看到 OpenClaw 控制信息中心。
- 在聊天界面中发送提示（例如“你好”），测试 OpenClaw 代理。
- 如需测试 Cloud Run 实例的长期生命周期，您可以提示 OpenClaw 代理执行更复杂的长期任务。例如，您可以让它跟踪新闻信息流或股市，并生成报告：
```
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.
```
- 然后，代理应在接下来的 24 小时内执行此任务。

9. （可选）验证消息传递渠道集成

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

在 Cloud Shell 中查看实例日志：

gcloud run instances logs read openclaw-instance --region ${REGION} --limit 20

打开 Telegram（或 WhatsApp），然后发送消息（例如 /start 或 Hello OpenClaw!）。
机器人将根据 openclaw.json 中的许可名单验证您的用户 ID，并使用 Gemini 进行回答！

10. 监控和检查实例日志

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"

11. （可选）使用技能扩展智能体

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 存储桶直接挂载到 /home/node/.openclaw，因此放置在 gs://${BUCKET_NAME}/skills/ 下的技能会在启动时自动加载，并在实例重启后保持不变：

创建本地技能目录：

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 控制网页界面。
- 现在，您可以使用 /summarize-logs 提示智能体，也可以使用与技能描述相符的自然语言提问！

12. 清理

为避免因本 Codelab 中使用的资源导致您的 Google Cloud 账号产生费用，请执行以下操作：

删除 Cloud Run 实例：

gcloud beta run instances delete openclaw-instance --region ${REGION} --quiet

删除 Secret Manager Secret：

gcloud secrets delete gemini-api-key --quiet
gcloud secrets delete telegram-bot-token --quiet
gcloud secrets delete openclaw-gateway-password --quiet

删除 Cloud Storage 存储桶：

gcloud storage rm -r gs://${BUCKET_NAME}

删除专用服务账号：

gcloud iam service-accounts delete ${SERVICE_ACCOUNT} --quiet

13. 总结

恭喜！您已成功在 Cloud Run 实例上部署了 OpenClaw 的安全、完全持久化实例，该实例由 Cloud Storage、Secret Manager 和您首选的消息传递渠道提供支持！