GCP Compute Engine에서 OpenClaw 운영 (Docker, 프로덕션 VPS 가이드)

목표

GCP Compute Engine VM에서 Docker를 사용하여 영구 상태, 이미지에 포함된 바이너리, 안전한 재시작 동작을 갖춘 OpenClaw 게이트웨이를 운영합니다.

“월 ~$5-12로 OpenClaw를 24/7 운영”하고 싶다면, Google Cloud에서 안정적인 구성입니다. 가격은 머신 타입과 리전에 따라 다릅니다. 워크로드에 맞는 가장 작은 VM으로 시작하고 OOM이 발생하면 스케일 업하세요.

간단히 말하면?

GCP 프로젝트를 만들고 결제를 활성화합니다
Compute Engine VM을 생성합니다
Docker를 설치합니다(격리된 앱 런타임)
Docker에서 OpenClaw 게이트웨이를 시작합니다
호스트에 ~/.openclaw + ~/.openclaw/workspace를 유지합니다(재시작/리빌드에도 보존)
SSH 터널을 통해 노트북에서 Control UI에 접속합니다

게이트웨이 접속 방법:

노트북에서 SSH 포트 포워딩
방화벽과 토큰을 직접 관리하는 경우 직접 포트 노출

이 가이드는 GCP Compute Engine의 Debian을 사용합니다. Ubuntu도 가능합니다. 패키지를 적절히 매핑하세요. 일반적인 Docker 플로우는 Docker를 참고하세요.

빠른 경로 (경험 있는 운영자용)

GCP 프로젝트 생성 + Compute Engine API 활성화
Compute Engine VM 생성 (e2-small, Debian 12, 20GB)
VM에 SSH 접속
Docker 설치
OpenClaw 저장소 클론
영구 호스트 디렉토리 생성
.env 및 docker-compose.yml 설정
필수 바이너리 포함, 빌드 및 실행

필요한 것

GCP 계정 (e2-micro는 무료 티어 대상)
gcloud CLI 설치 (또는 Cloud Console 사용)
노트북에서 SSH 접속
SSH + 복사/붙여넣기에 대한 기본적인 이해
약 20-30분
Docker 및 Docker Compose
모델 인증 정보
선택적 프로바이더 인증 정보
- WhatsApp QR
- Telegram 봇 토큰
- Gmail OAuth

1) gcloud CLI 설치 (또는 Console 사용)

옵션 A: gcloud CLI (자동화에 권장)

https://cloud.google.com/sdk/docs/install에서 설치합니다.

초기화 및 인증:

gcloud init
gcloud auth login

옵션 B: Cloud Console

모든 단계를 https://console.cloud.google.com 웹 UI에서 수행할 수 있습니다.

2) GCP 프로젝트 생성

CLI:

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

https://console.cloud.google.com/billing에서 결제를 활성화합니다(Compute Engine에 필요).

Compute Engine API 활성화:

gcloud services enable compute.googleapis.com

Console:

IAM & Admin > Create Project로 이동
이름을 지정하고 생성
프로젝트에 결제 활성화
APIs & Services > Enable APIs > “Compute Engine API” 검색 > 활성화

3) VM 생성

머신 타입:

타입	사양	비용	비고
e2-medium	2 vCPU, 4GB RAM	월 ~$25	로컬 Docker 빌드에 가장 안정적
e2-small	2 vCPU, 2GB RAM	월 ~$12	Docker 빌드 최소 권장
e2-micro	2 vCPU (공유), 1GB RAM	무료 티어 대상	Docker 빌드 OOM (exit 137) 자주 발생

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:

Compute Engine > VM instances > Create instance로 이동
이름: openclaw-gateway
리전: us-central1, 존: us-central1-a
머신 타입: e2-small
부팅 디스크: Debian 12, 20GB
생성

4) VM에 SSH 접속

CLI:

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

Console:

Compute Engine 대시보드에서 VM 옆의 “SSH” 버튼을 클릭합니다.

참고: VM 생성 후 SSH 키 전파에 1-2분이 걸릴 수 있습니다. 연결이 거부되면 잠시 기다렸다가 재시도하세요.

5) Docker 설치 (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

그룹 변경을 적용하기 위해 로그아웃합니다:

exit

다시 SSH 접속합니다:

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

확인:

docker --version
docker compose version

6) OpenClaw 저장소 클론

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

