如何在 Cloud Run 執行個體上部署 OpenClaw

1. 簡介

總覽

在本實驗室中，您將在 Cloud Run 執行個體上部署 OpenClaw 的完整持續性安全執行個體。OpenClaw 是開放原始碼的 AI 代理程式架構。您可以使用 OpenClaw 的內建網頁 UI 直接與 AI 代理程式互動 (可選擇連結 Telegram 或 WhatsApp 等訊息管道)，並透過 Google Cloud Storage 備份主工作區，以及使用 Google Cloud Secret Manager 安全地管理 API 憑證。

開始之前，您可以先瀏覽 OpenClaw 說明文件，熟悉 OpenClaw 的架構、工具和代理程式工作流程。

學習內容

  • 啟用必要的 Google Cloud API，並建立具備必要 IAM 權限的專屬服務帳戶。
  • 在 Secret Manager 中安全地儲存 API 金鑰和閘道密碼。
  • 準備 openclaw.json 設定檔，並啟用 Gemini 模型設定和閘道 UI。
  • 準備 Cloud Storage bucket，用於保存容器狀態。
  • 使用 gcloud beta run instances deploy 部署 OpenClaw。
  • 使用內建的網頁 UI，直接與 OpenClaw AI 代理互動。
  • (選用) 設定訊息管道 (Telegram 或 WhatsApp)。
  • (選用) 將自訂技能新增至 Cloud Storage，擴充代理程式的功能。

課程內容

  • 如何將 OpenClaw 部署至 Cloud Run 執行個體，並使用內建的控制網頁版 UI。
  • 如何將 Cloud Storage 值區掛接至 Cloud Run 執行個體。
  • 如何安全地將 Secret Manager 密鑰以環境變數的形式注入 Cloud Run。
  • 如何在 Cloud Run 執行個體上執行長時間執行的持續性代理程式工作負載。
  • 如何設定自訂代理技能並上傳至 Cloud Storage。

2. 設定和需求條件

設定 GCP 專案

  1. 登入 Google Cloud 控制台。
  2. 建立或選取 Google Cloud 專案。
  3. 確認 Google Cloud 專案已啟用計費功能。

開啟 Cloud Shell

從 Cloud Shell 的頂端工具列啟用 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 機器人

  1. 開啟 Telegram 並搜尋 @BotFather。
  2. 傳送 /newbot 指令，然後按照提示指定機器人名稱和使用者名稱。
  3. 複製產生的 HTTP API 權杖 (例如 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ)。
  4. 在 Telegram 上搜尋 @userinfobot，傳送 /start，然後複製數字 User ID (例如 8035936176)。

選項 B：設定 WhatsApp

  1. 取得個人 WhatsApp 電話號碼，並採用國際電話號碼格式，不得包含空格或符號 (例如 +15551234567)。
  2. 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 金鑰

  1. 前往 Google AI Studio，使用 Google 帳戶登入。
  2. 按一下「建立 API 金鑰」，然後選取 Google Cloud 專案 (${PROJECT_ID})。
  3. 複製產生的 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 bucket 和 openclaw.json 設定

OpenClaw 需要位於 /home/node/.openclaw/openclaw.json 的 openclaw.json 設定檔。

  1. 建立 Cloud Storage bucket 並授予存取權：
    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. 建立 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 }
    }
  }
}
  3. 上傳 openclaw.json 至 Cloud Storage bucket 根目錄：
    gcloud storage cp openclaw.json gs://${BUCKET_NAME}/openclaw.json
    驗證 Cloud Storage bucket 版面配置：確認 bucket 結構的根目錄包含 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 bucket 直接掛接至 /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 網頁版 UI 直接互動

OpenClaw 內建控制網頁 UI，可讓您直接透過瀏覽器管理 AI 代理並與之對話：

  1. 擷取 Cloud Run 執行個體網址：在 Cloud Shell 中執行：
    gcloud beta run instances describe openclaw-instance \
  --region ${REGION} \
  --format="value(status.urls[0])"
  2. 存取 OpenClaw 控制項使用者介面：
    • 在網路瀏覽器中開啟輸出內容網址。
    • 在 OpenClaw 控制項 UI 中看到驗證提示時：
      • 輸入從 Secret Manager 產生的閘道密碼 (${OPENCLAW_GATEWAY_PASSWORD})。
      • 如果登入強制回應顯示個別的「使用者名稱」和「密碼」欄位，請將使用者名稱欄位留空 (或輸入 admin)，並在密碼欄位中輸入 ${OPENCLAW_GATEWAY_PASSWORD}。
  3. 提示代理程式 (執行個體運作中)：
    • 驗證完成後，您會看到 OpenClaw 控制資訊主頁。
    • 在聊天使用者介面中傳送提示 (例如「Hello」)，測試 OpenClaw 代理程式。
    • 如要測試 Cloud Run 執行個體的長期生命週期，可以提示 OpenClaw 代理執行更複雜的長期工作。舉例來說，您可以讓 AI 追蹤新聞動態消息或股市，並生成報表：
      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，可以按照下列步驟確認訊息是否已送達：

  1. 在 Cloud Shell 中查看執行個體記錄：
    gcloud run instances logs read openclaw-instance --region ${REGION} --limit 20
  2. 開啟 Telegram (或 WhatsApp)，然後傳送訊息 (例如 /start 或 Hello OpenClaw!)。
  3. 機器人會根據 openclaw.json 中的允許清單驗證使用者 ID，並使用 Gemini 回覆！

10. 監控及檢查執行個體記錄

Cloud Run 執行個體會擷取容器的 stdout 和 stderr，並直接串流至 Google Cloud Logging。您可以使用 Cloud Shell 或 Cloud Console 監控閘道流量，並即時檢查代理程式工具的執行情況。

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 檔案的目錄。開頭是指定中繼資料的 YAML frontmatter (name 和 description)，後面接著 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：技能 ID (也可直接做為斜線指令呼叫，例如 /summarize-logs)。
  • description：告知 OpenClaw 的模型何時在自然對話中自動叫用這項技能。

將自訂技能新增至 Cloud Storage 值區

由於 Cloud Storage 值區會直接掛接至 /home/node/.openclaw，因此啟動時會自動載入 gs://${BUCKET_NAME}/skills/ 下的技能，並在執行個體重新啟動時保留：

  1. 建立本機技能目錄：
    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. 將 Skill 上傳至 Cloud Storage：
    gcloud storage cp -r my-skill gs://${BUCKET_NAME}/skills/
  3. 在 Chat 中使用技能：
    • 返回 OpenClaw 控制網頁版 UI。
    • 現在可以使用 /summarize-logs 提示代理，或以自然語言提問，問題內容符合技能說明即可！

12. 清除

如要避免系統向您的 Google Cloud 帳戶收取本程式碼研究室所用資源的費用，請按照下列步驟操作：

  1. 刪除 Cloud Run 執行個體：
    gcloud beta run instances delete openclaw-instance --region ${REGION} --quiet
  2. 刪除 Secret Manager Secret：
    gcloud secrets delete gemini-api-key --quiet
gcloud secrets delete telegram-bot-token --quiet
gcloud secrets delete openclaw-gateway-password --quiet
  3. 刪除 Cloud Storage bucket：
    gcloud storage rm -r gs://${BUCKET_NAME}
  4. 刪除專屬服務帳戶：
    gcloud iam service-accounts delete ${SERVICE_ACCOUNT} --quiet

13. 結語

恭喜！您已成功在 Cloud Run 執行個體上部署 OpenClaw 的安全全持續性執行個體，並由 Cloud Storage、Secret Manager 和您偏好的訊息管道提供支援！