Hetzner VPS에서 Docker로 OpenClaw 운영하기

로컬 환경에서 잘 돌아가던 도구가 서버에 올리기만 하면 재시작할 때마다 설정이 초기화되거나, 의존성 문제로 제대로 작동하지 않아 당황했던 적 있으시죠? 매번 수동으로 환경을 세팅하는 번거로움 없이 24시간 내내 안정적으로 서비스를 돌리고 싶은 마음은 모든 개발자가 비슷할 거예요.

OpenClaw를 Hetzner VPS에서 Docker로 실행하면 월 약 5달러 정도의 저렴한 비용으로 나만의 Gateway를 구축할 수 있습니다. 데이터를 안전하게 보존하면서도 관리가 쉬운 최적의 설정 방법을 정리해 드릴게요.

필요한 것

• root 권한이 있는 Hetzner VPS (Ubuntu 또는 Debian 권장)
• 로컬 컴퓨터에서의 SSH 접속 권한
• SSH 사용 및 명령어 복사/붙여넣기에 익숙한 숙련도
• 약 20분의 시간
• Docker 및 Docker Compose
• Model auth 인증 정보
• 선택 사항: 서비스 제공자 인증 정보 (WhatsApp QR, Telegram 토큰, Gmail OAuth 등)

빠른 시작

1) VPS 준비 및 접속

Hetzner에서 Ubuntu 또는 Debian VPS를 생성하세요. 생성 후 root 계정으로 접속합니다.

ssh root@YOUR_VPS_IP

이 가이드는 VPS를 데이터가 유지되는 상태 저장(Stateful) 서버로 취급합니다. 일회용 인프라로 다루지 마세요.

2) Docker 설치

apt-get update
apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sh

설치가 완료되면 버전을 확인합니다.

docker --version
docker compose version

3) OpenClaw 저장소 복제

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

4) 데이터 보존용 디렉토리 생성

Docker 컨테이너는 기본적으로 일시적입니다. 데이터가 사라지지 않도록 호스트 서버에 저장 공간을 만듭니다.

mkdir -p /root/.openclaw
mkdir -p /root/.openclaw/workspace

# 컨테이너 사용자(uid 1000)에게 권한 부여:
chown -R 1000:1000 /root/.openclaw
chown -R 1000:1000 /root/.openclaw/workspace

5) 환경 변수 설정

저장소 루트에 .env 파일을 만듭니다. OPENCLAW_GATEWAY_TOKEN과 GOG_KEYRING_PASSWORD는 강력한 문자열로 변경하세요.

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

OPENCLAW_CONFIG_DIR=/root/.openclaw
OPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace

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

강력한 비밀번호가 필요하다면 이 명령어를 사용하세요.

openssl rand -hex 32

6) Docker Compose 설정

docker-compose.yml 파일을 다음과 같이 작성하거나 업데이트하세요. 보안을 위해 Gateway는 127.0.0.1에 바인딩하고 SSH 터널링으로 접속하는 것이 좋습니다.

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:
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND}",
        "--port",
        "${OPENCLAW_GATEWAY_PORT}",
      ]

7) 필수 Binary를 Image에 포함하기 (중요)

실행 중인 컨테이너 안에 Binary를 직접 설치하면 안 됩니다. 컨테이너가 재시작되면 모두 사라지기 때문이죠. 필요한 외부 도구들은 반드시 빌드 시점에 Dockerfile에 포함해야 합니다.

아래 예시는 Gmail(gog), Google Places(goplaces), WhatsApp(wacli) 도구를 포함하는 Dockerfile 예시입니다.

FROM node:22-bookworm

RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*

# 예시 1: Gmail CLI
RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog

# 예시 2: Google Places CLI
RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces

# 예시 3: WhatsApp CLI
RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli

WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN corepack enable
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]

8) 빌드 및 실행

docker compose build
docker compose up -d openclaw-gateway

설치된 도구들이 정상적으로 작동하는지 확인합니다.

docker compose exec openclaw-gateway which gog
docker compose exec openclaw-gateway which goplaces
docker compose exec openclaw-gateway which wacli

9) Gateway 접속 확인

로그를 확인하여 Gateway가 준비되었는지 봅니다.

docker compose logs -f openclaw-gateway

[gateway] listening on ws://0.0.0.0:18789 메시지가 보이면 성공입니다. 이제 로컬 컴퓨터에서 SSH 터널을 뚫어 접속합니다.

ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP

브라우저에서 http://127.0.0.1:18789/를 열고 설정한 Gateway 토큰을 입력하세요.

문제 해결

• 문제: 컨테이너를 재시작하거나 이미지를 다시 빌드하면 실행 중에 설치했던 외부 도구들이 사라집니다.
• 해결책: 7단계에서 설명한 것처럼, 필요한 모든 Binary는 반드시 Dockerfile에 포함(Bake)해야 합니다. 새로운 도구가 필요해지면 Dockerfile을 수정하고 다시 빌드하세요.

---

궁금한 점이 있거나 설정 중에 도움이 필요하다면 AI Setup Assistant를 이용해 보세요.

다음 단계

• Docker 설치 상세 가이드
• Gateway 보안 설정