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

목표

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

“월 ~$5로 OpenClaw를 24/7 운영”하고 싶다면, 이것이 가장 간단하고 안정적인 구성입니다. Hetzner 가격은 변동될 수 있습니다. 가장 작은 Debian/Ubuntu VPS로 시작하고 OOM이 발생하면 스케일 업하세요.

보안 모델 참고:

같은 신뢰 경계 안에 있고 런타임이 업무 전용이라면 회사 공유 에이전트도 괜찮습니다.
엄격한 분리를 유지하세요: 전용 VPS/런타임 + 전용 계정. 해당 호스트에 개인 Apple/Google/브라우저/비밀번호 관리자 프로필을 사용하지 마세요.
사용자 간에 적대적 관계가 있다면 게이트웨이/호스트/OS 사용자 단위로 분리하세요.

보안과 VPS 호스팅을 참고하세요.

간단히 말하면?

소규모 Linux 서버를 임대합니다 (Hetzner VPS)
Docker를 설치합니다 (격리된 앱 런타임)
Docker에서 OpenClaw 게이트웨이를 시작합니다
호스트에 ~/.openclaw + ~/.openclaw/workspace를 유지합니다 (재시작/리빌드에도 보존)
SSH 터널을 통해 노트북에서 Control UI에 접속합니다

게이트웨이 접속 방법:

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

이 가이드는 Hetzner의 Ubuntu 또는 Debian을 기준으로 합니다. 다른 Linux VPS를 사용한다면 패키지를 적절히 매핑하세요. 일반적인 Docker 플로우는 Docker를 참고하세요.

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

Hetzner VPS 프로비저닝
Docker 설치
OpenClaw 저장소 클론
영구 호스트 디렉토리 생성
.env 및 docker-compose.yml 설정
이미지에 필수 바이너리 포함
docker compose up -d
영구 보존 및 게이트웨이 접속 확인

필요한 것

root 접근이 가능한 Hetzner VPS
노트북에서 SSH 접속
SSH + 복사/붙여넣기에 대한 기본적인 이해
약 20분
Docker 및 Docker Compose
모델 인증 정보
선택적 프로바이더 인증 정보
- WhatsApp QR
- Telegram 봇 토큰
- Gmail OAuth

1) VPS 프로비저닝

Hetzner에서 Ubuntu 또는 Debian VPS를 생성합니다.

root로 접속합니다:

ssh root@YOUR_VPS_IP

이 가이드는 VPS가 상태 보존(stateful)임을 전제로 합니다. 일회용 인프라로 취급하지 마세요.

2) Docker 설치 (VPS에서)

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/workspace

# 컨테이너 사용자 (uid 1000)에게 소유권 설정:
chown -R 1000:1000 /root/.openclaw

5) 환경 변수 설정

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

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을 생성하거나 업데이트합니다.

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}",
        "--allow-unconfigured",
      ]

--allow-unconfigured는 부트스트랩 편의를 위한 것이며, 적절한 게이트웨이 설정을 대체하지 않습니다. 여전히 인증(gateway.auth.token 또는 비밀번호)을 설정하고 배포에 안전한 바인드 설정을 사용하세요.

7) 공유 Docker VM 런타임 단계

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

8) Hetzner 전용 접속

공유 빌드 및 실행 단계 후, 노트북에서 터널을 엽니다:

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

브라우저에서 엽니다:

http://127.0.0.1:18789/

게이트웨이 토큰을 붙여넣습니다.

공유 영구 보존 맵은 Docker VM 런타임에 있습니다.

Infrastructure as Code (Terraform)

코드로 인프라를 관리하는 팀을 위해, 커뮤니티에서 관리하는 Terraform 구성이 다음을 제공합니다:

원격 상태 관리를 갖춘 모듈식 Terraform 설정
cloud-init을 통한 자동화된 프로비저닝
배포 스크립트 (부트스트랩, 배포, 백업/복원)
보안 강화 (방화벽, UFW, SSH 전용 접근)
게이트웨이 접속을 위한 SSH 터널 설정

저장소:

인프라: openclaw-terraform-hetzner
Docker 설정: openclaw-docker-config

이 접근 방식은 위의 Docker 설정을 재현 가능한 배포, 버전 관리 인프라, 자동화된 재해 복구로 보완합니다.

참고: 커뮤니티에서 관리합니다. 이슈나 기여는 위의 저장소 링크를 참고하세요.