GCP Compute Engine에서 OpenClaw 실행하기 (Docker, 프로덕션 VPS 가이드)

목표

Docker를 사용해 GCP Compute Engine VM에서 지속적인 OpenClaw Gateway를 실행하고, 지속 가능한 상태, 내장 바이너리, 안전한 재시작 동작을 확보합니다. “월 약 $5~12로 OpenClaw를 24/7 실행”하고 싶다면, 이것은 Google Cloud에서 신뢰할 수 있는 설정입니다. 가격은 머신 유형과 리전에 따라 다르며, 워크로드에 맞는 가장 작은 VM을 선택한 뒤 OOM이 발생하면 상향 조정하세요.

무엇을 하게 되나요? (쉽게 설명)

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

마운트된 ~/.openclaw 상태에는 openclaw.json, agent별 agents/<agentId>/agent/auth-profiles.json, .env가 포함됩니다. Gateway에는 다음 방식으로 접근할 수 있습니다:

노트북에서 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 free tier 자격 가능)
gcloud CLI 설치됨(또는 Cloud Console 사용)
노트북에서의 SSH 접근
SSH + 복사/붙여넣기에 대한 기본적인 익숙함
약 20~30분
Docker 및 Docker Compose
모델 인증 자격 증명
선택적 공급자 자격 증명
- WhatsApp QR
- Telegram 봇 토큰
- Gmail OAuth

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에서도 수행할 수 있습니다.

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” 검색 > Enable

VM 만들기

머신 유형:

유형	사양	비용	참고
e2-medium	2 vCPU, 4GB RAM	약 $25/월	로컬 Docker 빌드에 가장 안정적
e2-small	2 vCPU, 2GB RAM	약 $12/월	Docker 빌드를 위한 최소 권장 사양
e2-micro	2 vCPU(공유), 1GB RAM	free tier 가능	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
Create

VM에 SSH 접속

CLI:

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

Console:Compute Engine 대시보드에서 VM 옆의 “SSH” 버튼을 클릭하세요.참고: SSH 키 전파에는 VM 생성 후 1~2분이 걸릴 수 있습니다. 연결이 거부되면 잠시 기다렸다가 다시 시도하세요.

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

OpenClaw 저장소 클론

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

이 가이드는 바이너리 지속성을 보장하기 위해 사용자 지정 이미지를 빌드한다고 가정합니다.

영구 호스트 디렉터리 생성

Docker 컨테이너는 일시적입니다. 오래 유지되어야 하는 모든 상태는 호스트에 있어야 합니다.

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

환경 변수 구성

저장소 루트에 .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

강력한 secret 생성:

openssl rand -hex 32

이 파일은 커밋하지 마세요.이 .env 파일은 OPENCLAW_GATEWAY_TOKEN 같은 컨테이너/런타임 환경 변수용입니다. 저장된 공급자 OAuth/API key 인증은 마운트된 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json에 저장됩니다.

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:
      # 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는 bootstrap 편의를 위한 것일 뿐이며, 올바른 gateway 구성의 대체재가 아닙니다. 여전히 auth(gateway.auth.token 또는 password)를 설정하고 배포에 맞는 안전한 bind 설정을 사용하세요.

공유 Docker VM 런타임 단계

공통 Docker 호스트 흐름에는 공유 런타임 가이드를 사용하세요:

GCP 전용 실행 참고

GCP에서 pnpm install --frozen-lockfile 중 Killed 또는 exit code 137로 빌드가 실패하면, VM 메모리가 부족한 것입니다. 최소 e2-small, 더 안정적인 첫 빌드를 위해서는 e2-medium을 사용하세요.LAN에 바인딩할 경우(OPENCLAW_GATEWAY_BIND=lan), 계속하기 전에 신뢰된 브라우저 origin을 구성하세요:

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

gateway 포트를 변경했다면 18789를 구성한 포트로 바꾸세요.

노트북에서 접근

Gateway 포트를 전달하도록 SSH 터널을 만드세요:

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

브라우저에서 열기:http://127.0.0.1:18789/깔끔한 dashboard 링크 다시 출력:

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

UI가 shared-secret auth를 요청하면, 구성된 토큰 또는 비밀번호를 Control UI 설정에 붙여넣으세요. 이 Docker 흐름은 기본적으로 토큰을 작성합니다. 컨테이너 구성을 password auth로 바꿨다면 그 비밀번호를 대신 사용하세요.Control UI에 unauthorized 또는 disconnected (1008): pairing required가 표시되면, 브라우저 장치를 승인하세요:

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

공유 persistence 및 업데이트 참조가 다시 필요하신가요? Docker VM Runtime 및 Docker VM Runtime updates를 참조하세요.

문제 해결

SSH 연결 거부됨 SSH 키 전파에는 VM 생성 후 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:openclaw-deploy@my-openclaw-project.iam.gserviceaccount.com" \
  --role="roles/compute.instanceAdmin.v1"

자동화에는 Owner 역할 사용을 피하세요. 최소 권한 원칙을 사용하세요. IAM 역할 세부 사항은 https://cloud.google.com/iam/docs/understanding-roles를 참조하세요.

다음 단계

메시징 채널 설정: Channels
로컬 장치를 노드로 페어링: Nodes
Gateway 구성: Gateway configuration

Install overview

Containers

Hosting

Maintenance

GCP

GCP Compute Engine에서 OpenClaw 실행하기 (Docker, 프로덕션 VPS 가이드)

목표

무엇을 하게 되나요? (쉽게 설명)

빠른 경로(숙련된 운영자용)

필요한 것

문제 해결

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

다음 단계

Install overview

Containers

Hosting

Maintenance

​GCP Compute Engine에서 OpenClaw 실행하기 (Docker, 프로덕션 VPS 가이드)

​목표

​무엇을 하게 되나요? (쉽게 설명)

​빠른 경로(숙련된 운영자용)

​필요한 것

​문제 해결

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

​다음 단계

GCP Compute Engine에서 OpenClaw 실행하기 (Docker, 프로덕션 VPS 가이드)

목표

무엇을 하게 되나요? (쉽게 설명)

빠른 경로(숙련된 운영자용)

필요한 것

문제 해결

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

다음 단계