이 가이드는 바이너리 유지를 보장하기 위해 커스텀 이미지를 빌드하는 것을 전제로 합니다.

7) 영구 호스트 디렉토리 생성

Docker 컨테이너는 임시적입니다. 모든 장기 보존 상태는 호스트에 있어야 합니다.

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

8) 환경 변수 설정

저장소 루트에 .env를 생성합니다.

OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=change-me-now
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789

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

GOG_KEYRING_PASSWORD=change-me-now
XDG_CONFIG_HOME=/home/node/.openclaw

강력한 시크릿 생성:

openssl rand -hex 32

이 파일을 커밋하지 마세요.

9) Docker Compose 설정

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:
      # 권장: VPS에서 게이트웨이를 루프백 전용으로 유지하고 SSH 터널로 접속합니다.
      # 퍼블릭으로 노출하려면 `127.0.0.1:` 접두사를 제거하고 방화벽을 설정하세요.
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND}",
        "--port",
        "${OPENCLAW_GATEWAY_PORT}",
      ]

10) 공유 Docker VM 런타임 단계

공통 Docker 호스트 플로우는 공유 런타임 가이드를 참고하세요:

11) GCP 관련 실행 참고사항

GCP에서 pnpm install --frozen-lockfile 도중 Killed 또는 exit code 137로 빌드가 실패하면 VM의 메모리가 부족한 것입니다. 최소 e2-small, 또는 안정적인 첫 빌드를 위해 e2-medium을 사용하세요.

LAN에 바인딩(OPENCLAW_GATEWAY_BIND=lan)할 때, 계속하기 전에 신뢰된 브라우저 오리진을 설정하세요:

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

게이트웨이 포트를 변경했다면 18789를 설정한 포트로 교체하세요.

12) 노트북에서 접속

게이트웨이 포트를 포워딩하는 SSH 터널을 생성합니다:

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

브라우저에서 엽니다:

http://127.0.0.1:18789/

토큰이 포함된 대시보드 링크를 새로 가져옵니다:

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

해당 URL의 토큰을 붙여넣습니다.

Control UI에서 unauthorized 또는 disconnected (1008): pairing required가 표시되면 브라우저 기기를 승인합니다:

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

공유 영구 보존 및 업데이트 참고가 다시 필요하면 Docker VM 런타임과 Docker VM 런타임 업데이트를 참고하세요.

문제 해결

SSH 연결 거부

VM 생성 후 SSH 키 전파에 1-2분이 걸릴 수 있습니다. 기다렸다가 재시도하세요.

OS Login 문제

OS Login 프로필을 확인합니다:

gcloud compute os-login describe-profile

계정에 필요한 IAM 권한(Compute OS Login 또는 Compute OS Admin Login)이 있는지 확인하세요.

메모리 부족 (OOM)

Docker 빌드가 Killed 및 exit code 137로 실패하면 VM이 OOM으로 종료된 것입니다. 최소 e2-small 또는 안정적인 로컬 빌드를 위해 e2-medium으로 업그레이드하세요:

# VM 먼저 중지
gcloud compute instances stop openclaw-gateway --zone=us-central1-a

# 머신 타입 변경
gcloud compute instances set-machine-type openclaw-gateway \
  --zone=us-central1-a \
  --machine-type=e2-small

# VM 시작
gcloud compute instances start openclaw-gateway --zone=us-central1-a

서비스 계정 (보안 모범 사례)

개인용으로는 기본 사용자 계정으로 충분합니다.

자동화나 CI/CD 파이프라인에서는 최소 권한의 전용 서비스 계정을 생성하세요:

서비스 계정 생성:

gcloud iam service-accounts create openclaw-deploy \
  --display-name="OpenClaw Deployment"

Compute Instance Admin 역할(또는 더 좁은 커스텀 역할) 부여:

gcloud projects add-iam-policy-binding my-openclaw-project \
  --member="serviceAccount:[email protected]" \
  --role="roles/compute.instanceAdmin.v1"

자동화에 Owner 역할은 피하세요. 최소 권한 원칙을 적용하세요.

IAM 역할 상세는 https://cloud.google.com/iam/docs/understanding-roles를 참고하세요.

다음 단계

메시징 채널 설정: 채널
로컬 기기를 노드로 페어링: 노드
게이트웨이 설정: 게이트웨이 구성