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

목표

Docker를 사용하여 Hetzner VPS에서 지속적인 OpenClaw Gateway를 실행하며, 내구성 있는 상태, 내장된 바이너리 및 안전한 재시작 동작을 갖춥니다.

"월 ~$5로 OpenClaw 24/7"을 원한다면, 이것이 가장 간단하고 신뢰할 수 있는 설정입니다. Hetzner 가격은 변경됩니다; 가장 작은 Debian/Ubuntu VPS를 선택하고 OOM이 발생하면 확장하세요.

간단히 말하면 무엇을 하나요?

  • 작은 Linux 서버 임대 (Hetzner VPS)
  • Docker 설치 (격리된 앱 런타임)
  • Docker에서 OpenClaw Gateway 시작
  • 호스트에서 ~/.openclaw + ~/.openclaw/workspace 지속 (재시작/재빌드 후에도 유지)
  • SSH 터널을 통해 노트북에서 Control UI 접근

Gateway는 다음을 통해 접근할 수 있습니다:

  • 노트북에서 SSH 포트 포워딩
  • 방화벽 및 token을 직접 관리하는 경우 직접 포트 노출

이 가이드는 Hetzner의 Ubuntu 또는 Debian을 가정합니다. 다른 Linux VPS를 사용하는 경우, 그에 맞게 패키지를 매핑하세요. 일반적인 Docker 흐름은 Docker를 참조하세요.

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

  1. Hetzner VPS 프로비저닝
  2. Docker 설치
  3. OpenClaw 레포지토리 클론
  4. 영구 호스트 디렉토리 생성
  5. .env 및 docker-compose.yml 구성
  6. 이미지에 필요한 바이너리 베이크
  7. docker compose up -d
  8. 지속성 및 Gateway 접근 확인

필요한 것

  • root 접근 권한이 있는 Hetzner VPS
  • 노트북에서 SSH 접근
  • SSH + 복사/붙여넣기에 대한 기본적인 익숙함
  • ~20분
  • Docker 및 Docker Compose
  • Model 인증 자격 증명
  • 선택적 제공업체 자격 증명
    • WhatsApp QR
    • Telegram bot token
    • Gmail OAuth

1) VPS 프로비저닝

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

root로 연결:

ssh root@YOUR_VPS_IP

이 가이드는 VPS가 상태 저장형이라고 가정합니다. 일회성 인프라로 취급하지 마세요.

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
mkdir -p /root/.openclaw/workspace

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

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에서 Gateway를 loopback 전용으로 유지; SSH 터널을 통해 접근.
      # 공개적으로 노출하려면, `127.0.0.1:` 접두사를 제거하고 적절히 방화벽을 설정하세요.
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"

      # 선택사항: 이 VPS에 대해 iOS/Android nodes를 실행하고 Canvas host가 필요한 경우에만.
      # 공개적으로 노출하는 경우, /gateway/security를 읽고 적절히 방화벽을 설정하세요.
      # - "18793:18793"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND}",
        "--port",
        "${OPENCLAW_GATEWAY_PORT}"
      ]

7) 이미지에 필요한 바이너리 베이크 (중요)

실행 중인 컨테이너 내부에 바이너리를 설치하는 것은 함정입니다. 런타임에 설치된 모든 것은 재시작 시 손실됩니다.

Skills에 필요한 모든 외부 바이너리는 이미지 빌드 시 설치해야 합니다.

아래 예시는 세 가지 일반적인 바이너리만 보여줍니다:

  • Gmail 접근을 위한 gog
  • Google Places를 위한 goplaces
  • WhatsApp을 위한 wacli

이들은 예시이며 완전한 목록이 아닙니다. 동일한 패턴을 사용하여 필요한 만큼 많은 바이너리를 설치할 수 있습니다.

나중에 추가 바이너리에 의존하는 새 skills를 추가하는 경우:

  1. Dockerfile 업데이트
  2. 이미지 재빌드
  3. 컨테이너 재시작

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

예상 출력:

/usr/local/bin/gog
/usr/local/bin/goplaces
/usr/local/bin/wacli

9) Gateway 확인

docker compose logs -f openclaw-gateway

성공:

[gateway] listening on ws://0.0.0.0:18789

노트북에서:

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

열기:

http://127.0.0.1:18789/

Gateway token을 붙여넣습니다.

무엇이 어디에 지속되는가 (진실의 원천)

OpenClaw는 Docker에서 실행되지만, Docker는 진실의 원천이 아닙니다. 모든 장기 상태는 재시작, 재빌드 및 재부팅에서 살아남아야 합니다.

구성 요소위치지속성 메커니즘비고
Gateway 구성/home/node/.openclaw/호스트 볼륨 마운트openclaw.json, token 포함
Model 인증 프로필/home/node/.openclaw/호스트 볼륨 마운트OAuth token, API 키
Skill 구성/home/node/.openclaw/skills/호스트 볼륨 마운트Skill 수준 상태
Agent 작업 공간/home/node/.openclaw/workspace/호스트 볼륨 마운트코드 및 agent 아티팩트
WhatsApp 세션/home/node/.openclaw/호스트 볼륨 마운트QR 로그인 보존
Gmail keyring/home/node/.openclaw/호스트 볼륨 + 비밀번호GOG_KEYRING_PASSWORD 필요
외부 바이너리/usr/local/bin/Docker 이미지빌드 시 베이크해야 함
Node 런타임컨테이너 파일시스템Docker 이미지모든 이미지 빌드마다 재빌드
OS 패키지컨테이너 파일시스템Docker 이미지런타임에 설치하지 마세요
Docker 컨테이너임시재시작 가능안전하게 파괴 가능
← 문서로 돌아가기