GCP

Cài đặt gcloud CLI (hoặc dùng Console)

Tùy chọn A: gcloud CLI (khuyến nghị cho tự động hóa)

Cài đặt từ https://cloud.google.com/sdk/docs/install

Khởi tạo và xác thực:

gcloud init
gcloud auth login

Tùy chọn B: Cloud Console

Tất cả các bước có thể thực hiện qua UI web tại https://console.cloud.google.com

Tạo một dự án GCP

CLI:

gcloud projects create my-openclaw-project --name="OpenClaw Gateway"
gcloud config set project my-openclaw-project

Bật thanh toán tại https://console.cloud.google.com/billing (bắt buộc cho Compute Engine).

Bật Compute Engine API:

gcloud services enable compute.googleapis.com

Console:

1. Vào IAM & Admin > Create Project
2. Đặt tên và tạo
3. Bật thanh toán cho dự án
4. Điều hướng đến APIs & Services > Enable APIs > tìm "Compute Engine API" > Enable

Tạo VM

Loại máy:

CLI:

gcloud compute instances create openclaw-gateway \
  --zone=us-central1-a \
  --machine-type=e2-small \
  --boot-disk-size=20GB \
  --image-family=debian-12 \
  --image-project=debian-cloud

Console:

1. Vào Compute Engine > VM instances > Create instance
2. Tên: openclaw-gateway
3. Khu vực: us-central1, Zone: us-central1-a
4. Loại máy: e2-small
5. Boot disk: Debian 12, 20GB
6. Tạo

SSH vào VM

CLI:

gcloud compute ssh openclaw-gateway --zone=us-central1-a

Console:

Nhấp nút "SSH" bên cạnh VM của bạn trong dashboard Compute Engine.

Lưu ý: Việc lan truyền khóa SSH có thể mất 1-2 phút sau khi tạo VM. Nếu kết nối bị từ chối, hãy chờ rồi thử lại.

Cài đặt Docker (trên VM)

sudo apt-get update
sudo apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

Đăng xuất rồi đăng nhập lại để thay đổi nhóm có hiệu lực:

exit

Sau đó SSH lại vào:

gcloud compute ssh openclaw-gateway --zone=us-central1-a

Xác minh:

docker --version
docker compose version

Clone repository OpenClaw

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Hướng dẫn này giả định bạn sẽ build image tùy chỉnh để đảm bảo binary được lưu bền vững.

Tạo các thư mục host bền vững

Docker container là tạm thời. Mọi trạng thái tồn tại lâu dài phải nằm trên host.

mkdir -p ~/.openclaw
mkdir -p ~/.openclaw/workspace

Cấu hình biến môi trường

Tạo .env ở root của repository.

OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789

OPENCLAW_CONFIG_DIR=/home/$USER/.openclaw
OPENCLAW_WORKSPACE_DIR=/home/$USER/.openclaw/workspace

GOG_KEYRING_PASSWORD=
XDG_CONFIG_HOME=/home/node/.openclaw

Đặt OPENCLAW_GATEWAY_TOKEN khi bạn muốn quản lý token Gateway ổn định thông qua .env; nếu không, hãy cấu hình gateway.auth.token trước khi dựa vào client qua các lần khởi động lại. Nếu không có nguồn nào tồn tại, OpenClaw dùng token chỉ trong runtime cho lần khởi động đó. Tạo mật khẩu keyring và dán vào GOG_KEYRING_PASSWORD:

openssl rand -hex 32

Không commit tệp này.

Tệp .env này dành cho env container/runtime như OPENCLAW_GATEWAY_TOKEN. Auth OAuth/API-key của provider đã lưu nằm trong ~/.openclaw/agents/<agentId>/agent/auth-profiles.json được mount.

Cấu hình Docker Compose

Tạo hoặc cập nhật docker-compose.yml.

services:
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE}
    build: .
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - HOME=/home/node
      - NODE_ENV=production
      - TERM=xterm-256color
      - OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND}
      - OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT}
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
      - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    ports:
      # Recommended: keep the Gateway loopback-only on the VM; access via SSH tunnel.
      # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND}",
        "--port",
        "${OPENCLAW_GATEWAY_PORT}",
        "--allow-unconfigured",
      ]

--allow-unconfigured chỉ để tiện bootstrap, không phải thay thế cho cấu hình gateway đúng cách. Vẫn cần đặt auth (gateway.auth.token hoặc mật khẩu) và dùng thiết lập bind an toàn cho deployment của bạn.

Các bước runtime VM Docker dùng chung

Dùng hướng dẫn runtime dùng chung cho luồng host Docker phổ biến:

• Tích hợp các binary cần thiết vào image
• Build và khởi chạy
• Những gì được lưu bền vững ở đâu
• Cập nhật

Ghi chú khởi chạy riêng cho GCP

Trên GCP, nếu build thất bại với Killed hoặc exit code 137 trong lúc chạy pnpm install --frozen-lockfile, VM đã hết bộ nhớ. Dùng tối thiểu e2-small, hoặc e2-medium để các lần build đầu tiên đáng tin cậy hơn.

Khi bind vào LAN (OPENCLAW_GATEWAY_BIND=lan), hãy cấu hình origin trình duyệt đáng tin cậy trước khi tiếp tục:

docker compose run --rm openclaw-cli config set gateway.controlUi.allowedOrigins '["http://127.0.0.1:18789"]' --strict-json

Nếu bạn đã đổi cổng gateway, thay 18789 bằng cổng đã cấu hình.

Truy cập từ laptop của bạn

Tạo SSH tunnel để chuyển tiếp cổng Gateway:

gcloud compute ssh openclaw-gateway --zone=us-central1-a -- -L 18789:127.0.0.1:18789

Mở trong trình duyệt của bạn:

http://127.0.0.1:18789/

In lại liên kết dashboard sạch:

docker compose run --rm openclaw-cli dashboard --no-open

Nếu UI yêu cầu auth bằng shared-secret, hãy dán token hoặc mật khẩu đã cấu hình vào thiết lập Control UI. Luồng Docker này ghi token theo mặc định; nếu bạn chuyển cấu hình container sang auth bằng mật khẩu, hãy dùng mật khẩu đó thay thế.

Nếu Control UI hiển thị unauthorized hoặc disconnected (1008): pairing required, hãy phê duyệt thiết bị trình duyệt:

docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

Cần lại tham chiếu về lưu bền vững và cập nhật dùng chung? Xem Docker VM Runtime và các cập nhật Docker VM Runtime.