GCP

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:

1. IAM & Admin > Create Project로 이동합니다
2. 이름을 지정하고 생성합니다
3. 프로젝트의 결제를 활성화합니다
4. APIs & Services > Enable APIs로 이동 > "Compute Engine API" 검색 > 활성화

VM 생성

머신 유형:

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. Compute Engine > VM instances > Create instance로 이동합니다
2. 이름: openclaw-gateway
3. 리전: us-central1, 존: us-central1-a
4. 머신 유형: e2-small
5. 부팅 디스크: Debian 12, 20GB
6. 생성합니다

VM에 SSH 접속

CLI:

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

Console:

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

참고: VM 생성 후 SSH 키 전파에 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=
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

안정적인 gateway 토큰을 .env를 통해 관리하려면 OPENCLAW_GATEWAY_TOKEN을 설정하세요. 그렇지 않으면 재시작 후에도 클라이언트에 의존하기 전에 gateway.auth.token을 구성하세요. 어느 소스도 없으면 OpenClaw는 해당 시작에만 유효한 런타임 전용 토큰을 사용합니다. 키링 비밀번호를 생성하고 GOG_KEYRING_PASSWORD에 붙여넣습니다.

openssl rand -hex 32

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

이 .env 파일은 OPENCLAW_GATEWAY_TOKEN 같은 컨테이너/런타임 env용입니다. 저장된 provider 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는 부트스트랩 편의를 위한 것일 뿐이며, 적절한 gateway 구성을 대체하지 않습니다. 배포 환경에 맞게 인증(gateway.auth.token 또는 비밀번호)을 설정하고 안전한 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/

깔끔한 대시보드 링크를 다시 출력합니다.

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

UI에서 shared-secret 인증을 요청하면 구성한 토큰 또는 비밀번호를 Control UI 설정에 붙여넣으세요. 이 Docker 흐름은 기본적으로 토큰을 씁니다. 컨테이너 구성을 비밀번호 인증으로 전환한 경우에는 대신 해당 비밀번호를 사용하세요.

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 Runtime 및 Docker VM Runtime 업데이트를 참조하세요.