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 포트 포워딩
방화벽과 토큰을 직접 관리하는 경우 포트를 직접 노출

이 가이드는 Hetzner 의 Ubuntu 또는 Debian 을 가정합니다.
다른 Linux VPS 를 사용하는 경우 패키지를 적절히 매핑하십시오. 일반적인 Docker 흐름은 Docker를 참고하십시오.

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

Hetzner VPS 프로비저닝
Docker 설치
OpenClaw 리포지토리 클론
영속적인 호스트 디렉토리 생성
.env 및 docker-compose.yml 구성
필요한 바이너리를 이미지에 포함
docker compose up -d
영속성 및 Gateway(게이트웨이) 접근 확인

필요한 사항

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 가 상태를 유지한다고 가정합니다. 이를 일회성 인프라로 취급하지 마십시오.

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 컨테이너는 일시적입니다. 모든 장기 상태는 호스트에 존재해야 합니다.

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

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

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

--allow-unconfigured는 부트스트랩 편의를 위한 옵션일 뿐이며, 적절한 게이트웨이 구성의 대체물이 아닙니다. 배포 환경에 맞게 인증(gateway.auth.token 또는 비밀번호)을 설정하고 안전한 바인드 설정을 사용하세요.

7. 필요한 바이너리를 이미지에 포함 (중요)

실행 중인 컨테이너 안에 바이너리를 설치하는 것은 함정입니다. 런타임에 설치된 모든 것은 재시작 시 사라집니다. Skills 에 필요한 모든 외부 바이너리는 이미지 빌드 시점에 설치되어야 합니다. 아래 예시는 세 가지 일반적인 바이너리만을 보여줍니다:

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

이는 예시이며 완전한 목록이 아닙니다. 동일한 패턴을 사용하여 필요한 만큼 바이너리를 설치할 수 있습니다. 나중에 추가 바이너리에 의존하는 새로운 Skills 를 추가하는 경우 다음을 수행해야 합니다:

Dockerfile 업데이트
이미지 재빌드
컨테이너 재시작

예시 Dockerfile

FROM node:22-bookworm

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

# Example binary 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

# Example binary 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

# Example binary 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

# Add more binaries below using the same pattern

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 토큰을 붙여넣습니다.

무엇이 어디에 영속화되는가 (단일 기준점)

OpenClaw 는 Docker 에서 실행되지만, Docker 가 단일 기준점은 아닙니다. 모든 장기 상태는 재시작, 재빌드, 재부팅 이후에도 유지되어야 합니다.

구성 요소	위치	영속성 메커니즘	참고 자료
Gateway 설정	`/home/node/.openclaw/`	호스트 볼륨 마운트	`openclaw.json`, 토큰 포함
모델 인증 프로필	`/home/node/.openclaw/`	호스트 볼륨 마운트	OAuth 토큰, API 키
Skill 설정	`/home/node/.openclaw/skills/`	호스트 볼륨 마운트	Skill 수준 상태
에이전트 작업 공간	`/home/node/.openclaw/workspace/`	호스트 볼륨 마운트	코드 및 에이전트 아티팩트
WhatsApp 세션	`/home/node/.openclaw/`	호스트 볼륨 마운트	QR 로그인 유지
Gmail 키링	`/home/node/.openclaw/`	호스트 볼륨 + 비밀번호	`GOG_KEYRING_PASSWORD` 필요
외부 바이너리	`/usr/local/bin/`	Docker 이미지	Must be baked at build time
Node 런타임	컨테이너 파일 시스템	Docker 이미지	매 이미지 빌드마다 재생성
OS 패키지	컨테이너 파일 시스템	Docker 이미지	런타임에 설치하지 말 것
Docker 컨테이너	일회성입니다	재시작 가능	삭제해도 안전함

Infrastructure as Code (Terraform)

인프라를 코드로 관리하는 워크플로를 선호하는 팀을 위해, 커뮤니티에서 유지 관리하는 Terraform 설정은 다음을 제공합니다:

원격 상태 관리를 포함한 모듈식 Terraform 구성
cloud-init을 통한 자동 프로비저닝
배포 스크립트(bootstrap, deploy, backup/restore)
보안 강화(firewall, UFW, SSH 전용 액세스)
gateway 액세스를 위한 SSH 터널 구성

리포지토리:

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

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

참고: 커뮤니티에서 유지 관리됩니다. 문제 발생 또는 기여 방법은 위의 저장소 링크를 참고하세요.

설치 개요

기타 설치 방법

유지 관리

호스팅 및 배포

고급

Hetzner

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

목표

우리는 무엇을 하고 있나요? (쉽게 설명하면)

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

필요한 사항

1. VPS 프로비저닝

2. Docker 설치 (VPS 에서)

3. OpenClaw 리포지토리 클론

4. 영속적인 호스트 디렉토리 생성

5. 환경 변수 구성

6. Docker Compose 구성

7. 필요한 바이너리를 이미지에 포함 (중요)

8. 빌드 및 실행

9. Gateway(게이트웨이) 확인

무엇이 어디에 영속화되는가 (단일 기준점)

Infrastructure as Code (Terraform)

설치 개요

기타 설치 방법

유지 관리

호스팅 및 배포

고급

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

​목표

​우리는 무엇을 하고 있나요? (쉽게 설명하면)

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

​필요한 사항

​1. VPS 프로비저닝

​2. Docker 설치 (VPS 에서)

​3. OpenClaw 리포지토리 클론

​4. 영속적인 호스트 디렉토리 생성

​5. 환경 변수 구성

​6. Docker Compose 구성

​7. 필요한 바이너리를 이미지에 포함 (중요)

​8. 빌드 및 실행

​9. Gateway(게이트웨이) 확인

​무엇이 어디에 영속화되는가 (단일 기준점)

​Infrastructure as Code (Terraform)

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

목표

우리는 무엇을 하고 있나요? (쉽게 설명하면)

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

필요한 사항

1. VPS 프로비저닝

2. Docker 설치 (VPS 에서)

3. OpenClaw 리포지토리 클론

4. 영속적인 호스트 디렉토리 생성

5. 환경 변수 구성

6. Docker Compose 구성

7. 필요한 바이너리를 이미지에 포함 (중요)

8. 빌드 및 실행

9. Gateway(게이트웨이) 확인

무엇이 어디에 영속화되는가 (단일 기준점)

Infrastructure as Code (Terraform)